From 1aa45df11ff950d78db39cc90d3c190658b66156 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 20:39:37 +0300
Subject: [PATCH 001/158] chore: prepare the repository for the upyo port

The transport layer is about to be ported from upyo 0.7.0, one subpath per
upstream package. This sets up what every subpath needs before the first one
lands:

- LICENSE carries upyo's MIT notice, and CLAUDE.md the rules of the port
  (attribution header, upstream behavior kept, upstream lint suppressed on
  the line, describe/it kept in ported suites).
- export-parity, bundle, size and check:dts read the exports map, so a
  subpath is checked as soon as it is declared; graph.test.js forbids require
  cycles and cross-subpath requires outside an allow-list.
- src/version.js holds the name and version for the OpenTelemetry scope,
  tested against package.json and bumped by the release process.
- .gitattributes keeps LF on Windows checkouts, where MIME and DKIM tests
  compare bytes; sideEffects is false, and tests may use console.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/npm-publish/SKILL.md |   4 +-
 .gitattributes                      |   7 ++
 .oxlintrc.json                      |   3 +-
 CLAUDE.md                           |  53 +++++++++++--
 LICENSE                             |  26 +++++++
 package.json                        |   3 +-
 scripts/check-dts.js                |  29 +++++++
 scripts/size.js                     | 114 +++++++++++++++++++++-------
 src/version.js                      |   5 ++
 tests/unit/bundle.test.js           |  28 +++++--
 tests/unit/export-parity.test.js    |  65 ++++++++++------
 tests/unit/graph.test.js            | 103 +++++++++++++++++++++++++
 tests/unit/scripts.test.js          |  56 +++++++++++++-
 tests/unit/version.test.js          |   8 ++
 14 files changed, 434 insertions(+), 70 deletions(-)
 create mode 100644 .gitattributes
 create mode 100644 scripts/check-dts.js
 create mode 100644 src/version.js
 create mode 100644 tests/unit/graph.test.js
 create mode 100644 tests/unit/version.test.js

diff --git a/.claude/skills/npm-publish/SKILL.md b/.claude/skills/npm-publish/SKILL.md
index 0f50d46..acdb27d 100644
--- a/.claude/skills/npm-publish/SKILL.md
+++ b/.claude/skills/npm-publish/SKILL.md
@@ -31,7 +31,7 @@ pnpm run lint                    # oxlint
 pnpm run format:check            # oxfmt
 pnpm run test:coverage           # tests under the c8 coverage gate
 pnpm run test:types              # tsd
-pnpm run check:dts               # tsc over index.d.ts
+pnpm run check:dts               # tsc over the d.ts of every entry of the exports map
 ```
 
 These are the same gates `prepublishOnly` runs. CI adds three more; run them too:
@@ -58,7 +58,7 @@ Compute the new version based on user intent and semver rules:
 - **prerelease**: `1.2.3` → `1.2.4-<label>.0`, or `1.2.4-beta.0` → `1.2.4-beta.1`
 - **Removing prerelease tag**: `4.0.3-prerelease` → `4.0.3` (just strip the suffix)
 
-Update `"version"` in `package.json` with the Edit tool, not `pnpm version`: the bump is a plain edit, and the commit, tag and changelog are handled by hand in the steps below.
+Update `"version"` in `package.json` with the Edit tool, not `pnpm version`: the bump is a plain edit, and the commit, tag and changelog are handled by hand in the steps below. Bump `version` in `src/version.js` to the same value (the OpenTelemetry instrumentation scope reads it; `tests/unit/version.test.js` fails while the two differ).
 
 ## Step 3: Update CHANGELOG.md
 
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..3460171
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,7 @@
+# LF everywhere, also on Windows checkouts: MIME output, DKIM canonicalization
+# and the SMTP dot-stuffing tests compare bytes.
+* text=auto eol=lf
+
+# Fixtures compared byte for byte are never converted.
+*.pem -text
+*.eml -text
diff --git a/.oxlintrc.json b/.oxlintrc.json
index e009fde..47f0d88 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -261,7 +261,8 @@
     {
       "files": [
         "scripts/**",
-        "bench/**"
+        "bench/**",
+        "tests/**"
       ],
       "rules": {
         "no-console": "off"
diff --git a/CLAUDE.md b/CLAUDE.md
index 009e9f9..4a8d032 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -60,8 +60,17 @@ is no build step.
   runtime exports with the declared value exports and imports every name from ESM.
   `tests/types/index.test-d.ts` (tsd) pins signatures. `check:dts` needs `--target es2022` because
   there is no tsconfig.
-- `package.json` has a closed `exports` map (`types` first, then `default`) and a `files`
-  allowlist: `index.js`, `index.d.ts`, `src`, README, CHANGELOG, LICENSE and SECURITY.
+- `package.json` has a closed `exports` map (`types` first, then `default`), `sideEffects: false`
+  and a `files` allowlist: `index.js`, `index.d.ts`, `src`, README, CHANGELOG, LICENSE and
+  SECURITY.
+- **Subpaths, not a monorepo.** A subpath is a directory `src/<subpath>/` with an `index.js` that
+  lists its exports by name, an `index.d.ts`, and an entry
+  `"./<subpath>": { "types": "./src/<subpath>/index.d.ts", "default": "./src/<subpath>/index.js" }`
+  in the exports map. The export-parity, bundle and graph tests, `scripts/size.js` and
+  `check:dts` (`scripts/check-dts.js`) read the exports map, so a subpath is checked as soon as
+  it is declared. A subpath's d.ts imports the shared types from `'../../index.js'`.
+  `tests/unit/graph.test.js` keeps `src/` free of require cycles and lets a subpath require
+  another one only along the edges it lists.
 
 ## Zero dependencies: drivers are passed in
 
@@ -78,6 +87,29 @@ There is no `dependencies` or `peerDependencies` key in `package.json`, and ther
 - If a small helper is needed, copy it into `src/` with an attribution header rather than adding a
   dependency.
 
+## Code ported from upyo
+
+Most of the transport layer is a port of [upyo](https://github.com/dahlia/upyo) 0.7.0 (MIT,
+Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo package, with
+`@upyo/core` at the root, `@upyo/opentelemetry` as `./otel`, and `@upyo/logtape` replaced by
+`./logger`, which takes any pino-like logger.
+
+- Every ported file, source or test, starts with the attribution header:
+  ```js
+  // Ported from upyo v0.7.0 (packages/smtp/src/smtp-connection.ts)
+  // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+  ```
+- **The port keeps upstream's behavior.** What changes is the platform: CommonJS and the code
+  style below, `node:crypto` instead of `@noble/hashes`, the OpenTelemetry providers and the
+  logger passed in, fallbacks for runtimes older than Node 22 dropped, and the `@since` tags of
+  upyo versions removed. A known upstream bug is fixed afterwards in its own `fix:` commit with a
+  test that fails without it, not during the port.
+- A lint rule that upstream code breaks is suppressed on the line,
+  `// oxlint-disable-next-line <rule> -- upstream`, rather than rewritten; lifting those is a later
+  refactor, like TS `private` fields, which stay plain properties (the tests reach into them).
+- Ported test suites keep upstream's `describe`/`it`, so they can be compared with upyo's; new
+  suites use the flat style of "Testing notes".
+
 ## Repository layout
 
 ```
@@ -85,11 +117,16 @@ index.js  index.d.ts   root entry shim + hand-written types
 src/
   index.js          public barrel (explicit named exports)
   mailer.js         createMailer placeholder
+  version.js        the package name and version (OpenTelemetry scope), kept equal to package.json
+  <subpath>/        one directory per subpath: index.js + index.d.ts + its modules
 tests/
-  unit/*.test.js    node:test suites, one per area
-  types/*.test-d.ts tsd assertions
+  unit/*.test.js    node:test suites, one per area (<subpath>-<module>.test.js for a subpath)
+  helpers/<sub>/    shared test code of a subpath (fake servers, fixtures builders)
+  fixtures/<sub>/   static fixtures (certificates)
+  types/*.test-d.ts tsd assertions, one file per entry
 scripts/
-  size.js           bundle-size report and budget gate (CI smoke)
+  size.js           bundle-size report and budget gates, one per subpath (CI smoke)
+  check-dts.js      tsc --strict over the d.ts of every entry of the exports map
   comparison.js     renders docs/comparison.json into docs/guide/comparison.md
 bench/              zero-dependency ops/sec harness; baseline.json is a snapshot for --compare
 docs/               VitePress site (mailerat.vercel.app), not published
@@ -231,7 +268,8 @@ change. **This file wins** if they ever disagree.
 ## Testing notes
 
 - Runner: Node's built-in `node:test` + `node:assert`. Suites use flat
-  `test('Area: description', …)`; keep that style.
+  `test('Area: description', …)`; keep that style. The suites ported from upyo are the exception:
+  they keep upstream's `describe`/`it` (see "Code ported from upyo").
 - `pnpm test` passes the glob unquoted (`tests/unit/*.test.js`): the shell expands it on Linux and
   macOS, and Node ≥ 22 expands it itself where cmd.exe does not, so Windows runs every version.
 - `tests/unit/bundle.test.js` builds `index.js` with esbuild in memory (minified and not) and calls
@@ -269,7 +307,8 @@ published to npm, and lint/format do not cover it.
 
 Manual, as in the sibling repositories. The `npm-publish` skill walks through it step by step:
 
-1. Bump `version` in `package.json`.
+1. Bump `version` in `package.json` and in `src/version.js` (`tests/unit/version.test.js` fails
+   while they differ).
 2. Turn `## [Unreleased]` in CHANGELOG.md into `## [X.Y.Z] - YYYY-MM-DD` and add its link
    reference.
 3. Commit, then tag `vX.Y.Z`.
diff --git a/LICENSE b/LICENSE
index 834d88f..40405b4 100644
--- a/LICENSE
+++ b/LICENSE
@@ -19,3 +19,29 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+Portions of this software are derived from Upyo (https://github.com/dahlia/upyo),
+version 0.7.0, which is distributed under the following license:
+
+MIT License
+
+Copyright 2025 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/package.json b/package.json
index 57324be..49633d9 100644
--- a/package.json
+++ b/package.json
@@ -18,6 +18,7 @@
   "packageManager": "pnpm@10.34.5",
   "main": "index.js",
   "types": "index.d.ts",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./index.d.ts",
@@ -43,7 +44,7 @@
     "test": "node --test tests/unit/*.test.js",
     "test:coverage": "c8 --all --include 'src/**' --check-coverage --lines 98 --statements 98 --branches 90 --functions 100 --reporter text --reporter lcov node --test tests/unit/*.test.js",
     "test:types": "tsd",
-    "check:dts": "tsc --noEmit --strict --target es2022 --skipLibCheck false index.d.ts",
+    "check:dts": "node scripts/check-dts.js",
     "lint": "oxlint src tests scripts bench",
     "format": "oxfmt src tests scripts bench",
     "format:check": "oxfmt --check src tests scripts bench",
diff --git a/scripts/check-dts.js b/scripts/check-dts.js
new file mode 100644
index 0000000..3af4205
--- /dev/null
+++ b/scripts/check-dts.js
@@ -0,0 +1,29 @@
+/**
+ * Compiles the hand-written type surface on its own, run with
+ * `pnpm run check:dts`: index.d.ts and the d.ts of every subpath of the
+ * exports map, under `--strict` and without `skipLibCheck`. There is no
+ * tsconfig, hence the explicit target; the d.ts files that need newer library
+ * types (`AsyncDisposable`) reference them with `/// <reference lib>`.
+ */
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+const pkg = require('../package.json');
+
+const ROOT = path.join(__dirname, '..');
+
+const typesOf = (exportsMap) => Object.values(exportsMap).map((entry) => entry.types);
+
+const main = () => {
+  const tsc = path.join(ROOT, 'node_modules/typescript/bin/tsc');
+  const args = ['--noEmit', '--strict', '--target', 'es2022', '--skipLibCheck', 'false'];
+  const result = spawnSync(process.execPath, [tsc, ...args, ...typesOf(pkg.exports)], {
+    cwd: ROOT,
+    stdio: 'inherit',
+  });
+  process.exitCode = result.status ?? 1;
+};
+
+if (require.main === module) main();
+
+module.exports = { typesOf };
diff --git a/scripts/size.js b/scripts/size.js
index f38fab9..ef4bcd8 100644
--- a/scripts/size.js
+++ b/scripts/size.js
@@ -1,13 +1,22 @@
 /**
  * Bundle-size report, run with `pnpm size`. With `--max-gzip <KB>` it also fails
- * when the entry exceeds that min+gzip budget (CI uses it as a gate).
+ * when the root entry exceeds that min+gzip budget, and with
+ * `--max-gzip-<subpath> <KB>` when a subpath of the exports map adds more than
+ * that on top of the root entry (`--max-gzip-smtp` for `./smtp`). CI passes one
+ * flag per subpath as a gate.
  *
- * Bundles the shipped entry point with esbuild the way a consumer's bundler
+ * Bundles the shipped entry points with esbuild the way a consumer's bundler
  * would (a serverless function, a single-file deploy), then reports:
  *   - raw:      bundled, un-minified
  *   - min:      fully minified (whitespace + identifier mangling + syntax)
  *   - min+gzip: the number that matters for cold-start budgets
  *
+ * The subpaths require the core of the root entry (Message, Receipt), so on
+ * their own they would bundle it again; each is measured as the difference
+ * between a bundle of the root entry plus the subpath and the root entry
+ * alone, which is what a consumer that imports both pays for it. A subpath
+ * that requires another one (./smtp requires ./mime) is charged for it.
+ *
  * The package has no runtime dependencies, so a third-party module required
  * from src/ by mistake would be bundled in (devDependencies are installed)
  * and show up here as a jump over the budget, besides failing
@@ -17,14 +26,38 @@
 const { gzipSync } = require('node:zlib');
 const path = require('node:path');
 const esbuild = require('esbuild');
+const pkg = require('../package.json');
 
 const ROOT = path.join(__dirname, '..');
 
-const ENTRIES = [{ label: 'Node entry (index.js)', entry: 'index.js', platform: 'node' }];
+const ENTRY = { label: 'Node entry (index.js)', entry: 'index.js', platform: 'node' };
+
+// One row per subpath of the exports map.
+const subpathsOf = (exportsMap) =>
+  Object.entries(exportsMap)
+    .filter(([subpath]) => subpath !== '.')
+    .map(([subpath, { default: file }]) => {
+      const name = subpath.slice(2);
+      return {
+        label: `${name[0].toUpperCase()}${name.slice(1)} (${subpath}) on top of the Node entry`,
+        entry: ENTRY.entry,
+        platform: ENTRY.platform,
+        subpath: file,
+        flag: `--max-gzip-${name}`,
+      };
+    });
 
-const bundle = async (entry, platform, minify) => {
+const SUBPATHS = subpathsOf(pkg.exports);
+
+// `entry` alone, or `entry` plus subpaths in one bundle, exported so that
+// the bundle keeps them: the package says `sideEffects: false`, and esbuild
+// drops a require whose result nothing uses.
+const bundle = async (entry, platform, minify, subpaths = []) => {
+  let extra = '';
+  for (const subpath of subpaths) extra += `, require('${subpath}')`;
+  const contents = `module.exports = [require('./${entry}')${extra}];`;
   const result = await esbuild.build({
-    entryPoints: [path.join(ROOT, entry)],
+    stdin: { contents, resolveDir: ROOT },
     bundle: true,
     minify,
     platform,
@@ -36,42 +69,67 @@ const bundle = async (entry, platform, minify) => {
 
 const kb = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;
 
-const budget = () => {
+const budget = (flag) => {
   const args = process.argv.slice(2);
-  const index = args.indexOf('--max-gzip');
+  const index = args.indexOf(flag);
   if (index === -1) return null;
   const limit = Number(args[index + 1]);
   if (!Number.isFinite(limit) || limit <= 0) {
-    throw new Error('--max-gzip needs a positive number of kilobytes');
+    throw new Error(`${flag} needs a positive number of kilobytes`);
   }
   return limit * 1024;
 };
 
-const main = async () => {
-  const maxGzip = budget();
-  const rows = [];
-  for (const { label, entry, platform } of ENTRIES) {
-    const raw = await bundle(entry, platform, false);
-    const min = await bundle(entry, platform, true);
-    const gzip = gzipSync(min, { level: 9 });
-    rows.push({ label, raw: raw.length, min: min.length, gzip: gzip.length });
+const measure = async ({ label, entry, platform }, subpaths) => {
+  const raw = await bundle(entry, platform, false, subpaths);
+  const min = await bundle(entry, platform, true, subpaths);
+  const gzip = gzipSync(min, { level: 9 });
+  return { label, raw: raw.length, min: min.length, gzip: gzip.length };
+};
+
+const exceeded = (row, max) => {
+  console.error(`Bundle budget exceeded: ${row.label} is ${kb(row.gzip)} min+gzip, max ${kb(max)}`);
+  process.exitCode = 1;
+};
+
+// The rows of the subpaths: each measured as the difference between the root
+// entry plus the subpath and the root entry alone. `size` and `subpaths` are
+// parameters so that the arithmetic is tested without esbuild.
+const extrasOf = async (core, size = measure, subpaths = SUBPATHS) => {
+  const extras = [];
+  for (const entry of subpaths) {
+    const both = await size(entry, [entry.subpath]);
+    extras.push({
+      label: entry.label,
+      max: budget(entry.flag),
+      raw: both.raw - core.raw,
+      min: both.min - core.min,
+      gzip: both.gzip - core.gzip,
+    });
   }
+  return extras;
+};
+
+const main = async () => {
+  const maxGzip = budget('--max-gzip');
+  const core = await measure(ENTRY);
+  const extras = await extrasOf(core);
   console.log('| Entry | raw | min | min+gzip |');
   console.log('| ----- | ---:| ---:| --------:|');
-  for (const row of rows) {
+  for (const row of [core, ...extras]) {
     console.log(`| ${row.label} | ${kb(row.raw)} | ${kb(row.min)} | ${kb(row.gzip)} |`);
   }
-  if (maxGzip === null) return;
-  const over = rows.filter((row) => row.gzip > maxGzip);
-  for (const row of over) {
-    console.error(
-      `Bundle budget exceeded: ${row.label} is ${kb(row.gzip)} min+gzip, max ${kb(maxGzip)}`,
-    );
+  if (maxGzip !== null && core.gzip > maxGzip) exceeded(core, maxGzip);
+  for (const row of extras) {
+    if (row.max !== null && row.gzip > row.max) exceeded(row, row.max);
   }
-  if (over.length > 0) process.exitCode = 1;
 };
 
-main().catch((error) => {
-  console.error(error);
-  process.exitCode = 1;
-});
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { SUBPATHS, subpathsOf, extrasOf };
diff --git a/src/version.js b/src/version.js
new file mode 100644
index 0000000..d7c9319
--- /dev/null
+++ b/src/version.js
@@ -0,0 +1,5 @@
+// The package's own name and version, for the instrumentation scope of the
+// OpenTelemetry tracer and meter: a relative require of package.json would
+// bundle the whole manifest into ./otel. tests/unit/version.test.js keeps it
+// equal to package.json, and the release process bumps both.
+module.exports = { name: '@alexify/mailer', version: '0.0.1' };
diff --git a/tests/unit/bundle.test.js b/tests/unit/bundle.test.js
index 5e48dee..677f2b4 100644
--- a/tests/unit/bundle.test.js
+++ b/tests/unit/bundle.test.js
@@ -3,16 +3,16 @@ const assert = require('node:assert');
 const path = require('node:path');
 const vm = require('node:vm');
 const esbuild = require('esbuild');
+const pkg = require('../../package.json');
 
 const ROOT = path.join(__dirname, '../..');
 
-// Loads the entry point the way a consumer's bundler would (a serverless
-// function, a single-file deploy), minified and not, and calls the API
-// through the result: the shipped files must work after bundling, not only
-// when required from source.
-const loadNode = async (minify) => {
+// Loads an entry point the way a consumer's bundler would (a serverless
+// function, a single-file deploy), minified and not: the shipped files must
+// work after bundling, not only when required from source.
+const loadNode = async (entry, minify) => {
   const result = await esbuild.build({
-    entryPoints: [path.join(ROOT, 'index.js')],
+    entryPoints: [path.join(ROOT, entry)],
     bundle: true,
     write: false,
     logLevel: 'silent',
@@ -29,8 +29,22 @@ const loadNode = async (minify) => {
 for (const minify of [false, true]) {
   const label = minify ? 'minified' : 'unminified';
   test(`Bundle: node entry, ${label}`, async () => {
-    const { createMailer } = await loadNode(minify);
+    const { createMailer } = await loadNode('index.js', minify);
     assert.strictEqual(typeof createMailer, 'function');
     assert.throws(() => createMailer({}), { message: 'createMailer is not implemented yet' });
   });
+
+  // Every entry of the exports map bundles on its own and keeps the names and
+  // the kinds of its exports: a require the bundler cannot follow, or a module
+  // that fails while it loads, shows up here.
+  for (const { default: file } of Object.values(pkg.exports)) {
+    test(`Bundle: ${file}, ${label}`, async () => {
+      const bundled = await loadNode(file, minify);
+      const source = require(path.join(ROOT, file));
+      assert.deepStrictEqual(Object.keys(bundled), Object.keys(source));
+      for (const name of Object.keys(source)) {
+        assert.strictEqual(typeof bundled[name], typeof source[name], name);
+      }
+    });
+  }
 }
diff --git a/tests/unit/export-parity.test.js b/tests/unit/export-parity.test.js
index 9909481..f298fde 100644
--- a/tests/unit/export-parity.test.js
+++ b/tests/unit/export-parity.test.js
@@ -3,12 +3,14 @@ const assert = require('node:assert');
 const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
+const pkg = require('../../package.json');
 
 const ROOT = path.join(__dirname, '../..');
 
-// index.d.ts is written by hand: every runtime export must be declared in it,
-// and every declared value export must exist at runtime. `export type` and
-// `export interface` have no runtime counterpart and are not compared.
+// The d.ts files are written by hand: every runtime export must be declared
+// in them, and every declared value export must exist at runtime.
+// `export type` and `export interface` have no runtime counterpart and are
+// not compared.
 const declaredValueExports = (dtsFile) => {
   const source = fs.readFileSync(path.join(ROOT, dtsFile), 'utf8');
   const pattern = /^export (?:declare )?(?:abstract )?(?:class|function|const|let|var) ([\w$]+)/gm;
@@ -17,24 +19,43 @@ const declaredValueExports = (dtsFile) => {
   return names;
 };
 
-test('Exports: index.js matches index.d.ts', () => {
-  const runtime = new Set(Object.keys(require(path.join(ROOT, 'index.js'))));
-  const declared = declaredValueExports('index.d.ts');
-  const undeclared = [...runtime].filter((name) => !declared.has(name)).sort();
-  const phantom = [...declared].filter((name) => !runtime.has(name)).sort();
-  assert.deepStrictEqual(undeclared, [], 'missing from index.d.ts');
-  assert.deepStrictEqual(phantom, [], 'absent from index.js at runtime');
-});
+// Every entry of the closed exports map, `.` and each subpath: what a
+// consumer imports, so a subpath is checked as soon as it is declared.
+const entryPoints = Object.entries(pkg.exports).map(([subpath, { types, default: file }]) => ({
+  specifier: subpath === '.' ? pkg.name : `${pkg.name}/${subpath.slice(2)}`,
+  runtimeFile: file,
+  dtsFile: types,
+}));
 
-test('Exports: named imports work from ESM', () => {
-  const names = [...declaredValueExports('index.d.ts')].sort();
-  const source = [
-    `import { ${names.join(', ')} } from '@alexify/mailer';`,
-    `const values = { ${names.join(', ')} };`,
-    'const missing = Object.keys(values).filter((name) => values[name] === undefined);',
-    'process.stdout.write(JSON.stringify(missing));',
-  ].join('\n');
-  const args = ['--input-type=module', '-e', source];
-  const output = execFileSync(process.execPath, args, { cwd: ROOT, encoding: 'utf8' });
-  assert.deepStrictEqual(JSON.parse(output), []);
+test('Exports: the exports map lists types first, then default', () => {
+  assert.ok(entryPoints.length > 0);
+  for (const entry of Object.values(pkg.exports)) {
+    assert.deepStrictEqual(Object.keys(entry), ['types', 'default']);
+  }
 });
+
+for (const { specifier, runtimeFile, dtsFile } of entryPoints) {
+  test(`Exports: ${runtimeFile} matches ${dtsFile}`, () => {
+    const runtime = new Set(Object.keys(require(path.join(ROOT, runtimeFile))));
+    const declared = declaredValueExports(dtsFile);
+    const undeclared = [...runtime].filter((name) => !declared.has(name)).sort();
+    const phantom = [...declared].filter((name) => !runtime.has(name)).sort();
+    assert.ok(runtime.size > 0, `${runtimeFile} exports nothing`);
+    assert.deepStrictEqual(undeclared, [], `missing from ${dtsFile}`);
+    assert.deepStrictEqual(phantom, [], `absent from ${runtimeFile} at runtime`);
+  });
+
+  test(`Exports: ${specifier} resolves to ${runtimeFile} and imports by name from ESM`, () => {
+    assert.strictEqual(require(specifier), require(path.join(ROOT, runtimeFile)));
+    const names = [...declaredValueExports(dtsFile)].sort();
+    const source = [
+      `import { ${names.join(', ')} } from '${specifier}';`,
+      `const values = { ${names.join(', ')} };`,
+      'const missing = Object.keys(values).filter((name) => values[name] === undefined);',
+      'process.stdout.write(JSON.stringify(missing));',
+    ].join('\n');
+    const args = ['--input-type=module', '-e', source];
+    const output = execFileSync(process.execPath, args, { cwd: ROOT, encoding: 'utf8' });
+    assert.deepStrictEqual(JSON.parse(output), []);
+  });
+}
diff --git a/tests/unit/graph.test.js b/tests/unit/graph.test.js
new file mode 100644
index 0000000..c68bdca
--- /dev/null
+++ b/tests/unit/graph.test.js
@@ -0,0 +1,103 @@
+// The module graph of src/ has no cycles: a module that requires, through
+// the requires of what it requires, a module still being loaded would get a
+// partial module object. And a program that imports one subpath carries no
+// other, except along the edges allowed below.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const pkg = require('../../package.json');
+
+const SRC = path.join(__dirname, '../../src');
+const REQUIRE = /require\('(\.{1,2}\/[^']+)'\)/g;
+
+const modulesOf = (dir, out = []) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) modulesOf(full, out);
+    else if (entry.name.endsWith('.js')) out.push(full);
+  }
+  return out;
+};
+
+const edgesOf = (file) => {
+  const source = fs.readFileSync(file, 'utf8');
+  const targets = [];
+  for (const match of source.matchAll(REQUIRE)) {
+    targets.push(path.resolve(path.dirname(file), match[1]));
+  }
+  return targets;
+};
+
+// POSIX separators on every platform, so the names compare the same on
+// Windows, where path.relative joins with a backslash.
+const relative = (file) => path.relative(SRC, file).split(path.sep).join('/');
+
+// Every cycle of the graph, as the path that closes it.
+const cyclesOf = (graph) => {
+  const VISITING = 1;
+  const DONE = 2;
+  const state = new Map();
+  const stack = [];
+  const cycles = [];
+  const visit = (file) => {
+    const seen = state.get(file);
+    if (seen === DONE) return;
+    if (seen === VISITING) {
+      cycles.push([...stack.slice(stack.indexOf(file)), file].map(relative).join(' -> '));
+      return;
+    }
+    state.set(file, VISITING);
+    stack.push(file);
+    for (const target of graph.get(file)) {
+      assert.ok(graph.has(target), `${relative(file)} requires ${target}, not a module of src/`);
+      visit(target);
+    }
+    stack.pop();
+    state.set(file, DONE);
+  };
+  for (const file of graph.keys()) visit(file);
+  return cycles;
+};
+
+test('Graph: the modules of src/ require each other without a cycle', () => {
+  const graph = new Map();
+  for (const file of modulesOf(SRC)) graph.set(file, edgesOf(file));
+  assert.ok(graph.size > 0);
+  assert.deepStrictEqual(cyclesOf(graph), []);
+  // The check sees a cycle when there is one.
+  const a = path.join(SRC, 'a.js');
+  const b = path.join(SRC, 'b.js');
+  const looped = new Map([
+    [a, [b]],
+    [b, [a]],
+  ]);
+  assert.deepStrictEqual(cyclesOf(looped), ['a.js -> b.js -> a.js']);
+});
+
+// The directories of the subpaths, from the exports map: `./smtp` lives in
+// src/smtp/. Everything else (src/*.js, src/core/) is the root entry, which
+// requires no subpath.
+const SUBPATHS = Object.keys(pkg.exports)
+  .filter((subpath) => subpath !== '.')
+  .map((subpath) => pkg.exports[subpath].default.split('/')[2]);
+const SUBPATH_EDGES = [];
+
+const subpathOf = (name) => {
+  const top = name.split('/')[0];
+  return SUBPATHS.includes(top) ? top : null;
+};
+
+test('Graph: the root requires no subpath, a subpath another only where allowed', () => {
+  const crossings = [];
+  for (const file of modulesOf(SRC)) {
+    const from = relative(file);
+    for (const target of edgesOf(file)) {
+      const to = relative(target);
+      const source = subpathOf(from);
+      const destination = subpathOf(to);
+      if (destination !== null && destination !== source) crossings.push(`${from} -> ${to}`);
+    }
+  }
+  assert.deepStrictEqual(crossings.sort(), [...SUBPATH_EDGES].sort());
+});
diff --git a/tests/unit/scripts.test.js b/tests/unit/scripts.test.js
index 8027a51..23b0bea 100644
--- a/tests/unit/scripts.test.js
+++ b/tests/unit/scripts.test.js
@@ -2,22 +2,74 @@ const { test } = require('node:test');
 const assert = require('node:assert');
 const { spawnSync } = require('node:child_process');
 const path = require('node:path');
+const pkg = require('../../package.json');
 
 const ROOT = path.join(__dirname, '../..');
 
 const run = (script, args) =>
   spawnSync(process.execPath, [path.join(ROOT, script), ...args], { cwd: ROOT, encoding: 'utf8' });
 
-test('Scripts: size reports the entry and enforces the gzip budget', () => {
-  const ok = run('scripts/size.js', ['--max-gzip', '100']);
+test('Scripts: a subpath is measured on top of the root entry', async () => {
+  const { subpathsOf, extrasOf } = require('../../scripts/size.js');
+  const subpaths = subpathsOf({
+    '.': { types: './index.d.ts', default: './index.js' },
+    './smtp': { types: './src/smtp/index.d.ts', default: './src/smtp/index.js' },
+    './mime': { types: './src/mime/index.d.ts', default: './src/mime/index.js' },
+  });
+  assert.deepStrictEqual(
+    subpaths.map(({ label, subpath, flag }) => [label, subpath, flag]),
+    [
+      ['Smtp (./smtp) on top of the Node entry', './src/smtp/index.js', '--max-gzip-smtp'],
+      ['Mime (./mime) on top of the Node entry', './src/mime/index.js', '--max-gzip-mime'],
+    ],
+  );
+  // A fake measure: a size per subpath in the bundle, over a core of 1000.
+  const sizes = { './src/smtp/index.js': 400, './src/mime/index.js': 70 };
+  const size = (entry, list) => {
+    let total = 1000;
+    for (const subpath of list) total += sizes[subpath];
+    return { label: entry.label, raw: total * 3, min: total * 2, gzip: total };
+  };
+  const core = { label: 'core', raw: 3000, min: 2000, gzip: 1000 };
+  const extras = await extrasOf(core, size, subpaths);
+  assert.deepStrictEqual(
+    extras.map(({ gzip, min, raw, max }) => [gzip, min, raw, max]),
+    [
+      [400, 800, 1200, null],
+      [70, 140, 210, null],
+    ],
+  );
+});
+
+test('Scripts: size reports the entries and enforces the gzip budgets', () => {
+  const { SUBPATHS } = require('../../scripts/size.js');
+  const budgets = ['--max-gzip', '100'];
+  for (const { flag } of SUBPATHS) budgets.push(flag, '100');
+  const ok = run('scripts/size.js', budgets);
   assert.strictEqual(ok.status, 0, ok.stderr);
   assert.match(ok.stdout, /\| Node entry \(index\.js\) \|/);
+  for (const { label } of SUBPATHS) assert.ok(ok.stdout.includes(`| ${label} |`), label);
 
   const over = run('scripts/size.js', ['--max-gzip', '0.01']);
   assert.strictEqual(over.status, 1);
   assert.match(over.stderr, /Bundle budget exceeded: Node entry/);
 
+  for (const { flag, label } of SUBPATHS) {
+    const subpathOver = run('scripts/size.js', [flag, '0.01']);
+    assert.strictEqual(subpathOver.status, 1, flag);
+    assert.ok(subpathOver.stderr.includes(`Bundle budget exceeded: ${label}`), flag);
+  }
+
   const bad = run('scripts/size.js', ['--max-gzip', 'lots']);
   assert.strictEqual(bad.status, 1);
   assert.match(bad.stderr, /positive number of kilobytes/);
 });
+
+test('Scripts: check-dts compiles the types of every entry of the exports map', () => {
+  const { typesOf } = require('../../scripts/check-dts.js');
+  assert.deepStrictEqual(
+    typesOf(pkg.exports),
+    Object.values(pkg.exports).map((entry) => entry.types),
+  );
+  assert.strictEqual(typesOf(pkg.exports)[0], './index.d.ts');
+});
diff --git a/tests/unit/version.test.js b/tests/unit/version.test.js
new file mode 100644
index 0000000..8843dd3
--- /dev/null
+++ b/tests/unit/version.test.js
@@ -0,0 +1,8 @@
+const { test } = require('node:test');
+const assert = require('node:assert');
+const pkg = require('../../package.json');
+const version = require('../../src/version.js');
+
+test('Version: src/version.js matches package.json', () => {
+  assert.deepStrictEqual(version, { name: pkg.name, version: pkg.version });
+});

From a558ce2174eec4fd56fba62599676e132f99571e Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 20:46:35 +0300
Subject: [PATCH 002/158] feat(core): port the message model and the transport
 contract from upyo 0.7.0

The root entry now exports @upyo/core: createMessage and the Message,
Address and Attachment model, the Transport, RawTransport and
VerifiableTransport contract, Receipt and its error classification,
Message-ID and threading helpers, the iCalendar part and the raw-message
plan. The modules live in src/core/, the types in index.d.ts, next to the
createMailer placeholder.

The code is upstream's, converted to CommonJS: the only changes are the
fallbacks for runtimes without AbortSignal.any or Blob, which Node 22 always
has. Upstream's suites are ported as they are; tests/unit/core.test.js covers
the paths they leave out, and the root size budget goes to 7 KB.

CLAUDE.md describes the ported architecture, revises the decisions on the
transport and the providers, and lists the upstream bugs to fix after the
port.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/npm-publish/SKILL.md   |    4 +-
 .github/workflows/ci.yml              |    2 +-
 CLAUDE.md                             |   76 +-
 index.d.ts                            | 1213 ++++++++++++++++++++++++-
 src/core/abort-signal.js              |   25 +
 src/core/address.js                   |  247 +++++
 src/core/attachment.js                |  187 ++++
 src/core/calendar.js                  |  411 +++++++++
 src/core/message-id.js                |  300 ++++++
 src/core/message.js                   |  192 ++++
 src/core/priority.js                  |   25 +
 src/core/raw-message.js               |  192 ++++
 src/core/receipt.js                   |  253 ++++++
 src/core/transport.js                 |   22 +
 src/index.js                          |   67 +-
 tests/types/index.test-d.ts           |   69 +-
 tests/unit/abort-signal.test.js       |   42 +
 tests/unit/address.test.js            |  324 +++++++
 tests/unit/attachment-content.test.js |  139 +++
 tests/unit/attachment.test.js         |  177 ++++
 tests/unit/calendar.test.js           |  591 ++++++++++++
 tests/unit/core.test.js               |  201 ++++
 tests/unit/message-id.test.js         |  212 +++++
 tests/unit/message.test.js            |  629 +++++++++++++
 tests/unit/priority.test.js           |   20 +
 tests/unit/raw-message.test.js        |  204 +++++
 tests/unit/receipt.test.js            |  257 ++++++
 tests/unit/transport.test.js          |   28 +
 28 files changed, 6084 insertions(+), 25 deletions(-)
 create mode 100644 src/core/abort-signal.js
 create mode 100644 src/core/address.js
 create mode 100644 src/core/attachment.js
 create mode 100644 src/core/calendar.js
 create mode 100644 src/core/message-id.js
 create mode 100644 src/core/message.js
 create mode 100644 src/core/priority.js
 create mode 100644 src/core/raw-message.js
 create mode 100644 src/core/receipt.js
 create mode 100644 src/core/transport.js
 create mode 100644 tests/unit/abort-signal.test.js
 create mode 100644 tests/unit/address.test.js
 create mode 100644 tests/unit/attachment-content.test.js
 create mode 100644 tests/unit/attachment.test.js
 create mode 100644 tests/unit/calendar.test.js
 create mode 100644 tests/unit/core.test.js
 create mode 100644 tests/unit/message-id.test.js
 create mode 100644 tests/unit/message.test.js
 create mode 100644 tests/unit/priority.test.js
 create mode 100644 tests/unit/raw-message.test.js
 create mode 100644 tests/unit/receipt.test.js
 create mode 100644 tests/unit/transport.test.js

diff --git a/.claude/skills/npm-publish/SKILL.md b/.claude/skills/npm-publish/SKILL.md
index acdb27d..20b277a 100644
--- a/.claude/skills/npm-publish/SKILL.md
+++ b/.claude/skills/npm-publish/SKILL.md
@@ -37,7 +37,7 @@ pnpm run check:dts               # tsc over the d.ts of every entry of the expor
 These are the same gates `prepublishOnly` runs. CI adds three more; run them too:
 
 ```bash
-pnpm size --max-gzip 4                                           # the bundle budget
+pnpm size --max-gzip 7                                           # the bundle budget
 pnpm docs:comparison && git diff --exit-code docs/guide/comparison.md   # the table matches docs/comparison.json
 pnpm run docs:build                                              # the docs site; a dead link fails it
 ```
@@ -180,7 +180,7 @@ Report the file count and the bundle size from `pnpm run size` to the user.
 Run the gates one more time after all edits:
 
 ```bash
-pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts && pnpm size --max-gzip 4 && pnpm run docs:build
+pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts && pnpm size --max-gzip 7 && pnpm run docs:build
 ```
 
 Must exit 0. If it fails, fix and re-run.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 72c221d..ab2430a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 4
+      - run: pnpm size --max-gzip 7
 
   types:
     runs-on: ubuntu-latest
diff --git a/CLAUDE.md b/CLAUDE.md
index 4a8d032..a58682a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,17 +7,20 @@ Guidance for Claude Code when working in this repository.
 **mailer** (npm package `@alexify/mailer`) is an email library for Node.js, in the place of
 Nodemailer, emailjs or Upyo, made of two parts:
 
-1. **The transport:** its own SMTP client, MIME builder and DKIM signing, and HTTP providers on
-   `fetch`, starting with Amazon SES v2.
+1. **The transport,** ported from upyo 0.7.0 (see "Code ported from upyo"): the message model,
+   its own SMTP client, MIME builder and DKIM signing, Amazon SES v2 and seven more HTTP providers
+   on `fetch`, JMAP, and the pool, retry, mock, OpenTelemetry and logger decorators, one subpath
+   each.
 2. **A reliability layer on top of it,** which none of the fourteen libraries in
    `docs/comparison.json` has: a persistent queue and outbox, an append-only audit log, one model
    of delivery events, suppression, idempotency and failover between providers.
 
 It has zero runtime dependencies and runs on Node.js ≥ 22 only (no browser entry).
 
-**Status: the API is being designed.** `createMailer` is exported as a placeholder that throws
-(`src/mailer.js`); its signature in `index.d.ts` is provisional. The package, its tooling, tests and
-docs are already wired around that name. The direction is in "Roadmap" below.
+**Status: the transport is being ported, the mailer designed.** The root entry exports the message
+model and the transport contract of upyo; the subpaths land one by one. `createMailer`, the entry of
+the reliability layer, is a placeholder that throws (`src/mailer.js`); its signature in
+`index.d.ts` is provisional. The direction is in "Roadmap" below.
 
 It is maintained by Alexis Technologies and set up like the sibling libraries
 `@alexify/metaschema` and `@alexify/protoarray` (the scaffold follows protoarray's
@@ -37,7 +40,7 @@ pnpm run test:types                # tsd: tests/types/*.test-d.ts against index.
 pnpm run check:dts                 # tsc --noEmit --strict over index.d.ts on its own
 pnpm run lint                      # oxlint src tests scripts bench
 pnpm run format                    # oxfmt src tests scripts bench (format:check in CI)
-pnpm size [--max-gzip <KB>]        # esbuild bundle size of index.js; CI gates at 4 KB min+gzip
+pnpm size [--max-gzip <KB>]        # esbuild bundle sizes; CI gates the root at 7 KB min+gzip and each subpath
 pnpm bench [filter] [--json] [--save] [--compare]   # ops/sec harness, manual only; --save writes bench/baseline.json
 pnpm docs:comparison               # renders docs/comparison.json into docs/guide/comparison.md
 pnpm run docs:dev                  # VitePress dev server for docs/ (docs:build, docs:preview)
@@ -108,7 +111,29 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
   `// oxlint-disable-next-line <rule> -- upstream`, rather than rewritten; lifting those is a later
   refactor, like TS `private` fields, which stay plain properties (the tests reach into them).
 - Ported test suites keep upstream's `describe`/`it`, so they can be compared with upyo's; new
-  suites use the flat style of "Testing notes".
+  suites use the flat style of "Testing notes". Tests for paths that upstream's suites leave out go
+  into a new flat suite (`tests/unit/core.test.js` for `src/core/`).
+
+**Known upstream bugs, each to fix in its own `fix:` commit after the port:**
+
+1. mime: inline images (`contentId`) go into `multipart/mixed`, not `multipart/related`.
+2. mailgun: an inline attachment is sent under its `filename`, not its `contentId`
+   (`message-converter.js`), so a `cid:` in the HTML does not match it.
+3. `validateSsl` is accepted and never read (ses, resend, sendgrid, mailgun, mailtrap, plunk).
+4. SMTP AUTH PLAIN and LOGIN encode with `btoa`, which fails on non-Latin-1 credentials; so does
+   Basic auth in jmap and mailgun.
+5. `cram-md5` is in the `SmtpAuth` type but not implemented.
+6. DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails.
+7. pool: `continueOnSuccess` is never read.
+8. otel: `_active_sends` is not decremented after `sendMany` and drifts under sampling;
+   `durationBuckets` and `auto` are ignored; `recordRetry` is never called; `sendMany` buffers
+   its whole input; `defaultErrorClassifier` matches `"auth"` as a substring.
+9. resend, plunk: the sleep between retries ignores the `AbortSignal`; ses, resend, sendgrid,
+   mailgun and plunk parse `Retry-After` but do not wait for it.
+10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
+11. resend: the `Idempotency-Key` comes from `Math.random`.
+12. `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of `process.emitWarning` or
+    an injected logger.
 
 ## Repository layout
 
@@ -136,13 +161,25 @@ docs/               VitePress site (mailerat.vercel.app), not published
 
 ## Architecture
 
-To be written with Phase 0. The contracts it starts from:
+The root entry is the contract every subpath shares, ported from `@upyo/core` (`src/core/`):
+
+- **`Message`**, built by `createMessage()`, which parses and validates the addresses (CR and LF
+  are rejected), the attachments, the Message-ID and the threading headers, the date and an
+  iCalendar part. `Address`, `Attachment` (bytes, a `Promise`, a `Blob` or a factory of chunks)
+  and `Priority` go with it.
+- **`Transport<TProviderId>`**: `send(message, { signal }) → Receipt` and
+  `sendMany(messages) → AsyncIterable<Receipt>`. `RawTransport` adds `sendRaw()` for a ready MIME
+  message (`RawMessage`, checked by `createRawMessagePlan`), `VerifiableTransport` adds
+  `verify()`.
+- **`Receipt`**: `{ successful: true, messageId }` or
+  `{ successful: false, errorMessages, errors, retryable }`. A `ReceiptError` carries a `category`
+  (auth, rate-limit, network, timeout, validation, rejected, server-error, service-unavailable,
+  configuration, unknown), `retryable`, `statusCode` and `retryAfterMilliseconds`;
+  `classifyHttpStatus` and `classifyReceiptError` classify. A transport reports a failure in a
+  receipt rather than by throwing.
+
+The contracts of the reliability layer, still to be designed (Phase 0):
 
-- **`Message`** with a typed builder that rejects CRLF in every header field, and the MIME
-  rendering of it (`multipart/alternative`, `multipart/mixed`, `multipart/related` for inline
-  images, RFC 2047/2231 encoding, SMTPUTF8).
-- **`Transport`**: `send(rendered) → { messageId, accepted, rejected }` or a classified error
-  (permanent, temporary, ambiguous). SMTP and the HTTP providers implement it.
 - **`QueueDriver`**: enqueue, reserve, ack, retry with a delay; drivers for an outbox in MongoDB,
   BullMQ and an in-memory one for tests.
 - **`AuditSink`**: append-only records of state changes; sinks for MongoDB, stdout/OTel logs and a
@@ -196,12 +233,15 @@ optional React Email adapter (no template engine of its own); more providers.
 
 **Decisions:**
 
-- **The transport is our own, not a wrapper over Nodemailer.** The comparison advises against
-  rewriting SMTP (Nodemailer has 15 years of edge cases); the product needs the transport and the
-  layers designed together, so the risk is paid for by the correctness suite in Phase 1.
+- **The transport is ported from upyo, not a wrapper over Nodemailer.** The comparison advises
+  against rewriting SMTP (Nodemailer has 15 years of edge cases). Upyo already has the transport
+  this roadmap planned, on the same platform (zero dependencies, `node:net`, `fetch`), so it is
+  ported file by file instead of written anew; its known bugs are fixed afterwards (see "Code
+  ported from upyo"), and the correctness suite of Phase 1 still applies to it.
 - **BullMQ is one driver, not the base:** it ties the queue to Redis/Valkey; the MongoDB outbox
   gives a queue with no new infrastructure.
-- **Few providers, done well.** Each provider adds its webhooks and API drift to maintain.
+- **Few new providers.** The eight HTTP providers of upyo come with the port. Each provider adds
+  its webhooks and API drift to maintain, so another one waits for a user who needs it.
 
 **What the competitors appear to get wrong, to not repeat** (findings from reading their code in
 October 2026, not reproduced except for emailjs, which was run against fake SMTP servers): no
@@ -211,7 +251,7 @@ Bcc in the headers of the message (worker-mailer); relaxed body canonicalization
 every empty line instead of the trailing ones (sently); retrying permanent SMTP 5xx (sently);
 inline images in `multipart/mixed` instead of `multipart/related` (Upyo, unemail); options
 accepted but never read (Upyo `validateSsl`); no CRLF sanitization and `os.EOL` instead of CRLF
-(MIMEText).
+(MIMEText). The Upyo ones came with the port and are on the list of "Code ported from upyo".
 
 **Out of scope:** SMS, WhatsApp and push (a `Channel` interface may stay, implementations no);
 inbound mail; the management APIs of the providers (domains, templates, statistics), which the
diff --git a/index.d.ts b/index.d.ts
index d9dd3d9..9f5ce4f 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -1,3 +1,1214 @@
+// The types of @alexify/mailer, written by hand: the message model and the
+// transport contract (src/core/) are ported from @upyo/core 0.7.0
+// (https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee).
+
+/**
+ * A type alias for email address strings that must contain an @ symbol.
+ */
+export type EmailAddress = `${string}@${string}`;
+/**
+ * A pair of name (which is optional) and email address.
+ */
+export interface Address {
+  /**
+   * The name of the person or entity associated with the email address.
+   */
+  readonly name?: string;
+  /**
+   * The email address itself.
+   */
+  readonly address: EmailAddress;
+}
+/**
+ * Formats an address object into a string representation.  This function is
+ * an inverse of the {@link parseAddress} function.
+ *
+ * @example Formatting an address with a name
+ * ```ts
+ * import { type Address, formatAddress } from "@alexify/mailer/address";
+ * const address: Address = { name: "John Doe", address: "john@example.com" };
+ * console.log(formatAddress(address)); // "John Doe <john@example.com>"
+ * ```
+ *
+ * @example Formatting an address without a name
+ * ```ts
+ * import { type Address, formatAddress } from "@alexify/mailer/address";
+ * const address: Address = { address: "jane@examle.com" };
+ * console.log(formatAddress(address)); // "jane@example.com"
+ * ```
+ *
+ * @param address The address object to format.
+ * @return A string representation of the address.
+ */
+export declare function formatAddress(address: Address): string;
+/**
+ * Parses a string representation of an email address into an {@link Address}
+ * object.  This function is an inverse of the {@link formatAddress} function.
+ *
+ * @example Parsing an address with a name
+ * ```ts
+ * import { parseAddress } from "@alexify/mailer/address";
+ * const address = parseAddress("John Doe <john@example.com>");
+ * console.log(address); // { name: "John Doe", address: "john@example.com" }
+ * ```
+ *
+ * @example Parsing an address without a name
+ * ```ts
+ * import { parseAddress } from "@alexify/mailer/address";
+ * const address = parseAddress("jane@example.com");
+ * console.log(address); // { address: "jane@example.com" }
+ * ```
+ *
+ * @example Trying to parse an invalid address
+ * ```ts
+ * import { parseAddress } from "@alexify/mailer/address";
+ * const address = parseAddress("invalid-email");
+ * console.log(address); // undefined
+ * ```
+ *
+ * @param address The string representation of the address to parse.
+ * @returns An {@link Address} object if the parsing is successful,
+ *          or `undefined` if the input is invalid.
+ */
+export declare function parseAddress(address: string): Address | undefined;
+/**
+ * Type guard function that checks if a given value is a valid email address.
+ *
+ * @example
+ * ```ts
+ * import { isEmailAddress } from "@alexify/mailer/address";
+ *
+ * const userInput = "user@example.com";
+ * if (isEmailAddress(userInput)) {
+ *   // TypeScript now knows userInput is EmailAddress type
+ *   console.log(userInput); // Type: `${string}@${string}`
+ * }
+ * ```
+ *
+ * @param email The value to check
+ * @returns `true` if the value is a valid email address, `false` otherwise
+ */
+export declare function isEmailAddress(email: unknown): email is EmailAddress;
+
+/**
+ * Result of combining abort signals.
+ */
+export interface CombinedSignal {
+  /**
+   * The signal that aborts when any input signal aborts.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Releases what the composition holds; a no-op with `AbortSignal.any()`, kept so
+   * that callers can always call it.
+   */
+  cleanup(): void;
+}
+/**
+ * Combines a primary abort signal with an optional external signal.
+ *
+ * The returned signal aborts as soon as either input signal aborts, with the
+ * reason of the signal that aborted first (`AbortSignal.any()`).
+ *
+ * @param primarySignal The signal owned by the current operation.
+ * @param externalSignal Optional caller-supplied signal to compose.
+ * @returns A combined signal and cleanup callback.
+ */
+export declare function combineSignals(
+  primarySignal: AbortSignal,
+  externalSignal?: AbortSignal | null,
+): CombinedSignal;
+
+/**
+ * Opens a fresh, independent attachment reader on every invocation. Readers
+ * must produce identical bytes for retries, concurrent sends, and DKIM passes.
+ * A yielded chunk must remain valid until the next read. Factories should honor
+ * the signal during acquisition and release resources when iteration ends.
+ * @param signal Cancellation signal owned by the reader.
+ * @returns A new iterable, optionally acquired asynchronously.
+ */
+export type AttachmentContentFactory = (
+  signal?: AbortSignal,
+) => AsyncIterable<Uint8Array> | Promise<AsyncIterable<Uint8Array>>;
+/**
+ * Replayable attachment bytes. One-shot iterables are intentionally excluded;
+ * wrap them in a factory that opens a new reader for each invocation.
+ */
+export type AttachmentContent = Uint8Array | Promise<Uint8Array> | Blob | AttachmentContentFactory;
+/**
+ * Represents an attachment in an email message.
+ */
+export interface Attachment {
+  /**
+   * Whether the attachment is intended to be used for inline images.
+   */
+  readonly inline: boolean;
+  /**
+   * The filename of the attachment, which is used for display purposes
+   * and may not be the actual name of the file on disk.
+   */
+  readonly filename: string;
+  /**
+   * Replayable attachment content. Use {@link readAttachmentContent} to collect
+   * bytes or {@link iterateAttachmentContent} to read them incrementally.
+   */
+  readonly content: AttachmentContent;
+  /**
+   * The media type of the attachment, which indicates the type of content
+   * and how it should be handled by email clients.
+   */
+  readonly contentType: `${string}/${string}`;
+  /**
+   * The content ID of the attachment, which is used to reference
+   * inline images in HTML emails.
+   */
+  readonly contentId: string;
+}
+/**
+ * Checks if the provided value is an {@link Attachment} object.
+ * @param attachment The value to check.
+ * @return `true` if the value is an {@link Attachment}, otherwise `false`.
+ */
+export declare function isAttachment(attachment: unknown): attachment is Attachment;
+/**
+ * Reads attachment chunks without prefetching. Early exit or cancellation
+ * aborts the source and requests cleanup without waiting for an uncooperative
+ * producer. Producers remain responsible for honoring cancellation.
+ * @param content Replayable content to read.
+ * @param signal Optional cancellation signal.
+ * @returns An iterable of byte chunks, valid until the next read.
+ * @throws {TypeError} If a source or yielded chunk is invalid.
+ * @throws {Error} If reading fails or cancellation is requested.
+ */
+export declare function iterateAttachmentContent(
+  content: AttachmentContent,
+  signal?: AbortSignal,
+): AsyncIterable<Uint8Array>;
+/**
+ * Collects an attachment in memory. Existing arrays retain their identity;
+ * streamed chunks are copied before the producer can reuse their storage.
+ * @param content Replayable content to collect.
+ * @param signal Optional cancellation signal.
+ * @returns The complete attachment bytes.
+ * @throws {TypeError} If a source or yielded chunk is invalid.
+ * @throws {RangeError} If the attachment cannot fit in a byte array.
+ * @throws {Error} If reading fails or cancellation is requested.
+ */
+export declare function readAttachmentContent(
+  content: AttachmentContent,
+  signal?: AbortSignal,
+): Promise<Uint8Array>;
+
+/**
+ * An iTIP method, naming what a scheduling message does.
+ *
+ * These are the methods registered by RFC 5546 §1.4.  A method written as an
+ * `x-name` or as an unregistered IANA token is rejected rather than passed
+ * through, because the value is written into a `Content-Type` parameter and has
+ * to agree with the calendar object that carries it.
+ */
+export type CalendarMethod =
+  | 'PUBLISH'
+  | 'REQUEST'
+  | 'REPLY'
+  | 'ADD'
+  | 'CANCEL'
+  | 'REFRESH'
+  | 'COUNTER'
+  | 'DECLINECOUNTER';
+/**
+ * The scheduling payload of a message, in the form a transport serializes.
+ *
+ * This is what {@link Message.calendar} holds.  Both fields are settled: the
+ * method has been checked against the calendar object's own `METHOD` property,
+ * and the content carries the CRLF line endings RFC 5545 §3.1 makes normative.
+ */
+export interface CalendarContent {
+  /**
+   * The method the calendar object declares, which the MIME `method` parameter
+   * repeats.
+   */
+  readonly method: CalendarMethod;
+  /**
+   * The iCalendar object, with CRLF line endings and a terminating CRLF.
+   */
+  readonly content: string;
+}
+/**
+ * The scheduling payload in the looser form a caller supplies.
+ *
+ * This is what {@link MessageConstructor.calendar} accepts.  Line endings are
+ * normalized and the method is resolved when the message is created.
+ */
+export interface CalendarConstructor {
+  /**
+   * Asserts which method the calendar object carries.
+   *
+   * This is a guard, not a source: the resolved method always comes from the
+   * object's own `METHOD` property, and supplying a value that disagrees with
+   * it is an error rather than an override.  Leave it unset unless you want the
+   * check.
+   */
+  readonly method?: CalendarMethod;
+  /**
+   * The iCalendar object.  Bare LF and bare CR line endings are accepted and
+   * normalized to CRLF; the object's own line folding is left alone.
+   */
+  readonly content: string;
+}
+/**
+ * Reads the method a calendar object declares.
+ *
+ * This is a convenience parser for a payload arriving from elsewhere, so it
+ * returns `undefined` rather than throwing, the way {@link parseMessageId}
+ * does.  It answers one question—which iTIP method does this object declare?—
+ * and answers `undefined` whenever it cannot answer with confidence: no
+ * `METHOD` at the top level, more than one, a method Upyo does not support, or
+ * malformed content line syntax or component structure.  It never salvages a
+ * plausible token from malformed input.
+ *
+ * Use {@link resolveCalendarContent} instead when you want to know *why* a
+ * payload was refused.
+ *
+ * @example
+ * ```ts
+ * import { parseCalendarMethod } from "@alexify/mailer/calendar";
+ * parseCalendarMethod("BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR\r\n");
+ * // "REQUEST"
+ * ```
+ *
+ * @param content The iCalendar object to read.
+ * @returns The declared method, or `undefined` if there is not exactly one
+ *          supported top-level method.
+ */
+export declare function parseCalendarMethod(content: string): CalendarMethod | undefined;
+/**
+ * Checks a scheduling payload and puts it in the form a transport serializes.
+ *
+ * A transport calls this before composing, the way it calls
+ * {@link formatMessageId}: {@link Message} is a structural interface, so a
+ * value that never passed through {@link createMessage} still has to be checked
+ * before its method reaches a `Content-Type` parameter.
+ *
+ * This is deliberately not a full iCalendar validator.  It checks what MIME
+ * composition depends on: the syntax of every content line, one calendar
+ * object with balanced components, and exactly one supported method.  It
+ * leaves property-specific value syntax and scheduling semantics to the caller.
+ * Whether the object names an `ORGANIZER`, carries a stable `UID`, bumps
+ * `SEQUENCE` on an update, or satisfies the iTIP constraints for its method is
+ * not checked here.
+ *
+ * @example
+ * ```ts
+ * import { resolveCalendarContent } from "@alexify/mailer/calendar";
+ * const calendar = resolveCalendarContent({ content: ics });
+ * calendar.method;  // "REQUEST"
+ * ```
+ *
+ * @param calendar The payload to check.
+ * @returns The payload with CRLF line endings and a resolved method.
+ * @throws {TypeError} If the content is not a single well-formed calendar
+ * object with valid content line syntax, if it does not declare exactly one
+ * supported method, or if it declares a method other than the one asserted.
+ */
+export declare function resolveCalendarContent(calendar: CalendarConstructor): CalendarContent;
+/**
+ * Builds the *invite.ics* part that stands in for a calendar alternative.
+ *
+ * A transport that cannot compose a `text/calendar` body alternative falls back
+ * to this, so the payload travels rather than being dropped.  The part keeps
+ * the calendar media type and the `method` parameter, which is what a client
+ * needs to treat it as scheduling content, but whether a provider preserves
+ * that parameter is the provider's business; see the transport's documentation.
+ *
+ * The content ID is empty, which marks the part as an ordinary attachment
+ * across the transports that infer inline disposition from one.
+ *
+ * @param calendar The payload to carry.
+ * @returns An attachment holding the calendar object.
+ * @throws {TypeError} If the payload is not valid; see
+ * {@link resolveCalendarContent}.
+ */
+export declare function createCalendarAttachment(calendar: CalendarConstructor): Attachment;
+
+/**
+ * Represents an email message with various properties such as
+ * sender, recipients, subject, content, and attachments.
+ *
+ * You wouldn't typically create this type directly.  Instead, you probably
+ * want to use the {@link createMessage} function, which provides a more
+ * convenient API for creating messages.
+ */
+export interface Message {
+  /**
+   * The email address of the sender of the message.
+   */
+  readonly sender: Address;
+  /**
+   * The email addresses of the recipient of the message.
+   */
+  readonly recipients: readonly Address[];
+  /**
+   * The email addresses of the carbon copy (CC) recipients of the message.
+   */
+  readonly ccRecipients: readonly Address[];
+  /**
+   * The email addresses of the blind carbon copy (BCC) recipients of the message.
+   */
+  readonly bccRecipients: readonly Address[];
+  /**
+   * The email addresses of the reply-to recipients of the message.
+   */
+  readonly replyRecipients: readonly Address[];
+  /**
+   * The attachments included in the email message.  These are files that
+   * are sent along with the email, such as documents, images, or other
+   * media files.  Each attachment is represented by an {@link Attachment}
+   * object, which contains information about the attachment such as its
+   * filename, content type, and content ID.
+   */
+  readonly attachments: readonly Attachment[];
+  /**
+   * The subject of the email message.  This is typically a brief summary
+   * of the content of the email, and is used to help the recipient identify
+   * the purpose of the message.
+   */
+  readonly subject: string;
+  /**
+   * The content of the email message, which can be either HTML or plain text.
+   * This property is represented by the {@link MessageContent} type, which
+   * includes both HTML and plain text content.  The HTML content is typically
+   * used for rich formatting and layout, while the plain text content is
+   * used for simple text emails or for compatibility with email clients
+   * that do not support HTML.
+   */
+  readonly content: MessageContent;
+  /**
+   * The priority of the email message, which indicates its importance
+   * relative to other messages.  The priority can be one of three
+   * levels: `"high"`, `"normal"`, or `"low"`.  This is represented by
+   * the {@link Priority} type, which is a string literal type that
+   * allows only these three values.
+   */
+  readonly priority: Priority;
+  /**
+   * The tags associated with the email message.
+   */
+  readonly tags: readonly string[];
+  /**
+   * The headers of the email message.  This is represented by
+   * the {@link ImmutableHeaders} type, which is a supertype of
+   * the standard `Headers` class.  The `ImmutableHeaders` type
+   * includes only the methods for reading the headers, such as `get`, `keys`,
+   * `has`, and `entries`, but does not include methods for modifying
+   * the headers, such as `append`, `delete`, or `set`.
+   */
+  readonly headers: ImmutableHeaders;
+  /**
+   * An idempotency key to ensure that the same message is not sent multiple
+   * times.  This is useful for retrying failed send operations without
+   * risking duplicate delivery.
+   *
+   * If provided, the transport will use this key to deduplicate requests.
+   * If not provided, the transport may generate its own key internally
+   * (behavior varies by transport implementation).
+   *
+   * The key should be unique for each distinct message you want to send.
+   * When retrying the same message, use the same idempotency key.
+   *
+   * Note: Not all transports support idempotency keys.  Check the specific
+   * transport documentation for details.
+   */
+  readonly idempotencyKey?: string;
+  /**
+   * The RFC 5322 message identifier of the message, without the enclosing
+   * angle brackets.
+   *
+   * Set this when the identity of the message matters to the application, so
+   * that it can be stored and a reply arriving with a matching `In-Reply-To`
+   * correlated back to the conversation.  The value stays the same across
+   * delivery retries.  When it is left unset, a transport that composes the
+   * message itself generates one.
+   *
+   * Not every transport carries this.  A provider that composes the message on
+   * its own side may assign or rewrite the identifier regardless of what is
+   * given here; see the transport's documentation.  This is also unrelated to
+   * {@link Receipt.messageId}, which is the delivery handle the transport or
+   * the provider reports back.
+   */
+  readonly messageId?: string;
+  /**
+   * The origination date of the message: when its author considers it to have
+   * been sent, which is not necessarily when a transport delivers it.
+   *
+   * When it is left unset, a transport that composes the message itself uses
+   * the time of conversion, so a retry carries a later date than the first
+   * attempt.  Set it to keep the date stable.
+   */
+  readonly date?: Date;
+  /**
+   * The identifiers of the messages this one directly replies to, without the
+   * enclosing angle brackets.
+   *
+   * An empty array means the message deliberately replies to nothing, which
+   * suppresses an `In-Reply-To` header supplied through {@link headers};
+   * leaving the field unset lets that header through.
+   */
+  readonly inReplyTo?: readonly string[];
+  /**
+   * The identifiers of the conversation this message belongs to, oldest first
+   * and without the enclosing angle brackets.
+   *
+   * A reply usually carries the parent's references followed by the parent's
+   * own identifier, which is how a mail client reconstructs a thread.
+   *
+   * An empty array means the message deliberately belongs to no conversation,
+   * which suppresses a `References` header supplied through {@link headers};
+   * leaving the field unset lets that header through.
+   */
+  readonly references?: readonly string[];
+  /**
+   * The scheduling payload of the message: an iCalendar object describing an
+   * invitation, a reply to one, or a cancellation.
+   *
+   * A calendar client recognizes a scheduling message from a `text/calendar`
+   * body part whose `method` parameter repeats the object's own `METHOD`
+   * property, which is what this field lets a transport compose.  Attaching an
+   * *.ics* file yourself does not do the same thing.
+   *
+   * The human-readable {@link content} is still required and still carries the
+   * message: a recipient whose client knows nothing about scheduling sees that
+   * and nothing else.  Keep it consistent with the calendar object, since
+   * Outlook substitutes the HTML alternative for the object's `DESCRIPTION`.
+   *
+   * Not every transport composes this.  One that cannot sends the object as an
+   * *invite.ics* attachment instead, which preserves the payload but not
+   * necessarily the scheduling semantics; see the transport's documentation.
+   */
+  readonly calendar?: CalendarContent;
+}
+/**
+ * Represents the content of an email message, which can be either HTML
+ * or plain text.  The `html` property is optional, and if it is
+ * provided, the `text` property may also be included for
+ * compatibility with email clients that do not support HTML.
+ */
+export type MessageContent =
+  | {
+      /**
+       * The HTML content of the email message.  This is typically used
+       * for rich formatting and layout.
+       */
+      html: string;
+      /**
+       * The alternative plain text content of the email message.  This is
+       * optional and may be included for compatibility with email
+       * clients that do not support HTML.
+       */
+      text?: string;
+    }
+  | {
+      /**
+       * The plain text content of the email message.  This is typically
+       * used for simple text emails.
+       */
+      text: string;
+    };
+/**
+ * Represents the headers of an email message.  This type is a supertype of
+ * the standard `Headers` class, which is used to manage HTTP headers.
+ * Note that this type does not include methods for modifying the headers,
+ * such as `append`, `delete`, or `set`.  It is intended to be used for
+ * read-only access to the headers of an email message.
+ */
+export type ImmutableHeaders = Omit<Headers, 'append' | 'delete' | 'set'>;
+/**
+ * A constructor interface for creating a new email message using
+ * the {@link createMessage} function.
+ */
+export interface MessageConstructor {
+  /**
+   * The email address of the sender of the message.
+   */
+  readonly from: Address | string;
+  /**
+   * The email addresses of the recipient of the message.
+   */
+  readonly to: Address | string | (Address | string)[];
+  /**
+   * The email addresses of the carbon copy (CC) recipients of the message.
+   * @default `[]`
+   */
+  readonly cc?: Address | string | (Address | string)[];
+  /**
+   * The email addresses of the blind carbon copy (BCC) recipients of the message.
+   * @default `[]`
+   */
+  readonly bcc?: Address | string | (Address | string)[];
+  /**
+   * The email addresses of the reply-to recipients of the message.
+   * @default `[]`
+   */
+  readonly replyTo?: Address | string | (Address | string)[];
+  /**
+   * The attachments included in the email message.  These are files that
+   * are sent along with the email, such as documents, images, or other
+   * media files.  Each attachment can be represented by an {@link Attachment}
+   * or a `File` object, which contains information about the attachment such as
+   * its filename and content type.
+   * @default `[]`
+   */
+  readonly attachments?: Attachment | File | (Attachment | File)[];
+  /**
+   * The subject of the email message.  This is typically a brief summary
+   * of the content of the email, and is used to help the recipient identify
+   * the purpose of the message.
+   */
+  readonly subject: string;
+  /**
+   * The content of the email message, which can be either HTML or plain text.
+   * This property is represented by the {@link MessageContent} type, which
+   * includes both HTML and plain text content.  The HTML content is typically
+   * used for rich formatting and layout, while the plain text content is
+   * used for simple text emails or for compatibility with email clients
+   * that do not support HTML.
+   */
+  readonly content: MessageContent;
+  /**
+   * The priority of the email message, which indicates its importance
+   * relative to other messages.  The priority can be one of three
+   * levels: `"high"`, `"normal"`, or `"low"`.  This is represented by
+   * the {@link Priority} type, which is a string literal type that
+   * allows only these three values.
+   * @default `"normal"`
+   */
+  readonly priority?: Priority;
+  /**
+   * The tags associated with the email message.
+   * @default `[]`
+   */
+  readonly tags?: string[];
+  /**
+   * The headers of the email message.
+   * @default `{}`
+   */
+  readonly headers?: ImmutableHeaders | Record<string, string>;
+  /**
+   * An idempotency key to ensure that the same message is not sent multiple
+   * times.  This is useful for retrying failed send operations without
+   * risking duplicate delivery.
+   *
+   * If provided, the transport will use this key to deduplicate requests.
+   * If not provided, the transport may generate its own key internally
+   * (behavior varies by transport implementation).
+   *
+   * The key should be unique for each distinct message you want to send.
+   * When retrying the same message, use the same idempotency key.
+   *
+   * Note: Not all transports support idempotency keys.  Check the specific
+   * transport documentation for details.
+   */
+  readonly idempotencyKey?: string;
+  /**
+   * The RFC 5322 message identifier of the message.  The enclosing angle
+   * brackets are optional and stripped, so both `abc@example.com` and
+   * `<abc@example.com>` are accepted.
+   *
+   * Use {@link generateMessageId} to mint one before sending, so that it can
+   * be stored alongside whatever the message is about.
+   */
+  readonly messageId?: string;
+  /**
+   * The origination date of the message.
+   */
+  readonly date?: Date;
+  /**
+   * The identifier, or identifiers, of the messages this one directly replies
+   * to.  A single string is one identifier, never a list.  An empty array
+   * suppresses an `In-Reply-To` header supplied through {@link headers}.
+   */
+  readonly inReplyTo?: string | readonly string[];
+  /**
+   * The identifiers of the conversation this message belongs to, oldest first.
+   * A single string is one identifier, never a list.  An empty array
+   * suppresses a `References` header supplied through {@link headers}.
+   */
+  readonly references?: string | readonly string[];
+  /**
+   * The scheduling payload of the message: an iCalendar object your
+   * application, or a library such as *ical-generator*, produced.  Upyo does
+   * not generate one.
+   *
+   * The method is taken from the object's own `METHOD` property; supplying
+   * {@link CalendarConstructor.method} asserts what that property says rather
+   * than overriding it.  Line endings are normalized to CRLF.
+   */
+  readonly calendar?: CalendarConstructor;
+}
+/**
+ * Creates a new email {@link Message} based on the provided constructor
+ * parameters.  This function provides a more convenient API for creating
+ * messages compared to constructing a {@link Message} object directly.
+ *
+ * @example
+ * ```typescript
+ * const message = createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient1@example.com",
+ *   subject: "Hello World",
+ *   content: { text: "This is a test message" }
+ * });
+ * ```
+ *
+ * @param constructor The constructor parameters for the message. Uses more
+ *                    user-friendly types like accepting strings for email
+ *                    addresses and `File` objects for attachments.
+ * @returns A new {@link Message} object with all properties normalized and
+ *          validated.
+ * @throws {TypeError} When any email address string cannot be parsed, when an
+ *                     address or attachment carries a carriage return or line
+ *                     feed that could forge header fields, when an attachment
+ *                     object is invalid, when a message identifier is not
+ *                     valid, when the date is not one RFC 5322 can express, or
+ *                     when the calendar content is not a single well-formed
+ *                     iCalendar object declaring one supported method.
+ */
+export declare function createMessage(constructor: MessageConstructor): Message;
+
+/**
+ * Generates a globally unique message identifier rooted in a domain.
+ *
+ * The identifier is a random UUID followed by `@` and the domain, which makes
+ * it unique within the scope RFC 5322 §3.6.4 asks the generator to ensure.
+ * The same construction is used for attachment content IDs.
+ *
+ * The domain has to be a valid identifier right-hand side: a dot-atom such as
+ * `example.com` or an address literal such as `[192.0.2.1]`.  A URL, a host
+ * with a port, or a value carrying whitespace is rejected.  A domain written
+ * in a non-Latin script is converted to its ASCII (Punycode) form so that the
+ * *generated* identifier travels through mail software that predates RFC 6532;
+ * a non-ASCII domain that is not a DNS name is kept as it is.  An identifier
+ * supplied by a caller is never rewritten this way.
+ *
+ * @example
+ * ```ts
+ * import { generateMessageId } from "@alexify/mailer/message-id";
+ * const messageId = generateMessageId("example.com");
+ * // "1e2ee2e1-…-…@example.com"
+ * ```
+ *
+ * @param domain The domain the identifier is rooted in.
+ * @returns A bare message identifier, without angle brackets.
+ * @throws {TypeError} If the domain is not a valid identifier right-hand side.
+ */
+export declare function generateMessageId(domain: string): string;
+/**
+ * Parses a message identifier, with or without the enclosing angle brackets,
+ * into its bare form.
+ *
+ * This is the inverse of {@link formatMessageId}, and it returns `undefined`
+ * rather than throwing, the way {@link parseAddress} does.
+ *
+ * It parses *one* identifier.  An `In-Reply-To` or `References` field arriving
+ * from elsewhere may hold several identifiers, comments, folded whitespace, and
+ * obsolete syntax, none of which this function accepts; splitting such a field
+ * is the caller's job.
+ *
+ * @example
+ * ```ts
+ * import { parseMessageId } from "@alexify/mailer/message-id";
+ * parseMessageId("<abc@example.com>");  // "abc@example.com"
+ * parseMessageId("not an identifier");  // undefined
+ * ```
+ *
+ * @param value The identifier to parse.
+ * @returns The bare identifier, or `undefined` if the value is not one.
+ */
+export declare function parseMessageId(value: string): string | undefined;
+/**
+ * Formats a bare message identifier for a header field, by enclosing it in
+ * angle brackets.
+ *
+ * This is the inverse of {@link parseMessageId}.  It takes the *bare* form, so
+ * an already enclosed identifier is rejected rather than enclosed twice.  What
+ * it guarantees is syntax; a header field also has to fit the line-length limit
+ * the serializing transport enforces.
+ *
+ * @example
+ * ```ts
+ * import { formatMessageId } from "@alexify/mailer/message-id";
+ * formatMessageId("abc@example.com");  // "<abc@example.com>"
+ * ```
+ *
+ * @param id The bare identifier to format.
+ * @returns The identifier enclosed in angle brackets.
+ * @throws {TypeError} If the value is not a valid bare identifier.
+ */
+export declare function formatMessageId(id: string): string;
+/**
+ * Works out the reply threading header fields a transport should write for a
+ * message, from {@link Message.inReplyTo} and {@link Message.references}.
+ *
+ * The three states those fields can be in map onto the result like this:
+ *
+ *  -  A field the message leaves unset is absent from the map.  The message
+ *     does not own the header, so a transport may still write one supplied
+ *     through {@link Message.headers}.
+ *  -  A field set to an empty list maps to `null`.  The message owns the
+ *     header and deliberately writes nothing, which suppresses a custom header
+ *     of the same name.
+ *  -  A field with identifiers in it maps to the formatted field value.
+ *
+ * Keys are the canonical field names, `In-Reply-To` and `References`.  A header
+ * field name is case insensitive, so compare accordingly when deciding whether
+ * a custom header is shadowed.
+ *
+ * @example
+ * ```ts
+ * import { resolveThreadingHeaders } from "@alexify/mailer/message-id";
+ * // for a message replying to <122@example.com>:
+ * // Map { "In-Reply-To" => "<122@example.com>" }
+ * ```
+ *
+ * @param message The message being converted.
+ * @returns The header fields the message owns, keyed by canonical name.
+ * @throws {TypeError} If the message carries an invalid identifier.
+ */
+export declare function resolveThreadingHeaders(
+  message: Message,
+): ReadonlyMap<string, string | null>;
+
+/**
+ * The priority levels for email messages.
+ */
+export type Priority = 'high' | 'normal' | 'low';
+/**
+ * Compares two priority levels and returns a number indicating their
+ * relative order.
+ *
+ * @example Sorting priorities
+ * ```ts
+ * import { comparePriority, type Priority } from "@alexify/mailer/priority";
+ * const priorities: Priority[] = ["normal", "low", "high"];
+ * priorities.sort(comparePriority);
+ * console.log(priorities); // ["high", "normal", "low"]
+ * ```
+ *
+ * @param a The first priority to compare.
+ * @param b The second priority to compare.
+ * @return A negative number if `a` is less than `b`, a positive number
+ *         if `a` is greater than `b`, and zero if they are equal.
+ */
+export declare function comparePriority(a: Priority, b: Priority): number;
+
+/**
+ * A machine-readable category for an email delivery failure.
+ */
+export type ReceiptErrorCategory =
+  | 'auth'
+  | 'rate-limit'
+  | 'network'
+  | 'timeout'
+  | 'validation'
+  | 'rejected'
+  | 'server-error'
+  | 'service-unavailable'
+  | 'configuration'
+  | 'unknown';
+/**
+ * Structured information about an email delivery failure.
+ */
+export interface ReceiptError<TProviderId extends string = string> {
+  /**
+   * Human-readable error message.
+   */
+  readonly message: string;
+  /**
+   * Machine-readable provider or protocol error code.
+   */
+  readonly code: string;
+  /**
+   * Coarse error category for programmatic handling.
+   */
+  readonly category: ReceiptErrorCategory;
+  /**
+   * Whether retrying the same message may succeed.
+   */
+  readonly retryable: boolean;
+  /**
+   * Provider or transport that produced this error.
+   */
+  readonly provider?: TProviderId;
+  /**
+   * HTTP status code, when the failure came from an HTTP API.
+   */
+  readonly statusCode?: number;
+  /**
+   * Provider-supplied retry delay in milliseconds, when available.
+   */
+  readonly retryAfterMilliseconds?: number;
+  /**
+   * Provider-specific error details, when available.
+   */
+  readonly providerDetails?: unknown;
+}
+/**
+ * The response from the email service after sending an email message.
+ *
+ * This type uses a discriminated union to ensure type safety:
+ *
+ * - Successful sends have a `messageId` but no `errorMessages`
+ * - Failed sends have `errorMessages` but no `messageId`
+ *
+ * Failed receipts may also include structured `errors` and summary metadata
+ * for programmatic error handling.
+ */
+export type Receipt<TProviderId extends string = string> =
+  | {
+      /**
+       * Indicates that the email was sent successfully.
+       */
+      readonly successful: true;
+      /**
+       * The delivery handle the transport or the provider reports back, such as
+       * an SMTP queue identifier, a provider-assigned UUID, or a JMAP submission
+       * id.  Its shape differs between transports.
+       *
+       * This is not the RFC 5322 `Message-ID` of the message; that one is chosen
+       * by the sender and lives on {@link Message.messageId}.  Use this to look a
+       * delivery up with the provider, and that one to correlate a reply.
+       */
+      readonly messageId: string;
+      /**
+       * Provider or transport that produced this receipt.
+       */
+      readonly provider?: TProviderId;
+      /**
+       * Number of attempts made before this receipt was produced.
+       */
+      readonly attempts?: number;
+      /**
+       * ISO 8601 timestamp for when this receipt was produced.
+       */
+      readonly timestamp?: string;
+    }
+  | {
+      /**
+       * Indicates that the email failed to send.
+       */
+      readonly successful: false;
+      /**
+       * An array of error messages that occurred during the sending process.
+       */
+      readonly errorMessages: readonly string[];
+      /**
+       * Structured errors for programmatic handling.
+       */
+      readonly errors?: readonly ReceiptError<TProviderId>[];
+      /**
+       * Whether retrying the same message may succeed.
+       */
+      readonly retryable?: boolean;
+      /**
+       * Provider or transport that produced this receipt.
+       */
+      readonly provider?: TProviderId;
+      /**
+       * Number of attempts made before this receipt was produced.
+       */
+      readonly attempts?: number;
+      /**
+       * ISO 8601 timestamp for when this receipt was produced.
+       */
+      readonly timestamp?: string;
+    };
+/**
+ * Result of classifying a delivery failure.
+ */
+export interface ReceiptErrorClassification {
+  readonly category: ReceiptErrorCategory;
+  readonly retryable: boolean;
+  readonly code?: string;
+}
+/**
+ * Options for creating a structured receipt error.
+ */
+export interface CreateReceiptErrorOptions<TProviderId extends string = string> {
+  readonly code?: string;
+  readonly category?: ReceiptErrorCategory;
+  readonly retryable?: boolean;
+  readonly provider?: TProviderId;
+  readonly statusCode?: number;
+  readonly retryAfterMilliseconds?: number;
+  readonly providerDetails?: unknown;
+}
+/**
+ * Options for creating a failed receipt.
+ */
+export interface CreateFailedReceiptOptions<
+  TProviderId extends string = string,
+> extends CreateReceiptErrorOptions<TProviderId> {
+  readonly errors?: readonly ReceiptError<TProviderId>[];
+  readonly attempts?: number;
+  readonly timestamp?: string;
+}
+/**
+ * Classifies an HTTP status code for delivery error handling.
+ *
+ * @param statusCode The HTTP status code to classify.
+ * @returns The receipt error category and retryability.
+ */
+export declare function classifyHttpStatus(statusCode: number): ReceiptErrorClassification;
+/**
+ * Classifies an arbitrary delivery failure.
+ *
+ * @param error The error to classify.
+ * @returns The receipt error category, retryability, and default code.
+ */
+export declare function classifyReceiptError(error: unknown): Required<ReceiptErrorClassification>;
+/**
+ * Creates structured information about a delivery failure.
+ *
+ * @param message Human-readable error message.
+ * @param options Optional structured error metadata.
+ * @returns A structured receipt error.
+ */
+export declare function createReceiptError<TProviderId extends string = string>(
+  message: string,
+  options?: CreateReceiptErrorOptions<TProviderId>,
+): ReceiptError<TProviderId>;
+/**
+ * Creates a failed receipt with human-readable and structured errors.
+ *
+ * @param error Error message, structured error, or list of structured errors.
+ * @param options Optional receipt and error metadata.
+ * @returns A failed receipt.
+ */
+export declare function createFailedReceipt<TProviderId extends string = string>(
+  error: string | readonly (string | ReceiptError<TProviderId>)[] | ReceiptError<TProviderId>,
+  options?: CreateFailedReceiptOptions<TProviderId>,
+): Receipt<TProviderId> & {
+  readonly successful: false;
+};
+/**
+ * Parses an HTTP `Retry-After` header value into milliseconds.
+ *
+ * @param value Header value to parse.
+ * @param now Current time used when parsing HTTP dates.
+ * @returns Retry delay in milliseconds, or `undefined` if invalid.
+ */
+export declare function parseRetryAfter(
+  value: string | null | undefined,
+  now?: Date,
+): number | undefined;
+
+/**
+ * A common interface for email sending services.
+ */
+export interface Transport<TProviderId extends string = string> {
+  /**
+   * Stable provider identifier for receipts produced by this transport.
+   */
+  readonly id: TProviderId;
+  /**
+   * Sends a single message using the email service.
+   * @param message The message to send.
+   * @param options Optional parameters for sending the message.
+   * @returns A promise that resolves to a receipt containing the result of
+   *          the send operation.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
+  /**
+   * Sends multiple messages using the email service.
+   * @param messages An iterable of messages to send.
+   * @param options Optional parameters for sending the messages.
+   * @return An async iterable that yields receipts for each sent message.
+   */
+  sendMany(
+    messages: Iterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<TProviderId>>;
+  /**
+   * Sends multiple messages using the email service.
+   * @param messages An async iterable of messages to send.
+   * @param options Optional parameters for sending the messages.
+   * @return An async iterable that yields receipts for each sent message.
+   */
+  sendMany(
+    messages: AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<TProviderId>>;
+}
+/**
+ * Options for operations on the email service.
+ */
+export interface TransportOptions {
+  /**
+   * The abort signal to cancel the operation if needed.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Optional capability for delivering already serialized MIME messages.
+ * Wrappers must explicitly preserve this capability to expose it themselves.
+ */
+export interface RawTransport<TProviderId extends string = string> extends Transport<TProviderId> {
+  /**
+   * Delivers original MIME bytes using an explicit envelope.
+   * @param message The serialized message and its delivery envelope.
+   * @param options Optional cancellation signal.
+   * @returns A delivery receipt; server-side processing may modify the message.
+   * @throws {Error} If cancellation is requested.
+   */
+  sendRaw(message: RawMessage, options?: TransportOptions): Promise<Receipt<TProviderId>>;
+}
+/**
+ * Checks whether a transport exposes raw MIME delivery.
+ * @param transport The transport to inspect.
+ * @returns Whether the transport implements the optional raw capability.
+ */
+export declare function isRawTransport<TProviderId extends string>(
+  transport: Transport<TProviderId>,
+): transport is RawTransport<TProviderId>;
+/**
+ * Optional capability for checking setup without sending a message.
+ * Success describes the configuration at verification time, not acceptance of
+ * any particular sender, recipient, message, or eventual delivery. Wrappers
+ * must explicitly preserve this capability to expose it themselves.
+ */
+export interface VerifiableTransport<
+  TProviderId extends string = string,
+> extends Transport<TProviderId> {
+  /**
+   * Checks connectivity, configured authentication, and transport prerequisites.
+   * @param options Optional cancellation signal.
+   * @returns A promise that resolves when verification succeeds.
+   * @throws {Error} If setup or verification fails; errors are transport-specific.
+   * @throws The caller's abort reason if the operation is cancelled.
+   */
+  verify(options?: TransportOptions): Promise<void>;
+}
+/**
+ * Checks whether a transport exposes configuration verification.
+ * @param transport The transport to inspect.
+ * @returns Whether the transport implements the optional verification capability.
+ */
+export declare function isVerifiableTransport<TProviderId extends string>(
+  transport: Transport<TProviderId>,
+): transport is VerifiableTransport<TProviderId>;
+
+/** Replayable, already serialized MIME bytes. @since 0.6.0 */
+export type RawMessageContent = AttachmentContent;
+/**
+ * Transport requirements of serialized bytes, not a request to transcode them.
+ * With `8bit`, the caller guarantees ASCII MIME headers, including nested
+ * parts. Upyo checks only the top-level headers and does not parse nested MIME.
+ * `utf8` permits internationalized headers. Neither permits NUL or binary MIME
+ * transfer.
+ */
+export type RawMessageEncoding = '7bit' | '8bit' | 'utf8';
+/** Delivery addresses independent of the MIME headers. @since 0.6.0 */
+export interface RawMessageEnvelope {
+  /** Envelope sender, or null for a null reverse-path. */
+  readonly from: EmailAddress | null;
+  /** Nonempty list of envelope recipients, including any blind copies. */
+  readonly to: readonly EmailAddress[];
+}
+/**
+ * An already serialized message. The source must use CRLF, including its final
+ * line ending, contain no NUL, and have lines of at most 998 octets. Headers
+ * must not be empty; a body is optional. Upyo does not repair or compose MIME.
+ */
+export interface RawMessage {
+  /** Explicit delivery addresses; never inferred from message headers. */
+  readonly envelope: RawMessageEnvelope;
+  /** Fresh, independent readers must reproduce identical bytes on every call. */
+  readonly content: RawMessageContent;
+  /**
+   * With an explicit encoding, delivery reads the source once. Otherwise it
+   * reads twice: analysis, then transmission. Any non-ASCII byte conservatively
+   * selects `utf8`, even in a body that could be sent using `8bit`.
+   */
+  readonly encoding?: RawMessageEncoding;
+}
+/** Invalid raw-message metadata or wire structure. @since 0.6.0 */
+export declare class RawMessageValidationError extends TypeError {
+  /** The invalid message field. */
+  readonly field: 'envelope' | 'content' | 'encoding';
+  /** Zero-based byte offset, when the error refers to content. */
+  readonly byteOffset?: number;
+  /** One-based line number, when the error refers to content. */
+  readonly lineNumber?: number;
+  /**
+   * Creates a raw-message validation error.
+   * @param message Description of the failure.
+   * @param field The invalid field.
+   * @param byteOffset Optional zero-based content offset.
+   * @param lineNumber Optional one-based line number.
+   */
+  constructor(
+    message: string,
+    field: 'envelope' | 'content' | 'encoding',
+    byteOffset?: number,
+    lineNumber?: number,
+  );
+}
+/** @internal */
+export interface RawMessagePlan extends RawMessage {
+  /** Known byte length, excluding protocol framing. */
+  readonly size?: number;
+}
+/**
+ * Snapshots metadata and observes promised bytes before any asynchronous work.
+ * @param message The raw message to validate.
+ * @returns A replayable plan with a copied envelope.
+ * @throws {RawMessageValidationError} If metadata or the source kind is invalid.
+ * @internal
+ */
+export declare function createRawMessagePlan(message: RawMessage): RawMessagePlan;
+/** @internal */
+export interface RawMessageAnalysis {
+  readonly size: number;
+  readonly encoding: RawMessageEncoding;
+}
+/** @internal */
+export interface RawMessageReadOptions {
+  readonly signal?: AbortSignal;
+  readonly expectedSize?: number;
+  readonly encoding?: RawMessageEncoding;
+  readonly onProgress?: (analysis: RawMessageAnalysis) => void;
+}
+/**
+ * Validates and yields at most 32 KiB per chunk, without prefetching. Chunks
+ * remain valid until the next read; HTTP consumers must copy before enqueueing.
+ * The source's own errors and cancellation reasons are preserved.
+ * @param plan Validated metadata and replayable source.
+ * @param options Cancellation, analysis observations, and transmission checks.
+ * @returns Original bytes in bounded windows.
+ * @throws {RawMessageValidationError} If wire structure or encoding is invalid.
+ * @throws {Error} If the source fails or reading is cancelled.
+ * @internal
+ */
+export declare function iterateRawMessage(
+  plan: RawMessagePlan,
+  options?: RawMessageReadOptions,
+): AsyncIterable<Uint8Array>;
+/**
+ * Analyzes one complete traversal without retaining the message in memory.
+ * @param plan Validated metadata and replayable source.
+ * @param signal Cancellation signal.
+ * @param onProgress Optional incremental observations, also allowed to reject.
+ * @returns The byte length and conservative transport encoding.
+ * @throws {RawMessageValidationError} If the raw content is invalid.
+ * @throws {Error} If the source or progress callback fails, or reading is cancelled.
+ * @internal
+ */
+export declare function analyzeRawMessage(
+  plan: RawMessagePlan,
+  signal?: AbortSignal,
+  onProgress?: (analysis: RawMessageAnalysis) => void,
+): Promise<RawMessageAnalysis>;
+
 /**
  * A mailer: sends messages through a transport, with the reliability layer
  * (queue, audit log, delivery events) on top.
@@ -14,4 +1225,4 @@ export interface Mailer {
  * Placeholder: throws until the mailer is implemented. The signature is
  * provisional.
  */
-export function createMailer(options: object): Mailer;
+export declare function createMailer(options: object): Mailer;
diff --git a/src/core/abort-signal.js b/src/core/abort-signal.js
new file mode 100644
index 0000000..6742b0d
--- /dev/null
+++ b/src/core/abort-signal.js
@@ -0,0 +1,25 @@
+// Ported from upyo v0.7.0 (packages/core/src/abort-signal.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Combines a primary abort signal with an optional external signal.
+ *
+ * The returned signal aborts as soon as either input signal aborts, with the
+ * reason of the signal that aborted first (`AbortSignal.any()`).
+ *
+ * @param primarySignal The signal owned by the current operation.
+ * @param externalSignal Optional caller-supplied signal to compose.
+ * @returns A combined signal and cleanup callback.
+ */
+const combineSignals = (primarySignal, externalSignal) => {
+  if (externalSignal == null) {
+    return { signal: primarySignal, cleanup: () => {} };
+  }
+
+  return {
+    signal: AbortSignal.any([primarySignal, externalSignal]),
+    cleanup: () => {},
+  };
+};
+
+module.exports = { combineSignals };
diff --git a/src/core/address.js b/src/core/address.js
new file mode 100644
index 0000000..5d04235
--- /dev/null
+++ b/src/core/address.js
@@ -0,0 +1,247 @@
+// Ported from upyo v0.7.0 (packages/core/src/address.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Formats an address object into a string representation.  This function is
+ * an inverse of the {@link parseAddress} function.
+ *
+ * @example Formatting an address with a name
+ * ```ts
+ * import { type Address, formatAddress } from "@alexify/mailer/address";
+ * const address: Address = { name: "John Doe", address: "john@example.com" };
+ * console.log(formatAddress(address)); // "John Doe <john@example.com>"
+ * ```
+ *
+ * @example Formatting an address without a name
+ * ```ts
+ * import { type Address, formatAddress } from "@alexify/mailer/address";
+ * const address: Address = { address: "jane@examle.com" };
+ * console.log(formatAddress(address)); // "jane@example.com"
+ * ```
+ *
+ * @param address The address object to format.
+ * @return A string representation of the address.
+ */
+const formatAddress = (address) => {
+  return address.name == null ? address.address : `${address.name} <${address.address}>`;
+};
+
+/**
+ * Parses a string representation of an email address into an {@link Address}
+ * object.  This function is an inverse of the {@link formatAddress} function.
+ *
+ * @example Parsing an address with a name
+ * ```ts
+ * import { parseAddress } from "@alexify/mailer/address";
+ * const address = parseAddress("John Doe <john@example.com>");
+ * console.log(address); // { name: "John Doe", address: "john@example.com" }
+ * ```
+ *
+ * @example Parsing an address without a name
+ * ```ts
+ * import { parseAddress } from "@alexify/mailer/address";
+ * const address = parseAddress("jane@example.com");
+ * console.log(address); // { address: "jane@example.com" }
+ * ```
+ *
+ * @example Trying to parse an invalid address
+ * ```ts
+ * import { parseAddress } from "@alexify/mailer/address";
+ * const address = parseAddress("invalid-email");
+ * console.log(address); // undefined
+ * ```
+ *
+ * @param address The string representation of the address to parse.
+ * @returns An {@link Address} object if the parsing is successful,
+ *          or `undefined` if the input is invalid.
+ */
+const parseAddress = (address) => {
+  if (!address || typeof address !== 'string') {
+    return undefined;
+  }
+
+  const trimmed = address.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  // Check for name and angle bracket format: "Name <email@domain.com>"
+  const nameAngleBracketMatch = trimmed.match(/^(.+?)\s*<(.+?)>$/);
+  if (nameAngleBracketMatch) {
+    const name = nameAngleBracketMatch[1].trim();
+    const email = nameAngleBracketMatch[2].trim();
+
+    if (!isValidEmail(email)) {
+      return undefined;
+    }
+
+    // Remove quotes from name if present
+    const cleanName = name.replace(/^"(.+)"$/, '$1');
+    return { name: cleanName, address: email };
+  }
+
+  // Check for angle bracket format without name: "<email@domain.com>"
+  const angleBracketMatch = trimmed.match(/^<(.+?)>$/);
+  if (angleBracketMatch) {
+    const email = angleBracketMatch[1].trim();
+
+    if (!isValidEmail(email)) {
+      return undefined;
+    }
+
+    return { address: email };
+  }
+
+  // Check for plain email format: "email@domain.com"
+  if (isValidEmail(trimmed)) {
+    return { address: trimmed };
+  }
+
+  return undefined;
+};
+
+const isValidEmail = (email) => {
+  if (!email || typeof email !== 'string') {
+    return false;
+  }
+
+  // Prevent SMTP command injection by disallowing newlines
+  if (email.includes('\r') || email.includes('\n')) {
+    return false;
+  }
+
+  // Find the @ symbol that separates local and domain parts
+  // If the local part is quoted, we need to find the @ after the closing quote
+  let atIndex = -1;
+  let inQuotes = false;
+  let escaped = false;
+
+  for (let i = 0; i < email.length; i++) {
+    const char = email[i];
+
+    if (char === '"' && !escaped) {
+      inQuotes = !inQuotes;
+    } else if (char === '@' && !inQuotes) {
+      if (atIndex === -1) {
+        atIndex = i;
+      } else {
+        // Multiple @ symbols outside quotes
+        return false;
+      }
+    }
+    escaped = char === '\\' && !escaped;
+  }
+
+  if (atIndex === -1) {
+    return false;
+  }
+
+  const localPart = email.substring(0, atIndex);
+  const domainPart = email.substring(atIndex + 1);
+
+  return isValidLocalPart(localPart) && isValidDomainPart(domainPart);
+};
+
+const isValidLocalPart = (localPart) => {
+  if (!localPart || localPart.length === 0 || new TextEncoder().encode(localPart).byteLength > 64) {
+    return false;
+  }
+
+  // Check for quoted string format
+  if (localPart.startsWith('"') && localPart.endsWith('"')) {
+    const quotedContent = localPart.slice(1, -1);
+    for (let i = 0; i < quotedContent.length;) {
+      const codePoint = quotedContent.codePointAt(i);
+      if (codePoint == null || (codePoint >= 0xd800 && codePoint <= 0xdfff)) {
+        return false;
+      }
+      if (codePoint > 0x7f) {
+        i += codePoint > 0xffff ? 2 : 1;
+        continue;
+      }
+
+      if (codePoint === 0x5c) {
+        const escapedCodePoint = quotedContent.codePointAt(i + 1);
+        if (escapedCodePoint == null || escapedCodePoint < 0x20 || escapedCodePoint > 0x7e) {
+          return false;
+        }
+        i += 2;
+        continue;
+      }
+
+      if (codePoint < 0x20 || codePoint === 0x22 || codePoint === 0x5c || codePoint > 0x7e) {
+        return false;
+      }
+      i++;
+    }
+    return true;
+  }
+
+  // Check for dot-atom format (RFC 5322)
+  // No leading/trailing dots, no consecutive dots
+  if (localPart.startsWith('.') || localPart.endsWith('.') || localPart.includes('..')) {
+    return false;
+  }
+
+  // RFC 6531 extends atext with any well-formed non-ASCII UTF-8 character.
+  const asciiAtext = /^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]$/;
+  return localPart.split('.').every(
+    (atom) =>
+      atom.length > 0 &&
+      Array.from(atom).every((character) => {
+        if (asciiAtext.test(character)) return true;
+        const codePoint = character.codePointAt(0);
+        return (
+          codePoint != null && codePoint > 0x7f && !(codePoint >= 0xd800 && codePoint <= 0xdfff)
+        );
+      }),
+  );
+};
+
+const isValidDomainPart = (domainPart) => {
+  if (!domainPart || domainPart.length === 0 || domainPart.length > 253) {
+    return false;
+  }
+
+  // Check for domain literal format [IP]
+  if (domainPart.startsWith('[') && domainPart.endsWith(']')) {
+    const literal = domainPart.slice(1, -1);
+    // Use URL.canParse() for IP validation
+    try {
+      return URL.canParse(`http://${literal}/`);
+    } catch {
+      return false;
+    }
+  }
+
+  // For regular domain format, use URL.canParse() for validation
+  try {
+    // URL.canParse() expects a valid URL, so we prepend http://
+    return URL.canParse(`http://${domainPart}/`);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Type guard function that checks if a given value is a valid email address.
+ *
+ * @example
+ * ```ts
+ * import { isEmailAddress } from "@alexify/mailer/address";
+ *
+ * const userInput = "user@example.com";
+ * if (isEmailAddress(userInput)) {
+ *   // TypeScript now knows userInput is EmailAddress type
+ *   console.log(userInput); // Type: `${string}@${string}`
+ * }
+ * ```
+ *
+ * @param email The value to check
+ * @returns `true` if the value is a valid email address, `false` otherwise
+ */
+const isEmailAddress = (email) => {
+  return typeof email === 'string' && isValidEmail(email);
+};
+
+module.exports = { formatAddress, parseAddress, isEmailAddress };
diff --git a/src/core/attachment.js b/src/core/attachment.js
new file mode 100644
index 0000000..6aaaa83
--- /dev/null
+++ b/src/core/attachment.js
@@ -0,0 +1,187 @@
+// Ported from upyo v0.7.0 (packages/core/src/attachment.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('./abort-signal.js');
+
+/**
+ * Checks if the provided value is an {@link Attachment} object.
+ * @param attachment The value to check.
+ * @return `true` if the value is an {@link Attachment}, otherwise `false`.
+ */
+const isAttachment = (attachment) => {
+  return (
+    typeof attachment === 'object' &&
+    attachment !== null &&
+    'inline' in attachment &&
+    'filename' in attachment &&
+    'content' in attachment &&
+    'contentType' in attachment &&
+    'contentId' in attachment &&
+    typeof attachment.inline === 'boolean' &&
+    typeof attachment.filename === 'string' &&
+    (attachment.content instanceof Uint8Array ||
+      typeof attachment.content === 'function' ||
+      attachment.content instanceof Blob ||
+      (attachment.content instanceof Promise && typeof attachment.content.then === 'function')) &&
+    typeof attachment.contentType === 'string' &&
+    typeof attachment.contentId === 'string'
+  );
+};
+
+const waitForContent = (promise, signal) => {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    promise.then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', abort);
+    });
+    if (signal.aborted) abort();
+  });
+};
+
+const blobIterator = (blob) => {
+  const reader = blob.stream().getReader();
+  let pending;
+  let released = false;
+  const release = () => {
+    if (!released) {
+      released = true;
+      reader.releaseLock();
+    }
+  };
+  return {
+    async next() {
+      pending = reader.read();
+      const result = await pending;
+      if (result.done) release();
+      return result.done ? { done: true, value: undefined } : { done: false, value: result.value };
+    },
+    async return() {
+      try {
+        await reader.cancel();
+        await pending;
+      } finally {
+        release();
+      }
+      return { done: true, value: undefined };
+    },
+  };
+};
+
+/**
+ * Reads attachment chunks without prefetching. Early exit or cancellation
+ * aborts the source and requests cleanup without waiting for an uncooperative
+ * producer. Producers remain responsible for honoring cancellation.
+ * @param content Replayable content to read.
+ * @param signal Optional cancellation signal.
+ * @returns An iterable of byte chunks, valid until the next read.
+ * @throws {TypeError} If a source or yielded chunk is invalid.
+ * @throws {Error} If reading fails or cancellation is requested.
+ */
+const iterateAttachmentContent = async function* (content, signal) {
+  const controller = new AbortController();
+  const combined = combineSignals(controller.signal, signal);
+  const ownedSignal = combined.signal;
+  let iterator;
+  let returned = false;
+  let done = false;
+  const close = () => {
+    if (iterator == null || returned || done) return;
+    returned = true;
+    try {
+      Promise.resolve(iterator.return?.()).catch(() => {});
+    } catch {
+      // Cleanup must not replace the original read or cancellation failure.
+    }
+  };
+  const abort = () => close();
+  ownedSignal.addEventListener('abort', abort, { once: true });
+  try {
+    if (content instanceof Promise) content.catch(() => {});
+    ownedSignal.throwIfAborted();
+    if (content instanceof Uint8Array || content instanceof Promise) {
+      const bytes = await waitForContent(Promise.resolve(content), ownedSignal);
+      ownedSignal.throwIfAborted();
+      if (!(bytes instanceof Uint8Array)) {
+        throw new TypeError('Expected attachment bytes to be a Uint8Array.');
+      }
+      yield bytes;
+      done = true;
+      return;
+    }
+    if (content instanceof Blob) {
+      iterator = blobIterator(content);
+    } else if (typeof content === 'function') {
+      const opening = Promise.resolve(content(ownedSignal)).then((source) => {
+        iterator = source[Symbol.asyncIterator]();
+        if (ownedSignal.aborted) close();
+        return iterator;
+      });
+      iterator = await waitForContent(opening, ownedSignal);
+    } else {
+      throw new TypeError('Expected replayable attachment content.');
+    }
+    let iterations = 0;
+    let bytesRead = 0;
+    while (true) {
+      ownedSignal.throwIfAborted();
+      const result = await waitForContent(Promise.resolve(iterator.next()), ownedSignal);
+      ownedSignal.throwIfAborted();
+      if (result.done) {
+        done = true;
+        break;
+      }
+      if (!(result.value instanceof Uint8Array)) {
+        throw new TypeError('Expected an attachment chunk to be a Uint8Array.');
+      }
+      yield result.value;
+      bytesRead += result.value.length;
+      if (++iterations >= 256 || bytesRead >= 1024 * 1024) {
+        await waitForContent(new Promise((resolve) => setTimeout(resolve, 0)), ownedSignal);
+        iterations = bytesRead = 0;
+      }
+    }
+  } finally {
+    if (!done) {
+      controller.abort();
+      close();
+    }
+    ownedSignal.removeEventListener('abort', abort);
+    combined.cleanup();
+  }
+};
+
+/**
+ * Collects an attachment in memory. Existing arrays retain their identity;
+ * streamed chunks are copied before the producer can reuse their storage.
+ * @param content Replayable content to collect.
+ * @param signal Optional cancellation signal.
+ * @returns The complete attachment bytes.
+ * @throws {TypeError} If a source or yielded chunk is invalid.
+ * @throws {RangeError} If the attachment cannot fit in a byte array.
+ * @throws {Error} If reading fails or cancellation is requested.
+ */
+const readAttachmentContent = async (content, signal) => {
+  const chunks = [];
+  let length = 0;
+  for await (const chunk of iterateAttachmentContent(content, signal)) {
+    if (content instanceof Uint8Array || content instanceof Promise) {
+      return chunk;
+    }
+    if (chunk.length === 0) continue;
+    chunks.push(new Uint8Array(chunk));
+    length += chunk.length;
+    if (!Number.isSafeInteger(length)) {
+      throw new RangeError('Attachment size exceeds the safe integer range.');
+    }
+  }
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return bytes;
+};
+
+module.exports = { isAttachment, iterateAttachmentContent, readAttachmentContent };
diff --git a/src/core/calendar.js b/src/core/calendar.js
new file mode 100644
index 0000000..2dea75e
--- /dev/null
+++ b/src/core/calendar.js
@@ -0,0 +1,411 @@
+// Ported from upyo v0.7.0 (packages/core/src/calendar.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * The shape of an RFC 5545 §3.1 component name: an `iana-token` or an `x-name`,
+ * both of which are one or more of ALPHA, DIGIT and `-`.  Matched against the
+ * already upper-cased value.
+ */
+const componentNamePattern = /^[A-Z0-9-]+$/;
+
+const calendarMethods = new Set([
+  'PUBLISH',
+  'REQUEST',
+  'REPLY',
+  'ADD',
+  'CANCEL',
+  'REFRESH',
+  'COUNTER',
+  'DECLINECOUNTER',
+]);
+
+/**
+ * Reads the method a calendar object declares.
+ *
+ * This is a convenience parser for a payload arriving from elsewhere, so it
+ * returns `undefined` rather than throwing, the way {@link parseMessageId}
+ * does.  It answers one question—which iTIP method does this object declare?—
+ * and answers `undefined` whenever it cannot answer with confidence: no
+ * `METHOD` at the top level, more than one, a method Upyo does not support, or
+ * malformed content line syntax or component structure.  It never salvages a
+ * plausible token from malformed input.
+ *
+ * Use {@link resolveCalendarContent} instead when you want to know *why* a
+ * payload was refused.
+ *
+ * @example
+ * ```ts
+ * import { parseCalendarMethod } from "@alexify/mailer/calendar";
+ * parseCalendarMethod("BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR\r\n");
+ * // "REQUEST"
+ * ```
+ *
+ * @param content The iCalendar object to read.
+ * @returns The declared method, or `undefined` if there is not exactly one
+ *          supported top-level method.
+ */
+const parseCalendarMethod = (content) => {
+  if (typeof content !== 'string') return undefined;
+  try {
+    return readMethod(normalizeLineEndings(content));
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Checks a scheduling payload and puts it in the form a transport serializes.
+ *
+ * A transport calls this before composing, the way it calls
+ * {@link formatMessageId}: {@link Message} is a structural interface, so a
+ * value that never passed through {@link createMessage} still has to be checked
+ * before its method reaches a `Content-Type` parameter.
+ *
+ * This is deliberately not a full iCalendar validator.  It checks what MIME
+ * composition depends on: the syntax of every content line, one calendar
+ * object with balanced components, and exactly one supported method.  It
+ * leaves property-specific value syntax and scheduling semantics to the caller.
+ * Whether the object names an `ORGANIZER`, carries a stable `UID`, bumps
+ * `SEQUENCE` on an update, or satisfies the iTIP constraints for its method is
+ * not checked here.
+ *
+ * @example
+ * ```ts
+ * import { resolveCalendarContent } from "@alexify/mailer/calendar";
+ * const calendar = resolveCalendarContent({ content: ics });
+ * calendar.method;  // "REQUEST"
+ * ```
+ *
+ * @param calendar The payload to check.
+ * @returns The payload with CRLF line endings and a resolved method.
+ * @throws {TypeError} If the content is not a single well-formed calendar
+ * object with valid content line syntax, if it does not declare exactly one
+ * supported method, or if it declares a method other than the one asserted.
+ */
+const resolveCalendarContent = (calendar) => {
+  const content = normalizeLineEndings(calendar.content ?? '');
+  const method = readMethod(content);
+  if (method == null) {
+    throw new TypeError(
+      'The calendar content declares no supported top-level METHOD property.  ' +
+        'Add one, such as `METHOD:REQUEST`, to the VCALENDAR object: RFC 6047 ' +
+        '§2.4 requires the MIME method parameter to repeat it, and a calendar ' +
+        'client reads the property rather than the parameter.',
+    );
+  }
+  if (calendar.method != null && calendar.method !== method) {
+    throw new TypeError(
+      `The calendar content declares METHOD:${method}, but ${JSON.stringify(
+        calendar.method,
+      )} was given.  Leave the method unset to take it from the content.`,
+    );
+  }
+  return { method, content };
+};
+
+/**
+ * Builds the *invite.ics* part that stands in for a calendar alternative.
+ *
+ * A transport that cannot compose a `text/calendar` body alternative falls back
+ * to this, so the payload travels rather than being dropped.  The part keeps
+ * the calendar media type and the `method` parameter, which is what a client
+ * needs to treat it as scheduling content, but whether a provider preserves
+ * that parameter is the provider's business; see the transport's documentation.
+ *
+ * The content ID is empty, which marks the part as an ordinary attachment
+ * across the transports that infer inline disposition from one.
+ *
+ * @param calendar The payload to carry.
+ * @returns An attachment holding the calendar object.
+ * @throws {TypeError} If the payload is not valid; see
+ * {@link resolveCalendarContent}.
+ */
+const createCalendarAttachment = (calendar) => {
+  const resolved = resolveCalendarContent(calendar);
+  return {
+    inline: false,
+    filename: 'invite.ics',
+    content: new TextEncoder().encode(resolved.content),
+    // The charset is declared because RFC 6047 §2.4 requires it once the object
+    // leaves US-ASCII, and MIME would otherwise default to it and mis-read the
+    // UTF-8 bytes encoded above.
+    contentType: `text/calendar; charset=utf-8; method=${resolved.method}`,
+    contentId: '',
+  };
+};
+
+/**
+ * Normalizes line endings to CRLF and ensures a terminating one.
+ *
+ * RFC 5545 §3.1 makes CRLF the line ending of a content line, but a caller
+ * routinely holds an object with bare LFs, whether from a template file or from
+ * a generator that never wrote it to the wire.  Bare CR is normalized too, so
+ * that an old-Mac-style payload does not read as one enormous line.
+ *
+ * Blank lines around the object are dropped: a template literal opening with a
+ * newline, or a file saved with a trailing blank line, is ordinary, and no
+ * folded continuation can reach across an edge.  A blank line *inside* the
+ * object is left for {@link unfold} to refuse.
+ *
+ * @param content The object to normalize.
+ * @returns The object with CRLF line endings, or the empty string unchanged.
+ */
+const normalizeLineEndings = (content) => {
+  const normalized = content
+    .replace(/\r\n|\r|\n/g, '\r\n')
+    .replace(/^(?:\r\n)+/, '')
+    .replace(/(?:\r\n)+$/, '');
+  return normalized === '' ? '' : `${normalized}\r\n`;
+};
+
+/**
+ * Reads the one top-level method of a well-formed calendar object.
+ *
+ * Top level means the component stack is exactly `VCALENDAR`: a `METHOD` inside
+ * `VEVENT` or `VTIMEZONE` is a different property that happens to share a name,
+ * and a `METHOD:` appearing inside a property value is text.  Scanning
+ * continues past components rather than stopping at the first, so a second
+ * top-level `METHOD` written after one is still noticed.
+ *
+ * @param content The object, already normalized to CRLF.
+ * @returns The declared method, or `undefined` if there is not exactly one that
+ *          Upyo supports.
+ * @throws {TypeError} If the content is not a single well-formed calendar
+ * object.
+ */
+const readMethod = (content) => {
+  // Check the transmitted text before unfolding: a fold between two lone
+  // surrogates must not rescue them into a pair only in the parsed view.
+  for (const character of content) {
+    const code = character.codePointAt(0);
+    if (code >= 0xd800 && code <= 0xdfff) {
+      throw new TypeError('The calendar content contains an unpaired UTF-16 surrogate.');
+    }
+  }
+  const stack = [];
+  let closed = false;
+  let method;
+  let methods = 0;
+
+  for (const line of unfold(content)) {
+    const parsed = parseContentLine(line);
+    const { name } = parsed;
+    const value =
+      name === 'BEGIN' || name === 'END' || (name === 'METHOD' && stack.length === 1)
+        ? asciiUpperCase(parsed.value)
+        : parsed.value;
+
+    // Every line has passed the generic grammar.  Component delimiters also
+    // have the stricter BEGIN:<name> / END:<name> shape from RFC 5545 §3.4.
+    if ((name === 'BEGIN' || name === 'END') && parsed.hasParameters) {
+      throw new TypeError(`The calendar content carries parameters on a ${name} delimiter.`);
+    }
+
+    if (name === 'BEGIN') {
+      if (closed) {
+        throw new TypeError(
+          'The calendar content holds more than one VCALENDAR object, but a ' +
+            'message carries one.',
+        );
+      }
+      if (stack.length < 1 && value !== 'VCALENDAR') {
+        throw new TypeError(
+          `The calendar content begins with ${JSON.stringify(
+            value,
+          )} rather than a VCALENDAR object.`,
+        );
+      }
+      // RFC 5545 §3.4 has no VCALENDAR inside a VCALENDAR.  A nested one
+      // balances, so nothing else in this scan would notice it, and the object
+      // would be sent as though it were the single one this API accepts.
+      if (stack.length > 0 && value === 'VCALENDAR') {
+        throw new TypeError('The calendar content nests a VCALENDAR object inside another.');
+      }
+      // A component name is an `iana-token` or an `x-name`, both of which are
+      // one or more of ALPHA, DIGIT and "-".  A malformed name balances with
+      // its END the same way a well-formed one does, so it has to be checked
+      // here or not at all.
+      if (!componentNamePattern.test(value)) {
+        throw new TypeError(
+          `The calendar content opens a component named ${JSON.stringify(
+            value,
+          )}, which is not a component name.`,
+        );
+      }
+      stack.push(value);
+      continue;
+    }
+    if (name === 'END') {
+      if (stack.pop() !== value) {
+        throw new TypeError(
+          `The calendar content closes ${JSON.stringify(value)} that was never opened.`,
+        );
+      }
+      if (stack.length < 1) closed = true;
+      continue;
+    }
+    if (stack.length < 1) {
+      throw new TypeError('The calendar content holds a property outside any VCALENDAR object.');
+    }
+    if (name === 'METHOD' && stack.length === 1) {
+      methods++;
+      method = calendarMethods.has(value) ? value : undefined;
+    }
+  }
+
+  if (stack.length > 0) {
+    throw new TypeError(
+      `The calendar content leaves ${JSON.stringify(stack[stack.length - 1])} unclosed.`,
+    );
+  }
+  if (!closed) {
+    throw new TypeError('The calendar content holds no VCALENDAR object.');
+  }
+  return methods === 1 ? method : undefined;
+};
+
+/**
+ * Upper-cases the ASCII letters of a token, leaving everything else alone.
+ *
+ * RFC 5545 tokens are ASCII, and the case-insensitivity this folding implements
+ * is only ever applied to them.  `String.prototype.toUpperCase` would apply the
+ * full Unicode mapping instead, under which `\u017F` becomes `S` and `\u0131`
+ * becomes `I`, so `METHOD:reque\u017Ft` would read as `REQUEST`.  The payload
+ * would still carry the character no calendar client accepts, and the
+ * `Content-Type` would name a method the object does not declare, which is the
+ * exact disagreement this module exists to prevent.
+ *
+ * @param token The token to fold.
+ * @returns The token with its ASCII letters upper-cased.
+ */
+const asciiUpperCase = (token) => {
+  return token.replace(/[a-z]/g, (letter) => String.fromCharCode(letter.charCodeAt(0) - 32));
+};
+
+/**
+ * Parses the generic content line grammar of RFC 5545 §3.1.
+ *
+ * VALUE-CHAR allows HTAB, printable ASCII and non-ASCII characters.  QSAFE-CHAR
+ * further excludes quotes, and SAFE-CHAR also excludes commas, semicolons and
+ * colons.  After checking VALUE-CHAR across the line, the cursor recognizes
+ * those delimiters only where the parameter grammar permits them.  Backslashes
+ * and caret sequences are data; property-specific value syntax is not checked.
+ *
+ * @param line An unfolded line from already well-formed UTF-16 content.
+ * @returns The ASCII-folded name, unchanged value and parameter presence.
+ * @throws {TypeError} If the line does not match the content line grammar.
+ */
+const parseContentLine = (line) => {
+  const fail = (reason) => {
+    throw new TypeError(`The calendar content has ${reason}: ${JSON.stringify(line)}`);
+  };
+
+  for (const character of line) {
+    const code = character.codePointAt(0);
+    if ((code < 0x20 && code !== 0x09) || code === 0x7f) {
+      fail('a forbidden control character in a content line');
+    }
+  }
+
+  let cursor = 0;
+  const readName = () => {
+    const start = cursor;
+    while (isTokenCharacter(line.charCodeAt(cursor))) cursor++;
+    if (cursor === start) fail('an invalid property or parameter name');
+    return line.slice(start, cursor);
+  };
+
+  const name = asciiUpperCase(readName());
+  const hasParameters = line[cursor] === ';';
+  while (line[cursor] === ';') {
+    cursor++;
+    readName();
+    if (line[cursor] !== '=') fail('a parameter without an equals sign');
+    cursor++;
+
+    // Both paramtext and quoted-string may be empty.  A comma therefore
+    // always starts another value, even immediately before ';' or ':'.
+    while (true) {
+      if (line[cursor] === '"') {
+        cursor++;
+        while (cursor < line.length && line[cursor] !== '"') cursor++;
+        if (cursor === line.length) fail('an unterminated quoted parameter');
+        cursor++;
+      } else {
+        while (
+          cursor < line.length &&
+          line[cursor] !== ',' &&
+          line[cursor] !== ';' &&
+          line[cursor] !== ':'
+        ) {
+          if (line[cursor] === '"') {
+            fail('a quote inside an unquoted parameter');
+          }
+          cursor++;
+        }
+      }
+      if (line[cursor] !== ',') break;
+      cursor++;
+    }
+    if (line[cursor] !== ';' && line[cursor] !== ':') {
+      fail('an invalid delimiter after a parameter value');
+    }
+  }
+  if (line[cursor] !== ':') fail('a missing content line value separator');
+  return { name, value: line.slice(cursor + 1), hasParameters };
+};
+
+/** Whether a code unit belongs to the iana-token / x-name character set. */
+const isTokenCharacter = (code) => {
+  return (
+    (code >= 0x41 && code <= 0x5a) ||
+    (code >= 0x61 && code <= 0x7a) ||
+    (code >= 0x30 && code <= 0x39) ||
+    code === 0x2d
+  );
+};
+
+/**
+ * Unfolds the content lines of a calendar object.
+ *
+ * RFC 5545 §3.1 folds a long line by inserting CRLF and *one* space or tab,
+ * which unfolding removes.  Only that one character is removed: the rest of a
+ * whitespace run belongs to the value.  A `\n` written inside a property value
+ * is an escape sequence rather than a line ending and is left alone, which
+ * falls out of splitting on CRLF alone.
+ *
+ * A continuation joins the line immediately before it, so an empty line is
+ * refused rather than skipped over.  Skipping one would let a continuation
+ * reach across the gap and assemble a property the transmitted content does not
+ * actually hold — a `METHOD` in particular, which would then contradict the
+ * MIME parameter naming it.  An iCalendar object has no empty content lines
+ * anyway.
+ *
+ * @param content The object, already normalized to CRLF.
+ * @returns The unfolded content lines, without their endings.
+ * @throws {TypeError} If the content opens with a continuation line, or holds
+ * an empty one.
+ */
+const unfold = (content) => {
+  const split = content.split('\r\n');
+  // The terminating CRLF leaves a final empty element that is not a line.
+  if (split[split.length - 1] === '') split.pop();
+
+  const lines = [];
+  for (const line of split) {
+    if (line === '') {
+      throw new TypeError('The calendar content holds an empty line.');
+    }
+    if (line.startsWith(' ') || line.startsWith('\t')) {
+      if (lines.length < 1) {
+        throw new TypeError('The calendar content opens with a folded continuation line.');
+      }
+      lines[lines.length - 1] += line.slice(1);
+      continue;
+    }
+    lines.push(line);
+  }
+  return lines;
+};
+
+module.exports = { parseCalendarMethod, resolveCalendarContent, createCalendarAttachment };
diff --git a/src/core/message-id.js b/src/core/message-id.js
new file mode 100644
index 0000000..061368c
--- /dev/null
+++ b/src/core/message-id.js
@@ -0,0 +1,300 @@
+// Ported from upyo v0.7.0 (packages/core/src/message-id.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Generates a globally unique message identifier rooted in a domain.
+ *
+ * The identifier is a random UUID followed by `@` and the domain, which makes
+ * it unique within the scope RFC 5322 §3.6.4 asks the generator to ensure.
+ * The same construction is used for attachment content IDs.
+ *
+ * The domain has to be a valid identifier right-hand side: a dot-atom such as
+ * `example.com` or an address literal such as `[192.0.2.1]`.  A URL, a host
+ * with a port, or a value carrying whitespace is rejected.  A domain written
+ * in a non-Latin script is converted to its ASCII (Punycode) form so that the
+ * *generated* identifier travels through mail software that predates RFC 6532;
+ * a non-ASCII domain that is not a DNS name is kept as it is.  An identifier
+ * supplied by a caller is never rewritten this way.
+ *
+ * @example
+ * ```ts
+ * import { generateMessageId } from "@alexify/mailer/message-id";
+ * const messageId = generateMessageId("example.com");
+ * // "1e2ee2e1-…-…@example.com"
+ * ```
+ *
+ * @param domain The domain the identifier is rooted in.
+ * @returns A bare message identifier, without angle brackets.
+ * @throws {TypeError} If the domain is not a valid identifier right-hand side.
+ */
+const generateMessageId = (domain) => {
+  return `${crypto.randomUUID()}@${normalizeIdRight(domain)}`;
+};
+
+/**
+ * Parses a message identifier, with or without the enclosing angle brackets,
+ * into its bare form.
+ *
+ * This is the inverse of {@link formatMessageId}, and it returns `undefined`
+ * rather than throwing, the way {@link parseAddress} does.
+ *
+ * It parses *one* identifier.  An `In-Reply-To` or `References` field arriving
+ * from elsewhere may hold several identifiers, comments, folded whitespace, and
+ * obsolete syntax, none of which this function accepts; splitting such a field
+ * is the caller's job.
+ *
+ * @example
+ * ```ts
+ * import { parseMessageId } from "@alexify/mailer/message-id";
+ * parseMessageId("<abc@example.com>");  // "abc@example.com"
+ * parseMessageId("not an identifier");  // undefined
+ * ```
+ *
+ * @param value The identifier to parse.
+ * @returns The bare identifier, or `undefined` if the value is not one.
+ */
+const parseMessageId = (value) => {
+  if (typeof value !== 'string') return undefined;
+  const bare =
+    value.length > 1 && value.startsWith('<') && value.endsWith('>') ? value.slice(1, -1) : value;
+  return isMessageId(bare) ? bare : undefined;
+};
+
+/**
+ * Formats a bare message identifier for a header field, by enclosing it in
+ * angle brackets.
+ *
+ * This is the inverse of {@link parseMessageId}.  It takes the *bare* form, so
+ * an already enclosed identifier is rejected rather than enclosed twice.  What
+ * it guarantees is syntax; a header field also has to fit the line-length limit
+ * the serializing transport enforces.
+ *
+ * @example
+ * ```ts
+ * import { formatMessageId } from "@alexify/mailer/message-id";
+ * formatMessageId("abc@example.com");  // "<abc@example.com>"
+ * ```
+ *
+ * @param id The bare identifier to format.
+ * @returns The identifier enclosed in angle brackets.
+ * @throws {TypeError} If the value is not a valid bare identifier.
+ */
+const formatMessageId = (id) => {
+  if (!isMessageId(id)) {
+    throw new TypeError(`Invalid message ID: ${JSON.stringify(id)}`);
+  }
+  return `<${id}>`;
+};
+
+/**
+ * Tells whether a value is a message identifier in its bare form.
+ *
+ * The accepted syntax is `id-left "@" id-right` from RFC 5322 §3.6.4, extended
+ * with UTF-8 by RFC 6532, and then narrowed by a few deliberate restrictions
+ * described on {@link isDotAtomText} and {@link isNoFoldLiteral}.
+ *
+ * @param id The value to check.
+ * @returns Whether the value is a bare message identifier.
+ */
+const isMessageId = (id) => {
+  // A modern `id-left` is a dot-atom, which cannot contain an at sign, so the
+  // first one separates the two halves.  An `id-right` written as an address
+  // literal may contain further at signs.
+  const separator = id.indexOf('@');
+  if (separator < 0) return false;
+  const left = id.slice(0, separator);
+  const right = id.slice(separator + 1);
+  return isDotAtomText(left) && (isDotAtomText(right) || isNoFoldLiteral(right));
+};
+
+/**
+ * Normalizes a domain for {@link generateMessageId}.
+ *
+ * @param domain The domain to normalize.
+ * @returns The domain, converted to its ASCII form when it is a DNS name
+ *          written in a non-Latin script.
+ * @throws {TypeError} If the domain is not a valid identifier right-hand side.
+ */
+const normalizeIdRight = (domain) => {
+  if (typeof domain !== 'string' || !isIdRight(domain)) {
+    throw new TypeError(`Invalid message ID domain: ${JSON.stringify(domain)}`);
+  }
+  if (!hasNonAscii(domain) || !dnsNamePattern.test(domain)) return domain;
+  // `URL` applies IDNA, which is the only Punycode implementation available on
+  // every runtime Upyo targets.  It is used for the conversion alone; the
+  // value has already been validated, and the result is validated again.
+  let url;
+  try {
+    url = new URL(`http://${domain}/`);
+  } catch {
+    return domain;
+  }
+  const ascii = url.hostname;
+  return url.host === ascii && url.pathname === '/' && isIdRight(ascii) ? ascii : domain;
+};
+
+/**
+ * The shape a domain has to have before {@link normalizeIdRight} hands it to
+ * `URL` for IDNA conversion.  Anything else, such as an address literal or a
+ * dot-atom using punctuation `URL` would read as a delimiter, is left alone,
+ * since the conversion would silently truncate it.  Combining marks are
+ * allowed: a decomposed spelling is as much a DNS name as its precomposed
+ * equivalent, and IDNA normalizes the two to the same label.
+ */
+const dnsNamePattern = /^[\p{L}\p{N}][\p{L}\p{N}\p{M}\-.]*$/u;
+
+/**
+ * Tells whether a value is a valid `id-right`.
+ *
+ * @param value The value to check.
+ * @returns Whether the value is a valid `id-right`.
+ */
+const isIdRight = (value) => {
+  return isDotAtomText(value) || isNoFoldLiteral(value);
+};
+
+/**
+ * Tells whether a value is a `dot-atom-text`: one or more `atext` runs joined
+ * by single dots, so neither a leading, a trailing, nor a doubled dot.
+ *
+ * @param value The value to check.
+ * @returns Whether the value is a `dot-atom-text`.
+ */
+const isDotAtomText = (value) => {
+  if (value === '') return false;
+  for (const atom of value.split('.')) {
+    if (atom === '') return false;
+    for (const character of atom) {
+      if (!isAtext(character)) return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Tells whether a value is a `no-fold-literal`: an address literal such as
+ * `[192.0.2.1]`.
+ *
+ * An empty literal is rejected, which RFC 5322 would allow: it identifies
+ * nothing, and a generator that produces one is more likely broken than
+ * deliberate.
+ *
+ * @param value The value to check.
+ * @returns Whether the value is a `no-fold-literal`.
+ */
+const isNoFoldLiteral = (value) => {
+  if (value.length < 3 || !value.startsWith('[') || !value.endsWith(']')) {
+    return false;
+  }
+  for (const character of value.slice(1, -1)) {
+    if (!isDtext(character)) return false;
+  }
+  return true;
+};
+
+/**
+ * The ASCII punctuation RFC 5322 allows in an atom, besides letters and digits.
+ */
+const asciiAtextSymbols = "!#$%&'*+-/=?^_`{|}~";
+
+/**
+ * Tells whether a character is `atext`, the character class an atom is built
+ * from, extended with UTF-8 by RFC 6532.
+ *
+ * @param character A single character, which may be a surrogate pair.
+ * @returns Whether the character is `atext`.
+ */
+const isAtext = (character) => {
+  const codePoint = character.codePointAt(0);
+  if (codePoint == null) return false;
+  if (codePoint > 0x7f) return isNonAsciiText(codePoint);
+  return /[A-Za-z0-9]/.test(character) || asciiAtextSymbols.includes(character);
+};
+
+/**
+ * Tells whether a character is `dtext`, the character class the inside of an
+ * address literal is built from, extended with UTF-8 by RFC 6532.
+ *
+ * Angle brackets are excluded although RFC 5322 permits them here.  They are
+ * unambiguous only to a parser that tracks the literal, and an identifier
+ * carrying one would be truncated by every reader that simply looks for the
+ * closing bracket of the field.
+ *
+ * @param character A single character, which may be a surrogate pair.
+ * @returns Whether the character is `dtext`.
+ */
+const isDtext = (character) => {
+  const codePoint = character.codePointAt(0);
+  if (codePoint == null) return false;
+  if (codePoint > 0x7f) return isNonAsciiText(codePoint);
+  return (
+    ((codePoint >= 0x21 && codePoint <= 0x5a) || (codePoint >= 0x5e && codePoint <= 0x7e)) &&
+    character !== '<' &&
+    character !== '>'
+  );
+};
+
+/**
+ * Tells whether a code point beyond ASCII may appear in a header field under
+ * RFC 6532.  An unpaired surrogate may not: it cannot be encoded as UTF-8.
+ *
+ * @param codePoint The code point to check.
+ * @returns Whether the code point is usable.
+ */
+const isNonAsciiText = (codePoint) => {
+  return codePoint < 0xd800 || codePoint > 0xdfff;
+};
+
+/**
+ * Tells whether a value contains a character beyond ASCII.
+ *
+ * @param value The value to check.
+ * @returns Whether the value contains a character beyond ASCII.
+ */
+const hasNonAscii = (value) => {
+  return !/^[\x20-\x7E]*$/.test(value);
+};
+
+/**
+ * Works out the reply threading header fields a transport should write for a
+ * message, from {@link Message.inReplyTo} and {@link Message.references}.
+ *
+ * The three states those fields can be in map onto the result like this:
+ *
+ *  -  A field the message leaves unset is absent from the map.  The message
+ *     does not own the header, so a transport may still write one supplied
+ *     through {@link Message.headers}.
+ *  -  A field set to an empty list maps to `null`.  The message owns the
+ *     header and deliberately writes nothing, which suppresses a custom header
+ *     of the same name.
+ *  -  A field with identifiers in it maps to the formatted field value.
+ *
+ * Keys are the canonical field names, `In-Reply-To` and `References`.  A header
+ * field name is case insensitive, so compare accordingly when deciding whether
+ * a custom header is shadowed.
+ *
+ * @example
+ * ```ts
+ * import { resolveThreadingHeaders } from "@alexify/mailer/message-id";
+ * // for a message replying to <122@example.com>:
+ * // Map { "In-Reply-To" => "<122@example.com>" }
+ * ```
+ *
+ * @param message The message being converted.
+ * @returns The header fields the message owns, keyed by canonical name.
+ * @throws {TypeError} If the message carries an invalid identifier.
+ */
+const resolveThreadingHeaders = (message) => {
+  const resolved = new Map();
+  const fields = [
+    ['In-Reply-To', message.inReplyTo],
+    ['References', message.references],
+  ];
+  for (const [name, ids] of fields) {
+    if (ids == null) continue;
+    resolved.set(name, ids.length < 1 ? null : ids.map(formatMessageId).join(' '));
+  }
+  return resolved;
+};
+
+module.exports = { generateMessageId, parseMessageId, formatMessageId, resolveThreadingHeaders };
diff --git a/src/core/message.js b/src/core/message.js
new file mode 100644
index 0000000..259c600
--- /dev/null
+++ b/src/core/message.js
@@ -0,0 +1,192 @@
+// Ported from upyo v0.7.0 (packages/core/src/message.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { parseAddress } = require('./address.js');
+const { isAttachment } = require('./attachment.js');
+const { resolveCalendarContent } = require('./calendar.js');
+const { parseMessageId } = require('./message-id.js');
+
+/**
+ * Creates a new email {@link Message} based on the provided constructor
+ * parameters.  This function provides a more convenient API for creating
+ * messages compared to constructing a {@link Message} object directly.
+ *
+ * @example
+ * ```typescript
+ * const message = createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient1@example.com",
+ *   subject: "Hello World",
+ *   content: { text: "This is a test message" }
+ * });
+ * ```
+ *
+ * @param constructor The constructor parameters for the message. Uses more
+ *                    user-friendly types like accepting strings for email
+ *                    addresses and `File` objects for attachments.
+ * @returns A new {@link Message} object with all properties normalized and
+ *          validated.
+ * @throws {TypeError} When any email address string cannot be parsed, when an
+ *                     address or attachment carries a carriage return or line
+ *                     feed that could forge header fields, when an attachment
+ *                     object is invalid, when a message identifier is not
+ *                     valid, when the date is not one RFC 5322 can express, or
+ *                     when the calendar content is not a single well-formed
+ *                     iCalendar object declaring one supported method.
+ */
+const createMessage = (constructor) => {
+  const sender = checkAddress('sender', constructor.from);
+  return {
+    sender,
+    recipients: ensureArray(constructor.to).map((to) => checkAddress('recipient', to)),
+    ccRecipients: ensureArray(constructor.cc).map((cc) => checkAddress('CC', cc)),
+    bccRecipients: ensureArray(constructor.bcc).map((bcc) => checkAddress('BCC', bcc)),
+    replyRecipients: ensureArray(constructor.replyTo).map((replyTo) =>
+      checkAddress('reply-to', replyTo),
+    ),
+    // oxlint-disable-next-line array-callback-return -- upstream: the last branch throws
+    attachments: ensureArray(constructor.attachments).map((attachment) => {
+      if (attachment instanceof File) {
+        return checkAttachment({
+          inline: false,
+          filename: attachment.name,
+          content: attachment,
+          contentType:
+            attachment.type == null || attachment.type === ''
+              ? 'application/octet-stream'
+              : attachment.type,
+          contentId: `${crypto.randomUUID()}@${sender.address.replace(/^[^@]*@/, '')}`,
+        });
+      } else if (isAttachment(attachment)) {
+        return checkAttachment(attachment);
+      } else {
+        throwTypeError(`Invalid attachment: ${JSON.stringify(attachment)}`);
+      }
+    }),
+    subject: constructor.subject,
+    content: constructor.content,
+    priority: constructor.priority ?? 'normal',
+    tags: ensureArray(constructor.tags),
+    headers: new Headers(constructor.headers ?? {}),
+    idempotencyKey: constructor.idempotencyKey,
+    messageId:
+      constructor.messageId == null ? undefined : checkMessageId('', constructor.messageId),
+    date: checkDate(constructor.date),
+    inReplyTo: checkMessageIds('in-reply-to ', constructor.inReplyTo),
+    references: checkMessageIds('references ', constructor.references),
+    calendar:
+      constructor.calendar == null ? undefined : resolveCalendarContent(constructor.calendar),
+  };
+};
+
+const throwTypeError = (message) => {
+  throw new TypeError(message);
+};
+
+/**
+ * Normalizes an address and rejects one that could forge header fields.
+ *
+ * A transport that composes a message itself writes the address into a header
+ * field as given, so a carriage return or line feed in it would end that field
+ * and let the rest of the value appear as further fields.  The string form has
+ * always been rejected by {@link parseAddress}; the object form used to pass
+ * through unchecked.
+ *
+ * @param label How the address is described in the error message.
+ * @param address The address, either an object or a string to parse.
+ * @returns The normalized address.
+ * @throws {TypeError} If the string cannot be parsed, or if the resulting
+ * address contains a carriage return or line feed.
+ */
+const checkAddress = (label, address) => {
+  const parsed =
+    typeof address === 'string'
+      ? (parseAddress(address) ??
+        throwTypeError(`Invalid ${label} address: ${JSON.stringify(address)}`))
+      : address;
+  if (/[\r\n]/.test(parsed.address)) {
+    throwTypeError(`Invalid ${label} address: ${JSON.stringify(parsed.address)}`);
+  }
+  return parsed;
+};
+
+/**
+ * Rejects an attachment whose content type or content ID could forge header
+ * fields.
+ *
+ * A transport that composes MIME itself writes both into the part headers as
+ * given, so a carriage return or line feed in either would end that field and
+ * let the rest of the value appear as further fields.  An uploaded file's
+ * declared content type is routinely chosen by whoever uploaded it.
+ *
+ * @param attachment The attachment to check.
+ * @returns The attachment, unchanged.
+ * @throws {TypeError} If the content type or content ID contains a carriage
+ * return or line feed.
+ */
+const checkAttachment = (attachment) => {
+  if (/[\r\n]/.test(attachment.contentType)) {
+    throwTypeError(`Invalid attachment content type: ${JSON.stringify(attachment.contentType)}`);
+  }
+  if (/[\r\n]/.test(attachment.contentId)) {
+    throwTypeError(`Invalid attachment content ID: ${JSON.stringify(attachment.contentId)}`);
+  }
+  return attachment;
+};
+
+/**
+ * Normalizes a message identifier, rejecting one that is not valid.
+ *
+ * A transport writes the identifier into a structured header field as given,
+ * without the RFC 2047 encoding that neutralizes a carriage return or line feed
+ * in a free-form value, so an invalid one has to be refused rather than
+ * repaired.
+ *
+ * @param label How the identifier is described in the error message.
+ * @param id The identifier, with or without the enclosing angle brackets.
+ * @returns The identifier in its bare form.
+ * @throws {TypeError} If the value is not a valid message identifier.
+ */
+const checkMessageId = (label, id) => {
+  return parseMessageId(id) ?? throwTypeError(`Invalid ${label}message ID: ${JSON.stringify(id)}`);
+};
+
+/**
+ * Normalizes a list of message identifiers, preserving the difference between
+ * an absent list and an empty one: the first defers to a header supplied
+ * through {@link MessageConstructor.headers}, while the second suppresses it.
+ *
+ * @param label How the identifiers are described in the error message.
+ * @param ids One identifier, several, or none.
+ * @returns The identifiers in their bare form, or `undefined` if none were
+ *          given.
+ * @throws {TypeError} If any value is not a valid message identifier.
+ */
+const checkMessageIds = (label, ids) => {
+  if (ids == null) return undefined;
+  return (typeof ids === 'string' ? [ids] : ids).map((id) => checkMessageId(label, id));
+};
+
+/**
+ * Checks an origination date and copies it, so that a later mutation of the
+ * caller's `Date` cannot change what a retry sends.
+ *
+ * @param date The date to check, if any.
+ * @returns A copy of the date, or `undefined` if none was given.
+ * @throws {TypeError} If the date is invalid, or earlier than RFC 5322 §3.3
+ * can express.
+ */
+const checkDate = (date) => {
+  if (date == null) return undefined;
+  const time = date instanceof Date ? date.getTime() : Number.NaN;
+  if (Number.isNaN(time) || date.getUTCFullYear() < 1900) {
+    throwTypeError(`Invalid date: ${JSON.stringify(date)}`);
+  }
+  return new Date(time);
+};
+
+const ensureArray = (value) => {
+  return Array.isArray(value) ? value : value == null ? [] : [value];
+};
+
+module.exports = { createMessage };
diff --git a/src/core/priority.js b/src/core/priority.js
new file mode 100644
index 0000000..0e63808
--- /dev/null
+++ b/src/core/priority.js
@@ -0,0 +1,25 @@
+// Ported from upyo v0.7.0 (packages/core/src/priority.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Compares two priority levels and returns a number indicating their
+ * relative order.
+ *
+ * @example Sorting priorities
+ * ```ts
+ * import { comparePriority, type Priority } from "@alexify/mailer/priority";
+ * const priorities: Priority[] = ["normal", "low", "high"];
+ * priorities.sort(comparePriority);
+ * console.log(priorities); // ["high", "normal", "low"]
+ * ```
+ *
+ * @param a The first priority to compare.
+ * @param b The second priority to compare.
+ * @return A negative number if `a` is less than `b`, a positive number
+ *         if `a` is greater than `b`, and zero if they are equal.
+ */
+const comparePriority = (a, b) => {
+  return a === b ? 0 : a === 'high' ? -1 : b === 'high' ? 1 : a === 'low' ? 1 : -1;
+};
+
+module.exports = { comparePriority };
diff --git a/src/core/raw-message.js b/src/core/raw-message.js
new file mode 100644
index 0000000..4b5ec1f
--- /dev/null
+++ b/src/core/raw-message.js
@@ -0,0 +1,192 @@
+// Ported from upyo v0.7.0 (packages/core/src/raw-message.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isEmailAddress } = require('./address.js');
+const { iterateAttachmentContent } = require('./attachment.js');
+
+/** Invalid raw-message metadata or wire structure. @since 0.6.0 */
+class RawMessageValidationError extends TypeError {
+  /** The invalid message field. */
+  field;
+  /** Zero-based byte offset, when the error refers to content. */
+  byteOffset;
+  /** One-based line number, when the error refers to content. */
+  lineNumber;
+
+  /**
+   * Creates a raw-message validation error.
+   * @param message Description of the failure.
+   * @param field The invalid field.
+   * @param byteOffset Optional zero-based content offset.
+   * @param lineNumber Optional one-based line number.
+   */
+  constructor(message, field, byteOffset, lineNumber) {
+    super(message);
+    this.name = 'RawMessageValidationError';
+    this.field = field;
+    this.byteOffset = byteOffset;
+    this.lineNumber = lineNumber;
+  }
+}
+
+/**
+ * Snapshots metadata and observes promised bytes before any asynchronous work.
+ * @param message The raw message to validate.
+ * @returns A replayable plan with a copied envelope.
+ * @throws {RawMessageValidationError} If metadata or the source kind is invalid.
+ * @internal
+ */
+const createRawMessagePlan = (message) => {
+  const content = message?.content;
+  if (content instanceof Promise) content.catch(() => {});
+  const envelope = message?.envelope;
+  if (
+    envelope == null ||
+    (envelope.from !== null && !isEmailAddress(envelope.from)) ||
+    !Array.isArray(envelope.to) ||
+    envelope.to.length === 0 ||
+    !Array.from(envelope.to).every(isEmailAddress)
+  ) {
+    throw new RawMessageValidationError('Invalid raw message envelope.', 'envelope');
+  }
+  if (
+    message.encoding !== undefined &&
+    message.encoding !== '7bit' &&
+    message.encoding !== '8bit' &&
+    message.encoding !== 'utf8'
+  ) {
+    throw new RawMessageValidationError('Invalid raw message encoding.', 'encoding');
+  }
+  if (
+    !(content instanceof Uint8Array) &&
+    !(content instanceof Promise) &&
+    !(content instanceof Blob) &&
+    typeof content !== 'function'
+  ) {
+    throw new RawMessageValidationError('Expected replayable raw message bytes.', 'content');
+  }
+  return {
+    envelope: { from: envelope.from, to: [...envelope.to] },
+    content,
+    encoding: message.encoding,
+    size:
+      content instanceof Uint8Array
+        ? content.byteLength
+        : content instanceof Blob
+          ? content.size
+          : undefined,
+  };
+};
+
+/**
+ * Validates and yields at most 32 KiB per chunk, without prefetching. Chunks
+ * remain valid until the next read; HTTP consumers must copy before enqueueing.
+ * The source's own errors and cancellation reasons are preserved.
+ * @param plan Validated metadata and replayable source.
+ * @param options Cancellation, analysis observations, and transmission checks.
+ * @returns Original bytes in bounded windows.
+ * @throws {RawMessageValidationError} If wire structure or encoding is invalid.
+ * @throws {Error} If the source fails or reading is cancelled.
+ * @internal
+ */
+const iterateRawMessage = async function* (plan, options = {}) {
+  let offset = 0;
+  let line = 1;
+  let column = 0;
+  let pendingCr = false;
+  let headers = true;
+  let nonAscii = false;
+  let sinceYield = 0;
+  const encoding = options.encoding ?? plan.encoding;
+  const fail = (message, field = 'content') => {
+    throw new RawMessageValidationError(message, field, offset, line);
+  };
+  for await (const chunk of iterateAttachmentContent(plan.content, options.signal)) {
+    for (let start = 0; start < chunk.length; start += 32768) {
+      options.signal?.throwIfAborted();
+      const window = chunk.subarray(start, start + 32768);
+      for (const byte of window) {
+        if (pendingCr) {
+          if (byte !== 10) fail('Expected LF after CR.');
+          if (line === 1 && column === 0) {
+            fail('Raw message headers must not be empty.');
+          }
+          if (column === 0) headers = false;
+          pendingCr = false;
+          column = 0;
+          line++;
+        } else if (byte === 13) {
+          pendingCr = true;
+        } else if (byte === 10) {
+          fail('Raw messages must use CRLF line endings.');
+        } else {
+          if (byte === 0) fail('Raw messages must not contain NUL.');
+          if (++column > 998) {
+            fail('Raw message lines must not exceed 998 octets.');
+          }
+          if (byte > 127) {
+            nonAscii = true;
+            if (encoding === '7bit' || (encoding === '8bit' && headers)) {
+              fail('Raw message bytes exceed the declared encoding.', 'encoding');
+            }
+          }
+        }
+        offset++;
+      }
+      if (options.expectedSize !== undefined && offset > options.expectedSize) {
+        fail('Raw message size changed between reads.');
+      }
+      options.onProgress?.({
+        size: offset,
+        encoding: encoding ?? (nonAscii ? 'utf8' : '7bit'),
+      });
+      options.signal?.throwIfAborted();
+      yield window;
+      options.signal?.throwIfAborted();
+      sinceYield += window.length;
+      if (sinceYield >= 1024 * 1024) {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        options.signal?.throwIfAborted();
+        sinceYield = 0;
+      }
+    }
+  }
+  options.signal?.throwIfAborted();
+  if (offset === 0) fail('Raw message headers must not be empty.');
+  if (pendingCr || column !== 0) fail('Raw messages must end with CRLF.');
+  if (options.expectedSize !== undefined && offset !== options.expectedSize) {
+    fail('Raw message size changed between reads.');
+  }
+};
+
+/**
+ * Analyzes one complete traversal without retaining the message in memory.
+ * @param plan Validated metadata and replayable source.
+ * @param signal Cancellation signal.
+ * @param onProgress Optional incremental observations, also allowed to reject.
+ * @returns The byte length and conservative transport encoding.
+ * @throws {RawMessageValidationError} If the raw content is invalid.
+ * @throws {Error} If the source or progress callback fails, or reading is cancelled.
+ * @internal
+ */
+const analyzeRawMessage = async (plan, signal, onProgress) => {
+  let result = { size: 0, encoding: '7bit' };
+  // oxlint-disable-next-line no-unused-vars -- upstream: only the progress callback is read
+  for await (const _ of iterateRawMessage(plan, {
+    signal,
+    onProgress(info) {
+      result = info;
+      onProgress?.(info);
+    },
+  })) {
+    /* Validation happens during iteration. */
+  }
+  return result;
+};
+
+module.exports = {
+  RawMessageValidationError,
+  createRawMessagePlan,
+  iterateRawMessage,
+  analyzeRawMessage,
+};
diff --git a/src/core/receipt.js b/src/core/receipt.js
new file mode 100644
index 0000000..00a8a8e
--- /dev/null
+++ b/src/core/receipt.js
@@ -0,0 +1,253 @@
+// Ported from upyo v0.7.0 (packages/core/src/receipt.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Classifies an HTTP status code for delivery error handling.
+ *
+ * @param statusCode The HTTP status code to classify.
+ * @returns The receipt error category and retryability.
+ */
+const classifyHttpStatus = (statusCode) => {
+  if (statusCode === 401 || statusCode === 403) {
+    return { category: 'auth', retryable: false };
+  }
+  if (statusCode === 408 || statusCode === 504) {
+    return { category: 'timeout', retryable: true };
+  }
+  if (statusCode === 429) {
+    return { category: 'rate-limit', retryable: true };
+  }
+  if (statusCode === 503) {
+    return { category: 'service-unavailable', retryable: true };
+  }
+  if (statusCode >= 400 && statusCode < 500) {
+    return { category: 'validation', retryable: false };
+  }
+  if (statusCode >= 500 && statusCode < 600) {
+    return { category: 'server-error', retryable: true };
+  }
+  return { category: 'unknown', retryable: false };
+};
+
+/**
+ * Classifies an arbitrary delivery failure.
+ *
+ * @param error The error to classify.
+ * @returns The receipt error category, retryability, and default code.
+ */
+const classifyReceiptError = (error) => {
+  const message = getStringProperty(error, 'message') ?? String(error);
+  const name = getStringProperty(error, 'name') ?? '';
+  const text = `${name} ${message}`.toLowerCase();
+
+  if (text.includes('timeout') || text.includes('timed out')) {
+    return { category: 'timeout', retryable: true, code: 'timeout' };
+  }
+  if (
+    text.includes('network') ||
+    text.includes('connect') ||
+    text.includes('fetch failed') ||
+    text.includes('dns') ||
+    text.includes('econnreset') ||
+    text.includes('econnrefused') ||
+    text.includes('enotfound') ||
+    name === 'NetworkError'
+  ) {
+    return { category: 'network', retryable: true, code: 'network' };
+  }
+  if (
+    text.includes('authentication') ||
+    text.includes('authenticate') ||
+    text.includes('authorization') ||
+    text.includes('authorize') ||
+    /\bauth\b/.test(text) ||
+    text.includes('unauthorized') ||
+    text.includes('not authorized') ||
+    text.includes('forbidden') ||
+    text.includes('invalid api key') ||
+    text.includes('invalid token') ||
+    text.includes('401') ||
+    text.includes('403')
+  ) {
+    return { category: 'auth', retryable: false, code: 'auth' };
+  }
+  if (
+    text.includes('rate limit') ||
+    text.includes('rate-limit') ||
+    text.includes('too many requests') ||
+    text.includes('quota') ||
+    text.includes('throttle') ||
+    text.includes('429')
+  ) {
+    return {
+      category: 'rate-limit',
+      retryable: true,
+      code: 'rate-limit',
+    };
+  }
+  if (
+    text.includes('invalid') ||
+    text.includes('malformed') ||
+    text.includes('validation') ||
+    text.includes('bad request') ||
+    text.includes('400') ||
+    text.includes('422')
+  ) {
+    return { category: 'validation', retryable: false, code: 'validation' };
+  }
+  if (
+    text.includes('rejected') ||
+    text.includes('bounce') ||
+    text.includes('complaint') ||
+    text.includes('suppressed') ||
+    text.includes('unsubscribed')
+  ) {
+    return { category: 'rejected', retryable: false, code: 'rejected' };
+  }
+  if (
+    text.includes('service unavailable') ||
+    text.includes('temporarily unavailable') ||
+    text.includes('503')
+  ) {
+    return {
+      category: 'service-unavailable',
+      retryable: true,
+      code: 'service-unavailable',
+    };
+  }
+  if (
+    text.includes('internal server error') ||
+    text.includes('bad gateway') ||
+    text.includes('500') ||
+    text.includes('502')
+  ) {
+    return {
+      category: 'server-error',
+      retryable: true,
+      code: 'server-error',
+    };
+  }
+  if (text.includes('config') || text.includes('unsupported')) {
+    return {
+      category: 'configuration',
+      retryable: false,
+      code: 'configuration',
+    };
+  }
+  return { category: 'unknown', retryable: false, code: 'unknown' };
+};
+
+/**
+ * Creates structured information about a delivery failure.
+ *
+ * @param message Human-readable error message.
+ * @param options Optional structured error metadata.
+ * @returns A structured receipt error.
+ */
+const createReceiptError = (message, options = {}) => {
+  const classification =
+    options.statusCode == null
+      ? classifyReceiptError(message)
+      : classifyHttpStatus(options.statusCode);
+  const category = options.category ?? classification.category;
+  const retryable = options.retryable ?? classification.retryable;
+  const code =
+    options.code ??
+    (options.statusCode == null
+      ? options.category != null
+        ? category
+        : (classification.code ?? category)
+      : `http.${options.statusCode}`);
+
+  return omitUndefined({
+    message,
+    category,
+    code,
+    retryable,
+    provider: options.provider,
+    statusCode: options.statusCode,
+    retryAfterMilliseconds: options.retryAfterMilliseconds,
+    providerDetails: options.providerDetails,
+  });
+};
+
+/**
+ * Creates a failed receipt with human-readable and structured errors.
+ *
+ * @param error Error message, structured error, or list of structured errors.
+ * @param options Optional receipt and error metadata.
+ * @returns A failed receipt.
+ */
+const createFailedReceipt = (error, options = {}) => {
+  const errors =
+    options.errors ??
+    (typeof error === 'string'
+      ? [createReceiptError(error, options)]
+      : Array.isArray(error)
+        ? error.map((item) => (typeof item === 'string' ? createReceiptError(item, options) : item))
+        : [error]);
+  const errorMessages =
+    typeof error === 'string'
+      ? [error]
+      : Array.isArray(error)
+        ? error.map((item) => (typeof item === 'string' ? item : item.message))
+        : errors.map((receiptError) => receiptError.message);
+  const retryable = options.retryable ?? errors.some((receiptError) => receiptError.retryable);
+  const provider = options.provider ?? errors[0]?.provider;
+
+  return omitUndefined({
+    successful: false,
+    errorMessages,
+    errors,
+    retryable,
+    provider,
+    attempts: options.attempts,
+    timestamp: options.timestamp ?? new Date().toISOString(),
+  });
+};
+
+/**
+ * Parses an HTTP `Retry-After` header value into milliseconds.
+ *
+ * @param value Header value to parse.
+ * @param now Current time used when parsing HTTP dates.
+ * @returns Retry delay in milliseconds, or `undefined` if invalid.
+ */
+const parseRetryAfter = (value, now = new Date()) => {
+  if (value == null || value.trim() === '') return undefined;
+
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) {
+    const delay = Number(trimmed) * 1000;
+    return delay;
+  }
+
+  const timestamp = Date.parse(trimmed);
+  if (Number.isNaN(timestamp)) return undefined;
+
+  const delay = timestamp - now.getTime();
+  return delay > 0 ? delay : undefined;
+};
+
+const getStringProperty = (value, property) => {
+  if (value instanceof Error) {
+    return value[property];
+  }
+  if (typeof value !== 'object' || value == null || !(property in value)) {
+    return undefined;
+  }
+  const propertyValue = value[property];
+  return propertyValue == null ? undefined : String(propertyValue);
+};
+
+const omitUndefined = (value) => {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+};
+
+module.exports = {
+  classifyHttpStatus,
+  classifyReceiptError,
+  createReceiptError,
+  createFailedReceipt,
+  parseRetryAfter,
+};
diff --git a/src/core/transport.js b/src/core/transport.js
new file mode 100644
index 0000000..c4f6093
--- /dev/null
+++ b/src/core/transport.js
@@ -0,0 +1,22 @@
+// Ported from upyo v0.7.0 (packages/core/src/transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Checks whether a transport exposes raw MIME delivery.
+ * @param transport The transport to inspect.
+ * @returns Whether the transport implements the optional raw capability.
+ */
+const isRawTransport = (transport) => {
+  return 'sendRaw' in transport && typeof transport.sendRaw === 'function';
+};
+
+/**
+ * Checks whether a transport exposes configuration verification.
+ * @param transport The transport to inspect.
+ * @returns Whether the transport implements the optional verification capability.
+ */
+const isVerifiableTransport = (transport) => {
+  return 'verify' in transport && typeof transport.verify === 'function';
+};
+
+module.exports = { isRawTransport, isVerifiableTransport };
diff --git a/src/index.js b/src/index.js
index 6039197..9f3b503 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,3 +1,68 @@
+// The root entry: the message model and the transport contract ported from
+// @upyo/core 0.7.0 (src/core/), in upstream's order, and the mailer.
+const { formatAddress, parseAddress, isEmailAddress } = require('./core/address.js');
+const { combineSignals } = require('./core/abort-signal.js');
+const {
+  isAttachment,
+  iterateAttachmentContent,
+  readAttachmentContent,
+} = require('./core/attachment.js');
+const {
+  parseCalendarMethod,
+  resolveCalendarContent,
+  createCalendarAttachment,
+} = require('./core/calendar.js');
+const { createMessage } = require('./core/message.js');
+const {
+  generateMessageId,
+  parseMessageId,
+  formatMessageId,
+  resolveThreadingHeaders,
+} = require('./core/message-id.js');
+const { comparePriority } = require('./core/priority.js');
+const {
+  classifyHttpStatus,
+  classifyReceiptError,
+  createReceiptError,
+  createFailedReceipt,
+  parseRetryAfter,
+} = require('./core/receipt.js');
+const { isRawTransport, isVerifiableTransport } = require('./core/transport.js');
+const {
+  RawMessageValidationError,
+  createRawMessagePlan,
+  iterateRawMessage,
+  analyzeRawMessage,
+} = require('./core/raw-message.js');
 const { createMailer } = require('./mailer.js');
 
-module.exports = { createMailer };
+module.exports = {
+  formatAddress,
+  parseAddress,
+  isEmailAddress,
+  combineSignals,
+  isAttachment,
+  iterateAttachmentContent,
+  readAttachmentContent,
+  parseCalendarMethod,
+  resolveCalendarContent,
+  createCalendarAttachment,
+  createMessage,
+  generateMessageId,
+  parseMessageId,
+  formatMessageId,
+  resolveThreadingHeaders,
+  comparePriority,
+  classifyHttpStatus,
+  classifyReceiptError,
+  createReceiptError,
+  createFailedReceipt,
+  parseRetryAfter,
+  isRawTransport,
+  isVerifiableTransport,
+  RawMessageValidationError,
+  createRawMessagePlan,
+  iterateRawMessage,
+  analyzeRawMessage,
+  createMailer,
+};
diff --git a/tests/types/index.test-d.ts b/tests/types/index.test-d.ts
index dda90ef..d636af5 100644
--- a/tests/types/index.test-d.ts
+++ b/tests/types/index.test-d.ts
@@ -1,5 +1,22 @@
-import { expectError, expectType } from 'tsd';
-import { createMailer, type Mailer } from '../../index.js';
+import { expectAssignable, expectError, expectType } from 'tsd';
+import {
+  createFailedReceipt,
+  createMailer,
+  createMessage,
+  createReceiptError,
+  isRawTransport,
+  isVerifiableTransport,
+  parseAddress,
+  RawMessageValidationError,
+  type Address,
+  type Mailer,
+  type Message,
+  type RawTransport,
+  type Receipt,
+  type ReceiptError,
+  type Transport,
+  type VerifiableTransport,
+} from '../../index.js';
 
 const mailer = createMailer({});
 expectType<Mailer>(mailer);
@@ -8,3 +25,51 @@ expectType<Promise<unknown>>(mailer.send({ to: 'alex@example.com', subject: 'Hel
 expectError(createMailer());
 expectError(createMailer('smtp://localhost'));
 expectError(mailer.send('Hello'));
+
+// The message model.
+const message = createMessage({
+  from: 'Alex <alex@example.com>',
+  to: ['bob@example.com', { address: 'carol@example.com' }],
+  subject: 'Hello',
+  content: { text: 'Hi', html: '<p>Hi</p>' },
+});
+expectType<Message>(message);
+expectType<Address>(message.sender);
+expectType<readonly Address[]>(message.recipients);
+expectError(createMessage({ from: 'alex@example.com', subject: 'Hello' }));
+expectError(createMessage({ from: 'alex', to: 'bob@example.com', subject: 'x', content: {} }));
+expectType<Address | undefined>(parseAddress('Alex <alex@example.com>'));
+
+// A receipt narrows on `successful`.
+const receipt = {} as Receipt<'smtp'>;
+if (receipt.successful) {
+  expectType<string>(receipt.messageId);
+} else {
+  expectType<readonly string[]>(receipt.errorMessages);
+}
+
+// The provider id flows through errors, receipts and transports
+// (receipt.test.ts of upstream checks the same at the type level).
+const typedError: ReceiptError<'mailgun'> = createReceiptError('Too many requests', {
+  provider: 'mailgun',
+  statusCode: 429,
+});
+expectType<'mailgun' | undefined>(typedError.provider);
+const typedReceipt: Receipt<'sendgrid'> = createFailedReceipt('Too many requests', {
+  provider: 'sendgrid',
+  statusCode: 429,
+});
+expectType<'sendgrid' | undefined>(typedReceipt.provider);
+
+const transport: Transport<'smtp'> = {
+  id: 'smtp',
+  send: () => Promise.resolve({ successful: true, messageId: 'message-id', provider: 'smtp' }),
+  async *sendMany() {
+    yield { successful: true, messageId: 'message-id', provider: 'smtp' } as const;
+  },
+};
+expectType<'smtp'>(transport.id);
+if (isRawTransport(transport)) expectType<RawTransport<'smtp'>>(transport);
+if (isVerifiableTransport(transport)) expectType<VerifiableTransport<'smtp'>>(transport);
+
+expectAssignable<TypeError>(new RawMessageValidationError('Bad line.', 'content', 12, 2));
diff --git a/tests/unit/abort-signal.test.js b/tests/unit/abort-signal.test.js
new file mode 100644
index 0000000..ef38ade
--- /dev/null
+++ b/tests/unit/abort-signal.test.js
@@ -0,0 +1,42 @@
+// Ported from upyo v0.7.0 (packages/core/src/abort-signal.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { combineSignals } = require('../../src/core/abort-signal.js');
+
+describe('combineSignals', () => {
+  it('returns the primary signal when no external signal is provided', () => {
+    const controller = new AbortController();
+    const combined = combineSignals(controller.signal);
+
+    assert.equal(combined.signal, controller.signal);
+    combined.cleanup();
+  });
+
+  it('aborts when the primary signal aborts', () => {
+    const reason = new Error('Timed out.');
+    const timeout = new AbortController();
+    const external = new AbortController();
+    const combined = combineSignals(timeout.signal, external.signal);
+
+    timeout.abort(reason);
+
+    assert.ok(combined.signal.aborted);
+    assert.equal(combined.signal.reason, reason);
+    combined.cleanup();
+  });
+
+  it('aborts when the external signal aborts', () => {
+    const reason = new Error('Cancelled.');
+    const timeout = new AbortController();
+    const external = new AbortController();
+    const combined = combineSignals(timeout.signal, external.signal);
+
+    external.abort(reason);
+
+    assert.ok(combined.signal.aborted);
+    assert.equal(combined.signal.reason, reason);
+    combined.cleanup();
+  });
+});
diff --git a/tests/unit/address.test.js b/tests/unit/address.test.js
new file mode 100644
index 0000000..18a3946
--- /dev/null
+++ b/tests/unit/address.test.js
@@ -0,0 +1,324 @@
+// Ported from upyo v0.7.0 (packages/core/src/address.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { formatAddress, isEmailAddress, parseAddress } = require('../../src/core/address.js');
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+
+test('formatAddress()', () => {
+  const addr = formatAddress({ name: 'John Doe', address: 'john@example.com' });
+  assert.strictEqual(addr, 'John Doe <john@example.com>');
+  const addr2 = formatAddress({ address: 'jane@example.com' });
+  assert.strictEqual(addr2, 'jane@example.com');
+});
+
+test('parseAddress()', () => {
+  // Test plain email address
+  const addr1 = parseAddress('john@example.com');
+  assert.deepStrictEqual(addr1, { address: 'john@example.com' });
+
+  // Test email with name
+  const addr2 = parseAddress('John Doe <john@example.com>');
+  assert.deepStrictEqual(addr2, {
+    name: 'John Doe',
+    address: 'john@example.com',
+  });
+
+  // Test email with quoted name
+  const addr3 = parseAddress('"John Doe" <john@example.com>');
+  assert.deepStrictEqual(addr3, {
+    name: 'John Doe',
+    address: 'john@example.com',
+  });
+
+  // Test email with angle brackets only
+  const addr4 = parseAddress('<john@example.com>');
+  assert.deepStrictEqual(addr4, { address: 'john@example.com' });
+
+  // Test complex valid email addresses
+  const addr5 = parseAddress('user.name+tag@example.com');
+  assert.deepStrictEqual(addr5, { address: 'user.name+tag@example.com' });
+
+  const addr6 = parseAddress('test@sub.example.com');
+  assert.deepStrictEqual(addr6, { address: 'test@sub.example.com' });
+
+  // Test quoted local part
+  const addr7 = parseAddress('"test@test"@example.com');
+  assert.deepStrictEqual(addr7, { address: '"test@test"@example.com' });
+
+  // Test domain literal
+  const addr8 = parseAddress('test@[192.168.1.1]');
+  assert.deepStrictEqual(addr8, { address: 'test@[192.168.1.1]' });
+
+  // Test invalid addresses - should return undefined
+  assert.strictEqual(parseAddress(''), undefined);
+  assert.strictEqual(parseAddress('   '), undefined);
+  assert.strictEqual(parseAddress('invalid'), undefined);
+  assert.strictEqual(parseAddress('@example.com'), undefined);
+  assert.strictEqual(parseAddress('user@'), undefined);
+  assert.strictEqual(parseAddress('user@@example.com'), undefined);
+  assert.strictEqual(parseAddress('.user@example.com'), undefined);
+  assert.strictEqual(parseAddress('user.@example.com'), undefined);
+  assert.strictEqual(parseAddress('user..name@example.com'), undefined);
+  assert.strictEqual(parseAddress('John Doe <invalid>'), undefined);
+  assert.strictEqual(parseAddress('<invalid>'), undefined);
+  assert.strictEqual(parseAddress('test@[999.999.999.999]'), undefined);
+
+  // Test edge cases
+  assert.strictEqual(parseAddress(null), undefined);
+  assert.strictEqual(parseAddress(undefined), undefined);
+  assert.strictEqual(parseAddress(123), undefined);
+});
+
+test('parseAddress() roundtrip with formatAddress()', () => {
+  // Test that parseAddress and formatAddress are inverses
+  const testCases = [
+    'john@example.com',
+    'John Doe <john@example.com>',
+    'user.name+tag@example.sub.com',
+  ];
+
+  for (const testCase of testCases) {
+    const parsed = parseAddress(testCase);
+    assert.notStrictEqual(parsed, undefined);
+    const formatted = formatAddress(parsed);
+    const reparsed = parseAddress(formatted);
+    assert.deepStrictEqual(parsed, reparsed);
+  }
+});
+
+test('parseAddress() - complex quoted string cases', () => {
+  // Test quoted strings with special characters
+  const addr1 = parseAddress('"user with spaces"@example.com');
+  assert.deepStrictEqual(addr1, { address: '"user with spaces"@example.com' });
+
+  // Test quoted string with escaped quotes
+  const addr2 = parseAddress('"user\\"quote"@example.com');
+  assert.deepStrictEqual(addr2, { address: '"user\\"quote"@example.com' });
+
+  // Test quoted string with backslash
+  const addr3 = parseAddress('"user\\\\backslash"@example.com');
+  assert.deepStrictEqual(addr3, { address: '"user\\\\backslash"@example.com' });
+
+  // Test quoted string with dot
+  const addr4 = parseAddress('".user.name."@example.com');
+  assert.deepStrictEqual(addr4, { address: '".user.name."@example.com' });
+
+  // Test quoted string with @ symbol
+  const addr5 = parseAddress('"user@domain"@example.com');
+  assert.deepStrictEqual(addr5, { address: '"user@domain"@example.com' });
+
+  // Test invalid quoted strings
+  assert.strictEqual(parseAddress('"unterminated@example.com'), undefined);
+  assert.strictEqual(parseAddress('unterminated"@example.com'), undefined);
+  assert.strictEqual(parseAddress('"newline\n"@example.com'), undefined);
+  assert.strictEqual(parseAddress('"carriage\r"@example.com'), undefined);
+  assert.strictEqual(parseAddress('"unescaped"quote"@example.com'), undefined);
+});
+
+test('parseAddress() - domain literal cases', () => {
+  // Test IPv4 address literals
+  const addr1 = parseAddress('user@[192.168.1.1]');
+  assert.deepStrictEqual(addr1, { address: 'user@[192.168.1.1]' });
+
+  const addr2 = parseAddress('user@[127.0.0.1]');
+  assert.deepStrictEqual(addr2, { address: 'user@[127.0.0.1]' });
+
+  // Test IPv6 address literals (these may not be supported by URL.canParse)
+  const addr3 = parseAddress('user@[2001:db8::1]');
+  // IPv6 literals might not be supported by current implementation
+  if (addr3) {
+    assert.deepStrictEqual(addr3, { address: 'user@[2001:db8::1]' });
+  }
+
+  const addr4 = parseAddress('user@[::1]');
+  // IPv6 literals might not be supported by current implementation
+  if (addr4) {
+    assert.deepStrictEqual(addr4, { address: 'user@[::1]' });
+  }
+
+  // Test invalid domain literals (current implementation may be permissive due to URL.canParse)
+  // Note: Some invalid formats may not be rejected by current implementation
+  assert.strictEqual(parseAddress('user@[999.999.999.999]'), undefined);
+  assert.strictEqual(parseAddress('user@[192.168.1.1'), undefined);
+  assert.strictEqual(parseAddress('user@192.168.1.1]'), undefined);
+});
+
+test('parseAddress() - international domain names', () => {
+  // Test internationalized domain names (punycode)
+  const addr1 = parseAddress('user@xn--e1afmkfd.xn--p1ai'); // пример.рф
+  assert.deepStrictEqual(addr1, { address: 'user@xn--e1afmkfd.xn--p1ai' });
+
+  const addr2 = parseAddress('user@xn--fsq.xn--0zwm56d'); // 测试.测试
+  assert.deepStrictEqual(addr2, { address: 'user@xn--fsq.xn--0zwm56d' });
+
+  // Test Unicode domain names (these should be valid)
+  const addr3 = parseAddress('user@한글.kr');
+  assert.deepStrictEqual(addr3, { address: 'user@한글.kr' });
+
+  const addr4 = parseAddress('user@例え.テスト');
+  assert.deepStrictEqual(addr4, { address: 'user@例え.テスト' });
+});
+
+test('parseAddress() - internationalized local parts', () => {
+  assert.deepStrictEqual(parseAddress('josé@example.com'), {
+    address: 'josé@example.com',
+  });
+  assert.deepStrictEqual(parseAddress('用户@例子.广告'), {
+    address: '用户@例子.广告',
+  });
+  assert.deepStrictEqual(parseAddress('"δοκιμή"@example.com'), {
+    address: '"δοκιμή"@example.com',
+  });
+  assert.deepStrictEqual(parseAddress('😀@example.com'), {
+    address: '😀@example.com',
+  });
+  assert.deepStrictEqual(parseAddress('"😀"@example.com'), {
+    address: '"😀"@example.com',
+  });
+
+  assert.strictEqual(parseAddress('josé name@example.com'), undefined);
+  assert.strictEqual(parseAddress('josé()@example.com'), undefined);
+  assert.strictEqual(parseAddress('"josé\t"@example.com'), undefined);
+  assert.strictEqual(parseAddress('"josé\\"@example.com'), undefined);
+  assert.ok(!isEmailAddress(`invalid\ud800@example.com`));
+});
+
+test('parseAddress() - internationalized local-part octet limit', () => {
+  const maximum = `${'é'.repeat(32)}@example.com`;
+  const tooLong = `${'é'.repeat(33)}@example.com`;
+
+  assert.deepStrictEqual(parseAddress(maximum), { address: maximum });
+  assert.strictEqual(parseAddress(tooLong), undefined);
+});
+
+test('parseAddress() - complex name parsing', () => {
+  // Test names with various quote combinations
+  const addr1 = parseAddress('John "Johnny" Doe <john@example.com>');
+  assert.deepStrictEqual(addr1, {
+    name: 'John "Johnny" Doe',
+    address: 'john@example.com',
+  });
+
+  // Test names with special characters
+  const addr2 = parseAddress('José María <jose@example.com>');
+  assert.deepStrictEqual(addr2, {
+    name: 'José María',
+    address: 'jose@example.com',
+  });
+
+  // Test names with comma
+  const addr3 = parseAddress('"Doe, John" <john@example.com>');
+  assert.deepStrictEqual(addr3, {
+    name: 'Doe, John',
+    address: 'john@example.com',
+  });
+
+  // Test names with parentheses
+  const addr4 = parseAddress('John Doe (Company) <john@example.com>');
+  assert.deepStrictEqual(addr4, {
+    name: 'John Doe (Company)',
+    address: 'john@example.com',
+  });
+
+  // Test names with extra whitespace
+  const addr5 = parseAddress('  John   Doe  <john@example.com>');
+  assert.deepStrictEqual(addr5, {
+    name: 'John   Doe',
+    address: 'john@example.com',
+  });
+});
+
+test('parseAddress() - edge cases with valid email patterns', () => {
+  // The local-part limit is 64 octets.
+  const maxLocal = 'a'.repeat(64) + '@example.com';
+  assert.deepStrictEqual(parseAddress(maxLocal), { address: maxLocal });
+  assert.strictEqual(parseAddress('a'.repeat(65) + '@example.com'), undefined);
+
+  // Test very long domain name (close to 253 char limit)
+  const longDomain = 'user@' + 'a'.repeat(60) + '.com';
+  const addr3 = parseAddress(longDomain);
+  assert.deepStrictEqual(addr3, { address: longDomain });
+
+  // Test single character local and domain parts
+  const addr4 = parseAddress('a@b.c');
+  assert.deepStrictEqual(addr4, { address: 'a@b.c' });
+
+  // Test email with multiple subdomains
+  const addr5 = parseAddress('user@mail.subdomain.example.com');
+  assert.deepStrictEqual(addr5, { address: 'user@mail.subdomain.example.com' });
+
+  // Test email with numbers
+  const addr6 = parseAddress('user123@example123.com');
+  assert.deepStrictEqual(addr6, { address: 'user123@example123.com' });
+
+  // Test email with hyphens and underscores
+  const addr7 = parseAddress('user_name-test@sub-domain.example.com');
+  assert.deepStrictEqual(addr7, {
+    address: 'user_name-test@sub-domain.example.com',
+  });
+});
+
+test('parseAddress() - boundary and malformed cases', () => {
+  // Test consecutive dots in local part (invalid)
+  assert.strictEqual(parseAddress('user..name@example.com'), undefined);
+
+  // Test local part starting with dot (invalid)
+  assert.strictEqual(parseAddress('.user@example.com'), undefined);
+
+  // Test local part ending with dot (invalid)
+  assert.strictEqual(parseAddress('user.@example.com'), undefined);
+
+  // Test empty local part
+  assert.strictEqual(parseAddress('@example.com'), undefined);
+
+  // Test empty domain part
+  assert.strictEqual(parseAddress('user@'), undefined);
+
+  // Test multiple @ symbols outside quotes
+  assert.strictEqual(parseAddress('user@domain@example.com'), undefined);
+
+  // Test email with space (invalid without quotes)
+  assert.strictEqual(parseAddress('user name@example.com'), undefined);
+
+  // Test email with tabs
+  assert.strictEqual(parseAddress('user\t@example.com'), undefined);
+
+  // Test incomplete angle bracket formats
+  assert.strictEqual(parseAddress('John Doe <john@example.com'), undefined);
+  assert.strictEqual(parseAddress('John Doe john@example.com>'), undefined);
+
+  // Test edge cases that might parse differently than expected
+  const spaceInBrackets = parseAddress('John Doe < john@example.com>');
+  // Current implementation might handle spaces differently - just verify it doesn't crash
+  assert.ok(spaceInBrackets === undefined || typeof spaceInBrackets === 'object');
+
+  // Test malformed quoted names
+  const malformedQuote1 = parseAddress('"John Doe <john@example.com>');
+  assert.ok(malformedQuote1 === undefined || typeof malformedQuote1 === 'object');
+
+  const malformedQuote2 = parseAddress('John Doe" <john@example.com>');
+  assert.ok(malformedQuote2 === undefined || typeof malformedQuote2 === 'object');
+
+  // Test edge cases that may be handled differently by current implementation
+  // Note: Current implementation uses URL.canParse which may be permissive for some invalid domains
+  const doubleDots = parseAddress('user@example..com');
+  const leadingDot = parseAddress('user@.example.com');
+  const invalidIp = parseAddress('user@[invalid-ip]');
+
+  // These should either be undefined or valid objects - just ensure they don't crash
+  assert.ok(doubleDots === undefined || typeof doubleDots === 'object');
+  assert.ok(leadingDot === undefined || typeof leadingDot === 'object');
+  assert.ok(invalidIp === undefined || typeof invalidIp === 'object');
+});
+
+test('parseAddress() - should not allow newlines', () => {
+  // Test for SMTP command injection vulnerabilities
+  assert.strictEqual(parseAddress('test@example.com\r\nVRFY root'), undefined);
+  assert.strictEqual(parseAddress('test@example.com\nVRFY root'), undefined);
+  assert.strictEqual(parseAddress('test@example.com\rVRFY root'), undefined);
+  assert.strictEqual(parseAddress('sender@example.com>\r\nVRFY root'), undefined);
+  assert.strictEqual(parseAddress('"test\r\n"@example.com'), undefined);
+});
+
+// cSpell: ignore reparsed punycode
diff --git a/tests/unit/attachment-content.test.js b/tests/unit/attachment-content.test.js
new file mode 100644
index 0000000..7e80d9c
--- /dev/null
+++ b/tests/unit/attachment-content.test.js
@@ -0,0 +1,139 @@
+// Ported from upyo v0.7.0 (packages/core/src/attachment-content.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { Buffer } = require('node:buffer');
+const { describe, it } = require('node:test');
+const { iterateAttachmentContent, readAttachmentContent } = require('../../src/core/attachment.js');
+
+describe('attachment content', () => {
+  it('does not return bytes when cancellation wins before the await resumes', async () => {
+    const controller = new AbortController();
+    let finish;
+    const input = new Promise((resolve) => (finish = resolve));
+    const pending = readAttachmentContent(input, controller.signal);
+    await Promise.resolve();
+    finish(new Uint8Array([1]));
+    queueMicrotask(() => controller.abort(new TypeError('Canceled.')));
+    await assert.rejects(pending, (error) => error === controller.signal.reason);
+  });
+  it('copies reusable Buffer chunks rather than retaining their slice views', async () => {
+    const bytes = Buffer.from([1]);
+    const collected = await readAttachmentContent(async function* () {
+      yield bytes;
+      bytes[0] = 2;
+      yield bytes;
+    });
+    assert.deepEqual(collected, new Uint8Array([1, 2]));
+  });
+  it('retains byte array identity and reads blobs', async () => {
+    const bytes = new Uint8Array([1, 2, 3]);
+    assert.equal(await readAttachmentContent(bytes), bytes);
+    assert.equal(await readAttachmentContent(Promise.resolve(bytes)), bytes);
+    assert.deepEqual(await readAttachmentContent(new Blob([bytes])), bytes);
+  });
+
+  it('reopens factories and copies chunks before the producer reuses them', async () => {
+    let calls = 0;
+    const source = async function* () {
+      calls++;
+      const buffer = new Uint8Array([1]);
+      yield buffer;
+      buffer[0] = 2;
+      yield buffer;
+    };
+    assert.deepEqual(await readAttachmentContent(source), new Uint8Array([1, 2]));
+    assert.deepEqual(await readAttachmentContent(source), new Uint8Array([1, 2]));
+    assert.equal(calls, 2);
+  });
+
+  it('requests return immediately when an outstanding next is aborted', async () => {
+    const controller = new AbortController();
+    let returns = 0;
+    let sourceSignal;
+    const source = (signal) => {
+      sourceSignal = signal;
+      return {
+        [Symbol.asyncIterator]() {
+          return {
+            next: () => new Promise(() => {}),
+            return: () => {
+              returns++;
+              return new Promise(() => {});
+            },
+          };
+        },
+      };
+    };
+    const pending = readAttachmentContent(source, controller.signal);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    const reason = new TypeError('Canceled.');
+    controller.abort(reason);
+    await assert.rejects(pending, (error) => error === reason);
+    assert.ok(sourceSignal?.aborted);
+    assert.equal(returns, 1);
+  });
+
+  it('closes a late factory result without pulling it', async () => {
+    const controller = new AbortController();
+    let resolve;
+    let returns = 0;
+    const pending = readAttachmentContent(
+      // oxlint-disable-next-line promise/param-names -- upstream: `resolve` is the outer binding
+      () => new Promise((done) => (resolve = done)),
+      controller.signal,
+    );
+    await Promise.resolve();
+    controller.abort();
+    await assert.rejects(pending);
+    resolve({
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            assert.fail('A canceled factory must not be pulled.');
+          },
+          return() {
+            returns++;
+            return Promise.resolve({ done: true, value: undefined });
+          },
+        };
+      },
+    });
+    // oxlint-disable-next-line promise/param-names -- upstream: `resolve` is the outer binding
+    await new Promise((done) => setTimeout(done, 0));
+    assert.equal(returns, 1);
+  });
+
+  it('aborts the source and closes it on early consumer exit', async () => {
+    let closed = false;
+    let sourceSignal;
+    for await (const chunk of iterateAttachmentContent(async function* (signal) {
+      sourceSignal = signal;
+      try {
+        yield new Uint8Array([1]);
+        assert.fail('Unexpected read ahead.');
+      } finally {
+        closed = true;
+      }
+    })) {
+      assert.equal(chunk[0], 1);
+      break;
+    }
+    assert.ok(closed);
+    assert.ok(sourceSignal?.aborted);
+  });
+
+  it('allows timers to cancel an endless stream of empty chunks', async () => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10);
+    try {
+      await assert.rejects(
+        readAttachmentContent(async function* () {
+          while (true) yield new Uint8Array();
+        }, controller.signal),
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  });
+});
diff --git a/tests/unit/attachment.test.js b/tests/unit/attachment.test.js
new file mode 100644
index 0000000..bcd1e89
--- /dev/null
+++ b/tests/unit/attachment.test.js
@@ -0,0 +1,177 @@
+// Ported from upyo v0.7.0 (packages/core/src/attachment.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isAttachment } = require('../../src/core/attachment.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+
+describe('isAttachment', () => {
+  it('should return true for valid attachment with Uint8Array content', () => {
+    const attachment = {
+      inline: false,
+      filename: 'test.pdf',
+      content: new Uint8Array([1, 2, 3]),
+      contentType: 'application/pdf',
+      contentId: 'test-id',
+    };
+
+    assert.ok(isAttachment(attachment));
+  });
+
+  it('should return true for valid attachment with Promise<Uint8Array> content', () => {
+    const attachment = {
+      inline: true,
+      filename: 'image.png',
+      content: Promise.resolve(new Uint8Array([1, 2, 3])),
+      contentType: 'image/png',
+      contentId: 'image-id',
+    };
+
+    assert.ok(isAttachment(attachment));
+  });
+
+  it('should return false for null', () => {
+    assert.ok(!isAttachment(null));
+  });
+
+  it('should return false for undefined', () => {
+    assert.ok(!isAttachment(undefined));
+  });
+
+  it('should return false for primitive values', () => {
+    assert.ok(!isAttachment('string'));
+    assert.ok(!isAttachment(123));
+    assert.ok(!isAttachment(true));
+  });
+
+  it('should return false for empty object', () => {
+    assert.ok(!isAttachment({}));
+  });
+
+  it('should return false when missing inline property', () => {
+    const obj = {
+      filename: 'test.pdf',
+      content: new Uint8Array([1, 2, 3]),
+      contentType: 'application/pdf',
+      contentId: 'test-id',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when missing filename property', () => {
+    const obj = {
+      inline: false,
+      content: new Uint8Array([1, 2, 3]),
+      contentType: 'application/pdf',
+      contentId: 'test-id',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when missing content property', () => {
+    const obj = {
+      inline: false,
+      filename: 'test.pdf',
+      contentType: 'application/pdf',
+      contentId: 'test-id',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when missing contentType property', () => {
+    const obj = {
+      inline: false,
+      filename: 'test.pdf',
+      content: new Uint8Array([1, 2, 3]),
+      contentId: 'test-id',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when missing contentId property', () => {
+    const obj = {
+      inline: false,
+      filename: 'test.pdf',
+      content: new Uint8Array([1, 2, 3]),
+      contentType: 'application/pdf',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when inline is not boolean', () => {
+    const obj = {
+      inline: 'false',
+      filename: 'test.pdf',
+      content: new Uint8Array([1, 2, 3]),
+      contentType: 'application/pdf',
+      contentId: 'test-id',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when filename is not string', () => {
+    const obj = {
+      inline: false,
+      filename: 123,
+      content: new Uint8Array([1, 2, 3]),
+      contentType: 'application/pdf',
+      contentId: 'test-id',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when content is not Uint8Array or Promise', () => {
+    const obj = {
+      inline: false,
+      filename: 'test.pdf',
+      content: 'invalid content',
+      contentType: 'application/pdf',
+      contentId: 'test-id',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when contentType is not string', () => {
+    const obj = {
+      inline: false,
+      filename: 'test.pdf',
+      content: new Uint8Array([1, 2, 3]),
+      contentType: 123,
+      contentId: 'test-id',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when contentId is not string', () => {
+    const obj = {
+      inline: false,
+      filename: 'test.pdf',
+      content: new Uint8Array([1, 2, 3]),
+      contentType: 'application/pdf',
+      contentId: 123,
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+
+  it('should return false when content is not a proper Promise', () => {
+    const obj = {
+      inline: false,
+      filename: 'test.pdf',
+      content: { then: 'not a function' },
+      contentType: 'application/pdf',
+      contentId: 'test-id',
+    };
+
+    assert.ok(!isAttachment(obj));
+  });
+});
diff --git a/tests/unit/calendar.test.js b/tests/unit/calendar.test.js
new file mode 100644
index 0000000..c6d5f36
--- /dev/null
+++ b/tests/unit/calendar.test.js
@@ -0,0 +1,591 @@
+// Ported from upyo v0.7.0 (packages/core/src/calendar.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const {
+  createCalendarAttachment,
+  parseCalendarMethod,
+  resolveCalendarContent,
+} = require('../../src/core/calendar.js');
+const { readAttachmentContent } = require('../../src/core/attachment.js');
+
+/** Builds an iCalendar object from lines, with the CRLF endings RFC 5545 asks
+ * for. */
+const ics = (...lines) => {
+  return lines.join('\r\n') + '\r\n';
+};
+
+const request = ics(
+  'BEGIN:VCALENDAR',
+  'VERSION:2.0',
+  'PRODID:-//Upyo//Test//EN',
+  'METHOD:REQUEST',
+  'BEGIN:VEVENT',
+  'UID:1@example.com',
+  'DTSTAMP:20260901T100000Z',
+  'DTSTART:20260902T100000Z',
+  'SUMMARY:Lunch',
+  'END:VEVENT',
+  'END:VCALENDAR',
+);
+
+describe('parseCalendarMethod()', () => {
+  it('should read a top-level METHOD', () => {
+    assert.equal(parseCalendarMethod(request), 'REQUEST');
+  });
+
+  it('should accept every iTIP method', () => {
+    const methods = [
+      'PUBLISH',
+      'REQUEST',
+      'REPLY',
+      'ADD',
+      'CANCEL',
+      'REFRESH',
+      'COUNTER',
+      'DECLINECOUNTER',
+    ];
+    for (const method of methods) {
+      const content = ics('BEGIN:VCALENDAR', `METHOD:${method}`, 'END:VCALENDAR');
+      assert.equal(parseCalendarMethod(content), method);
+    }
+  });
+
+  it('should uppercase a lowercase value and property name', () => {
+    const content = ics('BEGIN:VCALENDAR', 'method:request', 'END:VCALENDAR');
+    assert.equal(parseCalendarMethod(content), 'REQUEST');
+  });
+
+  it('should still fold ASCII component names case-insensitively', () => {
+    const content = ics('begin:vcalendar', 'METHOD:REQUEST', 'end:vcalendar');
+    assert.equal(parseCalendarMethod(content), 'REQUEST');
+  });
+
+  it('should accept bare LF line endings', () => {
+    assert.equal(parseCalendarMethod('BEGIN:VCALENDAR\nMETHOD:CANCEL\nEND:VCALENDAR\n'), 'CANCEL');
+  });
+
+  it('should unfold a folded property line', () => {
+    const content = ics('BEGIN:VCALENDAR', 'METHOD:REQ', ' UEST', 'END:VCALENDAR');
+    assert.equal(parseCalendarMethod(content), 'REQUEST');
+  });
+
+  it('should tolerate property parameters', () => {
+    const content = ics('BEGIN:VCALENDAR', 'METHOD;X-FOO=bar:REQUEST', 'END:VCALENDAR');
+    assert.equal(parseCalendarMethod(content), 'REQUEST');
+  });
+
+  it('should accept a multi-valued parameter', () => {
+    const content = ics('BEGIN:VCALENDAR', 'METHOD;X-A=a,b:REQUEST', 'END:VCALENDAR');
+    assert.equal(parseCalendarMethod(content), 'REQUEST');
+  });
+
+  it('should accept an empty parameter value', () => {
+    const content = ics('BEGIN:VCALENDAR', 'METHOD;X-A=:REQUEST', 'END:VCALENDAR');
+    assert.equal(parseCalendarMethod(content), 'REQUEST');
+  });
+
+  it('should ignore a colon inside a quoted parameter value', () => {
+    const content = ics('BEGIN:VCALENDAR', 'METHOD;X-FOO="a:b":REPLY', 'END:VCALENDAR');
+    assert.equal(parseCalendarMethod(content), 'REPLY');
+  });
+
+  it('should ignore a METHOD nested in a component', () => {
+    const content = ics(
+      'BEGIN:VCALENDAR',
+      'BEGIN:VTIMEZONE',
+      'METHOD:REQUEST',
+      'END:VTIMEZONE',
+      'END:VCALENDAR',
+    );
+    assert.equal(parseCalendarMethod(content), undefined);
+  });
+
+  it('should accept an extension component name', () => {
+    const content = ics(
+      'BEGIN:VCALENDAR',
+      'METHOD:REQUEST',
+      'BEGIN:X-WR-THING',
+      'END:X-WR-THING',
+      'END:VCALENDAR',
+    );
+    assert.equal(parseCalendarMethod(content), 'REQUEST');
+  });
+
+  it('should read a METHOD written after a component', () => {
+    const content = ics(
+      'BEGIN:VCALENDAR',
+      'BEGIN:VTIMEZONE',
+      'TZID:UTC',
+      'END:VTIMEZONE',
+      'METHOD:CANCEL',
+      'END:VCALENDAR',
+    );
+    assert.equal(parseCalendarMethod(content), 'CANCEL');
+  });
+
+  it('should not read a METHOD from a property value', () => {
+    const content = ics(
+      'BEGIN:VCALENDAR',
+      'BEGIN:VEVENT',
+      'DESCRIPTION:METHOD:REQUEST',
+      'END:VEVENT',
+      'END:VCALENDAR',
+    );
+    assert.equal(parseCalendarMethod(content), undefined);
+  });
+
+  const rejected = {
+    'no METHOD': ics('BEGIN:VCALENDAR', 'VERSION:2.0', 'END:VCALENDAR'),
+    'an unsupported method': ics('BEGIN:VCALENDAR', 'METHOD:X-CUSTOM', 'END:VCALENDAR'),
+    // U+017F upper-cases to "S" and U+0131 to "I" under the full Unicode
+    // mapping, which would turn an invalid token into a supported one while the
+    // payload kept the character a calendar client cannot read.
+    'a method spelled with U+017F': ics('BEGIN:VCALENDAR', 'METHOD:reque\u017Ft', 'END:VCALENDAR'),
+    'a method spelled with U+0131': ics('BEGIN:VCALENDAR', 'METHOD:publ\u0131sh', 'END:VCALENDAR'),
+    'two top-level METHODs': ics(
+      'BEGIN:VCALENDAR',
+      'METHOD:REQUEST',
+      'METHOD:CANCEL',
+      'END:VCALENDAR',
+    ),
+    'no envelope': 'METHOD:REQUEST\r\n',
+    'an unterminated envelope': ics('BEGIN:VCALENDAR', 'METHOD:REQUEST'),
+    'unbalanced components': ics(
+      'BEGIN:VCALENDAR',
+      'METHOD:REQUEST',
+      'BEGIN:VEVENT',
+      'END:VCALENDAR',
+    ),
+    // A parameter is `name=value`, so a bare token is not one.  The method it
+    // declares would be composed into a Content-Type while the content line
+    // carrying it is one a calendar client may refuse.
+    'a METHOD with a malformed parameter': ics(
+      'BEGIN:VCALENDAR',
+      'METHOD;BROKEN:REQUEST',
+      'END:VCALENDAR',
+    ),
+    'a METHOD with an unnamed parameter': ics(
+      'BEGIN:VCALENDAR',
+      'METHOD;=bar:REQUEST',
+      'END:VCALENDAR',
+    ),
+    // A component name is an iana-token or an x-name, both of which are one
+    // or more of ALPHA, DIGIT and "-".  A malformed pair still balances.
+    'an empty component name': ics(
+      'BEGIN:VCALENDAR',
+      'METHOD:REQUEST',
+      'BEGIN:',
+      'END:',
+      'END:VCALENDAR',
+    ),
+    'a component name carrying spaces': ics(
+      'BEGIN:VCALENDAR',
+      'METHOD:REQUEST',
+      'BEGIN:NOT A TOKEN',
+      'END:NOT A TOKEN',
+      'END:VCALENDAR',
+    ),
+    'a quoted component name': ics(
+      'BEGIN:VCALENDAR',
+      'METHOD:REQUEST',
+      'BEGIN:"X"',
+      'END:"X"',
+      'END:VCALENDAR',
+    ),
+    // RFC 5545 §3.4 spells a delimiter BEGIN:<name>, with no parameters.  A
+    // matching pair carrying them balances, so nothing else would notice.
+    'a BEGIN carrying parameters': ics(
+      'BEGIN;X=foo:VCALENDAR',
+      'METHOD:REQUEST',
+      'END;X=foo:VCALENDAR',
+    ),
+    'an END carrying parameters': ics('BEGIN:VCALENDAR', 'METHOD:REQUEST', 'END;X=foo:VCALENDAR'),
+    'an unterminated quote': ics('BEGIN:VCALENDAR', 'METHOD;X-FOO="a:REQUEST', 'END:VCALENDAR'),
+    'an orphan continuation line': ' METHOD:REQUEST\r\n',
+    // Unfolding joins a continuation to the line *immediately* before it, so a
+    // blank line in between must not let one bridge the gap and manufacture a
+    // method the transmitted content does not declare.
+    'a continuation across a blank line': ics(
+      'BEGIN:VCALENDAR',
+      'METHOD:REQ',
+      '',
+      ' UEST',
+      'END:VCALENDAR',
+    ),
+    'a blank line inside the object': ics('BEGIN:VCALENDAR', 'METHOD:REQUEST', '', 'END:VCALENDAR'),
+    'an empty string': '',
+  };
+  for (const [description, content] of Object.entries(rejected)) {
+    it(`should return undefined for ${description}`, () => {
+      assert.equal(parseCalendarMethod(content), undefined);
+    });
+  }
+});
+
+describe('resolveCalendarContent()', () => {
+  it('should resolve the method from the content', () => {
+    const resolved = resolveCalendarContent({ content: request });
+    assert.equal(resolved.method, 'REQUEST');
+    assert.equal(resolved.content, request);
+  });
+
+  it('should accept a method that agrees with the content', () => {
+    const resolved = resolveCalendarContent({
+      method: 'REQUEST',
+      content: request,
+    });
+    assert.equal(resolved.method, 'REQUEST');
+  });
+
+  it('should normalize bare LF endings to CRLF', () => {
+    const resolved = resolveCalendarContent({
+      content: 'BEGIN:VCALENDAR\nMETHOD:REQUEST\nEND:VCALENDAR\n',
+    });
+    assert.equal(resolved.content, 'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR\r\n');
+  });
+
+  it('should normalize bare CR endings to CRLF', () => {
+    const resolved = resolveCalendarContent({
+      content: 'BEGIN:VCALENDAR\rMETHOD:REQUEST\rEND:VCALENDAR\r',
+    });
+    assert.equal(resolved.content, 'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR\r\n');
+  });
+
+  it('should accept blank lines around the object', () => {
+    // A template literal opening with a newline, or a file saved with a
+    // trailing blank line, is ordinary; nothing can fold across an edge.
+    const resolved = resolveCalendarContent({
+      content: '\n\nBEGIN:VCALENDAR\nMETHOD:REQUEST\nEND:VCALENDAR\n\n\n',
+    });
+
+    assert.equal(resolved.method, 'REQUEST');
+    assert.equal(resolved.content, 'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR\r\n');
+  });
+
+  it('should still reject a blank line inside the object', () => {
+    assert.throws(
+      () =>
+        resolveCalendarContent({
+          content: ics('BEGIN:VCALENDAR', 'METHOD:REQ', '', ' UEST', 'END:VCALENDAR'),
+        }),
+      { name: 'TypeError', message: /empty line/ },
+    );
+  });
+
+  it('should add a terminating CRLF when the content lacks one', () => {
+    const resolved = resolveCalendarContent({
+      content: 'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR',
+    });
+    assert.ok(resolved.content.endsWith('END:VCALENDAR\r\n'));
+  });
+
+  it("should preserve the caller's line folding", () => {
+    const folded = ics(
+      'BEGIN:VCALENDAR',
+      'METHOD:REQUEST',
+      'BEGIN:VEVENT',
+      'SUMMARY:A very long summary that the caller chose to',
+      '  fold across two lines',
+      'END:VEVENT',
+      'END:VCALENDAR',
+    );
+    const resolved = resolveCalendarContent({ content: folded });
+    assert.equal(resolved.content, folded);
+  });
+
+  it('should preserve non-ASCII content', () => {
+    const content = ics(
+      'BEGIN:VCALENDAR',
+      'METHOD:REQUEST',
+      'BEGIN:VEVENT',
+      'SUMMARY:점심 식사 🍜',
+      'END:VEVENT',
+      'END:VCALENDAR',
+    );
+    assert.equal(resolveCalendarContent({ content }).content, content);
+  });
+
+  it('should reject a method that disagrees with the content', () => {
+    assert.throws(() => resolveCalendarContent({ method: 'CANCEL', content: request }), {
+      name: 'TypeError',
+      message: /METHOD/,
+    });
+  });
+
+  it('should reject content with no METHOD even when one is asserted', () => {
+    assert.throws(
+      () =>
+        resolveCalendarContent({
+          method: 'REQUEST',
+          content: ics('BEGIN:VCALENDAR', 'VERSION:2.0', 'END:VCALENDAR'),
+        }),
+      { name: 'TypeError', message: /METHOD/ },
+    );
+  });
+
+  const invalid = {
+    'an empty object': { content: '' },
+    'a missing envelope': { content: 'METHOD:REQUEST\r\n' },
+    'an unsupported method': {
+      content: ics('BEGIN:VCALENDAR', 'METHOD:X-CUSTOM', 'END:VCALENDAR'),
+    },
+    'a method a Unicode fold would rescue': {
+      content: ics('BEGIN:VCALENDAR', 'METHOD:reque\u017Ft', 'END:VCALENDAR'),
+    },
+    'two calendar objects': {
+      content:
+        ics('BEGIN:VCALENDAR', 'METHOD:REQUEST', 'END:VCALENDAR') +
+        ics('BEGIN:VCALENDAR', 'METHOD:REQUEST', 'END:VCALENDAR'),
+    },
+    // RFC 5545 has no VCALENDAR inside a VCALENDAR, and the components balance
+    // here, so nothing else in the scan would notice.
+    'a nested calendar object': {
+      content: ics(
+        'BEGIN:VCALENDAR',
+        'METHOD:REQUEST',
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        'END:VCALENDAR',
+        'END:VCALENDAR',
+      ),
+    },
+    'a nested object declaring its own method': {
+      content: ics(
+        'BEGIN:VCALENDAR',
+        'METHOD:REQUEST',
+        'BEGIN:VCALENDAR',
+        'METHOD:CANCEL',
+        'END:VCALENDAR',
+        'END:VCALENDAR',
+      ),
+    },
+  };
+  for (const [description, calendar] of Object.entries(invalid)) {
+    it(`should reject ${description}`, () => {
+      assert.throws(() => resolveCalendarContent(calendar), {
+        name: 'TypeError',
+      });
+    });
+  }
+});
+
+describe('createCalendarAttachment()', () => {
+  it('should build an invite.ics part carrying the method', async () => {
+    const attachment = createCalendarAttachment({ content: request });
+    assert.ok(!attachment.inline);
+    assert.equal(attachment.filename, 'invite.ics');
+    assert.equal(attachment.contentType, 'text/calendar; charset=utf-8; method=REQUEST');
+    assert.equal(attachment.contentId, '');
+    const bytes = await readAttachmentContent(attachment.content);
+    assert.equal(new TextDecoder().decode(bytes), request);
+  });
+
+  it('should carry the normalized content', async () => {
+    const attachment = createCalendarAttachment({
+      content: 'BEGIN:VCALENDAR\nMETHOD:CANCEL\nEND:VCALENDAR',
+    });
+    assert.equal(attachment.contentType, 'text/calendar; charset=utf-8; method=CANCEL');
+    const bytes = await readAttachmentContent(attachment.content);
+    assert.equal(
+      new TextDecoder().decode(bytes),
+      'BEGIN:VCALENDAR\r\nMETHOD:CANCEL\r\nEND:VCALENDAR\r\n',
+    );
+  });
+
+  it('should reject invalid calendar content', () => {
+    assert.throws(() => createCalendarAttachment({ content: 'nope' }), {
+      name: 'TypeError',
+    });
+  });
+});
+
+describe('createCalendarAttachment() charset', () => {
+  it('should declare UTF-8 so non-ASCII content decodes', () => {
+    // RFC 6047 §2.4 requires the charset parameter once the object leaves
+    // US-ASCII, and MIME's default would otherwise mis-read these bytes.
+    const attachment = createCalendarAttachment({
+      content: ics(
+        'BEGIN:VCALENDAR',
+        'METHOD:REQUEST',
+        'BEGIN:VEVENT',
+        'SUMMARY:점심 식사',
+        'END:VEVENT',
+        'END:VCALENDAR',
+      ),
+    });
+
+    assert.ok(attachment.contentType.includes('charset=utf-8'));
+  });
+});
+
+describe('calendar content line grammar', () => {
+  const invalidLines = {
+    'spaces in a property name': ['SUM MARY:x'],
+    'quoted property name': ['"SUMMARY":x'],
+    'empty property name': [':x'],
+    'non-ASCII property name': ['SUMMÁRY:x'],
+    'punctuation in a property name': ['SUM_MARY:x'],
+    'bare parameter': ['SUMMARY;BROKEN:Lunch'],
+    'unnamed parameter': ['SUMMARY;=x:y'],
+    'empty trailing parameter': ['SUMMARY;X=a;:y'],
+    'invalid parameter name': ['SUMMARY;X_A=x:y'],
+    'non-ASCII parameter name': ['SUMMARY;X-Á=x:y'],
+    'space in a parameter name': ['SUMMARY;X A=x:y'],
+    'quoted parameter name': ['SUMMARY;"X"=x:y'],
+    'embedded balanced quotes': ['METHOD;X=a"b":REQUEST'],
+    'junk after a quoted value': ['METHOD;X="a"b:REQUEST'],
+    'adjacent quoted values': ['METHOD;X="a""b":REQUEST'],
+    'space after a quoted value': ['METHOD;X="a" :REQUEST'],
+    'unterminated quoted value': ['SUMMARY;X="a:b'],
+    'missing colon after quoted value': ['SUMMARY;X="a"'],
+    'missing colon': ['SUMMARY'],
+    'backslash before an embedded quote': ['METHOD;X="a\\"b":REQUEST'],
+    'malformed nested METHOD': ['BEGIN:VEVENT', 'METHOD;BROKEN:REQUEST', 'END:VEVENT'],
+    'leading method whitespace': ['METHOD: REQUEST'],
+    'trailing method whitespace': ['METHOD:REQUEST '],
+    'lone high surrogate': ['SUMMARY:\uD83D'],
+    'lone low surrogate': ['SUMMARY:\uDE00'],
+    'surrogate pair split by folding': ['SUMMARY:\uD83D', ' \uDE00'],
+  };
+
+  // Only the METHOD-specific cases replace the valid top-level method.
+  const objectWith = (lines) => {
+    return ics(
+      'BEGIN:VCALENDAR',
+      ...(lines[0].startsWith('METHOD') ? [] : ['METHOD:REQUEST']),
+      ...lines,
+      'END:VCALENDAR',
+    );
+  };
+
+  for (const [description, lines] of Object.entries(invalidLines)) {
+    it(`should reject ${description} through both public functions`, () => {
+      const content = objectWith(lines);
+      assert.equal(parseCalendarMethod(content), undefined);
+      assert.throws(() => resolveCalendarContent({ content }), TypeError);
+    });
+  }
+
+  for (let code = 0; code <= 0x7f; code++) {
+    if (code === 9 || code === 10 || code === 13 || (code >= 32 && code < 127)) {
+      continue;
+    }
+    const character = String.fromCharCode(code);
+    for (const line of [
+      `SUMMARY:a${character}b`,
+      `METHOD;X=a${character}b:REQUEST`,
+      `METHOD;X="a${character}b":REQUEST`,
+    ]) {
+      it(`should reject control U+${code.toString(16)} in ${JSON.stringify(line)}`, () => {
+        const content = objectWith([line]);
+        assert.equal(parseCalendarMethod(content), undefined);
+        assert.throws(() => resolveCalendarContent({ content }), TypeError);
+      });
+    }
+  }
+
+  for (const value of ['\uD800', '\uDC00']) {
+    for (const parameter of [value, `"${value}"`]) {
+      it(`should reject a lone surrogate in parameter ${JSON.stringify(parameter)}`, () => {
+        const content = objectWith([`METHOD;X=${parameter}:REQUEST`]);
+        assert.equal(parseCalendarMethod(content), undefined);
+        assert.throws(() => resolveCalendarContent({ content }), TypeError);
+      });
+    }
+  }
+
+  it('should reject a byte order mark before the envelope', () => {
+    const content = '\uFEFF' + request;
+    assert.equal(parseCalendarMethod(content), undefined);
+    assert.throws(() => resolveCalendarContent({ content }), TypeError);
+  });
+
+  const validLines = {
+    'empty parameter values and list members': ['METHOD;X=,"",a,,b,:REQUEST'],
+    'mixed quoted and unquoted values': ['METHOD;X="a:b;c,d",plain,"":REQUEST'],
+    'equals, backslash and caret in parameters': ["METHOD;X=a=b\\c^n^'^^:REQUEST"],
+    'spaces and tabs in parameters': ['METHOD;X= a\tb ;Y=" a\tb ":REQUEST'],
+    'Unicode parameter and property values': [
+      'ATTENDEE;CN="점심 🍜";X=é\u0080\u0085\u009F:mailto:a@example.com',
+      'SUMMARY:점심 🍜\uD7FF\uE000\uFFFF\u{10FFFF}',
+    ],
+    'unknown token names': ['X-ABC-THING;X-ABC-PARAM=x:y', '1;-=x:y', 'X-:x'],
+    'empty property value': ['SUMMARY:'],
+    'realistic attendee parameters': [
+      'ATTENDEE;CUTYPE=INDIVIDUAL;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN=Jane Doe;X-NUM-GUESTS=0:mailto:jane@example.net',
+      'ATTENDEE;CN="Doe, Jane":mailto:jane@example.net',
+    ],
+    'structured values': [
+      'DTSTART;TZID=America/New_York:20260902T100000',
+      'RRULE:FREQ=WEEKLY;BYDAY=MO,WE;UNTIL=20261231T000000Z',
+      'GEO:37.386013;-122.082932',
+      'X-ALT-DESC;FMTTYPE=text/html:<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">',
+      'ATTACH;FMTTYPE=text/plain;ENCODING=BASE64;VALUE=BINARY:SGVsbG8=',
+      'DESCRIPTION:Line one\\nLine two\\, with comma',
+    ],
+    'property name folding': ['ME', ' THOD:REQUEST'],
+    'parameter name folding': ['METHOD;X-', ' A=1:REQUEST'],
+    'quoted parameter folding': ['ATTENDEE;CN="Doe,', '  Jane":mailto:jane@example.net'],
+    'fold immediately after colon': ['METHOD:', ' REQUEST'],
+    'fold after a closing quote': ['METHOD;X="a"', ' ,b:REQUEST'],
+    'tab-led continuation': ['METHOD:REQ', '\tUEST'],
+    'long unfolded line': ['SUMMARY:' + 'x'.repeat(100)],
+    'parameterized nested METHOD': ['BEGIN:VEVENT', 'METHOD;X-A=1:CANCEL', 'END:VEVENT'],
+  };
+  for (const [description, lines] of Object.entries(validLines)) {
+    it(`should preserve ${description}`, () => {
+      // A folded property name does not begin with METHOD until unfolded.
+      const content =
+        description === 'property name folding'
+          ? ics('BEGIN:VCALENDAR', ...lines, 'END:VCALENDAR')
+          : objectWith(lines);
+      assert.equal(parseCalendarMethod(content), 'REQUEST');
+      assert.deepEqual(resolveCalendarContent({ content }), {
+        method: 'REQUEST',
+        content,
+      });
+    });
+  }
+
+  it('should normalize a bare LF fold without removing it from output', () => {
+    const content = 'BEGIN:VCALENDAR\nMETHOD:REQUEST\nSUMMARY:a\n b\nEND:VCALENDAR\n';
+    assert.equal(parseCalendarMethod(content), 'REQUEST');
+    assert.equal(resolveCalendarContent({ content }).content, content.replaceAll('\n', '\r\n'));
+  });
+
+  it('should accept the documented invitation', () => {
+    const content = ics(
+      'BEGIN:VCALENDAR',
+      'VERSION:2.0',
+      'PRODID:-//Example//Booking//EN',
+      'METHOD:REQUEST',
+      'BEGIN:VEVENT',
+      'UID:booking-42@example.com',
+      'SEQUENCE:0',
+      'DTSTAMP:20260901T090000Z',
+      'DTSTART:20260902T120000Z',
+      'DTEND:20260902T130000Z',
+      'ORGANIZER:mailto:organizer@example.com',
+      'ATTENDEE;RSVP=TRUE:mailto:attendee@example.net',
+      'SUMMARY:Lunch',
+      'END:VEVENT',
+      'END:VCALENDAR',
+    );
+    assert.deepEqual(resolveCalendarContent({ content }), {
+      method: 'REQUEST',
+      content,
+    });
+  });
+
+  it('should refuse malformed lines when creating the attachment fallback', () => {
+    assert.throws(
+      () =>
+        createCalendarAttachment({
+          content: objectWith(['SUMMARY;BROKEN:Lunch']),
+        }),
+      TypeError,
+    );
+  });
+});
diff --git a/tests/unit/core.test.js b/tests/unit/core.test.js
new file mode 100644
index 0000000..c3abcf1
--- /dev/null
+++ b/tests/unit/core.test.js
@@ -0,0 +1,201 @@
+// Paths of the ported core (src/core/) that upstream's suites leave out.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const {
+  analyzeRawMessage,
+  classifyHttpStatus,
+  classifyReceiptError,
+  comparePriority,
+  createFailedReceipt,
+  createMessage,
+  createRawMessagePlan,
+  createReceiptError,
+  isEmailAddress,
+  iterateAttachmentContent,
+  iterateRawMessage,
+  RawMessageValidationError,
+  readAttachmentContent,
+  resolveCalendarContent,
+} = require('../../index.js');
+
+const base = {
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+};
+
+test('Address: a value that is not a string, or a bad quoted local part, is no address', () => {
+  assert.strictEqual(isEmailAddress(''), false);
+  assert.strictEqual(isEmailAddress(42), false);
+  assert.strictEqual(isEmailAddress('"\ud800"@example.com'), false);
+  assert.strictEqual(isEmailAddress('"a\\\u0001"@example.com'), false);
+  assert.strictEqual(isEmailAddress('alex@[127.0.0.1]'), true);
+});
+
+test('Message: an attachment that is neither a File nor an Attachment is rejected', () => {
+  assert.throws(() => createMessage({ ...base, attachments: [{}] }), {
+    name: 'TypeError',
+    message: 'Invalid attachment: {}',
+  });
+  assert.throws(() => createMessage({ ...base, date: '2020-01-01' }), {
+    message: 'Invalid date: "2020-01-01"',
+  });
+});
+
+test('Calendar: the content must begin with a VCALENDAR object', () => {
+  assert.throws(() => resolveCalendarContent({ content: 'BEGIN:VEVENT\r\nEND:VEVENT\r\n' }), {
+    name: 'TypeError',
+    message: 'The calendar content begins with "VEVENT" rather than a VCALENDAR object.',
+  });
+});
+
+test('Priority: high sorts first, low last', () => {
+  const sorted = ['normal', 'low', 'high', 'low', 'normal', 'high'].sort(comparePriority);
+  assert.deepStrictEqual(sorted, ['high', 'high', 'normal', 'normal', 'low', 'low']);
+});
+
+test('Receipt: HTTP statuses map to categories', () => {
+  assert.deepStrictEqual(classifyHttpStatus(408), { category: 'timeout', retryable: true });
+  assert.deepStrictEqual(classifyHttpStatus(504), { category: 'timeout', retryable: true });
+  assert.deepStrictEqual(classifyHttpStatus(422), { category: 'validation', retryable: false });
+  assert.deepStrictEqual(classifyHttpStatus(302), { category: 'unknown', retryable: false });
+});
+
+test('Receipt: error messages map to categories by keyword', () => {
+  const cases = [
+    ['Invalid recipient', 'validation', false],
+    ['Service Unavailable', 'service-unavailable', true],
+    ['Internal Server Error', 'server-error', true],
+    ['Unsupported option', 'configuration', false],
+    ['Something odd', 'unknown', false],
+  ];
+  for (const [message, category, retryable] of cases) {
+    assert.deepStrictEqual(
+      classifyReceiptError(new Error(message)),
+      { category, retryable, code: category },
+      message,
+    );
+  }
+  // A plain object is read by its properties; a null name counts as none.
+  assert.strictEqual(
+    classifyReceiptError({ message: 'Unsupported', name: null }).category,
+    'configuration',
+  );
+});
+
+test('Receipt: an explicit category is also the code, and a ReceiptError makes a receipt', () => {
+  assert.deepStrictEqual(createReceiptError('Bounced', { category: 'rejected' }), {
+    message: 'Bounced',
+    category: 'rejected',
+    code: 'rejected',
+    retryable: false,
+  });
+  const error = createReceiptError('Quota exceeded');
+  const receipt = createFailedReceipt(error, { timestamp: '2026-01-01T00:00:00.000Z' });
+  assert.deepStrictEqual(receipt, {
+    successful: false,
+    errorMessages: ['Quota exceeded'],
+    errors: [error],
+    retryable: true,
+    timestamp: '2026-01-01T00:00:00.000Z',
+  });
+  const mixed = createFailedReceipt(['Timed out', error], { provider: 'smtp' });
+  assert.deepStrictEqual(mixed.errorMessages, ['Timed out', 'Quota exceeded']);
+  assert.strictEqual(mixed.errors[0].category, 'timeout');
+  assert.strictEqual(mixed.errors[1], error);
+});
+
+test('Attachment: leaving a Blob early cancels its reader', async () => {
+  const blob = new Blob([new Uint8Array(70000).fill(65)]);
+  let chunks = 0;
+  for await (const chunk of iterateAttachmentContent(blob)) {
+    assert.ok(chunk.length > 0);
+    chunks++;
+    break;
+  }
+  assert.strictEqual(chunks, 1);
+  assert.strictEqual((await readAttachmentContent(blob)).length, 70000);
+});
+
+test('Attachment: content of the wrong type is rejected', async () => {
+  await assert.rejects(readAttachmentContent(Promise.resolve('text')), {
+    name: 'TypeError',
+    message: 'Expected attachment bytes to be a Uint8Array.',
+  });
+  await assert.rejects(readAttachmentContent('text'), {
+    name: 'TypeError',
+    message: 'Expected replayable attachment content.',
+  });
+  const strings = async function* () {
+    yield 'not bytes';
+  };
+  await assert.rejects(readAttachmentContent(strings), {
+    name: 'TypeError',
+    message: 'Expected an attachment chunk to be a Uint8Array.',
+  });
+});
+
+test('Attachment: a source whose return() throws does not fail the reader that leaves', async () => {
+  const factory = () => ({
+    [Symbol.asyncIterator]() {
+      return {
+        next: () => Promise.resolve({ done: false, value: new Uint8Array([1]) }),
+        return() {
+          throw new Error('return failed');
+        },
+      };
+    },
+  });
+  for await (const chunk of iterateAttachmentContent(factory)) {
+    assert.deepStrictEqual([...chunk], [1]);
+    break;
+  }
+});
+
+const raw = (text, options = {}) => ({
+  envelope: { from: 'alex@example.com', to: ['bob@example.com'] },
+  content: new TextEncoder().encode(text),
+  ...options,
+});
+
+test('Raw message: the encoding and the content are checked when planned', () => {
+  assert.throws(() => createRawMessagePlan(raw('A: b\r\n\r\nx\r\n', { encoding: 'base64' })), {
+    name: 'RawMessageValidationError',
+    message: 'Invalid raw message encoding.',
+  });
+  const error = (() => {
+    try {
+      createRawMessagePlan({ ...raw(''), content: 'A: b\r\n' });
+    } catch (caught) {
+      return caught;
+    }
+  })();
+  assert.ok(error instanceof RawMessageValidationError);
+  assert.strictEqual(error.field, 'content');
+});
+
+test('Raw message: a source that grows between reads fails the read', async () => {
+  let calls = 0;
+  const growing = async function* () {
+    calls++;
+    yield new TextEncoder().encode(calls === 1 ? 'A: b\r\n\r\nx\r\n' : 'A: b\r\n\r\nxyz\r\n');
+  };
+  const plan = createRawMessagePlan({ ...raw(''), content: growing });
+  const info = await analyzeRawMessage(plan);
+  await assert.rejects(async () => {
+    // oxlint-disable-next-line no-unused-vars -- the chunks are consumed, not read
+    for await (const _ of iterateRawMessage(plan, { expectedSize: info.size })) {
+      /* consume */
+    }
+  }, /size changed/);
+});
+
+test('Raw message: a long message yields to the event loop while it is read', async () => {
+  const line = `${'a'.repeat(76)}\r\n`;
+  const text = `A: b\r\n\r\n${line.repeat(16000)}`;
+  const plan = createRawMessagePlan(raw(text));
+  let size = 0;
+  for await (const chunk of iterateRawMessage(plan)) size += chunk.length;
+  assert.strictEqual(size, text.length);
+});
diff --git a/tests/unit/message-id.test.js b/tests/unit/message-id.test.js
new file mode 100644
index 0000000..4017c68
--- /dev/null
+++ b/tests/unit/message-id.test.js
@@ -0,0 +1,212 @@
+// Ported from upyo v0.7.0 (packages/core/src/message-id.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const {
+  formatMessageId,
+  generateMessageId,
+  parseMessageId,
+  resolveThreadingHeaders,
+} = require('../../src/core/message-id.js');
+
+describe('parseMessageId()', () => {
+  const accepted = [
+    ['<a@b>', 'a@b'],
+    ['a@b', 'a@b'],
+    ['ab@cd', 'ab@cd'],
+    ['a.b+tag@example.com', 'a.b+tag@example.com'],
+    ["!#$%&'*+-/=?^_`{|}~@example.com", "!#$%&'*+-/=?^_`{|}~@example.com"],
+    ['a@[x@y]', 'a@[x@y]'],
+    ['<a@[IPv6:::1]>', 'a@[IPv6:::1]'],
+    ['a@[192.0.2.1]', 'a@[192.0.2.1]'],
+    ['a@b\u{1F600}', 'a@b\u{1F600}'],
+    ['안녕@한국.한국', '안녕@한국.한국'],
+  ];
+
+  for (const [input, expected] of accepted) {
+    it(`accepts ${JSON.stringify(input)}`, () => {
+      assert.equal(parseMessageId(input), expected);
+    });
+  }
+
+  const rejected = [
+    '',
+    '<>',
+    'a@b c@d',
+    'a@b@c',
+    'a..b@c',
+    '.a@b',
+    'a.@b',
+    'a@',
+    '@b',
+    'a@b.',
+    'a@.b',
+    'a@[]',
+    'a@[x\\y]',
+    'a@[x[y]',
+    '<<a@b>>',
+    'a@b>',
+    '<a@b',
+    'a@b<',
+    '"q"@b',
+    'a(comment)@b',
+    'a@b\uD800',
+    ' a@b ',
+    'a@b\r\nX: y',
+    'a\t@b',
+  ];
+
+  for (const input of rejected) {
+    it(`rejects ${JSON.stringify(input)}`, () => {
+      assert.equal(parseMessageId(input), undefined);
+    });
+  }
+
+  it('obeys the round-trip law', () => {
+    for (const [input] of accepted) {
+      const parsed = parseMessageId(input);
+      assert.ok(parsed != null);
+      assert.equal(parseMessageId(formatMessageId(parsed)), parsed);
+    }
+  });
+});
+
+describe('formatMessageId()', () => {
+  it('wraps a bare identifier in angle brackets', () => {
+    assert.equal(formatMessageId('a@b'), '<a@b>');
+    assert.equal(formatMessageId('a@[x@y]'), '<a@[x@y]>');
+  });
+
+  it('rejects an already bracketed identifier', () => {
+    assert.throws(() => formatMessageId('<a@b>'), {
+      name: 'TypeError',
+      message: /Invalid message ID/,
+    });
+  });
+
+  it('rejects an invalid identifier', () => {
+    for (const invalid of ['', 'a', 'a@', '@b', 'a@b c@d']) {
+      assert.throws(() => formatMessageId(invalid), { name: 'TypeError' });
+    }
+  });
+});
+
+describe('generateMessageId()', () => {
+  it('roots the identifier in the given domain', () => {
+    const id = generateMessageId('example.com');
+    assert.ok(id.endsWith('@example.com'));
+    assert.equal(parseMessageId(id), id);
+  });
+
+  it('generates a distinct identifier every time', () => {
+    const ids = new Set();
+    for (let index = 0; index < 100; index++) {
+      ids.add(generateMessageId('example.com'));
+    }
+    assert.equal(ids.size, 100);
+  });
+
+  it('passes an ASCII domain through unchanged', () => {
+    for (const domain of ['example.com', '[192.0.2.1]', 'foo/bar', 'a!b']) {
+      assert.ok(generateMessageId(domain).endsWith(`@${domain}`));
+    }
+  });
+
+  it('converts a Unicode DNS name to its ASCII form', () => {
+    const id = generateMessageId('exämple.com');
+    assert.ok(
+      id.endsWith('@xn--exmple-cua.com'),
+      `expected a punycode domain, got ${JSON.stringify(id)}`,
+    );
+  });
+
+  it('converts a decomposed DNS name the same as a precomposed one', () => {
+    // "éxample.com" spelled with a combining acute accent.
+    const decomposed = generateMessageId('e\u0301xample.com');
+    const precomposed = generateMessageId('\u00e9xample.com');
+
+    assert.ok(
+      decomposed.endsWith('@xn--xample-9ua.com'),
+      `expected a punycode domain, got ${JSON.stringify(decomposed)}`,
+    );
+    assert.equal(
+      decomposed.slice(decomposed.indexOf('@')),
+      precomposed.slice(precomposed.indexOf('@')),
+    );
+  });
+
+  it('keeps a Unicode domain that is not a DNS name verbatim', () => {
+    const id = generateMessageId('föö/bar');
+    assert.ok(id.endsWith('@föö/bar'));
+  });
+
+  it('rejects a domain that is not a valid identifier right-hand side', () => {
+    for (const domain of [
+      '',
+      ' ',
+      'example.com:80',
+      'http://example.com',
+      'example com',
+      'exa\r\nmple.com',
+      '.example.com',
+      'example..com',
+      '[]',
+    ]) {
+      assert.throws(
+        () => generateMessageId(domain),
+        { name: 'TypeError' },
+        `expected ${JSON.stringify(domain)} to be rejected`,
+      );
+    }
+  });
+});
+
+describe('resolveThreadingHeaders()', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Test',
+    content: { text: 'Test' },
+  };
+
+  it('omits a field the message leaves unset', () => {
+    const resolved = resolveThreadingHeaders(createMessage(base));
+
+    assert.equal(resolved.size, 0);
+    assert.ok(!resolved.has('In-Reply-To'));
+  });
+
+  it('maps an empty list to null', () => {
+    const resolved = resolveThreadingHeaders(createMessage({ ...base, inReplyTo: [] }));
+
+    assert.ok(resolved.has('In-Reply-To'));
+    assert.equal(resolved.get('In-Reply-To'), null);
+    assert.ok(!resolved.has('References'));
+  });
+
+  it('formats the identifiers of a populated list', () => {
+    const resolved = resolveThreadingHeaders(
+      createMessage({
+        ...base,
+        inReplyTo: '122@example.com',
+        references: ['120@example.com', '121@example.com'],
+      }),
+    );
+
+    assert.equal(resolved.get('In-Reply-To'), '<122@example.com>');
+    assert.equal(resolved.get('References'), '<120@example.com> <121@example.com>');
+  });
+
+  it('rejects an invalid identifier a hand-built message carries', () => {
+    assert.throws(
+      () =>
+        resolveThreadingHeaders({
+          ...createMessage(base),
+          references: ['not an identifier'],
+        }),
+      { name: 'TypeError', message: /Invalid message ID/ },
+    );
+  });
+});
diff --git a/tests/unit/message.test.js b/tests/unit/message.test.js
new file mode 100644
index 0000000..82d4d62
--- /dev/null
+++ b/tests/unit/message.test.js
@@ -0,0 +1,629 @@
+// Ported from upyo v0.7.0 (packages/core/src/message.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const { readAttachmentContent } = require('../../src/core/attachment.js');
+const assert = require('node:assert/strict');
+const { createMessage } = require('../../src/core/message.js');
+
+describe('createMessage', () => {
+  it('should create a message with required fields only', () => {
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+    };
+
+    const message = createMessage(constructor);
+
+    assert.deepEqual(message.sender, {
+      address: 'sender@example.com',
+    });
+    assert.deepEqual(message.recipients, [
+      {
+        address: 'recipient@example.com',
+      },
+    ]);
+    assert.equal(message.subject, 'Test Subject');
+    assert.deepEqual(message.content, { text: 'Test content' });
+    assert.equal(message.priority, 'normal');
+    assert.deepEqual(message.ccRecipients, []);
+    assert.deepEqual(message.bccRecipients, []);
+    assert.deepEqual(message.replyRecipients, []);
+    assert.deepEqual(message.attachments, []);
+    assert.deepEqual(message.tags, []);
+    assert.ok(message.headers instanceof Headers);
+  });
+
+  it('should parse email addresses from strings', () => {
+    const constructor = {
+      from: 'John Doe <john@example.com>',
+      to: 'Jane Smith <jane@example.com>',
+      subject: 'Test',
+      content: { text: 'Test' },
+    };
+
+    const message = createMessage(constructor);
+
+    assert.deepEqual(message.sender, {
+      name: 'John Doe',
+      address: 'john@example.com',
+    });
+    assert.deepEqual(message.recipients, [
+      {
+        name: 'Jane Smith',
+        address: 'jane@example.com',
+      },
+    ]);
+  });
+
+  it('should parse internationalized email addresses', () => {
+    const message = createMessage({
+      from: 'José <josé@example.com>',
+      to: '用户@例子.广告',
+      subject: 'Test',
+      content: { text: 'Test' },
+    });
+
+    assert.deepEqual(message.sender, {
+      name: 'José',
+      address: 'josé@example.com',
+    });
+    assert.deepEqual(message.recipients, [
+      {
+        address: '用户@例子.广告',
+      },
+    ]);
+  });
+
+  it('should handle multiple recipients as array', () => {
+    const constructor = {
+      from: 'sender@example.com',
+      to: ['recipient1@example.com', 'recipient2@example.com'],
+      cc: ['cc1@example.com', 'cc2@example.com'],
+      bcc: 'bcc@example.com',
+      replyTo: ['reply1@example.com', 'reply2@example.com'],
+      subject: 'Test',
+      content: { text: 'Test' },
+    };
+
+    const message = createMessage(constructor);
+
+    assert.equal(message.recipients.length, 2);
+    assert.deepEqual(message.recipients[0], {
+      address: 'recipient1@example.com',
+    });
+    assert.deepEqual(message.recipients[1], {
+      address: 'recipient2@example.com',
+    });
+
+    assert.equal(message.ccRecipients.length, 2);
+    assert.deepEqual(message.ccRecipients[0], {
+      address: 'cc1@example.com',
+    });
+    assert.deepEqual(message.ccRecipients[1], {
+      address: 'cc2@example.com',
+    });
+
+    assert.equal(message.bccRecipients.length, 1);
+    assert.deepEqual(message.bccRecipients[0], {
+      address: 'bcc@example.com',
+    });
+
+    assert.equal(message.replyRecipients.length, 2);
+    assert.deepEqual(message.replyRecipients[0], {
+      address: 'reply1@example.com',
+    });
+    assert.deepEqual(message.replyRecipients[1], {
+      address: 'reply2@example.com',
+    });
+  });
+
+  it('should convert File objects to attachments', async () => {
+    const fileContent = new Uint8Array([1, 2, 3, 4]);
+    const file = new File([fileContent], 'test.txt', { type: 'text/plain' });
+
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+      attachments: file,
+    };
+
+    const message = createMessage(constructor);
+
+    assert.equal(message.attachments.length, 1);
+    const attachment = message.attachments[0];
+    assert.equal(attachment.filename, 'test.txt');
+    assert.equal(attachment.contentType.split(';')[0].trim(), 'text/plain');
+    assert.equal(attachment.inline, false);
+    assert.ok(
+      attachment.contentId.match(
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}@example.com$/,
+      ),
+    );
+
+    assert.equal(attachment.content, file);
+    const content = await readAttachmentContent(attachment.content);
+    assert.ok(content instanceof Uint8Array);
+    assert.deepEqual(content, fileContent);
+  });
+
+  it('should handle File with no type', () => {
+    const file = new File([new Uint8Array([1, 2, 3])], 'test.bin');
+
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+      attachments: file,
+    };
+
+    const message = createMessage(constructor);
+
+    assert.equal(message.attachments[0].contentType, 'application/octet-stream');
+  });
+
+  it('should handle multiple attachments', () => {
+    const file1 = new File([new Uint8Array([1])], 'file1.txt', {
+      type: 'text/plain',
+    });
+    const file2 = new File([new Uint8Array([2])], 'file2.txt', {
+      type: 'text/plain',
+    });
+
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+      attachments: [file1, file2],
+    };
+
+    const message = createMessage(constructor);
+
+    assert.equal(message.attachments.length, 2);
+    assert.equal(message.attachments[0].filename, 'file1.txt');
+    assert.equal(message.attachments[1].filename, 'file2.txt');
+  });
+
+  it('should set default values for optional properties', () => {
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+    };
+
+    const message = createMessage(constructor);
+
+    assert.equal(message.priority, 'normal');
+    assert.deepEqual(message.ccRecipients, []);
+    assert.deepEqual(message.bccRecipients, []);
+    assert.deepEqual(message.replyRecipients, []);
+    assert.deepEqual(message.attachments, []);
+    assert.deepEqual(message.tags, []);
+  });
+
+  it('should use provided optional values', () => {
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+      priority: 'high',
+      tags: ['important', 'urgent'],
+      headers: { 'X-Custom': 'value' },
+    };
+
+    const message = createMessage(constructor);
+
+    assert.equal(message.priority, 'high');
+    assert.deepEqual(message.tags, ['important', 'urgent']);
+    assert.equal(message.headers.get('X-Custom'), 'value');
+  });
+
+  it('should handle HTML content', () => {
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test',
+      content: { html: '<h1>Hello</h1>', text: 'Hello' },
+    };
+
+    const message = createMessage(constructor);
+
+    assert.deepEqual(message.content, {
+      html: '<h1>Hello</h1>',
+      text: 'Hello',
+    });
+  });
+
+  const lineBreaks = [
+    { label: 'CR', value: '\r' },
+    { label: 'LF', value: '\n' },
+    { label: 'CRLF', value: '\r\n' },
+  ];
+
+  const addressFields = [
+    { key: 'from', pattern: /Invalid sender address/ },
+    { key: 'to', pattern: /Invalid recipient address/ },
+    { key: 'cc', pattern: /Invalid CC address/ },
+    { key: 'bcc', pattern: /Invalid BCC address/ },
+    { key: 'replyTo', pattern: /Invalid reply-to address/ },
+  ];
+
+  for (const { label, value } of lineBreaks) {
+    for (const { key, pattern } of addressFields) {
+      it(`should reject ${label} in a ${key} address object`, () => {
+        const constructor = {
+          from: 'sender@example.com',
+          to: 'recipient@example.com',
+          subject: 'Test Subject',
+          content: { text: 'Test content' },
+          [key]: {
+            address: `victim@example.net${value}Bcc: attacker@evil.example`,
+          },
+        };
+
+        assert.throws(() => createMessage(constructor), { name: 'TypeError', message: pattern });
+      });
+    }
+
+    it(`should reject ${label} in an address string`, () => {
+      const constructor = {
+        from: 'sender@example.com',
+        to: `victim@example.net${value}Bcc: attacker@evil.example`,
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+      };
+
+      assert.throws(() => createMessage(constructor), {
+        name: 'TypeError',
+        message: /Invalid recipient address/,
+      });
+    });
+
+    it(`should reject ${label} in an attachment content type`, () => {
+      const constructor = {
+        from: 'sender@example.com',
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [
+          {
+            inline: false,
+            filename: 'report.pdf',
+            content: new Uint8Array([1, 2, 3]),
+            contentType: `application/pdf${value}X-Injected: header`,
+            contentId: 'cid@example.com',
+          },
+        ],
+      };
+
+      assert.throws(() => createMessage(constructor), {
+        name: 'TypeError',
+        message: /Invalid attachment content type/,
+      });
+    });
+
+    it(`should reject ${label} in an attachment content ID`, () => {
+      const constructor = {
+        from: 'sender@example.com',
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [
+          {
+            inline: true,
+            filename: 'logo.png',
+            content: new Uint8Array([1, 2, 3]),
+            contentType: 'image/png',
+            contentId: `cid@example.com>${value}X-Injected: header`,
+          },
+        ],
+      };
+
+      assert.throws(() => createMessage(constructor), {
+        name: 'TypeError',
+        message: /Invalid attachment content ID/,
+      });
+    });
+  }
+
+  it('should accept addresses and attachments without CR or LF', () => {
+    const message = createMessage({
+      from: { name: 'Sender', address: 'sender@example.com' },
+      to: { address: 'recipient@example.com' },
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+      attachments: [
+        {
+          inline: false,
+          filename: 'report.pdf',
+          content: new Uint8Array([1, 2, 3]),
+          contentType: 'application/pdf',
+          contentId: 'cid@example.com',
+        },
+      ],
+    });
+
+    assert.deepEqual(message.sender, {
+      name: 'Sender',
+      address: 'sender@example.com',
+    });
+    assert.equal(message.attachments.length, 1);
+    assert.equal(message.attachments[0].contentType, 'application/pdf');
+  });
+
+  it('should throw TypeError for invalid sender address', () => {
+    const constructor = {
+      from: 'invalid-email',
+      to: 'recipient@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+    };
+
+    assert.throws(() => createMessage(constructor), {
+      name: 'TypeError',
+      message: /Invalid sender address/,
+    });
+  });
+
+  it('should throw TypeError for invalid recipient address', () => {
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'invalid-email',
+      subject: 'Test',
+      content: { text: 'Test' },
+    };
+
+    assert.throws(() => createMessage(constructor), {
+      name: 'TypeError',
+      message: /Invalid recipient address/,
+    });
+  });
+
+  it('should throw TypeError for invalid CC address', () => {
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      cc: 'invalid-email',
+      subject: 'Test',
+      content: { text: 'Test' },
+    };
+
+    assert.throws(() => createMessage(constructor), {
+      name: 'TypeError',
+      message: /Invalid CC address/,
+    });
+  });
+
+  it('should throw TypeError for invalid BCC address', () => {
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      bcc: 'invalid-email',
+      subject: 'Test',
+      content: { text: 'Test' },
+    };
+
+    assert.throws(() => createMessage(constructor), {
+      name: 'TypeError',
+      message: /Invalid BCC address/,
+    });
+  });
+
+  it('should throw TypeError for invalid reply-to address', () => {
+    const constructor = {
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      replyTo: 'invalid-email',
+      subject: 'Test',
+      content: { text: 'Test' },
+    };
+
+    assert.throws(() => createMessage(constructor), {
+      name: 'TypeError',
+      message: /Invalid reply-to address/,
+    });
+  });
+});
+
+describe('createMessage() identity and threading', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Test',
+    content: { text: 'Test' },
+  };
+
+  it('should leave the fields unset when they are not given', () => {
+    const message = createMessage(base);
+
+    assert.equal(message.messageId, undefined);
+    assert.equal(message.date, undefined);
+    assert.equal(message.inReplyTo, undefined);
+    assert.equal(message.references, undefined);
+  });
+
+  it('should strip the angle brackets from an identifier', () => {
+    const message = createMessage({
+      ...base,
+      messageId: '<123@example.com>',
+      inReplyTo: '<122@example.com>',
+      references: ['<120@example.com>', '121@example.com'],
+    });
+
+    assert.equal(message.messageId, '123@example.com');
+    assert.deepEqual(message.inReplyTo, ['122@example.com']);
+    assert.deepEqual(message.references, ['120@example.com', '121@example.com']);
+  });
+
+  it('should keep an empty list distinct from an absent one', () => {
+    const message = createMessage({ ...base, inReplyTo: [], references: [] });
+
+    assert.deepEqual(message.inReplyTo, []);
+    assert.deepEqual(message.references, []);
+  });
+
+  it('should treat a single string as one identifier', () => {
+    const message = createMessage({ ...base, references: '120@example.com' });
+
+    assert.deepEqual(message.references, ['120@example.com']);
+  });
+
+  it('should copy the date and the identifier lists', () => {
+    const date = new Date('2026-09-01T10:00:00Z');
+    const references = ['120@example.com'];
+    const message = createMessage({ ...base, date, references });
+
+    date.setUTCFullYear(1999);
+    references.push('121@example.com');
+
+    assert.equal(message.date?.toISOString(), '2026-09-01T10:00:00.000Z');
+    assert.deepEqual(message.references, ['120@example.com']);
+  });
+
+  const invalidIds = [
+    '',
+    'no-at-sign',
+    'a@b c@d',
+    'a..b@example.com',
+    'a@example.com>',
+    'a@example.com\r\nX-Injected: yes',
+  ];
+
+  for (const invalid of invalidIds) {
+    it(`should reject ${JSON.stringify(invalid)} as a message ID`, () => {
+      assert.throws(() => createMessage({ ...base, messageId: invalid }), {
+        name: 'TypeError',
+        message: /Invalid message ID/,
+      });
+    });
+
+    it(`should reject ${JSON.stringify(invalid)} in a reply reference`, () => {
+      assert.throws(() => createMessage({ ...base, inReplyTo: invalid }), {
+        name: 'TypeError',
+        message: /Invalid in-reply-to message ID/,
+      });
+      assert.throws(() => createMessage({ ...base, references: [invalid] }), {
+        name: 'TypeError',
+        message: /Invalid references message ID/,
+      });
+    });
+  }
+
+  it('should reject an invalid date', () => {
+    assert.throws(() => createMessage({ ...base, date: new Date('nonsense') }), {
+      name: 'TypeError',
+      message: /Invalid date/,
+    });
+  });
+
+  it('should reject a date RFC 5322 cannot express', () => {
+    assert.throws(() => createMessage({ ...base, date: new Date('1899-12-31T23:59:59Z') }), {
+      name: 'TypeError',
+      message: /Invalid date/,
+    });
+    assert.doesNotThrow(() => createMessage({ ...base, date: new Date('1900-01-01T00:00:00Z') }));
+  });
+});
+
+describe('createMessage() calendar', () => {
+  const base = {
+    from: 'organizer@example.com',
+    to: 'attendee@example.net',
+    subject: 'Lunch',
+    content: { text: 'Lunch on Wednesday.' },
+  };
+
+  const request =
+    [
+      'BEGIN:VCALENDAR',
+      'VERSION:2.0',
+      'METHOD:REQUEST',
+      'BEGIN:VEVENT',
+      'UID:1@example.com',
+      'END:VEVENT',
+      'END:VCALENDAR',
+    ].join('\r\n') + '\r\n';
+
+  it('should leave the field unset when no calendar is given', () => {
+    assert.equal(createMessage(base).calendar, undefined);
+  });
+
+  it('should resolve the method from the content', () => {
+    const message = createMessage({ ...base, calendar: { content: request } });
+    assert.deepEqual(message.calendar, { method: 'REQUEST', content: request });
+  });
+
+  it('should accept a method asserting what the content declares', () => {
+    const message = createMessage({
+      ...base,
+      calendar: { method: 'REQUEST', content: request },
+    });
+    assert.equal(message.calendar?.method, 'REQUEST');
+  });
+
+  it('should normalize the line endings of the content', () => {
+    const message = createMessage({
+      ...base,
+      calendar: {
+        content: 'BEGIN:VCALENDAR\nMETHOD:CANCEL\nEND:VCALENDAR\n',
+      },
+    });
+    assert.equal(message.calendar?.method, 'CANCEL');
+    assert.equal(
+      message.calendar?.content,
+      'BEGIN:VCALENDAR\r\nMETHOD:CANCEL\r\nEND:VCALENDAR\r\n',
+    );
+  });
+
+  it('should reject a method that disagrees with the content', () => {
+    assert.throws(
+      () =>
+        createMessage({
+          ...base,
+          calendar: { method: 'CANCEL', content: request },
+        }),
+      { name: 'TypeError', message: /METHOD:REQUEST/ },
+    );
+  });
+
+  it('should reject content that declares no method', () => {
+    assert.throws(
+      () =>
+        createMessage({
+          ...base,
+          calendar: {
+            content: 'BEGIN:VCALENDAR\r\nVERSION:2.0\r\nEND:VCALENDAR\r\n',
+          },
+        }),
+      { name: 'TypeError', message: /METHOD/ },
+    );
+  });
+
+  it('should reject malformed calendar property syntax', () => {
+    assert.throws(
+      () =>
+        createMessage({
+          ...base,
+          calendar: {
+            content:
+              'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nSUMMARY;BROKEN:Lunch\r\nEND:VCALENDAR\r\n',
+          },
+        }),
+      TypeError,
+    );
+  });
+
+  it('should reject content that is not a calendar object', () => {
+    assert.throws(() => createMessage({ ...base, calendar: { content: 'METHOD:REQUEST' } }), {
+      name: 'TypeError',
+    });
+  });
+});
diff --git a/tests/unit/priority.test.js b/tests/unit/priority.test.js
new file mode 100644
index 0000000..c9dd43f
--- /dev/null
+++ b/tests/unit/priority.test.js
@@ -0,0 +1,20 @@
+// Ported from upyo v0.7.0 (packages/core/src/priority.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { comparePriority } = require('../../src/core/priority.js');
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+
+test('comparePriority()', () => {
+  const priorities = ['normal', 'low', 'high'];
+  priorities.sort(comparePriority);
+  assert.deepStrictEqual(priorities, ['high', 'normal', 'low']);
+
+  // Test individual comparisons
+  assert.strictEqual(comparePriority('high', 'normal'), -1);
+  assert.strictEqual(comparePriority('normal', 'high'), 1);
+  assert.strictEqual(comparePriority('low', 'normal'), 1);
+  assert.strictEqual(comparePriority('normal', 'low'), -1);
+  assert.strictEqual(comparePriority('high', 'low'), -1);
+  assert.strictEqual(comparePriority('low', 'high'), 1);
+});
diff --git a/tests/unit/raw-message.test.js b/tests/unit/raw-message.test.js
new file mode 100644
index 0000000..0948878
--- /dev/null
+++ b/tests/unit/raw-message.test.js
@@ -0,0 +1,204 @@
+// Ported from upyo v0.7.0 (packages/core/src/raw-message.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const {
+  analyzeRawMessage,
+  createRawMessagePlan,
+  iterateRawMessage,
+  RawMessageValidationError,
+} = require('../../src/core/raw-message.js');
+const { isRawTransport } = require('../../src/core/transport.js');
+
+const bytes = (s) => new TextEncoder().encode(s);
+const envelope = { from: 'a@example.com', to: ['b@example.com'] };
+const message = (text) => ({
+  envelope,
+  content: bytes(text),
+});
+const collect = async (plan) => {
+  const result = [];
+  for await (const chunk of iterateRawMessage(plan)) result.push(...chunk);
+  return new Uint8Array(result);
+};
+
+test('raw capability guard preserves the provider type', () => {
+  const transport = {
+    id: 'test',
+    send: () => Promise.resolve({ successful: true, provider: 'test', messageId: 'x' }),
+    async *sendMany() {},
+  };
+  assert.ok(!isRawTransport(transport));
+  const raw = { ...transport, sendRaw: transport.send };
+  assert.ok(isRawTransport(raw));
+});
+
+test('raw analysis accepts headers-only and preserves every chunk boundary', async () => {
+  const content = bytes('Subject: hello\r\n\r\n.body\r\n');
+  for (let split = 0; split <= content.length; split++) {
+    const plan = createRawMessagePlan({
+      envelope,
+      content: async function* () {
+        yield content.subarray(0, split);
+        yield content.subarray(split);
+      },
+    });
+    assert.deepEqual(await analyzeRawMessage(plan), {
+      size: content.length,
+      encoding: '7bit',
+    });
+    assert.deepEqual(await collect(plan), content);
+  }
+  assert.deepEqual(
+    await collect(createRawMessagePlan(message('Subject: x\r\n'))),
+    bytes('Subject: x\r\n'),
+  );
+});
+
+test('raw validation rejects invalid lines with locations', async () => {
+  for (const input of [
+    '',
+    '\r\n',
+    'X: y\n',
+    'X: y\r',
+    'X: y',
+    'X: \0\r\n',
+    'X:' + 'x'.repeat(997) + '\r\n',
+  ]) {
+    await assert.rejects(collect(createRawMessagePlan(message(input))), (error) => {
+      assert.ok(error instanceof RawMessageValidationError);
+      assert.equal(error.field, 'content');
+      assert.equal(typeof error.byteOffset, 'number');
+      assert.equal(typeof error.lineNumber, 'number');
+      return true;
+    });
+  }
+  await collect(createRawMessagePlan(message('X:' + 'x'.repeat(996) + '\r\n')));
+});
+
+test('raw encoding is conservative and declared 7bit is enforced', async () => {
+  const raw = message('X: y\r\n\r\nó\r\n');
+  assert.equal((await analyzeRawMessage(createRawMessagePlan(raw))).encoding, 'utf8');
+  await assert.rejects(
+    collect(createRawMessagePlan({ ...raw, encoding: '7bit' })),
+    RawMessageValidationError,
+  );
+  await collect(createRawMessagePlan({ ...raw, encoding: '8bit' }));
+});
+
+test('raw plans copy envelopes and observe rejected content before validation', async () => {
+  const recipients = ['b@example.com'];
+  const plan = createRawMessagePlan({
+    ...message('X: y\r\n'),
+    envelope: { from: null, to: recipients },
+  });
+  recipients.length = 0;
+  assert.deepEqual(plan.envelope.to, ['b@example.com']);
+  assert.throws(
+    () =>
+      createRawMessagePlan({
+        envelope: { from: null, to: [] },
+        content: Promise.reject(new TypeError('source')),
+      }),
+    RawMessageValidationError,
+  );
+  await new Promise((resolve) => setTimeout(resolve, 0));
+});
+
+test('raw sources support all replayable kinds and one or two traversals', async () => {
+  const content = bytes('X: y\r\n');
+  for (const source of [content, Promise.resolve(content), new Blob([content])]) {
+    const plan = createRawMessagePlan({ envelope, content: source });
+    assert.deepEqual(await collect(plan), content);
+    assert.deepEqual(await collect(plan), content);
+  }
+  let opens = 0;
+  const plan = createRawMessagePlan({
+    envelope,
+    encoding: '7bit',
+    content: async function* () {
+      opens++;
+      yield content;
+    },
+  });
+  await collect(plan);
+  assert.equal(opens, 1);
+  await analyzeRawMessage(plan);
+  await collect(plan);
+  assert.equal(opens, 3);
+});
+
+test('second traversal revalidates structure and known length', async () => {
+  let opens = 0;
+  const plan = createRawMessagePlan({
+    envelope,
+    content: async function* () {
+      yield bytes(opens++ === 0 ? 'X: y\r\n' : 'X: y\n\n');
+    },
+  });
+  const info = await analyzeRawMessage(plan);
+  await assert.rejects(async () => {
+    // oxlint-disable-next-line no-unused-vars -- upstream: the chunks are consumed, not read
+    for await (const _ of iterateRawMessage(plan, { expectedSize: info.size })) {
+      /* consume */
+    }
+  }, RawMessageValidationError);
+  await assert.rejects(async () => {
+    // oxlint-disable-next-line no-unused-vars -- upstream: the chunks are consumed, not read
+    for await (const _ of iterateRawMessage(createRawMessagePlan(message('X: y\r\n')), {
+      expectedSize: 99,
+    })) {
+      /* consume */
+    }
+  }, RawMessageValidationError);
+});
+
+test('raw cancellation closes a pending producer once and preserves its reason', async () => {
+  let closed = 0;
+  let started;
+  const ready = new Promise((resolve) => (started = resolve));
+  const controller = new AbortController();
+  const reason = new TypeError('stop');
+  const plan = createRawMessagePlan({
+    envelope,
+    content: () => ({
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            started();
+            return new Promise(() => {});
+          },
+          return() {
+            closed++;
+            return Promise.resolve({ done: true, value: undefined });
+          },
+        };
+      },
+    }),
+  });
+  const reading = analyzeRawMessage(plan, controller.signal);
+  await ready;
+  controller.abort(reason);
+  await assert.rejects(reading, (e) => e === reason);
+  assert.equal(closed, 1);
+});
+
+test('raw cancellation at final progress rejects instead of reporting EOF', async () => {
+  const controller = new AbortController();
+  const reason = new TypeError('stop at last byte');
+  await assert.rejects(
+    analyzeRawMessage(createRawMessagePlan(message('X: y\r\n')), controller.signal, () =>
+      controller.abort(reason),
+    ),
+    (error) => error === reason,
+  );
+});
+
+test('raw analysis retains validated explicit encoding requirements', async () => {
+  const plan = createRawMessagePlan({
+    ...message('X: y\r\n\r\nó\r\n'),
+    encoding: '8bit',
+  });
+  assert.equal((await analyzeRawMessage(plan)).encoding, '8bit');
+});
diff --git a/tests/unit/receipt.test.js b/tests/unit/receipt.test.js
new file mode 100644
index 0000000..8ba34d8
--- /dev/null
+++ b/tests/unit/receipt.test.js
@@ -0,0 +1,257 @@
+// Ported from upyo v0.7.0 (packages/core/src/receipt.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const {
+  classifyHttpStatus,
+  classifyReceiptError,
+  createFailedReceipt,
+  createReceiptError,
+  parseRetryAfter,
+} = require('../../src/core/receipt.js');
+
+describe('Receipt errors', () => {
+  it('classifies HTTP statuses into retryable receipt categories', () => {
+    assert.deepEqual(classifyHttpStatus(401), {
+      category: 'auth',
+      retryable: false,
+    });
+    assert.deepEqual(classifyHttpStatus(429), {
+      category: 'rate-limit',
+      retryable: true,
+    });
+    assert.deepEqual(classifyHttpStatus(409), {
+      category: 'validation',
+      retryable: false,
+    });
+    assert.deepEqual(classifyHttpStatus(422), {
+      category: 'validation',
+      retryable: false,
+    });
+    assert.deepEqual(classifyHttpStatus(500), {
+      category: 'server-error',
+      retryable: true,
+    });
+    assert.deepEqual(classifyHttpStatus(503), {
+      category: 'service-unavailable',
+      retryable: true,
+    });
+  });
+
+  it('parses Retry-After seconds and HTTP dates', () => {
+    assert.equal(parseRetryAfter('120'), 120_000);
+    assert.equal(parseRetryAfter('0'), 0);
+
+    const now = new Date('2026-06-30T00:00:00.000Z');
+    const retryAt = 'Tue, 30 Jun 2026 00:02:00 GMT';
+    assert.equal(parseRetryAfter(retryAt, now), 120_000);
+  });
+
+  it('ignores missing, invalid, and past Retry-After values', () => {
+    const now = new Date('2026-06-30T00:00:00.000Z');
+
+    assert.equal(parseRetryAfter(null, now), undefined);
+    assert.equal(parseRetryAfter('', now), undefined);
+    assert.equal(parseRetryAfter('not a date', now), undefined);
+    assert.equal(parseRetryAfter('Mon, 29 Jun 2026 00:00:00 GMT', now), undefined);
+  });
+
+  it('creates structured receipt errors from HTTP status metadata', () => {
+    const error = createReceiptError('Too Many Requests', {
+      provider: 'sendgrid',
+      statusCode: 429,
+      retryAfterMilliseconds: 30_000,
+      providerDetails: { requestId: 'req_123' },
+    });
+
+    assert.deepEqual(error, {
+      message: 'Too Many Requests',
+      category: 'rate-limit',
+      code: 'http.429',
+      retryable: true,
+      provider: 'sendgrid',
+      statusCode: 429,
+      retryAfterMilliseconds: 30_000,
+      providerDetails: { requestId: 'req_123' },
+    });
+  });
+
+  it('creates failed receipts with summary metadata', () => {
+    const receipt = createFailedReceipt('Network error', {
+      provider: 'mailgun',
+      category: 'network',
+      retryable: true,
+      attempts: 3,
+      timestamp: '2026-06-30T00:00:00.000Z',
+    });
+
+    assert.deepEqual(receipt, {
+      successful: false,
+      errorMessages: ['Network error'],
+      errors: [
+        {
+          message: 'Network error',
+          category: 'network',
+          code: 'network',
+          retryable: true,
+          provider: 'mailgun',
+        },
+      ],
+      retryable: true,
+      provider: 'mailgun',
+      attempts: 3,
+      timestamp: '2026-06-30T00:00:00.000Z',
+    });
+  });
+
+  it('keeps legacy failed receipts assignable', () => {
+    const receipt = {
+      successful: false,
+      errorMessages: ['Legacy failure'],
+    };
+
+    assert.equal(receipt.successful, false);
+    assert.deepEqual(receipt.errorMessages, ['Legacy failure']);
+  });
+
+  it('classifies generic errors without HTTP metadata', () => {
+    assert.deepEqual(classifyReceiptError(new Error('Connection timed out')), {
+      category: 'timeout',
+      retryable: true,
+      code: 'timeout',
+    });
+    assert.deepEqual(classifyReceiptError(new Error('Invalid API key')), {
+      category: 'auth',
+      retryable: false,
+      code: 'auth',
+    });
+    assert.deepEqual(classifyReceiptError('Authorization failed'), {
+      category: 'auth',
+      retryable: false,
+      code: 'auth',
+    });
+    assert.deepEqual(classifyReceiptError('Not authorized'), {
+      category: 'auth',
+      retryable: false,
+      code: 'auth',
+    });
+    assert.deepEqual(classifyReceiptError('Rate-limit exceeded'), {
+      category: 'rate-limit',
+      retryable: true,
+      code: 'rate-limit',
+    });
+    assert.deepEqual(classifyReceiptError('Something unexpected'), {
+      category: 'unknown',
+      retryable: false,
+      code: 'unknown',
+    });
+    assert.deepEqual(classifyReceiptError('Author domain failed policy checks'), {
+      category: 'unknown',
+      retryable: false,
+      code: 'unknown',
+    });
+    assert.deepEqual(classifyReceiptError('Certification authority unavailable'), {
+      category: 'unknown',
+      retryable: false,
+      code: 'unknown',
+    });
+  });
+
+  it('classifies error-like objects with message and name properties', () => {
+    assert.deepEqual(
+      classifyReceiptError({
+        name: 'NetworkError',
+        message: 'socket disconnected',
+      }),
+      {
+        category: 'network',
+        retryable: true,
+        code: 'network',
+      },
+    );
+  });
+
+  it('honors explicit category overrides when deriving error codes', () => {
+    const error = createReceiptError('Provider rejected the message', {
+      category: 'rejected',
+    });
+
+    assert.equal(error.category, 'rejected');
+    assert.equal(error.code, 'rejected');
+  });
+
+  it('keeps HTTP status codes when explicit categories are provided', () => {
+    const error = createReceiptError('Too many requests', {
+      category: 'rate-limit',
+      statusCode: 429,
+    });
+
+    assert.equal(error.category, 'rate-limit');
+    assert.equal(error.code, 'http.429');
+  });
+
+  it('normalizes mixed failed receipt error arrays', () => {
+    const receipt = createFailedReceipt(
+      ['Rate-limit exceeded', createReceiptError('Unauthorized', { provider: 'sendgrid' })],
+      {
+        timestamp: '2026-06-30T00:00:00.000Z',
+      },
+    );
+
+    assert.deepEqual(receipt.errorMessages, ['Rate-limit exceeded', 'Unauthorized']);
+    assert.deepEqual(receipt.errors, [
+      {
+        message: 'Rate-limit exceeded',
+        category: 'rate-limit',
+        code: 'rate-limit',
+        retryable: true,
+      },
+      {
+        message: 'Unauthorized',
+        category: 'auth',
+        code: 'auth',
+        retryable: false,
+        provider: 'sendgrid',
+      },
+    ]);
+    assert.equal(receipt.retryable, true);
+  });
+});
+
+const typedError = createReceiptError('Too many requests', {
+  provider: 'mailgun',
+  statusCode: 429,
+});
+const typedErrorProvider = typedError.provider;
+
+const typedReceipt = createFailedReceipt('Too many requests', {
+  provider: 'sendgrid',
+  statusCode: 429,
+});
+const typedReceiptProvider = typedReceipt.provider;
+
+const typedTransport = {
+  id: 'smtp',
+  send() {
+    return Promise.resolve({
+      successful: true,
+      messageId: 'message-id',
+      provider: 'smtp',
+    });
+  },
+  async *sendMany() {
+    yield {
+      successful: true,
+      messageId: 'message-id',
+      provider: 'smtp',
+    };
+  },
+};
+const typedTransportId = typedTransport.id;
+
+// oxlint-disable no-void -- upstream: marks the values of TypeScript type checks as used
+void typedErrorProvider;
+void typedReceiptProvider;
+void typedTransportId;
+// oxlint-enable no-void
diff --git a/tests/unit/transport.test.js b/tests/unit/transport.test.js
new file mode 100644
index 0000000..54705b1
--- /dev/null
+++ b/tests/unit/transport.test.js
@@ -0,0 +1,28 @@
+// Ported from upyo v0.7.0 (packages/core/src/transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { isVerifiableTransport } = require('../../src/core/transport.js');
+
+test('verification is an optional capability preserving the provider', async () => {
+  const transport = {
+    id: 'test',
+    send: () => Promise.resolve({ successful: true, messageId: 'x' }),
+    async *sendMany() {},
+  };
+  assert.ok(!isVerifiableTransport(transport));
+  const invalid = { ...transport, verify: true };
+  assert.ok(!isVerifiableTransport(invalid));
+  let called = false;
+  const capable = Object.assign({}, transport, {
+    verify: () => {
+      called = true;
+      return Promise.resolve();
+    },
+  });
+  assert.ok(isVerifiableTransport(capable));
+  const narrowed = capable;
+  assert.equal(await narrowed.verify(), undefined);
+  assert.ok(called);
+});

From d9df47771c68fedba045690f671355a269e2c48b Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 20:48:02 +0300
Subject: [PATCH 003/158] feat(mock): port the mock transport from upyo 0.7.0

./mock exports MockTransport: a transport that keeps what it is sent in
memory, with a configurable response, delay and failure rate, and helpers to
find and wait for messages. It is upstream's code converted to CommonJS, with
its types in src/mock/index.d.ts and its suites ported as they are;
tests/unit/mock.test.js covers the setters, aborts and timeouts they leave
out. The pool suites of a later commit use it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                    |   2 +-
 package.json                                |   4 +
 src/mock/config.js                          |  38 ++
 src/mock/index.d.ts                         | 267 ++++++++++++++
 src/mock/index.js                           |  39 ++
 src/mock/mock-transport.js                  | 377 ++++++++++++++++++++
 tests/helpers/mock/mock-validation-utils.js | 136 +++++++
 tests/helpers/mock/test-config.js           |  33 ++
 tests/types/mock.test-d.ts                  |  23 ++
 tests/unit/mock-config.test.js              |  97 +++++
 tests/unit/mock-transport.test.js           | 313 ++++++++++++++++
 tests/unit/mock.test.js                     |  73 ++++
 12 files changed, 1401 insertions(+), 1 deletion(-)
 create mode 100644 src/mock/config.js
 create mode 100644 src/mock/index.d.ts
 create mode 100644 src/mock/index.js
 create mode 100644 src/mock/mock-transport.js
 create mode 100644 tests/helpers/mock/mock-validation-utils.js
 create mode 100644 tests/helpers/mock/test-config.js
 create mode 100644 tests/types/mock.test-d.ts
 create mode 100644 tests/unit/mock-config.test.js
 create mode 100644 tests/unit/mock-transport.test.js
 create mode 100644 tests/unit/mock.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ab2430a..5797608 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7
+      - run: pnpm size --max-gzip 7 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 49633d9..d29d006 100644
--- a/package.json
+++ b/package.json
@@ -23,6 +23,10 @@
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
+    },
+    "./mock": {
+      "types": "./src/mock/index.d.ts",
+      "default": "./src/mock/index.js"
     }
   },
   "directories": {
diff --git a/src/mock/config.js b/src/mock/config.js
new file mode 100644
index 0000000..6b99c84
--- /dev/null
+++ b/src/mock/config.js
@@ -0,0 +1,38 @@
+// Ported from upyo v0.7.0 (packages/mock/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved mock configuration by applying default values to optional fields.
+ *
+ * This function takes a partial mock configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ *
+ * @param config - The mock configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ *
+ * @example
+ * ```typescript
+ * const resolved = createMockConfig({
+ *   delay: 100
+ * });
+ *
+ * // resolved.defaultResponse will be { successful: true, messageId: "mock-message-id" }
+ * // resolved.failureRate will be 0 (default)
+ * // resolved.generateUniqueMessageIds will be true (default)
+ * ```
+ */
+const createMockConfig = (config = {}) => {
+  return {
+    defaultResponse: config.defaultResponse ?? {
+      successful: true,
+      messageId: 'mock-message-id',
+      provider: 'mock',
+    },
+    delay: config.delay ?? 0,
+    randomDelayRange: config.randomDelayRange ?? { min: 0, max: 0 },
+    failureRate: config.failureRate ?? 0,
+    generateUniqueMessageIds: config.generateUniqueMessageIds ?? true,
+  };
+};
+
+module.exports = { createMockConfig };
diff --git a/src/mock/index.d.ts b/src/mock/index.d.ts
new file mode 100644
index 0000000..3c17a26
--- /dev/null
+++ b/src/mock/index.d.ts
@@ -0,0 +1,267 @@
+// Types ported from upyo v0.7.0 (packages/mock/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Configuration interface for Mock transport.
+ *
+ * This interface defines options for configuring the mock transport's
+ * behavior for testing scenarios.
+ *
+ * @example
+ * ```typescript
+ * const config: MockConfig = {
+ *   defaultResponse: { successful: true, messageId: "test-123" },
+ *   delay: 100,
+ *   failureRate: 0.1
+ * };
+ * ```
+ */
+export interface MockConfig {
+  /**
+   * The default response to return for send operations.
+   *
+   * @default { successful: true, messageId: "mock-message-id" }
+   */
+  readonly defaultResponse?: Receipt<'mock'>;
+  /**
+   * Fixed delay in milliseconds for all send operations.
+   *
+   * @default 0
+   */
+  readonly delay?: number;
+  /**
+   * Random delay range in milliseconds for send operations.
+   * When set, overrides the fixed delay setting.
+   */
+  readonly randomDelayRange?: {
+    readonly min: number;
+    readonly max: number;
+  };
+  /**
+   * Failure rate (0.0 to 1.0) for random failures.
+   * When set, sends will randomly fail at the specified rate.
+   *
+   * @default 0
+   */
+  readonly failureRate?: number;
+  /**
+   * Whether to automatically generate unique message IDs for successful responses.
+   *
+   * @default true
+   */
+  readonly generateUniqueMessageIds?: boolean;
+}
+/**
+ * Resolved mock configuration with all optional fields filled with default values.
+ *
+ * This type represents the final configuration after applying defaults,
+ * used internally by the mock transport implementation.
+ */
+type ResolvedMockConfig = Required<MockConfig>;
+/**
+ * Creates a resolved mock configuration by applying default values to optional fields.
+ *
+ * This function takes a partial mock configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ *
+ * @param config - The mock configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ *
+ * @example
+ * ```typescript
+ * const resolved = createMockConfig({
+ *   delay: 100
+ * });
+ *
+ * // resolved.defaultResponse will be { successful: true, messageId: "mock-message-id" }
+ * // resolved.failureRate will be 0 (default)
+ * // resolved.generateUniqueMessageIds will be true (default)
+ * ```
+ */
+
+/**
+ * A mock transport implementation for testing purposes.
+ *
+ * This transport doesn't actually send emails but stores them in memory,
+ * making it useful for unit testing email functionality. It provides
+ * comprehensive testing capabilities including message verification,
+ * behavior simulation, and async utilities.
+ */
+export declare class MockTransport implements Transport<'mock'> {
+  readonly id = 'mock';
+  /**
+   * The resolved configuration used by this mock transport.
+   */
+  config: ResolvedMockConfig;
+  /**
+   * Creates a new MockTransport instance.
+   *
+   * @param config Configuration options for the mock transport behavior.
+   */
+  constructor(config?: MockConfig);
+  /**
+   * Sends an email message through the mock transport.
+   *
+   * The message is stored in memory and can be retrieved for testing verification.
+   * Respects configured delays, failure rates, and response overrides.
+   *
+   * @param message The email message to send.
+   * @param options Transport options including abort signal.
+   * @returns A promise that resolves to a receipt indicating success or failure.
+   * @throws {DOMException} When the operation is aborted via `AbortSignal`.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'mock'>>;
+  /**
+   * Sends multiple email messages through the mock transport.
+   *
+   * Each message is processed sequentially using the send() method, respecting
+   * all configured behavior including delays and failure rates.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Transport options including abort signal.
+   * @returns An async iterable of receipts, one for each message.
+   * @throws {DOMException} When the operation is aborted via `AbortSignal`.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'mock'>>;
+  /**
+   * Get all messages that have been "sent" through this transport.
+   *
+   * @returns A readonly array containing copies of all sent messages.
+   */
+  getSentMessages(): readonly Message[];
+  /**
+   * Get the last message that was sent, or undefined if no messages have been sent.
+   *
+   * @returns The most recently sent message, or undefined if none.
+   */
+  getLastSentMessage(): Message | undefined;
+  /**
+   * Get the total number of messages that have been sent.
+   *
+   * @returns The count of messages sent through this transport.
+   */
+  getSentMessagesCount(): number;
+  /**
+   * Clear all stored messages.
+   *
+   * This removes all messages from the internal storage but does not
+   * reset other configuration like delays or failure rates.
+   */
+  clearSentMessages(): void;
+  /**
+   * Set the response that will be returned for the next send operation.
+   *
+   * After being used once, it will revert to the default response.
+   * This is useful for testing specific success or failure scenarios.
+   *
+   * @param receipt The receipt to return for the next send operation.
+   */
+  setNextResponse(receipt: Receipt<'mock'>): void;
+  /**
+   * Set the default response that will be returned for send operations.
+   *
+   * This response is used when no next response is set and random failures
+   * are not triggered.
+   *
+   * @param receipt The default receipt to return for send operations.
+   */
+  setDefaultResponse(receipt: Receipt<'mock'>): void;
+  /**
+   * Set the failure rate (0.0 to 1.0). When set, sends will randomly fail
+   * at the specified rate instead of using the configured responses.
+   *
+   * @param rate The failure rate as a decimal between 0.0 and 1.0.
+   * @throws {RangeError} When rate is not between 0.0 and 1.0.
+   */
+  setFailureRate(rate: number): void;
+  /**
+   * Set a fixed delay in milliseconds for all send operations.
+   *
+   * This overrides any random delay range that was previously configured.
+   *
+   * @param milliseconds The delay in milliseconds (must be non-negative).
+   * @throws {RangeError} When milliseconds is negative.
+   */
+  setDelay(milliseconds: number): void;
+  /**
+   * Set a random delay range in milliseconds for send operations.
+   *
+   * This overrides any fixed delay that was previously configured.
+   *
+   * @param min The minimum delay in milliseconds.
+   * @param max The maximum delay in milliseconds.
+   * @throws {RangeError} When min or max is negative, or min > max.
+   */
+  setRandomDelay(min: number, max: number): void;
+  /**
+   * Find the first message matching the given predicate.
+   *
+   * @param predicate A function that tests each message.
+   * @returns The first matching message, or undefined if none found.
+   */
+  findMessageBy(predicate: (message: Message) => boolean): Message | undefined;
+  /**
+   * Find all messages matching the given predicate.
+   *
+   * @param predicate A function that tests each message.
+   * @returns An array of all matching messages.
+   */
+  findMessagesBy(predicate: (message: Message) => boolean): readonly Message[];
+  /**
+   * Get all messages sent to a specific email address.
+   *
+   * Searches through To, CC, and BCC recipients to find messages
+   * that were sent to the specified email address.
+   *
+   * @param email The email address to search for.
+   * @returns An array of messages sent to the specified address.
+   */
+  getMessagesTo(email: string): readonly Message[];
+  /**
+   * Get all messages with a specific subject.
+   *
+   * @param subject The exact subject line to match.
+   * @returns An array of messages with the specified subject.
+   */
+  getMessagesBySubject(subject: string): readonly Message[];
+  /**
+   * Wait for a specific number of messages to be sent.
+   *
+   * This method polls the message count until the target is reached or
+   * the timeout expires.  Useful for testing async email workflows where you
+   * need to wait for messages to be sent.
+   *
+   * @param count The number of messages to wait for.
+   * @param timeout The timeout in milliseconds (default: 5000).
+   * @returns A promise that resolves when the count is reached.
+   * @throws {Error} When the timeout is exceeded before reaching the target
+   *                 count.
+   */
+  waitForMessageCount(count: number, timeout?: number): Promise<void>;
+  /**
+   * Wait for a message matching the given predicate.
+   *
+   * This method polls for a matching message until one is found or the timeout
+   * expires.  Useful for testing async email workflows where you need to wait
+   * for specific messages.
+   *
+   * @param predicate A function that tests each message for a match.
+   * @param timeout The timeout in milliseconds (default: 5000).
+   * @returns A promise that resolves with the matching message.
+   * @throws {Error} When the timeout is exceeded before finding a matching
+   *                 message.
+   */
+  waitForMessage(predicate: (message: Message) => boolean, timeout?: number): Promise<Message>;
+  /**
+   * Reset the transport to its initial state.
+   *
+   * Clears all messages, resets all configuration to defaults, and
+   * resets the message ID counter. This is useful for test cleanup.
+   */
+  reset(): void;
+}
diff --git a/src/mock/index.js b/src/mock/index.js
new file mode 100644
index 0000000..cf3515c
--- /dev/null
+++ b/src/mock/index.js
@@ -0,0 +1,39 @@
+// Ported from upyo v0.7.0 (packages/mock/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * @alexify/mailer/mock - Mock email transport for testing
+ *
+ * A mock transport implementation that doesn't actually send emails but stores
+ * them in memory, making it useful for unit testing email functionality.
+ *
+ * @example
+ * ```typescript
+ * import { MockTransport } from "@alexify/mailer/mock";
+ * import { createMessage } from "@alexify/mailer";
+ *
+ * const transport = new MockTransport({
+ *   delay: 100, // Simulate network delay
+ *   failureRate: 0.1 // 10% failure rate
+ * });
+ *
+ * const message = createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Test Email",
+ *   content: { text: "This is a test email" }
+ * });
+ *
+ * await transport.send(message);
+ *
+ * // Verify the message was "sent"
+ * const sentMessages = transport.getSentMessages();
+ * console.log(`Sent ${sentMessages.length} messages`);
+ * ```
+ *
+ * @module
+ */
+
+const { MockTransport } = require('./mock-transport.js');
+
+module.exports = { MockTransport };
diff --git a/src/mock/mock-transport.js b/src/mock/mock-transport.js
new file mode 100644
index 0000000..8d6e039
--- /dev/null
+++ b/src/mock/mock-transport.js
@@ -0,0 +1,377 @@
+// Ported from upyo v0.7.0 (packages/mock/src/mock-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createMockConfig } = require('./config.js');
+
+/**
+ * A mock transport implementation for testing purposes.
+ *
+ * This transport doesn't actually send emails but stores them in memory,
+ * making it useful for unit testing email functionality. It provides
+ * comprehensive testing capabilities including message verification,
+ * behavior simulation, and async utilities.
+ */
+class MockTransport {
+  id = 'mock';
+
+  /**
+   * The resolved configuration used by this mock transport.
+   */
+  config;
+
+  sentMessages = [];
+  nextResponse = null;
+  messageIdCounter = 1;
+
+  /**
+   * Creates a new MockTransport instance.
+   *
+   * @param config Configuration options for the mock transport behavior.
+   */
+  constructor(config = {}) {
+    this.config = createMockConfig(config);
+  }
+
+  /**
+   * Sends an email message through the mock transport.
+   *
+   * The message is stored in memory and can be retrieved for testing verification.
+   * Respects configured delays, failure rates, and response overrides.
+   *
+   * @param message The email message to send.
+   * @param options Transport options including abort signal.
+   * @returns A promise that resolves to a receipt indicating success or failure.
+   * @throws {DOMException} When the operation is aborted via `AbortSignal`.
+   */
+  async send(message, options) {
+    // Check for cancellation
+    if (options?.signal?.aborted) {
+      throw new DOMException('The operation was aborted.', 'AbortError');
+    }
+
+    // Apply delay if configured
+    await this.applyDelay();
+
+    // Check for cancellation after delay
+    if (options?.signal?.aborted) {
+      throw new DOMException('The operation was aborted.', 'AbortError');
+    }
+
+    // Store the message
+    this.sentMessages.push(message);
+
+    // Determine response
+    const response = this.getResponse();
+
+    return response;
+  }
+
+  /**
+   * Sends multiple email messages through the mock transport.
+   *
+   * Each message is processed sequentially using the send() method, respecting
+   * all configured behavior including delays and failure rates.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Transport options including abort signal.
+   * @returns An async iterable of receipts, one for each message.
+   * @throws {DOMException} When the operation is aborted via `AbortSignal`.
+   */
+  async *sendMany(messages, options) {
+    for await (const message of messages) {
+      if (options?.signal?.aborted) {
+        throw new DOMException('The operation was aborted.', 'AbortError');
+      }
+      yield await this.send(message, options);
+    }
+  }
+
+  /**
+   * Get all messages that have been "sent" through this transport.
+   *
+   * @returns A readonly array containing copies of all sent messages.
+   */
+  getSentMessages() {
+    return [...this.sentMessages];
+  }
+
+  /**
+   * Get the last message that was sent, or undefined if no messages have been sent.
+   *
+   * @returns The most recently sent message, or undefined if none.
+   */
+  getLastSentMessage() {
+    return this.sentMessages[this.sentMessages.length - 1];
+  }
+
+  /**
+   * Get the total number of messages that have been sent.
+   *
+   * @returns The count of messages sent through this transport.
+   */
+  getSentMessagesCount() {
+    return this.sentMessages.length;
+  }
+
+  /**
+   * Clear all stored messages.
+   *
+   * This removes all messages from the internal storage but does not
+   * reset other configuration like delays or failure rates.
+   */
+  clearSentMessages() {
+    this.sentMessages = [];
+  }
+
+  /**
+   * Set the response that will be returned for the next send operation.
+   *
+   * After being used once, it will revert to the default response.
+   * This is useful for testing specific success or failure scenarios.
+   *
+   * @param receipt The receipt to return for the next send operation.
+   */
+  setNextResponse(receipt) {
+    this.nextResponse = receipt;
+  }
+
+  /**
+   * Set the default response that will be returned for send operations.
+   *
+   * This response is used when no next response is set and random failures
+   * are not triggered.
+   *
+   * @param receipt The default receipt to return for send operations.
+   */
+  setDefaultResponse(receipt) {
+    this.config = {
+      ...this.config,
+      defaultResponse: receipt,
+    };
+  }
+
+  /**
+   * Set the failure rate (0.0 to 1.0). When set, sends will randomly fail
+   * at the specified rate instead of using the configured responses.
+   *
+   * @param rate The failure rate as a decimal between 0.0 and 1.0.
+   * @throws {RangeError} When rate is not between 0.0 and 1.0.
+   */
+  setFailureRate(rate) {
+    if (rate < 0 || rate > 1) {
+      throw new RangeError('Failure rate must be between 0.0 and 1.0');
+    }
+    this.config = {
+      ...this.config,
+      failureRate: rate,
+    };
+  }
+
+  /**
+   * Set a fixed delay in milliseconds for all send operations.
+   *
+   * This overrides any random delay range that was previously configured.
+   *
+   * @param milliseconds The delay in milliseconds (must be non-negative).
+   * @throws {RangeError} When milliseconds is negative.
+   */
+  setDelay(milliseconds) {
+    if (milliseconds < 0) {
+      throw new RangeError('Delay must be non-negative');
+    }
+    this.config = {
+      ...this.config,
+      delay: milliseconds,
+      randomDelayRange: { min: 0, max: 0 },
+    };
+  }
+
+  /**
+   * Set a random delay range in milliseconds for send operations.
+   *
+   * This overrides any fixed delay that was previously configured.
+   *
+   * @param min The minimum delay in milliseconds.
+   * @param max The maximum delay in milliseconds.
+   * @throws {RangeError} When min or max is negative, or min > max.
+   */
+  setRandomDelay(min, max) {
+    if (min < 0 || max < 0 || min > max) {
+      throw new RangeError('Invalid delay range');
+    }
+    this.config = {
+      ...this.config,
+      delay: 0,
+      randomDelayRange: { min, max },
+    };
+  }
+
+  /**
+   * Find the first message matching the given predicate.
+   *
+   * @param predicate A function that tests each message.
+   * @returns The first matching message, or undefined if none found.
+   */
+  findMessageBy(predicate) {
+    return this.sentMessages.find(predicate);
+  }
+
+  /**
+   * Find all messages matching the given predicate.
+   *
+   * @param predicate A function that tests each message.
+   * @returns An array of all matching messages.
+   */
+  findMessagesBy(predicate) {
+    return this.sentMessages.filter(predicate);
+  }
+
+  /**
+   * Get all messages sent to a specific email address.
+   *
+   * Searches through To, CC, and BCC recipients to find messages
+   * that were sent to the specified email address.
+   *
+   * @param email The email address to search for.
+   * @returns An array of messages sent to the specified address.
+   */
+  getMessagesTo(email) {
+    return this.sentMessages.filter((message) =>
+      [...message.recipients, ...message.ccRecipients, ...message.bccRecipients].some(
+        (addr) => addr.address === email,
+      ),
+    );
+  }
+
+  /**
+   * Get all messages with a specific subject.
+   *
+   * @param subject The exact subject line to match.
+   * @returns An array of messages with the specified subject.
+   */
+  getMessagesBySubject(subject) {
+    return this.sentMessages.filter((message) => message.subject === subject);
+  }
+
+  /**
+   * Wait for a specific number of messages to be sent.
+   *
+   * This method polls the message count until the target is reached or
+   * the timeout expires.  Useful for testing async email workflows where you
+   * need to wait for messages to be sent.
+   *
+   * @param count The number of messages to wait for.
+   * @param timeout The timeout in milliseconds (default: 5000).
+   * @returns A promise that resolves when the count is reached.
+   * @throws {Error} When the timeout is exceeded before reaching the target
+   *                 count.
+   */
+  async waitForMessageCount(count, timeout = 5000) {
+    const startTime = Date.now();
+
+    while (this.sentMessages.length < count) {
+      if (Date.now() - startTime > timeout) {
+        throw new Error(`Timeout waiting for ${count} messages (got ${this.sentMessages.length})`);
+      }
+      // Wait a bit before checking again
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+
+  /**
+   * Wait for a message matching the given predicate.
+   *
+   * This method polls for a matching message until one is found or the timeout
+   * expires.  Useful for testing async email workflows where you need to wait
+   * for specific messages.
+   *
+   * @param predicate A function that tests each message for a match.
+   * @param timeout The timeout in milliseconds (default: 5000).
+   * @returns A promise that resolves with the matching message.
+   * @throws {Error} When the timeout is exceeded before finding a matching
+   *                 message.
+   */
+  async waitForMessage(predicate, timeout = 5000) {
+    const startTime = Date.now();
+
+    while (true) {
+      const message = this.findMessageBy(predicate);
+      if (message) {
+        return message;
+      }
+
+      if (Date.now() - startTime > timeout) {
+        throw new Error('Timeout waiting for message');
+      }
+
+      // Wait a bit before checking again
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+
+  /**
+   * Reset the transport to its initial state.
+   *
+   * Clears all messages, resets all configuration to defaults, and
+   * resets the message ID counter. This is useful for test cleanup.
+   */
+  reset() {
+    this.sentMessages = [];
+    this.nextResponse = null;
+    this.config = createMockConfig();
+    this.messageIdCounter = 1;
+  }
+
+  async applyDelay() {
+    let delayMs = this.config.delay;
+
+    if (
+      this.config.randomDelayRange &&
+      (this.config.randomDelayRange.min > 0 || this.config.randomDelayRange.max > 0)
+    ) {
+      const { min, max } = this.config.randomDelayRange;
+      delayMs = Math.random() * (max - min) + min;
+    }
+
+    if (delayMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  getResponse() {
+    // Check for random failure first
+    if (this.config.failureRate > 0 && Math.random() < this.config.failureRate) {
+      return createFailedReceipt('Simulated random failure', {
+        provider: 'mock',
+        category: 'unknown',
+        code: 'mock.random_failure',
+        retryable: true,
+        attempts: 1,
+      });
+    }
+
+    // Use next response if set
+    if (this.nextResponse) {
+      const response = this.nextResponse;
+      this.nextResponse = null;
+      return response;
+    }
+
+    // Use default response, generating unique message ID if successful
+    if (this.config.defaultResponse.successful && this.config.generateUniqueMessageIds) {
+      const { attempts, timestamp } = this.config.defaultResponse;
+      return {
+        successful: true,
+        messageId: `mock-message-${this.messageIdCounter++}`,
+        provider: 'mock',
+        ...(attempts == null ? {} : { attempts }),
+        ...(timestamp == null ? {} : { timestamp }),
+      };
+    }
+
+    return this.config.defaultResponse;
+  }
+}
+
+module.exports = { MockTransport };
diff --git a/tests/helpers/mock/mock-validation-utils.js b/tests/helpers/mock/mock-validation-utils.js
new file mode 100644
index 0000000..7be3143
--- /dev/null
+++ b/tests/helpers/mock/mock-validation-utils.js
@@ -0,0 +1,136 @@
+// Ported from upyo v0.7.0 (packages/mock/src/test-utils/mock-validation-utils.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isEmailAddress } = require('../../../src/core/address.js');
+
+/**
+ * Validates that a receipt indicates a successful send operation.
+ *
+ * @param receipt The receipt to validate
+ * @throws {Error} If the receipt indicates failure
+ */
+const validateSuccessfulReceipt = (receipt) => {
+  if (!receipt.successful) {
+    throw new Error(
+      `Expected successful receipt, but got failure: ${receipt.errorMessages.join(', ')}`,
+    );
+  }
+
+  if (!receipt.messageId) {
+    throw new Error('Expected message ID in successful receipt');
+  }
+};
+
+/**
+ * Validates that a receipt indicates a failed send operation.
+ *
+ * @param receipt The receipt to validate
+ * @throws {Error} If the receipt indicates success
+ */
+const validateFailedReceipt = (receipt) => {
+  if (receipt.successful) {
+    throw new Error(
+      `Expected failed receipt, but got success with message ID: ${receipt.messageId}`,
+    );
+  }
+
+  if (!receipt.errorMessages || receipt.errorMessages.length === 0) {
+    throw new Error('Expected error messages in failed receipt');
+  }
+};
+
+/**
+ * Validates that all receipts in the array are successful.
+ *
+ * @param receipts Array of receipts to validate
+ * @throws {Error} If any receipt indicates failure
+ */
+const validateAllSuccessful = (receipts) => {
+  const failedReceipts = receipts.filter((r) => !r.successful);
+  if (failedReceipts.length > 0) {
+    const errorMessages = failedReceipts.flatMap((r) => (r.successful ? [] : r.errorMessages));
+    throw new Error(
+      `Expected all receipts to be successful, but ${failedReceipts.length} failed: ${errorMessages.join(
+        ', ',
+      )}`,
+    );
+  }
+};
+
+/**
+ * Validates that a message contains expected content.
+ *
+ * @param message The message to validate
+ * @param expected Expected message properties
+ * @throws {Error} If the message doesn't match expectations
+ */
+const validateMessageContent = (message, expected) => {
+  if (expected.from && message.sender.address !== expected.from) {
+    throw new Error(`Expected sender ${expected.from}, got ${message.sender.address}`);
+  }
+
+  if (expected.to) {
+    const expectedTo = Array.isArray(expected.to) ? expected.to : [expected.to];
+    const actualTo = message.recipients.map((r) => r.address);
+
+    for (const expectedAddr of expectedTo) {
+      if (!isEmailAddress(expectedAddr)) {
+        throw new Error(`Invalid expected email address: ${expectedAddr}`);
+      }
+      if (!actualTo.includes(expectedAddr)) {
+        throw new Error(
+          `Expected recipient ${expectedAddr}, but not found in [${actualTo.join(', ')}]`,
+        );
+      }
+    }
+  }
+
+  if (expected.subject && message.subject !== expected.subject) {
+    throw new Error(`Expected subject "${expected.subject}", got "${message.subject}"`);
+  }
+
+  if (expected.textContent) {
+    const textContent = 'text' in message.content ? message.content.text : message.content.text;
+    if (!textContent || !textContent.includes(expected.textContent)) {
+      throw new Error(`Expected text content to include "${expected.textContent}"`);
+    }
+  }
+
+  if (expected.htmlContent) {
+    const htmlContent = 'html' in message.content ? message.content.html : undefined;
+    if (!htmlContent || !htmlContent.includes(expected.htmlContent)) {
+      throw new Error(`Expected HTML content to include "${expected.htmlContent}"`);
+    }
+  }
+};
+
+/**
+ * Validates that messages are delivered in the expected order.
+ *
+ * @param actualMessages Messages in the order they were sent
+ * @param expectedSubjects Expected subjects in order
+ * @throws {Error} If the order doesn't match
+ */
+const validateMessageOrder = (actualMessages, expectedSubjects) => {
+  if (actualMessages.length !== expectedSubjects.length) {
+    throw new Error(`Expected ${expectedSubjects.length} messages, got ${actualMessages.length}`);
+  }
+
+  for (let i = 0; i < expectedSubjects.length; i++) {
+    if (actualMessages[i].subject !== expectedSubjects[i]) {
+      throw new Error(
+        `Message ${i}: expected subject "${expectedSubjects[i]}", got "${
+          actualMessages[i].subject
+        }"`,
+      );
+    }
+  }
+};
+
+module.exports = {
+  validateSuccessfulReceipt,
+  validateFailedReceipt,
+  validateAllSuccessful,
+  validateMessageContent,
+  validateMessageOrder,
+};
diff --git a/tests/helpers/mock/test-config.js b/tests/helpers/mock/test-config.js
new file mode 100644
index 0000000..28b17ef
--- /dev/null
+++ b/tests/helpers/mock/test-config.js
@@ -0,0 +1,33 @@
+// Ported from upyo v0.7.0 (packages/mock/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../../src/core/message.js');
+const { MockTransport } = require('../../../src/mock/mock-transport.js');
+const { createMockConfig } = require('../../../src/mock/config.js');
+
+/**
+ * Creates a test MockTransport with default configuration.
+ *
+ * @param config Optional configuration overrides
+ * @returns A configured MockTransport instance
+ */
+const createTestMockTransport = (config) => {
+  return new MockTransport(createMockConfig(config));
+};
+
+/**
+ * Creates a test message with sensible defaults for testing.
+ *
+ * @param overrides Optional properties to override defaults
+ * @returns A test Message object
+ */
+const createTestMessage = (overrides = {}) => {
+  return createMessage({
+    from: overrides.from ?? 'test-sender@example.com',
+    to: overrides.to ?? 'test-recipient@example.com',
+    subject: overrides.subject ?? 'Test Email',
+    content: overrides.content ?? { text: 'This is a test email message.' },
+  });
+};
+
+module.exports = { createTestMockTransport, createTestMessage };
diff --git a/tests/types/mock.test-d.ts b/tests/types/mock.test-d.ts
new file mode 100644
index 0000000..f846c10
--- /dev/null
+++ b/tests/types/mock.test-d.ts
@@ -0,0 +1,23 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Message, type Receipt, type Transport } from '../../index.js';
+import { MockTransport, type MockConfig } from '../../src/mock/index.js';
+
+const transport = new MockTransport({ delay: 10, failureRate: 0.1 });
+expectAssignable<Transport<'mock'>>(transport);
+expectType<'mock'>(transport.id);
+expectAssignable<MockTransport>(new MockTransport());
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'mock'>>>(transport.send(message));
+expectType<readonly Message[]>(transport.getSentMessages());
+expectType<Message | undefined>(transport.getLastSentMessage());
+expectType<Promise<Message>>(transport.waitForMessage((sent) => sent.subject === 'Hello'));
+
+expectAssignable<MockConfig>({ randomDelayRange: { min: 1, max: 5 } });
+expectError(new MockTransport({ delay: '10' }));
+expectError(transport.setNextResponse({ successful: true }));
diff --git a/tests/unit/mock-config.test.js b/tests/unit/mock-config.test.js
new file mode 100644
index 0000000..1ed7aa0
--- /dev/null
+++ b/tests/unit/mock-config.test.js
@@ -0,0 +1,97 @@
+// Ported from upyo v0.7.0 (packages/mock/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { createMockConfig } = require('../../src/mock/config.js');
+
+describe('createMockConfig', () => {
+  test('should apply default values for empty config', () => {
+    const config = createMockConfig();
+
+    assert.deepEqual(config.defaultResponse, {
+      successful: true,
+      messageId: 'mock-message-id',
+      provider: 'mock',
+    });
+    assert.equal(config.delay, 0);
+    assert.deepEqual(config.randomDelayRange, { min: 0, max: 0 });
+    assert.equal(config.failureRate, 0);
+    assert.equal(config.generateUniqueMessageIds, true);
+  });
+
+  test('should preserve provided values', () => {
+    const inputConfig = {
+      defaultResponse: {
+        successful: false,
+        errorMessages: ['Test error'],
+      },
+      delay: 100,
+      randomDelayRange: { min: 50, max: 150 },
+      failureRate: 0.1,
+      generateUniqueMessageIds: false,
+    };
+
+    const config = createMockConfig(inputConfig);
+
+    assert.deepEqual(config.defaultResponse, {
+      successful: false,
+      errorMessages: ['Test error'],
+    });
+    assert.equal(config.delay, 100);
+    assert.deepEqual(config.randomDelayRange, { min: 50, max: 150 });
+    assert.equal(config.failureRate, 0.1);
+    assert.equal(config.generateUniqueMessageIds, false);
+  });
+
+  test('should apply defaults only to undefined fields', () => {
+    const inputConfig = {
+      delay: 50,
+      failureRate: 0.05,
+    };
+
+    const config = createMockConfig(inputConfig);
+
+    assert.deepEqual(config.defaultResponse, {
+      successful: true,
+      messageId: 'mock-message-id',
+      provider: 'mock',
+    });
+    assert.equal(config.delay, 50);
+    assert.deepEqual(config.randomDelayRange, { min: 0, max: 0 });
+    assert.equal(config.failureRate, 0.05);
+    assert.equal(config.generateUniqueMessageIds, true);
+  });
+
+  test('should handle successful response configuration', () => {
+    const inputConfig = {
+      defaultResponse: {
+        successful: true,
+        messageId: 'custom-message-id',
+      },
+    };
+
+    const config = createMockConfig(inputConfig);
+
+    assert.deepEqual(config.defaultResponse, {
+      successful: true,
+      messageId: 'custom-message-id',
+    });
+  });
+
+  test('should handle failed response configuration', () => {
+    const inputConfig = {
+      defaultResponse: {
+        successful: false,
+        errorMessages: ['Network error', 'Timeout'],
+      },
+    };
+
+    const config = createMockConfig(inputConfig);
+
+    assert.deepEqual(config.defaultResponse, {
+      successful: false,
+      errorMessages: ['Network error', 'Timeout'],
+    });
+  });
+});
diff --git a/tests/unit/mock-transport.test.js b/tests/unit/mock-transport.test.js
new file mode 100644
index 0000000..5224e0c
--- /dev/null
+++ b/tests/unit/mock-transport.test.js
@@ -0,0 +1,313 @@
+// Ported from upyo v0.7.0 (packages/mock/src/mock-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const { MockTransport } = require('../../src/mock/index.js');
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { createTestMessage, createTestMockTransport } = require('../helpers/mock/test-config.js');
+const {
+  validateAllSuccessful,
+  validateFailedReceipt,
+  validateSuccessfulReceipt,
+} = require('../helpers/mock/mock-validation-utils.js');
+
+describe('MockTransport', () => {
+  test('should send a single message successfully', async () => {
+    const transport = createTestMockTransport();
+    const message = createTestMessage();
+
+    const receipt = await transport.send(message);
+
+    validateSuccessfulReceipt(receipt);
+    assert.equal(transport.getSentMessagesCount(), 1);
+    assert.equal(transport.getLastSentMessage(), message);
+  });
+
+  test('should generate unique message IDs', async () => {
+    const transport = createTestMockTransport();
+    const message1 = createTestMessage({ subject: 'First' });
+    const message2 = createTestMessage({ subject: 'Second' });
+
+    const receipt1 = await transport.send(message1);
+    const receipt2 = await transport.send(message2);
+
+    validateSuccessfulReceipt(receipt1);
+    validateSuccessfulReceipt(receipt2);
+    assert.notEqual(receipt1.messageId, receipt2.messageId);
+  });
+
+  test('should not copy failure fields into unique success receipts', async () => {
+    const defaultResponse = {
+      successful: true,
+      messageId: 'base-id',
+      errorMessages: ['should not be copied'],
+    };
+    const transport = new MockTransport({ defaultResponse });
+
+    const receipt = await transport.send(createTestMessage());
+
+    validateSuccessfulReceipt(receipt);
+    assert.equal(receipt.messageId, 'mock-message-1');
+    assert.ok(!('errorMessages' in receipt));
+  });
+
+  test('should store messages in order', async () => {
+    const transport = createTestMockTransport();
+    const messages = [
+      createTestMessage({ subject: 'First' }),
+      createTestMessage({ subject: 'Second' }),
+      createTestMessage({ subject: 'Third' }),
+    ];
+
+    for (const message of messages) {
+      await transport.send(message);
+    }
+
+    const sentMessages = transport.getSentMessages();
+    assert.equal(sentMessages.length, 3);
+    assert.equal(sentMessages[0].subject, 'First');
+    assert.equal(sentMessages[1].subject, 'Second');
+    assert.equal(sentMessages[2].subject, 'Third');
+  });
+
+  test('should handle sendMany with iterable', async () => {
+    const transport = createTestMockTransport();
+    const messages = [
+      createTestMessage({ subject: 'Batch 1' }),
+      createTestMessage({ subject: 'Batch 2' }),
+    ];
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 2);
+    validateAllSuccessful(receipts);
+    assert.equal(transport.getSentMessagesCount(), 2);
+  });
+
+  test('should handle sendMany with async iterable', async () => {
+    const transport = createTestMockTransport();
+
+    const generateMessages = async function* () {
+      yield createTestMessage({ subject: 'Async 1' });
+      yield createTestMessage({ subject: 'Async 2' });
+    };
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(generateMessages())) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 2);
+    validateAllSuccessful(receipts);
+  });
+
+  test('should support custom default response', async () => {
+    const customResponse = {
+      successful: true,
+      messageId: 'custom-id',
+    };
+    const transport = new MockTransport({
+      defaultResponse: customResponse,
+      generateUniqueMessageIds: false,
+    });
+
+    const message = createTestMessage();
+    const receipt = await transport.send(message);
+
+    validateSuccessfulReceipt(receipt);
+    assert.equal(receipt.messageId, 'custom-id');
+  });
+
+  test('should support next response override', async () => {
+    const transport = createTestMockTransport();
+    const customResponse = {
+      successful: false,
+      errorMessages: ['Custom error'],
+    };
+
+    transport.setNextResponse(customResponse);
+
+    const receipt = await transport.send(createTestMessage());
+    validateFailedReceipt(receipt);
+    assert.deepEqual(receipt.errorMessages, ['Custom error']);
+
+    // Next send should use default response
+    const receipt2 = await transport.send(createTestMessage());
+    validateSuccessfulReceipt(receipt2);
+  });
+
+  test('should simulate failure rate', async () => {
+    const transport = new MockTransport({
+      failureRate: 1.0, // 100% failure rate
+    });
+
+    const receipt = await transport.send(createTestMessage());
+    validateFailedReceipt(receipt);
+    assert.ok(receipt.errorMessages.includes('Simulated random failure'));
+  });
+
+  test('should apply fixed delay', async () => {
+    const transport = new MockTransport({
+      delay: 100,
+    });
+
+    const startTime = Date.now();
+    await transport.send(createTestMessage());
+    const elapsed = Date.now() - startTime;
+
+    assert.ok(elapsed >= 90); // Allow some tolerance
+  });
+
+  test('should apply random delay', async () => {
+    const transport = new MockTransport({
+      randomDelayRange: { min: 50, max: 100 },
+    });
+
+    const startTime = Date.now();
+    await transport.send(createTestMessage());
+    const elapsed = Date.now() - startTime;
+
+    assert.ok(elapsed >= 40); // Allow some tolerance
+  });
+
+  test('should support AbortSignal', async () => {
+    const transport = createTestMockTransport();
+    const controller = new AbortController();
+
+    controller.abort();
+
+    try {
+      await transport.send(createTestMessage(), { signal: controller.signal });
+      assert.fail('Should have thrown AbortError');
+    } catch (error) {
+      assert.ok(error instanceof Error);
+      assert.equal(error.name, 'AbortError');
+    }
+  });
+
+  test('should support message filtering', async () => {
+    const transport = createTestMockTransport();
+
+    await transport.send(
+      createTestMessage({
+        to: 'user1@example.com',
+        subject: 'Hello User 1',
+      }),
+    );
+    await transport.send(
+      createTestMessage({
+        to: 'user2@example.com',
+        subject: 'Hello User 2',
+      }),
+    );
+    await transport.send(
+      createTestMessage({
+        to: 'user1@example.com',
+        subject: 'Another for User 1',
+      }),
+    );
+
+    const user1Messages = transport.getMessagesTo('user1@example.com');
+    assert.equal(user1Messages.length, 2);
+
+    const helloMessages = transport.getMessagesBySubject('Hello User 1');
+    assert.equal(helloMessages.length, 1);
+
+    const foundMessage = transport.findMessageBy((m) => m.subject.includes('Another'));
+    assert.ok(foundMessage);
+    assert.equal(foundMessage.subject, 'Another for User 1');
+  });
+
+  test('should support waiting for messages', async () => {
+    const transport = createTestMockTransport();
+
+    // Start waiting for messages
+    const waitPromise = transport.waitForMessageCount(2, 1000);
+
+    // Send messages with small delays
+    setTimeout(() => transport.send(createTestMessage({ subject: 'First' })), 10);
+    setTimeout(() => transport.send(createTestMessage({ subject: 'Second' })), 20);
+
+    await waitPromise; // Should resolve when 2 messages are sent
+    assert.equal(transport.getSentMessagesCount(), 2);
+  });
+
+  test('should support waiting for specific message', async () => {
+    const transport = createTestMockTransport();
+
+    // Start waiting for a specific message
+    const waitPromise = transport.waitForMessage((m) => m.subject === 'Target Message', 1000);
+
+    // Send various messages
+    setTimeout(() => transport.send(createTestMessage({ subject: 'Other Message' })), 10);
+    setTimeout(() => transport.send(createTestMessage({ subject: 'Target Message' })), 20);
+
+    const foundMessage = await waitPromise;
+    assert.equal(foundMessage.subject, 'Target Message');
+  });
+
+  test('should reset to initial state', async () => {
+    const transport = createTestMockTransport();
+
+    // Send some messages and configure behavior
+    await transport.send(createTestMessage());
+    transport.setDelay(100);
+    transport.setFailureRate(0.5);
+    transport.setNextResponse({ successful: false, errorMessages: ['Error'] });
+
+    assert.equal(transport.getSentMessagesCount(), 1);
+
+    // Reset
+    transport.reset();
+
+    assert.equal(transport.getSentMessagesCount(), 0);
+    assert.equal(transport.getLastSentMessage(), undefined);
+
+    // Should use default behavior after reset
+    const receipt = await transport.send(createTestMessage());
+    validateSuccessfulReceipt(receipt);
+  });
+
+  test('should clear sent messages', async () => {
+    const transport = createTestMockTransport();
+
+    await transport.send(createTestMessage());
+    await transport.send(createTestMessage());
+
+    assert.equal(transport.getSentMessagesCount(), 2);
+
+    transport.clearSentMessages();
+
+    assert.equal(transport.getSentMessagesCount(), 0);
+    assert.equal(transport.getLastSentMessage(), undefined);
+  });
+});
+
+describe('MockTransport identity inspection', () => {
+  test('should expose the identity and threading fields of a sent message', async () => {
+    const transport = new MockTransport();
+    const message = createMessage({
+      from: 'support@example.com',
+      to: 'customer@example.net',
+      subject: 'Re: Your request',
+      content: { text: 'Thanks for getting in touch.' },
+      messageId: '<ticket-4821@example.com>',
+      date: new Date('2026-09-01T10:00:00Z'),
+      inReplyTo: '<122@example.com>',
+      references: ['<120@example.com>', '<121@example.com>'],
+    });
+
+    await transport.send(message);
+    const sent = transport.getLastSentMessage();
+
+    assert.ok(sent != null);
+    assert.equal(sent.messageId, 'ticket-4821@example.com');
+    assert.equal(sent.date?.toISOString(), '2026-09-01T10:00:00.000Z');
+    assert.deepEqual(sent.inReplyTo, ['122@example.com']);
+    assert.deepEqual(sent.references, ['120@example.com', '121@example.com']);
+  });
+});
diff --git a/tests/unit/mock.test.js b/tests/unit/mock.test.js
new file mode 100644
index 0000000..ebe29c1
--- /dev/null
+++ b/tests/unit/mock.test.js
@@ -0,0 +1,73 @@
+// Paths of the ported MockTransport (src/mock/) that upstream's suites leave out.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { MockTransport } = require('../../src/mock/index.js');
+
+const message = (subject) =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject,
+    content: { text: 'Hi' },
+  });
+
+test('Mock: the default response can be replaced', async () => {
+  const transport = new MockTransport({ generateUniqueMessageIds: false });
+  transport.setDefaultResponse({ successful: true, messageId: 'fixed' });
+  assert.deepStrictEqual(await transport.send(message('a')), {
+    successful: true,
+    messageId: 'fixed',
+  });
+});
+
+test('Mock: a random delay is validated and replaces the fixed one', async () => {
+  const transport = new MockTransport({ delay: 1000 });
+  assert.throws(() => transport.setRandomDelay(5, 1), RangeError);
+  assert.throws(() => transport.setRandomDelay(-1, 1), RangeError);
+  transport.setRandomDelay(0, 1);
+  const started = Date.now();
+  await transport.send(message('a'));
+  assert.ok(Date.now() - started < 500);
+});
+
+test('Mock: the failure rate and the delay are validated', () => {
+  const transport = new MockTransport();
+  assert.throws(() => transport.setFailureRate(1.5), {
+    name: 'RangeError',
+    message: 'Failure rate must be between 0.0 and 1.0',
+  });
+  assert.throws(() => transport.setDelay(-1), {
+    name: 'RangeError',
+    message: 'Delay must be non-negative',
+  });
+});
+
+test('Mock: findMessagesBy returns every match', async () => {
+  const transport = new MockTransport();
+  for (const subject of ['a', 'b', 'a']) await transport.send(message(subject));
+  assert.strictEqual(transport.findMessagesBy((sent) => sent.subject === 'a').length, 2);
+});
+
+test('Mock: an abort during the delay rejects the send and the batch', async () => {
+  const transport = new MockTransport({ delay: 20 });
+  const controller = new AbortController();
+  const sending = transport.send(message('a'), { signal: controller.signal });
+  controller.abort();
+  await assert.rejects(sending, { name: 'AbortError' });
+  assert.strictEqual(transport.getSentMessagesCount(), 0);
+
+  const batch = transport.sendMany([message('a')], { signal: AbortSignal.abort() });
+  await assert.rejects(batch[Symbol.asyncIterator]().next(), { name: 'AbortError' });
+});
+
+test('Mock: waiting for messages times out', async () => {
+  const transport = new MockTransport();
+  await assert.rejects(transport.waitForMessageCount(1, 20), {
+    message: 'Timeout waiting for 1 messages (got 0)',
+  });
+  await assert.rejects(
+    transport.waitForMessage(() => true, 20),
+    { message: 'Timeout waiting for message' },
+  );
+});

From c23eb4df66b8e51b2fe455200a597e21920a24e2 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 20:52:46 +0300
Subject: [PATCH 004/158] feat(mime): port the MIME builder and DKIM signing
 from upyo 0.7.0

./mime exports composeMessage, which turns a Message into replayable MIME
bytes with a separate envelope (Bcc stays out of the headers), optionally
DKIM-signed with RSA-SHA256 or Ed25519 in buffered or streaming body mode,
and MimeAttachmentReplayError. The SMTP transport of the next commit builds
on its internal modules.

The one runtime dependency of @upyo/mime, @noble/hashes, becomes
node:crypto's createHash: the incremental SHA-256 of the body hash and of
the replay check. Signing stays on WebCrypto, as upstream.

Upstream reaches most of the MIME builder through the SMTP suites; the new
tests/unit/mime.test.js covers it directly and reads every message back with
postal-mime (a devDependency, as upstream's compose suite uses it). It found
an upstream line-length bug, added to the list in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                  |   2 +-
 CLAUDE.md                                 |   3 +
 package.json                              |   5 +
 pnpm-lock.yaml                            |   8 +
 src/mime/bytes.js                         |  17 +
 src/mime/dkim/body-hash.js                | 107 ++++
 src/mime/dkim/canonicalize.js             | 145 +++++
 src/mime/dkim/sign.js                     | 299 ++++++++++
 src/mime/dkim/types.js                    |  39 ++
 src/mime/index.d.ts                       | 150 +++++
 src/mime/index.js                         |  61 ++
 src/mime/message.js                       | 681 ++++++++++++++++++++++
 src/mime/mime-stream.js                   |  64 ++
 src/mime/stream.js                        | 114 ++++
 tests/helpers/mime/dkim-test-keys.js      | 105 ++++
 tests/helpers/mime/verify-dkim.js         |  69 +++
 tests/types/mime.test-d.ts                |  29 +
 tests/unit/mime-cancellation.test.js      | 173 ++++++
 tests/unit/mime-compose.test.js           | 310 ++++++++++
 tests/unit/mime-dkim-body-hash.test.js    |  64 ++
 tests/unit/mime-dkim-canonicalize.test.js | 160 +++++
 tests/unit/mime-dkim-sign.test.js         | 350 +++++++++++
 tests/unit/mime-header-validation.test.js |  57 ++
 tests/unit/mime-stream.test.js            |  72 +++
 tests/unit/mime.test.js                   | 141 +++++
 25 files changed, 3224 insertions(+), 1 deletion(-)
 create mode 100644 src/mime/bytes.js
 create mode 100644 src/mime/dkim/body-hash.js
 create mode 100644 src/mime/dkim/canonicalize.js
 create mode 100644 src/mime/dkim/sign.js
 create mode 100644 src/mime/dkim/types.js
 create mode 100644 src/mime/index.d.ts
 create mode 100644 src/mime/index.js
 create mode 100644 src/mime/message.js
 create mode 100644 src/mime/mime-stream.js
 create mode 100644 src/mime/stream.js
 create mode 100644 tests/helpers/mime/dkim-test-keys.js
 create mode 100644 tests/helpers/mime/verify-dkim.js
 create mode 100644 tests/types/mime.test-d.ts
 create mode 100644 tests/unit/mime-cancellation.test.js
 create mode 100644 tests/unit/mime-compose.test.js
 create mode 100644 tests/unit/mime-dkim-body-hash.test.js
 create mode 100644 tests/unit/mime-dkim-canonicalize.test.js
 create mode 100644 tests/unit/mime-dkim-sign.test.js
 create mode 100644 tests/unit/mime-header-validation.test.js
 create mode 100644 tests/unit/mime-stream.test.js
 create mode 100644 tests/unit/mime.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5797608..529167b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/CLAUDE.md b/CLAUDE.md
index a58682a..7edff70 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -134,6 +134,9 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 11. resend: the `Idempotency-Key` comes from `Math.random`.
 12. `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of `process.emitWarning` or
     an injected logger.
+13. mime: the first encoded word of a header shares its line with the field name
+    (`Subject: =?UTF-8?B?…?=`, 84 characters), past the 76 that RFC 2047 allows a line with
+    encoded words.
 
 ## Repository layout
 
diff --git a/package.json b/package.json
index d29d006..02fda8e 100644
--- a/package.json
+++ b/package.json
@@ -24,6 +24,10 @@
       "types": "./index.d.ts",
       "default": "./index.js"
     },
+    "./mime": {
+      "types": "./src/mime/index.d.ts",
+      "default": "./src/mime/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
@@ -93,6 +97,7 @@
     "esbuild": "^0.28.2",
     "oxfmt": "^0.72.0",
     "oxlint": "^1.75.0",
+    "postal-mime": "^3.0.1",
     "tsd": "^0.33.0",
     "typescript": "^7.0.2",
     "vitepress": "^1.6.4"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 171305c..a7a4235 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -26,6 +26,9 @@ importers:
       oxlint:
         specifier: ^1.75.0
         version: 1.88.0
+      postal-mime:
+        specifier: ^3.0.1
+        version: 3.0.1
       tsd:
         specifier: ^0.33.0
         version: 0.33.0
@@ -1754,6 +1757,9 @@ packages:
     resolution: {integrity: sha512-4UGewrYgqDFw9vV6zNV+ADmPAUAfJPKtGvb/VdpQAx25X5f3xXdGdyOEVFwkl8Hl/tl7+xbeHqSEM+D5/TirUg==}
     engines: {node: '>=10'}
 
+  postal-mime@3.0.1:
+    resolution: {integrity: sha512-N86EnYOxZjW1uHQIgSXnnRdnJz+wxmtDsnk3C4R/9rQ1utj8A2znauXZ3Q3+stCHxG5ckY4/NrO09WiPU6rcdQ==}
+
   postcss@8.5.30:
     resolution: {integrity: sha512-zkd+e9S1AQHhmaBKye9zlFHWjOwVgqXl1q3ECYy8561K7qxR2cREf/STLskulBFd78k6AOFeA+ff1TtEzk9bAA==}
     engines: {node: ^10 || ^12 || >=14}
@@ -3463,6 +3469,8 @@ snapshots:
     dependencies:
       irregular-plurals: 3.5.0
 
+  postal-mime@3.0.1: {}
+
   postcss@8.5.30:
     dependencies:
       nanoid: 3.3.20
diff --git a/src/mime/bytes.js b/src/mime/bytes.js
new file mode 100644
index 0000000..5b7e961
--- /dev/null
+++ b/src/mime/bytes.js
@@ -0,0 +1,17 @@
+// Ported from upyo v0.7.0 (packages/mime/src/bytes.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/** @internal */
+const utf8 = (value) => {
+  return new TextEncoder().encode(value);
+};
+/** @internal */
+const base64 = (bytes) => {
+  let binary = '';
+  for (let offset = 0; offset < bytes.length; offset += 8192) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
+  }
+  return btoa(binary);
+};
+
+module.exports = { utf8, base64 };
diff --git a/src/mime/dkim/body-hash.js b/src/mime/dkim/body-hash.js
new file mode 100644
index 0000000..54c745a
--- /dev/null
+++ b/src/mime/dkim/body-hash.js
@@ -0,0 +1,107 @@
+// Ported from upyo v0.7.0 (packages/mime/src/dkim/body-hash.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createHash } = require('node:crypto');
+const { base64 } = require('../bytes.js');
+
+/** Incremental RFC 6376 body hash with bounded whitespace and line state. */
+class BodyHasher {
+  hash = createHash('sha256');
+  buffer = new Uint8Array(65536);
+  used = 0;
+  cr = false;
+  whitespace = false;
+  newlines = 0;
+  nonempty = false;
+
+  mode;
+
+  constructor(mode) {
+    this.mode = mode;
+  }
+
+  update(bytes) {
+    const relaxed = this.mode === 'relaxed';
+    for (let offset = 0; offset < bytes.length;) {
+      const byte = bytes[offset++];
+      if (this.cr) {
+        this.cr = false;
+        if (byte === 10) {
+          this.whitespace = false;
+          this.newlines++;
+          continue;
+        }
+        this.content(13);
+      }
+      if (byte === 13) {
+        this.cr = true;
+      } else if (relaxed && (byte === 32 || byte === 9)) {
+        this.whitespace = true;
+      } else {
+        this.content(byte);
+        // Only CR and relaxed-mode whitespace need per-byte state changes.
+        const start = offset;
+        while (
+          offset < bytes.length &&
+          bytes[offset] !== 13 &&
+          // oxlint-disable-next-line no-unmodified-loop-condition -- upstream
+          (!relaxed || (bytes[offset] !== 32 && bytes[offset] !== 9))
+        ) {
+          offset++;
+        }
+        this.emitSpan(bytes, start, offset);
+      }
+    }
+  }
+
+  emitSpan(bytes, start, end) {
+    while (start < end) {
+      const length = Math.min(end - start, this.buffer.length - this.used);
+      this.buffer.set(bytes.subarray(start, start + length), this.used);
+      this.used += length;
+      start += length;
+      if (this.used === this.buffer.length) {
+        this.hash.update(this.buffer);
+        this.used = 0;
+      }
+    }
+  }
+
+  content(byte) {
+    if (this.mode === 'relaxed' && (byte === 32 || byte === 9)) {
+      this.whitespace = true;
+      return;
+    }
+    while (this.newlines > 0) {
+      this.emit(13);
+      this.emit(10);
+      this.newlines--;
+    }
+    if (this.whitespace) {
+      this.emit(32);
+      this.whitespace = false;
+    }
+    this.emit(byte);
+    this.nonempty = true;
+  }
+
+  emit(byte) {
+    this.buffer[this.used++] = byte;
+    if (this.used === this.buffer.length) {
+      this.hash.update(this.buffer);
+      this.used = 0;
+    }
+  }
+
+  digest() {
+    if (this.cr) this.content(13);
+    if (this.nonempty || this.mode === 'simple') {
+      this.emit(13);
+      this.emit(10);
+    }
+    this.hash.update(this.buffer.subarray(0, this.used));
+    return base64(this.hash.digest());
+  }
+}
+
+module.exports = { BodyHasher };
diff --git a/src/mime/dkim/canonicalize.js b/src/mime/dkim/canonicalize.js
new file mode 100644
index 0000000..c9ce930
--- /dev/null
+++ b/src/mime/dkim/canonicalize.js
@@ -0,0 +1,145 @@
+// Ported from upyo v0.7.0 (packages/mime/src/dkim/canonicalize.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * DKIM Canonicalization algorithms per RFC 6376 Section 3.4.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6376#section-3.4
+ */
+
+/**
+ * Simple header canonicalization.
+ *
+ * The "simple" header canonicalization algorithm does not change header
+ * fields in any way. Header fields are presented to the signing or
+ * verification algorithm exactly as they are in the message.
+ *
+ * @param name - The header field name
+ * @param value - The header field value
+ * @returns The canonicalized header line (name:value)
+ * @see RFC 6376 Section 3.4.1
+ */
+const canonicalizeHeaderSimple = (name, value) => {
+  return `${name}:${value}`;
+};
+
+/**
+ * Relaxed header canonicalization.
+ *
+ * The "relaxed" header canonicalization algorithm:
+ * - Convert header field names to lowercase
+ * - Unfold header field continuation lines
+ * - Collapse whitespace sequences to a single space
+ * - Remove leading and trailing whitespace from header field values
+ *
+ * @param name - The header field name
+ * @param value - The header field value
+ * @returns The canonicalized header line (name:value)
+ * @see RFC 6376 Section 3.4.2
+ */
+const canonicalizeHeaderRelaxed = (name, value) => {
+  // Convert header field name to lowercase
+  const canonicalName = name.toLowerCase();
+
+  // Unfold header field value (remove CRLF followed by WSP)
+  // and collapse all sequences of WSP to a single space
+  const canonicalValue = value
+    .replace(/\r\n[\t ]+/g, ' ') // Unfold continuation lines
+    .replace(/[\t ]+/g, ' ') // Collapse whitespace sequences
+    .trim(); // Remove leading and trailing whitespace
+
+  return `${canonicalName}:${canonicalValue}`;
+};
+
+/**
+ * Simple body canonicalization.
+ *
+ * The "simple" body canonicalization algorithm:
+ * - Ignores all empty lines at the end of the message body
+ * - If the body is empty, a single CRLF is appended
+ * - If there is no trailing CRLF on the body, a CRLF is added
+ *
+ * @param body - The message body
+ * @returns The canonicalized body
+ * @see RFC 6376 Section 3.4.3
+ */
+const canonicalizeBodySimple = (body) => {
+  if (body === '') {
+    return '\r\n';
+  }
+
+  // Remove trailing empty lines (lines containing only CRLF)
+  let result = body.replace(/(\r\n)+$/, '');
+
+  // Ensure the body ends with a single CRLF
+  if (!result.endsWith('\r\n')) {
+    result += '\r\n';
+  }
+
+  return result;
+};
+
+/**
+ * Relaxed body canonicalization.
+ *
+ * The "relaxed" body canonicalization algorithm:
+ * - Reduce all sequences of WSP within a line to a single SP
+ * - Remove all trailing WSP at the end of each line (before CRLF)
+ * - Ignore all empty lines at the end of the message body
+ * - If the body is non-empty and doesn't end with CRLF, add CRLF
+ *
+ * @param body - The message body
+ * @returns The canonicalized body
+ * @see RFC 6376 Section 3.4.4
+ */
+const canonicalizeBodyRelaxed = (body) => {
+  if (body === '') {
+    return '';
+  }
+
+  // Ensure body ends with CRLF for processing
+  let processedBody = body;
+  if (!processedBody.endsWith('\r\n')) {
+    processedBody += '\r\n';
+  }
+
+  // Process each line
+  const lines = processedBody.split('\r\n');
+  const canonicalizedLines = [];
+
+  for (let i = 0; i < lines.length - 1; i++) {
+    // -1 because split creates an empty element after final CRLF
+    let line = lines[i];
+
+    // Collapse WSP sequences to single space
+    line = line.replace(/[\t ]+/g, ' ');
+
+    // Remove trailing WSP
+    line = line.replace(/[\t ]+$/, '');
+
+    canonicalizedLines.push(line);
+  }
+
+  // Remove trailing empty lines
+  while (
+    canonicalizedLines.length > 0 &&
+    canonicalizedLines[canonicalizedLines.length - 1] === ''
+  ) {
+    canonicalizedLines.pop();
+  }
+
+  // If no content remains, return empty string
+  if (canonicalizedLines.length === 0) {
+    return '';
+  }
+
+  // Join with CRLF and add final CRLF
+  return canonicalizedLines.join('\r\n') + '\r\n';
+};
+
+module.exports = {
+  canonicalizeHeaderSimple,
+  canonicalizeHeaderRelaxed,
+  canonicalizeBodySimple,
+  canonicalizeBodyRelaxed,
+};
diff --git a/src/mime/dkim/sign.js b/src/mime/dkim/sign.js
new file mode 100644
index 0000000..782b5c0
--- /dev/null
+++ b/src/mime/dkim/sign.js
@@ -0,0 +1,299 @@
+// Ported from upyo v0.7.0 (packages/mime/src/dkim/sign.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * DKIM Signing implementation per RFC 6376.
+ *
+ * Uses Web Crypto API for cross-runtime compatibility.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc6376
+ */
+
+const {
+  canonicalizeBodyRelaxed,
+  canonicalizeBodySimple,
+  canonicalizeHeaderRelaxed,
+  canonicalizeHeaderSimple,
+} = require('./canonicalize.js');
+const {
+  DEFAULT_ALGORITHM,
+  DEFAULT_CANONICALIZATION,
+  DEFAULT_SIGNED_HEADERS,
+} = require('./types.js');
+
+/**
+ * Signs a raw email message with DKIM.
+ *
+ * @param rawMessage - The complete raw email message (headers + body)
+ * @param config - DKIM signature configuration
+ * @param signal Optional cancellation signal.
+ * @returns The DKIM-Signature header result
+ * @throws Error if signing fails (e.g., invalid private key)
+ */
+const signMessage = async (rawMessage, config, signal) => {
+  signal?.throwIfAborted();
+  const { body } = parseMessage(rawMessage);
+  const bodyCanon = (config.canonicalization ?? DEFAULT_CANONICALIZATION).endsWith('/simple')
+    ? 'simple'
+    : 'relaxed';
+  const bodyHash = await computeBodyHash(body, bodyCanon);
+  return await signWithBodyHash(rawMessage, config, bodyHash, signal);
+};
+
+/**
+ * Signs frozen headers using a body hash computed by the MIME reader.
+ * @param rawHeaders Frozen wire headers, including earlier signatures.
+ * @param config Signature configuration.
+ * @param bodyHash Canonical body SHA-256 digest, encoded as base64.
+ * @param signal Optional cancellation signal.
+ * @returns A DKIM-Signature header value.
+ * @throws {Error} If key import, signing, or cancellation fails.
+ */
+const signWithBodyHash = async (rawHeaders, config, bodyHash, signal) => {
+  signal?.throwIfAborted();
+  const algorithm = config.algorithm ?? DEFAULT_ALGORITHM;
+  const canonicalization = config.canonicalization ?? DEFAULT_CANONICALIZATION;
+  const headerFields = config.headerFields ?? DEFAULT_SIGNED_HEADERS;
+
+  // Parse the raw message into headers and body
+  const { headers } = parseMessage(rawHeaders);
+
+  // Determine canonicalization methods
+  const [headerCanon] = canonicalization.split('/');
+
+  // Get or import the private key
+  const privateKey = await getPrivateKey(config.privateKey, algorithm);
+
+  signal?.throwIfAborted();
+
+  // Build the DKIM-Signature header value (without b= value)
+  const dkimHeaderValue = buildDkimHeaderValue({
+    algorithm,
+    canonicalization,
+    signingDomain: config.signingDomain,
+    selector: config.selector,
+    headerFields,
+    bodyHash,
+  });
+
+  // Compute the signature
+  const signatureData = buildSignatureData(headers, headerFields, headerCanon, dkimHeaderValue);
+
+  const signature = await signData(signatureData, privateKey, algorithm);
+  signal?.throwIfAborted();
+
+  // Return the complete DKIM-Signature header
+  return {
+    headerName: 'DKIM-Signature',
+    signature: `${dkimHeaderValue} b=${signature}`,
+  };
+};
+
+/**
+ * Parses a raw email message into headers and body.
+ */
+const parseMessage = (rawMessage) => {
+  // Find the separator between headers and body (empty line)
+  const separatorIndex = rawMessage.indexOf('\r\n\r\n');
+  if (separatorIndex === -1) {
+    // No body, all headers
+    return {
+      headers: parseHeaders(rawMessage),
+      body: '',
+    };
+  }
+
+  const headerSection = rawMessage.substring(0, separatorIndex);
+  const body = rawMessage.substring(separatorIndex + 4); // Skip \r\n\r\n
+
+  return {
+    headers: parseHeaders(headerSection),
+    body,
+  };
+};
+
+/**
+ * Parses header section into a map of header name to value.
+ * Handles folded headers (continuation lines).
+ */
+const parseHeaders = (headerSection) => {
+  const headers = new Map();
+  const lines = headerSection.split('\r\n');
+
+  let currentName = '';
+  let currentValue = '';
+
+  for (const line of lines) {
+    if (line.startsWith(' ') || line.startsWith('\t')) {
+      // Continuation of previous header (folded)
+      currentValue += '\r\n' + line;
+    } else {
+      // New header - save previous if exists
+      if (currentName) {
+        headers.set(currentName.toLowerCase(), {
+          name: currentName,
+          value: currentValue,
+        });
+      }
+
+      const colonIndex = line.indexOf(':');
+      if (colonIndex > 0) {
+        currentName = line.substring(0, colonIndex);
+        currentValue = line.substring(colonIndex + 1);
+      }
+    }
+  }
+
+  // Save the last header
+  if (currentName) {
+    headers.set(currentName.toLowerCase(), {
+      name: currentName,
+      value: currentValue,
+    });
+  }
+
+  return headers;
+};
+
+/**
+ * Gets the private key, either using a provided CryptoKey or importing from PEM.
+ */
+const getPrivateKey = (key, algorithm) => {
+  if (typeof key !== 'string') {
+    // Already a CryptoKey, use it directly
+    return key;
+  }
+  return importPrivateKey(key, algorithm);
+};
+
+/**
+ * Imports a PEM-encoded private key for use with Web Crypto API.
+ */
+const importPrivateKey = async (pem, algorithm) => {
+  try {
+    // Remove PEM headers/footers and whitespace
+    const pemContents = pem
+      .replace(/-----BEGIN (?:RSA )?PRIVATE KEY-----/, '')
+      .replace(/-----END (?:RSA )?PRIVATE KEY-----/, '')
+      .replace(/\s/g, '');
+
+    // Decode Base64 to binary
+    const binaryString = atob(pemContents);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+
+    // Determine the algorithm parameters based on DKIM algorithm
+    const keyAlgorithm =
+      algorithm === 'ed25519-sha256'
+        ? { name: 'Ed25519' }
+        : { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' };
+
+    return await crypto.subtle.importKey('pkcs8', bytes, keyAlgorithm, false, ['sign']);
+  } catch (error) {
+    // oxlint-disable-next-line preserve-caught-error -- upstream
+    throw new Error(
+      `Failed to import private key: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+};
+
+/**
+ * Computes the body hash (bh= tag value).
+ */
+const computeBodyHash = async (body, canonMethod) => {
+  // Canonicalize the body
+  const canonicalBody =
+    canonMethod === 'relaxed' ? canonicalizeBodyRelaxed(body) : canonicalizeBodySimple(body);
+
+  // Hash with SHA-256
+  const encoder = new TextEncoder();
+  const data = encoder.encode(canonicalBody);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+
+  // Base64 encode
+  return arrayBufferToBase64(hashBuffer);
+};
+
+/**
+ * Builds the DKIM-Signature header value without the b= signature.
+ */
+const buildDkimHeaderValue = (params) => {
+  const parts = [
+    'v=1',
+    `a=${params.algorithm}`,
+    `c=${params.canonicalization}`,
+    `d=${params.signingDomain}`,
+    `s=${params.selector}`,
+    `h=${params.headerFields.join(':')}`,
+    `bh=${params.bodyHash};`,
+  ];
+
+  return parts.join('; ');
+};
+
+/**
+ * Builds the data to be signed (canonicalized headers + DKIM-Signature header).
+ */
+const buildSignatureData = (headers, headerFields, canonMethod, dkimHeaderValue) => {
+  const lines = [];
+
+  // Canonicalize each header specified in h= tag
+  for (const field of headerFields) {
+    const header = headers.get(field.toLowerCase());
+    if (header !== undefined) {
+      const canonicalized =
+        canonMethod === 'relaxed'
+          ? canonicalizeHeaderRelaxed(header.name, header.value)
+          : canonicalizeHeaderSimple(header.name, header.value);
+      lines.push(canonicalized);
+    }
+  }
+
+  // Add the DKIM-Signature header itself (without trailing CRLF)
+  // The b= tag should be empty for signing
+  const dkimHeader =
+    canonMethod === 'relaxed'
+      ? canonicalizeHeaderRelaxed('DKIM-Signature', ' ' + dkimHeaderValue + ' b=')
+      : canonicalizeHeaderSimple('DKIM-Signature', ' ' + dkimHeaderValue + ' b=');
+
+  lines.push(dkimHeader);
+
+  // Join with CRLF (no trailing CRLF on last header per RFC 6376)
+  return lines.join('\r\n');
+};
+
+/**
+ * Signs data using the appropriate algorithm.
+ */
+const signData = async (data, privateKey, algorithm) => {
+  const encoder = new TextEncoder();
+  const dataBuffer = encoder.encode(data);
+
+  // Determine the signing algorithm based on DKIM algorithm
+  const signAlgorithm = algorithm === 'ed25519-sha256' ? 'Ed25519' : 'RSASSA-PKCS1-v1_5';
+
+  // RFC 8463 uses PureEd25519 over the SHA-256 header hash. RSA hashes
+  // internally through its imported key algorithm.
+  const signingInput =
+    algorithm === 'ed25519-sha256' ? await crypto.subtle.digest('SHA-256', dataBuffer) : dataBuffer;
+
+  const signature = await crypto.subtle.sign(signAlgorithm, privateKey, signingInput);
+
+  return arrayBufferToBase64(signature);
+};
+
+/**
+ * Converts an ArrayBuffer to a Base64 string.
+ */
+const arrayBufferToBase64 = (buffer) => {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+};
+
+module.exports = { signMessage, signWithBodyHash };
diff --git a/src/mime/dkim/types.js b/src/mime/dkim/types.js
new file mode 100644
index 0000000..bc5d4c4
--- /dev/null
+++ b/src/mime/dkim/types.js
@@ -0,0 +1,39 @@
+// Ported from upyo v0.7.0 (packages/mime/src/dkim/types.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Validates the runtime body-mode option without changing config identity.
+ * @param config Optional signing configuration.
+ * @throws {TypeError} If the body mode is unsupported.
+ */
+const validateDkimBodyMode = (config) => {
+  if (
+    config?.bodyMode !== undefined &&
+    config.bodyMode !== 'buffered' &&
+    config.bodyMode !== 'streaming'
+  ) {
+    throw new TypeError('Expected DKIM bodyMode to be buffered or streaming.');
+  }
+};
+
+/**
+ * Default header fields to sign if not specified.
+ */
+const DEFAULT_SIGNED_HEADERS = ['from', 'to', 'subject', 'date'];
+
+/**
+ * Default DKIM algorithm.
+ */
+const DEFAULT_ALGORITHM = 'rsa-sha256';
+
+/**
+ * Default canonicalization method.
+ */
+const DEFAULT_CANONICALIZATION = 'relaxed/relaxed';
+
+module.exports = {
+  validateDkimBodyMode,
+  DEFAULT_SIGNED_HEADERS,
+  DEFAULT_ALGORITHM,
+  DEFAULT_CANONICALIZATION,
+};
diff --git a/src/mime/index.d.ts b/src/mime/index.d.ts
new file mode 100644
index 0000000..6ee4010
--- /dev/null
+++ b/src/mime/index.d.ts
@@ -0,0 +1,150 @@
+// Types ported from upyo v0.7.0 (packages/mime/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import type { Message, RawMessage, RawMessageValidationError } from '../../index.js';
+
+/** Composition and lifetime options. @since 0.6.0 */
+export interface ComposeMessageOptions {
+  /** Optional DKIM signing; buffered body mode is the default. */
+  readonly dkim?: DkimConfig;
+  /** Cancels preparation and every future content reader. */
+  readonly signal?: AbortSignal;
+}
+/** Stable, replayable MIME bytes with a separate delivery envelope. @since 0.6.0 */
+export interface ComposedMessage extends RawMessage {
+  /** MIME encoding requirement, independent of internationalized envelope addresses. */
+  readonly encoding: '7bit' | 'utf8';
+  /** Opens an independent reader. The signal cancels only this reader. */
+  readonly content: (signal?: AbortSignal) => AsyncIterable<Uint8Array>;
+}
+/**
+ * Composes complete MIME bytes without SMTP framing or a Bcc header.
+ * Unsigned messages read attachments lazily. DKIM reads the body during
+ * preparation; streaming mode reads it again and verifies every replay.
+ * Metadata is snapshotted before asynchronous work. Keep attachment bytes
+ * immutable and provide independent, identical factory readers.
+ * @param message The structured message to serialize.
+ * @param options Signing and cancellation options.
+ * @returns Replayable bytes accepted by raw-message transports.
+ * @throws {RawMessageValidationError} If the derived envelope is invalid.
+ * @throws {TypeError} If message metadata or signing configuration is invalid.
+ * @throws {RangeError} If a MIME header exceeds the hard line-length limit.
+ * @throws {Error} If signing, attachment reading, or cancellation fails.
+ * Attachment errors can also occur during later content reads, after partial
+ * output. Streaming DKIM changes throw {@link MimeAttachmentReplayError}.
+ */
+export declare function composeMessage(
+  message: Message,
+  options?: ComposeMessageOptions,
+): Promise<ComposedMessage>;
+
+/**
+ * A replayable attachment changed between DKIM body reads.
+ */
+export declare class MimeAttachmentReplayError extends RawMessageValidationError {
+  /** Creates a replay validation failure. */
+  constructor();
+}
+
+/**
+ * Supported DKIM signing algorithms.
+ *
+ * - `rsa-sha256`: RSA with SHA-256, most widely used (RFC 6376)
+ * - `ed25519-sha256`: Ed25519 with SHA-256, shorter keys (RFC 8463)
+ */
+export type DkimAlgorithm = 'rsa-sha256' | 'ed25519-sha256';
+/**
+ * DKIM canonicalization methods for header and body.
+ *
+ * Format: "header-method/body-method"
+ *
+ * - `simple`: No modifications (preserves exact content)
+ * - `relaxed`: Normalizes whitespace and case
+ *
+ * @see RFC 6376 Section 3.4
+ */
+export type DkimCanonicalization =
+  | 'relaxed/relaxed'
+  | 'relaxed/simple'
+  | 'simple/relaxed'
+  | 'simple/simple';
+/**
+ * Configuration for a single DKIM signature.
+ *
+ * Each signature represents one DKIM-Signature header that will be added
+ * to the email. Multiple signatures can be used for different domains
+ * or selectors.
+ */
+export interface DkimSignature {
+  /**
+   * The domain name for the DKIM key (d= tag).
+   * This is the domain claiming responsibility for the message.
+   */
+  readonly signingDomain: string;
+  /**
+   * The DKIM selector (s= tag).
+   * Used to locate the public key in DNS: `selector._domainkey.signingDomain`
+   */
+  readonly selector: string;
+  /**
+   * The private key for signing.
+   *
+   * Can be either:
+   * - A PEM-encoded private key string (PKCS#8 format)
+   * - A `CryptoKey` object from Web Crypto API
+   *
+   * For RSA keys, use PKCS#8 PEM format or import via `crypto.subtle.importKey`.
+   * For Ed25519 keys, use PKCS#8 PEM format or import via `crypto.subtle.importKey`.
+   */
+  readonly privateKey: string | CryptoKey;
+  /**
+   * The signing algorithm (a= tag).
+   * @default "rsa-sha256"
+   */
+  readonly algorithm?: DkimAlgorithm;
+  /**
+   * The canonicalization method for header and body (c= tag).
+   * @default "relaxed/relaxed"
+   */
+  readonly canonicalization?: DkimCanonicalization;
+  /**
+   * Header fields to include in the signature (h= tag).
+   * @default ["from", "to", "subject", "date"]
+   */
+  readonly headerFields?: readonly string[];
+}
+/**
+ * Action to take when DKIM signing fails.
+ *
+ * - `throw`: Throw an error and abort sending (default)
+ * - `send-unsigned`: Log a warning and send the email without DKIM signature
+ */
+export type DkimSigningFailureAction = 'throw' | 'send-unsigned';
+/**
+ * Whether signing buffers the MIME body once or reads replayable sources twice.
+ */
+export type DkimBodyMode = 'buffered' | 'streaming';
+/**
+ * Configuration for DKIM signing in SMTP transport.
+ */
+export interface DkimConfig {
+  /**
+   * Body processing strategy. Streaming uses bounded attachment memory but
+   * requires a second source read; buffered reads once and retains all MIME.
+   * @default "buffered"
+   */
+  readonly bodyMode?: DkimBodyMode;
+  /**
+   * Array of DKIM signature configurations.
+   * Each configuration will result in one DKIM-Signature header.
+   */
+  readonly signatures: readonly DkimSignature[];
+  /**
+   * Action to take when DKIM signing fails.
+   * @default "throw"
+   */
+  readonly onSigningFailure?: DkimSigningFailureAction;
+}
+/**
+ * Default header fields to sign if not specified.
+ */
diff --git a/src/mime/index.js b/src/mime/index.js
new file mode 100644
index 0000000..0ed48df
--- /dev/null
+++ b/src/mime/index.js
@@ -0,0 +1,61 @@
+// Ported from upyo v0.7.0 (packages/mime/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createRawMessagePlan } = require('../core/raw-message.js');
+const { combineSignals } = require('../core/abort-signal.js');
+const { prepareMimeMessage } = require('./message.js');
+const { prepareMimeStream } = require('./stream.js');
+
+const { MimeAttachmentReplayError } = require('./stream.js');
+
+/**
+ * Composes complete MIME bytes without SMTP framing or a Bcc header.
+ * Unsigned messages read attachments lazily. DKIM reads the body during
+ * preparation; streaming mode reads it again and verifies every replay.
+ * Metadata is snapshotted before asynchronous work. Keep attachment bytes
+ * immutable and provide independent, identical factory readers.
+ * @param message The structured message to serialize.
+ * @param options Signing and cancellation options.
+ * @returns Replayable bytes accepted by raw-message transports.
+ * @throws {RawMessageValidationError} If the derived envelope is invalid.
+ * @throws {TypeError} If message metadata or signing configuration is invalid.
+ * @throws {RangeError} If a MIME header exceeds the hard line-length limit.
+ * @throws {Error} If signing, attachment reading, or cancellation fails.
+ * Attachment errors can also occur during later content reads, after partial
+ * output. Streaming DKIM changes throw {@link MimeAttachmentReplayError}.
+ */
+const composeMessage = async (message, options = {}) => {
+  const { signal } = options;
+  // The neutral plan observes promised sources even when envelope validation fails.
+  const plan = prepareMimeMessage(message, options.dkim);
+  const { envelope } = createRawMessagePlan({
+    envelope: {
+      from: message.sender.address,
+      to: [...message.recipients, ...message.ccRecipients, ...message.bccRecipients].map(
+        (recipient) => recipient.address,
+      ),
+    },
+    content: new Uint8Array(),
+  });
+  const stream = await prepareMimeStream(plan, { signal });
+  signal?.throwIfAborted();
+  return {
+    envelope,
+    encoding: stream.encoding,
+    async *content(readerSignal) {
+      const owned = new AbortController();
+      const lifetime = combineSignals(owned.signal, signal);
+      const reader = combineSignals(lifetime.signal, readerSignal);
+      try {
+        reader.signal.throwIfAborted();
+        yield* stream.read(reader.signal);
+      } finally {
+        owned.abort();
+        reader.cleanup();
+        lifetime.cleanup();
+      }
+    },
+  };
+};
+
+module.exports = { MimeAttachmentReplayError, composeMessage };
diff --git a/src/mime/message.js b/src/mime/message.js
new file mode 100644
index 0000000..5d0e698
--- /dev/null
+++ b/src/mime/message.js
@@ -0,0 +1,681 @@
+// Ported from upyo v0.7.0 (packages/mime/src/message.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { readAttachmentContent } = require('../core/attachment.js');
+const {
+  formatMessageId,
+  generateMessageId,
+  resolveThreadingHeaders,
+} = require('../core/message-id.js');
+const { resolveCalendarContent } = require('../core/calendar.js');
+const { validateDkimBodyMode } = require('./dkim/types.js');
+const { attachmentEncodedSize, encodeAttachment } = require('./mime-stream.js');
+const { base64, utf8 } = require('./bytes.js');
+
+/**
+ * Freezes message metadata without reading attachment content.
+ * @param message Message whose metadata will be frozen.
+ * @param dkimConfig Optional signing configuration.
+ * @returns A deterministic MIME plan for one send attempt.
+ * @throws {RangeError} If a header cannot fit the RFC 5322 line limit.
+ * @throws {TypeError} If the message carries an invalid message identifier or
+ * date, an address or identity header containing a carriage return or line
+ * feed, or an invalid custom header field name.
+ */
+const prepareMimeMessage = (message, dkimConfig) => {
+  // Observe every promise before validation can throw or an earlier reader stalls.
+  for (const attachment of message.attachments) {
+    if (attachment.content instanceof Promise) {
+      attachment.content.catch(() => {});
+    }
+  }
+  const dkim =
+    dkimConfig == null
+      ? undefined
+      : {
+          ...dkimConfig,
+          signatures: dkimConfig.signatures.map((signature) => ({
+            ...signature,
+            headerFields: signature.headerFields == null ? undefined : [...signature.headerFields],
+          })),
+        };
+  if (dkim != null) validateDkimBodyMode(dkim);
+  const parts = buildMimeParts(message);
+  const first = parts[0];
+  if (typeof first !== 'string') throw new TypeError('Missing MIME headers.');
+  const separator = first.indexOf('\r\n\r\n') + 4;
+  const headers = first.slice(0, separator);
+  parts[0] = first.slice(separator);
+
+  const encoding = [headers, ...parts.filter((part) => typeof part === 'string')].some(hasNonAscii)
+    ? 'utf8'
+    : '7bit';
+  return {
+    encoding,
+    dkim,
+    headers,
+    async *body(signal, progress) {
+      for (const part of parts) {
+        signal?.throwIfAborted();
+        if (typeof part === 'string') {
+          const bytes = utf8(part);
+          for (let offset = 0; offset < bytes.length; offset += 65536) {
+            signal?.throwIfAborted();
+            yield bytes.subarray(offset, offset + 65536);
+          }
+        } else {
+          yield* encodeAttachment(part.content, signal, progress);
+        }
+      }
+    },
+    async size(signal, checkSize) {
+      let size = utf8(headers).length;
+      let unknown = false;
+      for (const part of parts) {
+        signal?.throwIfAborted();
+        if (typeof part === 'string') size += utf8(part).length;
+        else {
+          if (part.content instanceof Promise) {
+            part.content = await readAttachmentContent(part.content, signal);
+          }
+          if (typeof part.content === 'function') unknown = true;
+          else {
+            size += attachmentEncodedSize(
+              part.content instanceof Uint8Array ? part.content.byteLength : part.content.size,
+            );
+          }
+        }
+        if (!Number.isSafeInteger(size)) {
+          throw new RangeError('Message size exceeds the safe integer range.');
+        }
+      }
+      checkSize?.(size);
+      return unknown ? undefined : size;
+    },
+  };
+};
+
+const buildMimeParts = (message) => {
+  const lines = [];
+  const boundary = generateBoundary();
+  const hasAttachments = message.attachments.length > 0;
+  const alternatives = buildAlternatives(message);
+  const isMultipart = hasAttachments || alternatives.length > 1;
+
+  // Standard headers
+  lines.push(foldHeader('From', encodeAddress(message.sender)));
+  lines.push(foldHeader('To', message.recipients.map(encodeAddress).join(', ')));
+
+  if (message.ccRecipients.length > 0) {
+    lines.push(foldHeader('Cc', message.ccRecipients.map(encodeAddress).join(', ')));
+  }
+
+  if (message.replyRecipients.length > 0) {
+    lines.push(foldHeader('Reply-To', message.replyRecipients.map(encodeAddress).join(', ')));
+  }
+
+  lines.push(foldHeader('Subject', encodeHeaderValue(message.subject, true)));
+
+  // The identity and threading fields all carry structured values, so they are
+  // written verbatim rather than RFC 2047 encoded.
+  lines.push(foldHeader('Date', resolveDate(message)));
+  lines.push(foldHeader('Message-ID', resolveMessageId(message)));
+  const threading = resolveThreadingHeaders(message);
+  for (const name of ['In-Reply-To', 'References']) {
+    // A field the message does not own falls back to a custom header, one it
+    // owns but left empty writes nothing at all.
+    const owned = threading.get(name);
+    const value = owned === undefined ? overridden(message, name) : owned;
+    if (value != null) lines.push(foldHeader(name, value));
+  }
+
+  // Names already written above, plus Cc and Reply-To even when the message
+  // carries no such recipients: a custom header there would list addresses the
+  // envelope never receives.  The identity and threading names are here
+  // unconditionally too, even when nothing was written: each of them has had
+  // its one chance to be emitted above, from the typed field or from the very
+  // custom header this loop would otherwise write again.
+  const composed = new Set([
+    'from',
+    'to',
+    'cc',
+    'reply-to',
+    'subject',
+    'date',
+    'message-id',
+    'in-reply-to',
+    'references',
+  ]);
+
+  // Priority header
+  if (message.priority !== 'normal') {
+    const priorityValue = message.priority === 'high' ? '1' : '5';
+    lines.push(`X-Priority: ${priorityValue}`);
+    lines.push(`X-MSMail-Priority: ${message.priority === 'high' ? 'High' : 'Low'}`);
+    composed.add('x-priority');
+    composed.add('x-msmail-priority');
+  }
+
+  // Custom headers
+  for (const [key, value] of message.headers) {
+    const name = key.toLowerCase();
+    if (composed.has(name) || reservedHeaders.has(name)) continue;
+    lines.push(foldHeader(key, encodeHeaderValue(value)));
+  }
+
+  // MIME headers
+  lines.push('MIME-Version: 1.0');
+
+  if (isMultipart) {
+    lines.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
+    lines.push('');
+    lines.push('This is a multi-part message in MIME format.');
+    lines.push('');
+
+    // Content part
+    lines.push(`--${boundary}`);
+
+    if (alternatives.length > 1) {
+      const contentBoundary = generateBoundary();
+      lines.push(`Content-Type: multipart/alternative; boundary="${contentBoundary}"`);
+      lines.push('');
+
+      for (const alternative of alternatives) {
+        lines.push(`--${contentBoundary}`);
+        lines.push(`Content-Type: ${alternative.contentType}`);
+        lines.push(`Content-Transfer-Encoding: ${alternative.encoding}`);
+        lines.push('');
+        lines.push(alternative.body);
+        lines.push('');
+      }
+
+      lines.push(`--${contentBoundary}--`);
+    } else {
+      lines.push(`Content-Type: ${alternatives[0].contentType}`);
+      lines.push(`Content-Transfer-Encoding: ${alternatives[0].encoding}`);
+      lines.push('');
+      lines.push(alternatives[0].body);
+    }
+
+    // Attachments
+    for (const attachment of message.attachments) {
+      lines.push('');
+      lines.push(`--${boundary}`);
+      lines.push(
+        foldHeader(
+          'Content-Type',
+          `${attachment.contentType}; ${encodeMimeParameter('name', attachment.filename)}`,
+        ),
+      );
+      lines.push('Content-Transfer-Encoding: base64');
+
+      if (attachment.inline) {
+        lines.push(
+          foldHeader(
+            'Content-Disposition',
+            `inline; ${encodeMimeParameter('filename', attachment.filename)}`,
+          ),
+        );
+        lines.push(foldHeader('Content-ID', `<${attachment.contentId}>`));
+      } else {
+        lines.push(
+          foldHeader(
+            'Content-Disposition',
+            `attachment; ${encodeMimeParameter('filename', attachment.filename)}`,
+          ),
+        );
+      }
+
+      lines.push('');
+      lines.push({ content: attachment.content });
+    }
+
+    lines.push('');
+    lines.push(`--${boundary}--`);
+  } else {
+    // Single part message
+    lines.push(`Content-Type: ${alternatives[0].contentType}`);
+    lines.push(`Content-Transfer-Encoding: ${alternatives[0].encoding}`);
+    lines.push('');
+    lines.push(alternatives[0].body);
+  }
+
+  const parts = [];
+  let text = '';
+  for (const line of lines) {
+    if (typeof line === 'string') text += line;
+    else {
+      parts.push(text, line);
+      text = '';
+    }
+    text += '\r\n';
+  }
+  parts.push(text);
+  return parts;
+};
+
+/**
+ * Collects the body alternatives of a message, least preferred first.
+ *
+ * RFC 2046 §5.1.4 orders a `multipart/alternative` by increasing richness, so a
+ * client picks the last one it understands.  Plain text comes first, then HTML,
+ * then the calendar object: a client that schedules should act on the
+ * invitation rather than render the prose describing it.
+ *
+ * The presence of a body is tested with `in` rather than truthiness, so an
+ * empty string a caller supplied deliberately still produces its part.
+ *
+ * @param message The message being composed.
+ * @returns At least one alternative, in the order they are written.
+ * @throws {TypeError} If the calendar content is not valid.
+ */
+const buildAlternatives = (message) => {
+  const alternatives = [];
+
+  if ('text' in message.content && message.content.text !== undefined) {
+    alternatives.push({
+      contentType: 'text/plain; charset=utf-8',
+      encoding: 'quoted-printable',
+      body: encodeQuotedPrintable(message.content.text),
+    });
+  }
+
+  if ('html' in message.content) {
+    alternatives.push({
+      contentType: 'text/html; charset=utf-8',
+      encoding: 'quoted-printable',
+      body: encodeQuotedPrintable(message.content.html),
+    });
+  }
+
+  if (message.calendar != null) {
+    // Re-validated here rather than trusted from the message: `Message` is a
+    // structural interface, and the method is written into a `Content-Type`
+    // parameter, the same reason `formatMessageId()` checks again below.
+    const calendar = resolveCalendarContent(message.calendar);
+    alternatives.push({
+      // The parameter repeats the object's own METHOD property, which RFC 6047
+      // §2.4 requires.  Base64 keeps the CRLF structure RFC 5545 §3.1 makes
+      // normative intact, which quoted-printable would not.
+      contentType: `text/calendar; charset=utf-8; method=${calendar.method}`,
+      encoding: 'base64',
+      body: encodeBase64Body(calendar.content),
+    });
+  }
+
+  if (alternatives.length < 1) {
+    alternatives.push({
+      contentType: 'text/plain; charset=utf-8',
+      encoding: 'quoted-printable',
+      body: '',
+    });
+  }
+
+  return alternatives;
+};
+
+/**
+ * Encodes a body as Base64, wrapped at the 76 columns RFC 2045 §6.8 allows.
+ *
+ * The result carries no trailing CRLF, because MIME assembly appends one to
+ * every line it writes.
+ *
+ * @param text The body to encode.
+ * @returns The wrapped Base64 payload.
+ */
+const encodeBase64Body = (text) => {
+  const encoded = base64(utf8(text));
+  const lines = [];
+  for (let offset = 0; offset < encoded.length; offset += 76) {
+    lines.push(encoded.slice(offset, offset + 76));
+  }
+  return lines.join('\r\n');
+};
+
+/**
+ * Reads a header field that overrides a generated default.
+ *
+ * Unlike custom headers, the value is written verbatim rather than RFC 2047
+ * encoded, so it cannot rely on `encodeHeaderValue()` to neutralize control
+ * characters.  `ImmutableHeaders` is a structural type, so a `Message` may
+ * carry an adapter that never rejected CR or LF the way a platform `Headers`
+ * does.
+ *
+ * @param message The message whose headers are read.
+ * @param name The header field name.
+ * @returns The supplied value, or `undefined` when the message has none.
+ * @throws {TypeError} If the value contains a carriage return or line feed,
+ * which would inject additional header fields into the message.
+ */
+const overridden = (message, name) => {
+  const value = message.headers.get(name);
+  if (value == null) return undefined;
+  if (/[\r\n]/.test(value)) {
+    throw new TypeError(`Header field ${name} must not contain a carriage return or line feed.`);
+  }
+  return value;
+};
+
+/**
+ * Header fields the composer owns but writes after the custom headers, or
+ * deliberately omits.  A custom header with one of these names is dropped
+ * rather than appended: the structured `Message` fields are authoritative,
+ * RFC 5322 §3.6 allows at most one of each, and a duplicate placed before the
+ * composer's own field makes parsers that take the first occurrence read the
+ * wrong value.
+ */
+const reservedHeaders = new Set([
+  // Bcc recipients travel in the SMTP envelope only, so a Bcc header would
+  // disclose them to every recipient.
+  'bcc',
+  'content-transfer-encoding',
+  'content-type',
+  'mime-version',
+]);
+
+/**
+ * Tells whether a value contains a character outside ASCII, which a message
+ * can only carry with the SMTPUTF8 extension (RFC 6531).
+ *
+ * @param value The value to check.
+ * @returns Whether the value contains a character outside ASCII.
+ */
+const hasNonAscii = (value) => {
+  for (const character of value) {
+    if ((character.codePointAt(0) ?? 0) > 0x7f) return true;
+  }
+  return false;
+};
+
+const generateBoundary = () => {
+  return `boundary-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+};
+
+/**
+ * Resolves the origination date: the typed field, then a custom header, then
+ * the time of conversion.
+ *
+ * @param message The message being composed.
+ * @returns The `Date` field value.
+ * @throws {TypeError} If the message carries an invalid date, or a custom
+ * `Date` header containing a carriage return or line feed.
+ */
+const resolveDate = (message) => {
+  return message.date === undefined
+    ? (overridden(message, 'Date') ?? formatDate(new Date()))
+    : formatDate(message.date);
+};
+
+/**
+ * Resolves the message identifier: the typed field, then a custom header, then
+ * one generated within the sender's domain.
+ *
+ * @param message The message being composed.
+ * @returns The `Message-ID` field value, enclosed in angle brackets.
+ * @throws {TypeError} If the message carries an invalid identifier, or a custom
+ * `Message-ID` header containing a carriage return or line feed.
+ */
+const resolveMessageId = (message) => {
+  if (message.messageId !== undefined) {
+    return formatMessageId(message.messageId);
+  }
+  const custom = overridden(message, 'Message-ID');
+  if (custom != null) return custom;
+  return formatMessageId(generateSenderMessageId(message.sender.address));
+};
+
+/**
+ * Generates an identifier rooted in the sender's domain.
+ *
+ * `parseAddress()` validates a domain with `URL`, which accepts spellings the
+ * identifier grammar does not, such as the trailing dot of a fully qualified
+ * name or a host carrying a port.  A sender written that way used to be
+ * delivered, so an unusable domain falls back to `localhost` rather than
+ * failing the send.  Uniqueness holds either way: the left half is a UUID.
+ *
+ * @param address The sender's address.
+ * @returns A bare message identifier.
+ */
+const generateSenderMessageId = (address) => {
+  const domain = domainOf(address).replace(/\.$/, '');
+  try {
+    return generateMessageId(domain);
+  } catch {
+    return generateMessageId('localhost');
+  }
+};
+
+/**
+ * Extracts the domain of an address.
+ *
+ * The separator is the first at sign outside a quoted local part, since a
+ * quoted one may contain at signs of its own, as in `"a@b"@example.com`.
+ *
+ * @param address The address to read.
+ * @returns The domain, or the whole address when it carries no separator.
+ */
+const domainOf = (address) => {
+  let quoted = false;
+  for (let index = 0; index < address.length; index++) {
+    const character = address[index];
+    if (quoted && character === '\\') index++;
+    else if (character === '"') quoted = !quoted;
+    else if (!quoted && character === '@') return address.slice(index + 1);
+  }
+  return address;
+};
+
+const dayNames = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+
+const monthNames = [
+  'Jan',
+  'Feb',
+  'Mar',
+  'Apr',
+  'May',
+  'Jun',
+  'Jul',
+  'Aug',
+  'Sep',
+  'Oct',
+  'Nov',
+  'Dec',
+];
+
+/**
+ * Formats a date as an RFC 5322 §3.3 `date-time` in UTC.
+ *
+ * `Date.toUTCString()` is close but ends in the obsolete `GMT` zone rather than
+ * the numeric `+0000` the current grammar asks for.
+ *
+ * @param date The date to format.
+ * @returns The formatted date.
+ * @throws {TypeError} If the date is invalid, or earlier than the grammar can
+ * express.
+ */
+const formatDate = (date) => {
+  const time = date instanceof Date ? date.getTime() : Number.NaN;
+  const year = Number.isNaN(time) ? Number.NaN : date.getUTCFullYear();
+  if (Number.isNaN(time) || year < 1900) {
+    throw new TypeError(`Invalid date: ${JSON.stringify(date)}`);
+  }
+  const pad = (value) => value.toString().padStart(2, '0');
+  return (
+    `${dayNames[date.getUTCDay()]}, ${pad(date.getUTCDate())} ` +
+    `${monthNames[date.getUTCMonth()]} ${year.toString().padStart(4, '0')} ` +
+    `${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:` +
+    `${pad(date.getUTCSeconds())} +0000`
+  );
+};
+
+const encodeAddress = (address) => {
+  if (/[\r\n]/.test(address.address)) {
+    throw new TypeError('Address must not contain a carriage return or line feed.');
+  }
+  if (address.name == null) {
+    // No display name, just return the email address
+    return address.address;
+  }
+
+  // Encode only the display name part, leave email address as-is
+  const encodedDisplayName = encodeHeaderValue(address.name, true);
+  return `${encodedDisplayName} <${address.address}>`;
+};
+
+const encodeHeaderValue = (value, encodeLongAsciiWords = false) => {
+  // RFC 2047 encoding for non-ASCII characters in headers
+  const hasLongWord = value.split(/\s+/).some((word) => word.length > 60);
+  if (!/^[\x20-\x7E]*$/.test(value) || (encodeLongAsciiWords && hasLongWord)) {
+    const encodeWord = (text) => {
+      const utf8Bytes = new TextEncoder().encode(text);
+      const encoded = base64(utf8Bytes);
+      return `=?UTF-8?B?${encoded}?=`;
+    };
+    const maxEncodedLength = 75;
+    const encodedWord = encodeWord(value);
+
+    if (encodedWord.length <= maxEncodedLength) {
+      return encodedWord;
+    }
+
+    const words = [];
+    let currentText = '';
+
+    for (const character of value) {
+      const candidate = currentText + character;
+      if (encodeWord(candidate).length <= maxEncodedLength) {
+        currentText = candidate;
+      } else {
+        if (currentText.length > 0) {
+          words.push(encodeWord(currentText));
+        }
+        currentText = character;
+      }
+    }
+
+    if (currentText.length > 0) {
+      words.push(encodeWord(currentText));
+    }
+
+    return words.join(' ');
+  }
+  return value;
+};
+
+const encodeMimeParameter = (name, value) => {
+  const escapedValue = value.replace(/[\\"]/g, '\\$&');
+  const quotedParameter = `${name}="${escapedValue}"`;
+  if (/^[\x20-\x7E]*$/.test(value) && quotedParameter.length <= 60) {
+    return quotedParameter;
+  }
+
+  const encodedBytes = Array.from(new TextEncoder().encode(value), (byte) => {
+    const character = String.fromCharCode(byte);
+    return /^[A-Za-z0-9!#$&+.^_`|~-]$/.test(character)
+      ? character
+      : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+  });
+  const segments = [];
+  let segment = '';
+
+  for (const encodedByte of encodedBytes) {
+    if (segment.length + encodedByte.length > 45) {
+      segments.push(segment);
+      segment = '';
+    }
+    segment += encodedByte;
+  }
+  if (segment.length > 0 || segments.length === 0) segments.push(segment);
+
+  return segments
+    .map((part, index) => `${name}*${index}*=${index === 0 ? "UTF-8''" : ''}${part}`)
+    .join('; ');
+};
+
+const foldHeader = (name, value) => {
+  if (!/^[\x21-\x39\x3b-\x7e]+$/.test(name)) {
+    throw new TypeError(
+      'Header field name must contain printable ASCII characters other than colon.',
+    );
+  }
+  const recommendedLineLength = 78;
+  const lines = [];
+  let prefix = `${name}: `;
+  let remaining = value;
+
+  while (prefix.length + remaining.length > recommendedLineLength) {
+    const availableLength = recommendedLineLength - prefix.length;
+    let breakIndex = -1;
+
+    for (let index = Math.min(availableLength, remaining.length - 1); index >= 0; index--) {
+      if (remaining[index] === ' ' || remaining[index] === '\t') {
+        breakIndex = index;
+        break;
+      }
+    }
+
+    if (breakIndex < 0) {
+      for (let index = Math.max(availableLength + 1, 0); index < remaining.length; index++) {
+        if (remaining[index] === ' ' || remaining[index] === '\t') {
+          breakIndex = index;
+          break;
+        }
+      }
+    }
+
+    if (breakIndex < 0) break;
+
+    let whitespaceEnd = breakIndex + 1;
+    while (
+      whitespaceEnd < remaining.length &&
+      (remaining[whitespaceEnd] === ' ' || remaining[whitespaceEnd] === '\t')
+    ) {
+      whitespaceEnd++;
+    }
+
+    if (whitespaceEnd === remaining.length) break;
+
+    lines.push(prefix + remaining.slice(0, breakIndex));
+    prefix = remaining.slice(breakIndex, whitespaceEnd);
+    remaining = remaining.slice(whitespaceEnd);
+  }
+
+  lines.push(prefix + remaining);
+  if (lines.some((line) => utf8(line).length > 998)) {
+    throw new RangeError(`Header field ${name} contains a token too long to fold.`);
+  }
+  return lines.join('\r\n');
+};
+
+const encodeQuotedPrintable = (text) => {
+  const bytes = utf8(text);
+  let result = '';
+  let column = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = bytes[i];
+    if (byte === 13 && bytes[i + 1] === 10) {
+      result += '\r\n';
+      column = 0;
+      i++;
+      continue;
+    }
+    const escaped =
+      byte < 32 ||
+      byte > 126 ||
+      byte === 61 ||
+      (byte === 32 && (i + 1 === bytes.length || bytes[i + 1] === 13 || bytes[i + 1] === 10)) ||
+      (byte === 46 && column === 0);
+    const encoded = escaped
+      ? `=${byte.toString(16).toUpperCase().padStart(2, '0')}`
+      : String.fromCharCode(byte);
+    if (column + encoded.length > 75) {
+      result += '=\r\n';
+      column = 0;
+    }
+    result += encoded;
+    column += encoded.length;
+  }
+  return result;
+};
+
+module.exports = { prepareMimeMessage };
diff --git a/src/mime/mime-stream.js b/src/mime/mime-stream.js
new file mode 100644
index 0000000..e323c2a
--- /dev/null
+++ b/src/mime/mime-stream.js
@@ -0,0 +1,64 @@
+// Ported from upyo v0.7.0 (packages/mime/src/mime-stream.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { iterateAttachmentContent } = require('../core/attachment.js');
+const { base64, utf8 } = require('./bytes.js');
+
+/** Encodes base64 without retaining producer-owned carry bytes. */
+const encodeAttachment = async function* (content, signal, progress) {
+  const carry = new Uint8Array(3);
+  let carried = 0;
+  let column = 0;
+  const wrap = (encoded) => {
+    const parts = [];
+    let offset = 0;
+    while (offset < encoded.length) {
+      if (column === 76) {
+        parts.push('\r\n');
+        column = 0;
+      }
+      const take = Math.min(76 - column, encoded.length - offset);
+      parts.push(encoded.slice(offset, offset + take));
+      offset += take;
+      column += take;
+    }
+    return utf8(parts.join(''));
+  };
+  let processed = 0;
+  for await (const chunk of iterateAttachmentContent(content, signal)) {
+    if (chunk.length > 0) progress?.();
+    let offset = 0;
+    if (carried > 0) {
+      while (carried < 3 && offset < chunk.length) {
+        carry[carried++] = chunk[offset++];
+      }
+      if (carried === 3) {
+        yield wrap(base64(carry));
+        carried = 0;
+      }
+    }
+    while (offset + 3 <= chunk.length) {
+      signal?.throwIfAborted();
+      const length = Math.min(45 * 1024, Math.floor((chunk.length - offset) / 3) * 3);
+      yield wrap(base64(chunk.subarray(offset, offset + length)));
+      offset += length;
+      processed += length;
+      if (processed >= 1024 * 1024) {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        processed = 0;
+      }
+    }
+    while (offset < chunk.length) carry[carried++] = chunk[offset++];
+  }
+  if (carried > 0) {
+    yield wrap(base64(carry.subarray(0, carried)));
+  }
+};
+
+/** Encoded payload length, excluding MIME framing and a trailing CRLF. */
+const attachmentEncodedSize = (length) => {
+  const encoded = 4 * Math.ceil(length / 3);
+  return encoded + (encoded === 0 ? 0 : 2 * Math.floor((encoded - 1) / 76));
+};
+
+module.exports = { encodeAttachment, attachmentEncodedSize };
diff --git a/src/mime/stream.js b/src/mime/stream.js
new file mode 100644
index 0000000..6ff8104
--- /dev/null
+++ b/src/mime/stream.js
@@ -0,0 +1,114 @@
+// Ported from upyo v0.7.0 (packages/mime/src/stream.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createHash } = require('node:crypto');
+const { RawMessageValidationError } = require('../core/raw-message.js');
+const { base64, utf8 } = require('./bytes.js');
+const { BodyHasher } = require('./dkim/body-hash.js');
+const { signWithBodyHash } = require('./dkim/sign.js');
+
+/**
+ * A replayable attachment changed between DKIM body reads.
+ */
+class MimeAttachmentReplayError extends RawMessageValidationError {
+  /** Creates a replay validation failure. */
+  constructor() {
+    super('Attachment content changed between DKIM body reads.', 'content');
+    this.name = 'MimeAttachmentReplayError';
+  }
+}
+
+/** Prepares signatures without speculative unsigned attachment reads. @internal */
+const prepareMimeStream = async (plan, options = {}) => {
+  const { knownSize, signal } = options;
+  signal?.throwIfAborted();
+  const progress = options.progress ?? (() => {});
+  const checkSize = (size) => {
+    if (!Number.isSafeInteger(size)) {
+      throw new RangeError('Message size exceeds the safe integer range.');
+    }
+    options.checkSize?.(size);
+  };
+  if (knownSize != null) checkSize(knownSize);
+  const signatures = plan.dkim?.signatures ?? [];
+  if (signatures.length === 0) {
+    return {
+      size: knownSize,
+      encoding: plan.encoding,
+      // oxlint-disable-next-line no-shadow -- upstream
+      async *read(signal, progress) {
+        signal?.throwIfAborted();
+        yield utf8(plan.headers);
+        yield* plan.body(signal, progress);
+      },
+    };
+  }
+  const buffered = plan.dkim?.bodyMode !== 'streaming';
+  const chunks = [];
+  const hashes = new Map();
+  for (const sig of signatures) {
+    const mode = sig.canonicalization?.endsWith('/simple') ? 'simple' : 'relaxed';
+    if (!hashes.has(mode)) hashes.set(mode, new BodyHasher(mode));
+  }
+  const rawHash = createHash('sha256');
+  let length = 0;
+  const headerLength = utf8(plan.headers).length;
+  for await (const chunk of plan.body(signal, progress)) {
+    length += chunk.length;
+    checkSize(headerLength + length);
+    if (chunk.length > 0) progress();
+    if (buffered) chunks.push(chunk.slice());
+    rawHash.update(chunk);
+    for (const hash of hashes.values()) hash.update(chunk);
+  }
+  const expectedDigest = base64(rawHash.digest());
+  const bodyHashes = new Map(Array.from(hashes, ([mode, hash]) => [mode, hash.digest()]));
+  let headers = plan.headers;
+  try {
+    for (const sig of signatures) {
+      const mode = sig.canonicalization?.endsWith('/simple') ? 'simple' : 'relaxed';
+      const result = await signWithBodyHash(headers, sig, bodyHashes.get(mode), signal);
+      headers = `${result.headerName}: ${result.signature}\r\n${headers}`;
+    }
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (plan.dkim?.onSigningFailure !== 'send-unsigned') throw error;
+    // oxlint-disable-next-line no-console -- upstream
+    console.warn('DKIM signing failed, sending unsigned:', error);
+  }
+  signal?.throwIfAborted();
+  if (headers.split('\r\n').some((line) => utf8(line).length > 998)) {
+    throw new RangeError('Signed MIME header exceeds the RFC 5322 line limit.');
+  }
+  const size = utf8(headers).length + length;
+  checkSize(size);
+  return {
+    size,
+    encoding: plan.encoding === 'utf8' || /[\u0080-\uffff]/.test(headers) ? 'utf8' : '7bit',
+    // oxlint-disable-next-line no-shadow -- upstream
+    async *read(signal, progress) {
+      signal?.throwIfAborted();
+      yield utf8(headers);
+      if (buffered) {
+        for (const chunk of chunks) {
+          signal?.throwIfAborted();
+          yield chunk.slice();
+        }
+        return;
+      }
+      const replayHash = createHash('sha256');
+      let replayLength = 0;
+      for await (const chunk of plan.body(signal, progress)) {
+        replayLength += chunk.length;
+        if (replayLength > length) throw new MimeAttachmentReplayError();
+        replayHash.update(chunk);
+        yield chunk;
+      }
+      if (replayLength !== length || base64(replayHash.digest()) !== expectedDigest) {
+        throw new MimeAttachmentReplayError();
+      }
+    },
+  };
+};
+
+module.exports = { MimeAttachmentReplayError, prepareMimeStream };
diff --git a/tests/helpers/mime/dkim-test-keys.js b/tests/helpers/mime/dkim-test-keys.js
new file mode 100644
index 0000000..778c5a2
--- /dev/null
+++ b/tests/helpers/mime/dkim-test-keys.js
@@ -0,0 +1,105 @@
+// Ported from upyo v0.7.0 (packages/mime/src/test-utils/dkim-test-keys.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Test key pairs for DKIM signing tests.
+ *
+ * WARNING: These keys are for testing purposes only.
+ * Never use these keys in production environments.
+ */
+
+// =============================================================================
+// RSA Keys (2048-bit)
+// =============================================================================
+
+/**
+ * Test RSA private key in PKCS#8 PEM format (2048-bit).
+ * For testing DKIM signing functionality only.
+ */
+const TEST_DKIM_PRIVATE_KEY = `-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCqNgoqaoK/hCH3
+BT9TeS2qxBjX18I1oBDEM2LuwI615Nt0QPicVYzW9pYeISfGgcBE4gDhszGvN+6g
+GAO/sdmzXlqPLupDeuV++RyjVSFlFJphN+MYVedaFeIzmY+5ryxtYl4BJBOKNdxp
+cgte1dgRLEjT5VRCoUxgFgGYZa6PL5zglnEHiU6Girt+7Xl3hbUMM2p1BvkNoUlu
+D4BCgHeeJwoF+eNBMiXpJRhqH3HPJosYNgZSpnsqEzeqRSjWk8aV+UwMfbFA8gXG
+DMuyyGSxmNrPKg+gM2SEc4UPJccLe0AzKj3YSjKWfiSbmsAZcIPIXh7c+t/4Qi49
+Dzhck5DPAgMBAAECggEAAcMrjp9CZbK25BXYekgNu5KRroNfvhG1j6gLeez/VKsy
+2IGnQBskqTfBaBVNuXmSOWu/VjR2b+OqtzOREcE/GDvbI1e0SLe9FNCtbTHTRIB5
+Jh/avul9txj1SzWO8ziCw5kuBv86SLhqR3uIKP4G15XBTKxe8CtesLs8D9cWnDD9
+2LK988qOBA/7zJoluLtKIGj3Iff5cjBFByCTKBKR9V97Z5GoUOB+dWtLFSnccFWY
+54LapDGnXBavadhsXWbTO5uTr0ElL0/5imBXz4i7dp246JDYAaWCxgEbXm4SsW3O
+Cez9Dx+uJy8IyHbAgGc3gTalsFrr8GXTkiqiZeffAQKBgQDuhzpYuJBwgBGUlWpZ
+WmhhKHmwDE1D3h+HYy9ncVwC36WWWUmWe1xRr9DI8Y2Bw858soirJRwPc0e8C/ql
+JbKG1XEBp2X6tmgt4oR5noCZrq+QaFJBl9jL8bME1PZ5DH3jttIH8MTLBTjv5Kzl
+oxbwfKItvKwVlp5bHX7Sra8/zwKBgQC2rcKUkvpVQNjiFn+1pDaG6yJqjnCnLhN5
+DXLNVp8Y7oqtVSQTOkb3rPdQrVXMczjT5T0bdfq48kiO7yE9vwcrxKNQZKJsLcnQ
+u8aG6biNHGD9KGmwrrvMt2ubbyOiv42AVwsnVmc/+jkaQ3W1hPOeidK6/QzgbqRu
+cOb38YHfAQKBgQCeCd7wtaiNwWzkg3LpLOuHpCesKxpuYxeEvoTEBumtxbyStyn4
+mFd8j/7HhLP7TF7dY/UFYBsNaZYX0+AH18hHadfr/puk14KDFFgttIUETidoiJYn
+e5Ja3hN8mhWL8mjenVzfgfkBgr5Mw7iCleI3CHzzzNQ/oYHeYNaMhCNfJQKBgE/c
+AlZFMp6WbLnZsBbOJPAyVqdSgbj0EZs339oYZhDWJ1XDBLRLI78epDdmrz1jmZI4
+gtBAcUzszf9+Vn/RxObDXcnFVKQKGFHh5NYR0pYNs/C3/Aw7Nuo1vRsEKQX6y3cx
+ljSqNxTm5JOwrgKejoneInuQKFLsy4FkZfQ6ZdYBAoGBAIWidb2aBSzwNvyqsLSE
+ld/sIMSUZs55elni/PYIVoVsucwi64RAf2Yp9CqxM2dY2B/tOaU8ZM8Ih7UBzpwG
+syOX7b1HHQ92Vc1Oq0qRkqh+FaAmCNfuitU+YvoRSXUkwoS4bAJgt7vUUZyVUBrY
+k2/wS0OnfGTaP+Ycq4Mz5+9S
+-----END PRIVATE KEY-----`;
+
+/**
+ * Test RSA public key in PEM format (2048-bit).
+ * Corresponds to TEST_DKIM_PRIVATE_KEY.
+ */
+const TEST_DKIM_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqjYKKmqCv4Qh9wU/U3kt
+qsQY19fCNaAQxDNi7sCOteTbdED4nFWM1vaWHiEnxoHAROIA4bMxrzfuoBgDv7HZ
+s15ajy7qQ3rlfvkco1UhZRSaYTfjGFXnWhXiM5mPua8sbWJeASQTijXcaXILXtXY
+ESxI0+VUQqFMYBYBmGWujy+c4JZxB4lOhoq7fu15d4W1DDNqdQb5DaFJbg+AQoB3
+nicKBfnjQTIl6SUYah9xzyaLGDYGUqZ7KhM3qkUo1pPGlflMDH2xQPIFxgzLsshk
+sZjazyoPoDNkhHOFDyXHC3tAMyo92Eoyln4km5rAGXCDyF4e3Prf+EIuPQ84XJOQ
+zwIDAQAB
+-----END PUBLIC KEY-----`;
+
+/**
+ * Test domain for DKIM signing.
+ */
+const TEST_DKIM_DOMAIN = 'test.example.com';
+
+/**
+ * Test selector for DKIM signing.
+ */
+const TEST_DKIM_SELECTOR = 'test2025';
+
+// =============================================================================
+// Ed25519 Keys
+// =============================================================================
+
+/**
+ * Test Ed25519 private key in PKCS#8 PEM format.
+ * For testing DKIM signing functionality only.
+ */
+const TEST_DKIM_ED25519_PRIVATE_KEY = `-----BEGIN PRIVATE KEY-----
+MC4CAQAwBQYDK2VwBCIEIHrEIaq5WKCJ5bo54PO3KNnCw7lvWx9ZC1p0q2SRY/7O
+-----END PRIVATE KEY-----`;
+
+/**
+ * Test Ed25519 public key in PEM format.
+ * Corresponds to TEST_DKIM_ED25519_PRIVATE_KEY.
+ */
+const TEST_DKIM_ED25519_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAYFNLXjz1u/YHsmLd15UAoGdOquVBRCDEQxfi6PmoPkE=
+-----END PUBLIC KEY-----`;
+
+/**
+ * Test selector for Ed25519 DKIM signing.
+ */
+const TEST_DKIM_ED25519_SELECTOR = 'ed25519-test2025';
+
+module.exports = {
+  TEST_DKIM_PRIVATE_KEY,
+  TEST_DKIM_PUBLIC_KEY,
+  TEST_DKIM_DOMAIN,
+  TEST_DKIM_SELECTOR,
+  TEST_DKIM_ED25519_PRIVATE_KEY,
+  TEST_DKIM_ED25519_PUBLIC_KEY,
+  TEST_DKIM_ED25519_SELECTOR,
+};
diff --git a/tests/helpers/mime/verify-dkim.js b/tests/helpers/mime/verify-dkim.js
new file mode 100644
index 0000000..ecfd837
--- /dev/null
+++ b/tests/helpers/mime/verify-dkim.js
@@ -0,0 +1,69 @@
+// Ported from upyo v0.7.0 (packages/mime/src/test-utils/verify-dkim.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { createHash, verify } = require('node:crypto');
+
+/** Independent wire-level oracle; does not import production canonicalizers. */
+const verifyDkim = (raw, publicKey) => {
+  const split = raw.indexOf('\r\n\r\n');
+  const fields = raw.slice(0, split).split(/\r\n(?![ \t])/);
+  const dkim = fields.find((field) => field.startsWith('DKIM-Signature:'));
+  assert.ok(dkim);
+  const tags = Object.fromEntries(
+    dkim
+      .slice(15)
+      .replace(/\r\n/g, '')
+      .split(';')
+      .map((tag) => {
+        const equal = tag.indexOf('=');
+        return [tag.slice(0, equal).trim(), tag.slice(equal + 1).trim()];
+      }),
+  );
+  const [headerMode, bodyMode] = tags.c.split('/');
+  let body = raw.slice(split + 4);
+  if (bodyMode === 'relaxed') {
+    body = body
+      .split('\r\n')
+      .map((line) => line.replace(/[ \t]+/g, ' ').replace(/ +$/, ''))
+      .join('\r\n');
+  }
+  body = body.replace(/(?:\r\n)*$/, '');
+  if (body.length > 0 || bodyMode === 'simple') body += '\r\n';
+  assert.equal(createHash('sha256').update(body).digest('base64'), tags.bh);
+  const remaining = fields.filter((field) => field !== dkim);
+  const selected = [];
+  for (const name of tags.h.split(':')) {
+    const index = remaining.findLastIndex(
+      (field) => field.slice(0, field.indexOf(':')).toLowerCase() === name.toLowerCase(),
+    );
+    if (index >= 0) selected.push(remaining.splice(index, 1)[0]);
+  }
+  selected.push(dkim.replace(/\bb=[\s\S]*$/, 'b='));
+  const canonical = selected
+    .map((field) => {
+      if (headerMode === 'simple') return field;
+      const colon = field.indexOf(':');
+      return (
+        field.slice(0, colon).toLowerCase() +
+        ':' +
+        field
+          .slice(colon + 1)
+          .replace(/\r\n/g, '')
+          .replace(/[ \t]+/g, ' ')
+          .trim()
+      );
+    })
+    .join('\r\n');
+  const input = new TextEncoder().encode(canonical);
+  assert.ok(
+    verify(
+      tags.a === 'rsa-sha256' ? 'RSA-SHA256' : null,
+      tags.a === 'rsa-sha256' ? input : createHash('sha256').update(input).digest(),
+      publicKey,
+      Uint8Array.from(atob(tags.b.replace(/\s/g, '')), (c) => c.charCodeAt(0)),
+    ),
+  );
+};
+
+module.exports = { verifyDkim };
diff --git a/tests/types/mime.test-d.ts b/tests/types/mime.test-d.ts
new file mode 100644
index 0000000..dfd00fb
--- /dev/null
+++ b/tests/types/mime.test-d.ts
@@ -0,0 +1,29 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, RawMessageValidationError, type RawMessage } from '../../index.js';
+import {
+  composeMessage,
+  MimeAttachmentReplayError,
+  type ComposedMessage,
+  type DkimConfig,
+} from '../../src/mime/index.js';
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+const dkim: DkimConfig = {
+  signatures: [{ signingDomain: 'example.com', selector: 'mail', privateKey: '-----BEGIN…' }],
+  bodyMode: 'streaming',
+  onSigningFailure: 'send-unsigned',
+};
+expectType<Promise<ComposedMessage>>(composeMessage(message, { dkim }));
+expectAssignable<Promise<RawMessage>>(composeMessage(message));
+const composed = {} as ComposedMessage;
+expectType<'7bit' | 'utf8'>(composed.encoding);
+expectType<AsyncIterable<Uint8Array>>(composed.content());
+expectAssignable<RawMessageValidationError>(new MimeAttachmentReplayError());
+
+expectError(composeMessage({ subject: 'not a message' }));
+expectError<DkimConfig>({ signatures: [{ signingDomain: 'example.com', algorithm: 'rsa-sha1' }] });
diff --git a/tests/unit/mime-cancellation.test.js b/tests/unit/mime-cancellation.test.js
new file mode 100644
index 0000000..ee3d0fa
--- /dev/null
+++ b/tests/unit/mime-cancellation.test.js
@@ -0,0 +1,173 @@
+// Ported from upyo v0.7.0 (packages/mime/src/cancellation.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const { readAttachmentContent } = require('../../src/core/attachment.js');
+const { composeMessage } = require('../../src/mime/index.js');
+const { TEST_DKIM_PRIVATE_KEY } = require('../helpers/mime/dkim-test-keys.js');
+
+const message = (content) =>
+  createMessage({
+    from: 'from@example.com',
+    to: 'to@example.com',
+    subject: 'Test',
+    content: { text: 'x'.repeat(200000) },
+    attachments:
+      content == null
+        ? []
+        : [
+            {
+              filename: 'a',
+              contentType: 'application/octet-stream',
+              contentId: 'a',
+              inline: false,
+              content,
+            },
+          ],
+  });
+const dkim = {
+  signatures: [
+    {
+      signingDomain: 'example.com',
+      selector: 'test',
+      privateKey: TEST_DKIM_PRIVATE_KEY,
+    },
+  ],
+};
+
+for (const signing of [false, true]) {
+  test(`abort before and after headers, signed=${signing}`, async () => {
+    const lifetime = new AbortController();
+    const reason = new TypeError('Stopped.');
+    const raw = await composeMessage(message(), {
+      signal: lifetime.signal,
+      dkim: signing ? dkim : undefined,
+    });
+    const iterator = raw.content()[Symbol.asyncIterator]();
+    assert.ok(!(await iterator.next()).done);
+    lifetime.abort(reason);
+    await assert.rejects(iterator.next(), (error) => error === reason);
+    await assert.rejects(readAttachmentContent(raw.content), (error) => error === reason);
+    await assert.rejects(
+      composeMessage(message(), { signal: lifetime.signal }),
+      (error) => error === reason,
+    );
+  });
+}
+
+test('reader cancellation leaves another reader usable', async () => {
+  const raw = await composeMessage(message());
+  const controller = new AbortController();
+  const iterator = raw.content(controller.signal)[Symbol.asyncIterator]();
+  await iterator.next();
+  controller.abort();
+  await assert.rejects(iterator.next(), { name: 'AbortError' });
+  assert.ok((await readAttachmentContent(raw.content)).length > 200000);
+});
+
+for (const exit of ['break', 'throw', 'source-error', 'abort']) {
+  test(`attachment cleanup after ${exit}`, async () => {
+    let returns = 0;
+    let sourceSignal;
+    let resolveOpened;
+    const opened = new Promise((resolve) => {
+      resolveOpened = resolve;
+    });
+    const error = new TypeError('Stopped.');
+    let pulls = 0;
+    const raw = await composeMessage(
+      message((signal) => {
+        sourceSignal = signal;
+        resolveOpened();
+        const iterator = {
+          [Symbol.asyncIterator]() {
+            return this;
+          },
+          next() {
+            pulls++;
+            if (pulls === 1) {
+              return Promise.resolve({
+                done: false,
+                value: new Uint8Array([1, 2, 3]),
+              });
+            }
+            if (exit === 'source-error') return Promise.reject(error);
+            return new Promise(() => {});
+          },
+          return() {
+            returns++;
+            return Promise.resolve({ done: true, value: undefined });
+          },
+        };
+        return iterator;
+      }),
+    );
+    assert.equal(pulls, 0);
+    const controller = new AbortController();
+    const consuming = (async () => {
+      // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+      for await (const _chunk of raw.content(controller.signal)) {
+        if (pulls > 0 && exit === 'break') break;
+        if (pulls > 0 && exit === 'throw') throw error;
+      }
+    })();
+    await opened;
+    if (exit === 'abort') controller.abort(error);
+    if (exit === 'break') await consuming;
+    else await assert.rejects(consuming, (actual) => actual === error);
+    assert.equal(returns, 1);
+    assert.ok(sourceSignal?.aborted);
+    assert.ok(pulls <= 2);
+  });
+}
+
+for (const phase of ['unsigned', 'prehash', 'replay']) {
+  test(`cancel pending acquisition in ${phase} and close late reader`, async () => {
+    let acquired;
+    let opened;
+    const opening = new Promise((resolve) => {
+      opened = resolve;
+    });
+    let calls = 0;
+    let returns = 0;
+    const controller = new AbortController();
+    const reason = new TypeError('Cancelled.');
+    const content = () => {
+      if (phase === 'replay' && calls++ === 0) {
+        return (async function* () {
+          yield new Uint8Array([1]);
+        })();
+      }
+      opened();
+      return new Promise((resolve) => {
+        acquired = resolve;
+      });
+    };
+    const composition = composeMessage(message(content), {
+      signal: controller.signal,
+      dkim: phase === 'unsigned' ? undefined : { ...dkim, bodyMode: 'streaming' },
+    });
+    const work =
+      phase === 'prehash'
+        ? composition
+        : composition.then((raw) => readAttachmentContent(raw.content));
+    await opening;
+    controller.abort(reason);
+    await assert.rejects(work, (actual) => actual === reason);
+    acquired({
+      [Symbol.asyncIterator]() {
+        return {
+          next: () => Promise.resolve({ done: true, value: undefined }),
+          return: () => {
+            returns++;
+            return Promise.resolve({ done: true, value: undefined });
+          },
+        };
+      },
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.equal(returns, 1);
+  });
+}
diff --git a/tests/unit/mime-compose.test.js b/tests/unit/mime-compose.test.js
new file mode 100644
index 0000000..f62b926
--- /dev/null
+++ b/tests/unit/mime-compose.test.js
@@ -0,0 +1,310 @@
+// Ported from upyo v0.7.0 (packages/mime/src/compose.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const { readAttachmentContent } = require('../../src/core/attachment.js');
+const { composeMessage } = require('../../src/mime/index.js');
+const PostalMime = require('postal-mime');
+const { RawMessageValidationError } = require('../../src/core/raw-message.js');
+const { createRawMessagePlan, iterateRawMessage } = require('../../src/core/raw-message.js');
+const { MimeAttachmentReplayError } = require('../../src/mime/index.js');
+const {
+  TEST_DKIM_ED25519_PRIVATE_KEY,
+  TEST_DKIM_ED25519_PUBLIC_KEY,
+  TEST_DKIM_PRIVATE_KEY,
+  TEST_DKIM_PUBLIC_KEY,
+} = require('../helpers/mime/dkim-test-keys.js');
+const { verifyDkim } = require('../helpers/mime/verify-dkim.js');
+
+test('compose without opening attachments; replay stable MIME and Bcc envelope', async () => {
+  let reads = 0;
+  const message = createMessage({
+    from: 'from@example.com',
+    to: 'to@example.com',
+    bcc: 'blind@example.com',
+    subject: 'Hello',
+    content: { text: 'first\r\nsecond' },
+    attachments: {
+      filename: 'a',
+      contentType: 'text/plain',
+      inline: false,
+      contentId: 'a',
+      content: async function* () {
+        reads++;
+        yield new TextEncoder().encode('hello');
+      },
+    },
+  });
+  const raw = await composeMessage(message);
+  assert.equal(reads, 0);
+  assert.deepEqual(raw.envelope.to, ['to@example.com', 'blind@example.com']);
+  const [a, b] = await Promise.all([
+    readAttachmentContent(raw.content),
+    readAttachmentContent(raw.content),
+  ]);
+  assert.deepEqual(a, b);
+  assert.equal(reads, 2);
+  assert.ok(!new TextDecoder().decode(a).includes('Bcc:'));
+  assert.ok(new TextDecoder().decode(a).endsWith('\r\n'));
+  assert.equal(raw.encoding, '7bit');
+});
+
+const message = () =>
+  createMessage({
+    from: 'from@example.com',
+    to: 'to@example.com',
+    subject: '안녕하세요',
+    content: { text: 'Hello' },
+  });
+const signature = {
+  signingDomain: 'example.com',
+  selector: 'test',
+  privateKey: TEST_DKIM_PRIVATE_KEY,
+};
+const attachment = {
+  filename: '파일.bin',
+  contentType: 'application/octet-stream',
+  contentId: 'inline',
+  inline: true,
+};
+const collect = async (raw, signal) =>
+  new TextDecoder().decode(await readAttachmentContent(raw.content, signal));
+
+for (const kind of ['bytes', 'promise', 'blob', 'factory']) {
+  test(`independent parser decodes Unicode, alternatives and ${kind} attachments`, async () => {
+    const bytes = Uint8Array.from({ length: 65539 }, (_, i) => i % 251);
+    const source =
+      kind === 'bytes'
+        ? bytes
+        : kind === 'promise'
+          ? Promise.resolve(bytes)
+          : kind === 'blob'
+            ? new Blob([bytes])
+            : async function* () {
+                const reused = new Uint8Array(13);
+                for (let offset = 0; offset < bytes.length; offset += reused.length) {
+                  const slice = bytes.subarray(offset, offset + reused.length);
+                  reused.set(slice);
+                  yield reused.subarray(0, slice.length);
+                }
+              };
+    const raw = await composeMessage({
+      ...message(),
+      content: { text: '한글\r\nNext \nend\r', html: '<b>한글</b>' },
+      attachments: [{ ...attachment, content: source }],
+    });
+    const wire = await collect(raw);
+    const parsed = await PostalMime.parse(wire);
+    assert.equal(parsed.subject, '안녕하세요');
+    assert.equal(parsed.html?.trim(), '<b>한글</b>');
+    assert.ok(parsed.text?.startsWith('한글\nNext \nend'));
+    assert.equal(parsed.attachments[0].filename, '파일.bin');
+    assert.equal(parsed.attachments[0].contentId, '<inline>');
+    assert.deepEqual(new Uint8Array(parsed.attachments[0].content), bytes);
+    assert.ok(wire.includes('multipart/alternative'));
+    for await (const chunk of iterateRawMessage(createRawMessagePlan(raw))) {
+      assert.ok(chunk.length <= 32768);
+    }
+  });
+}
+
+for (const method of ['REQUEST', 'REPLY', 'CANCEL']) {
+  test(`calendar ${method} preserves calendar CRLF`, async () => {
+    const calendar = `BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//Upyo//EN\r\nMETHOD:${method}\r\nEND:VCALENDAR\r\n`;
+    const raw = await composeMessage({
+      ...message(),
+      calendar: { method, content: calendar },
+    });
+    const wire = await collect(raw);
+    assert.ok(wire.includes(`text/calendar; charset=utf-8; method=${method}`));
+    assert.ok(wire.indexOf('text/plain') < wire.indexOf('text/calendar'));
+    const parsed = await PostalMime.parse(wire);
+    assert.equal(
+      new TextDecoder().decode(parsed.attachments[0].content),
+      calendar.replace(/\r\n/g, '\n'),
+    );
+    const payload = wire
+      .split(`method=${method}\r\nContent-Transfer-Encoding: base64\r\n\r\n`)[1]
+      .split('\r\n--')[0];
+    assert.equal(atob(payload.replace(/\s/g, '')), calendar);
+  });
+}
+
+for (const bodyMode of ['buffered', 'streaming']) {
+  for (const algorithm of ['rsa-sha256', 'ed25519-sha256']) {
+    for (const canonicalization of [
+      'simple/simple',
+      'simple/relaxed',
+      'relaxed/simple',
+      'relaxed/relaxed',
+    ]) {
+      test(`verify composed ${algorithm} ${canonicalization} ${bodyMode}`, async () => {
+        let reads = 0;
+        const raw = await composeMessage(
+          {
+            ...message(),
+            attachments: [
+              {
+                ...attachment,
+                content: async function* () {
+                  reads++;
+                  yield new Uint8Array([1, 2, 3]);
+                },
+              },
+            ],
+          },
+          {
+            dkim: {
+              bodyMode,
+              signatures: [
+                {
+                  ...signature,
+                  algorithm,
+                  canonicalization,
+                  privateKey:
+                    algorithm === 'rsa-sha256'
+                      ? TEST_DKIM_PRIVATE_KEY
+                      : TEST_DKIM_ED25519_PRIVATE_KEY,
+                },
+              ],
+            },
+          },
+        );
+        assert.equal(reads, 1);
+        const wire = await collect(raw);
+        verifyDkim(
+          wire,
+          algorithm === 'rsa-sha256' ? TEST_DKIM_PUBLIC_KEY : TEST_DKIM_ED25519_PUBLIC_KEY,
+        );
+        assert.equal(await collect(raw), wire);
+        assert.equal(reads, bodyMode === 'buffered' ? 1 : 3);
+      });
+    }
+  }
+}
+
+test('buffered signed readers cannot mutate retained chunks', async () => {
+  const raw = await composeMessage(message(), {
+    dkim: { signatures: [signature] },
+  });
+  const expected = await collect(raw);
+  for await (const chunk of raw.content()) chunk.fill(0);
+  assert.equal(await collect(raw), expected);
+});
+
+test('streaming replay mismatch is a raw validation error', async () => {
+  let reads = 0;
+  const raw = await composeMessage(
+    {
+      ...message(),
+      attachments: [
+        {
+          ...attachment,
+          content: async function* () {
+            yield new Uint8Array([reads++]);
+          },
+        },
+      ],
+    },
+    { dkim: { bodyMode: 'streaming', signatures: [signature] } },
+  );
+  await assert.rejects(
+    collect(raw),
+    (error) =>
+      error instanceof MimeAttachmentReplayError &&
+      error instanceof RawMessageValidationError &&
+      error.field === 'content',
+  );
+});
+
+test('unsigned compose does not await promised bytes and observes later rejection', async () => {
+  let reject;
+  const error = new TypeError('Attachment failed.');
+  // oxlint-disable-next-line promise/param-names -- upstream
+  const content = new Promise((_, r) => {
+    reject = r;
+  });
+  const raw = await composeMessage({
+    ...message(),
+    attachments: [{ ...attachment, content }],
+  });
+  reject(error);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await assert.rejects(collect(raw), (actual) => actual === error);
+});
+
+test('snapshots metadata and signing configuration before awaiting bytes', async () => {
+  let resolve;
+  const headers = new Headers({ 'X-Test': 'before' });
+  const date = new Date('2026-09-01T00:00:00Z');
+  const signatures = [{ ...signature, headerFields: ['from', 'subject'] }];
+  const dkim = { signatures };
+  const composing = composeMessage(
+    {
+      ...message(),
+      headers,
+      date,
+      attachments: [
+        {
+          ...attachment,
+          // oxlint-disable-next-line promise/param-names -- upstream
+          content: new Promise((r) => {
+            resolve = r;
+          }),
+        },
+      ],
+    },
+    { dkim },
+  );
+  headers.set('X-Test', 'after');
+  date.setUTCFullYear(2000);
+  signatures[0].selector = 'changed';
+  signatures[0].headerFields.push('date');
+  resolve(new Uint8Array());
+  const wire = await collect(await composing);
+  assert.ok(wire.includes('x-test: before'));
+  assert.ok(wire.includes('2026'));
+  assert.ok(wire.includes('s=test;'));
+  assert.ok(wire.includes('h=from:subject;'));
+});
+
+test('nested and signed Unicode headers determine MIME encoding', async () => {
+  assert.equal(
+    (
+      await composeMessage({
+        ...message(),
+        attachments: [
+          {
+            ...attachment,
+            contentId: '한글',
+            content: new Uint8Array(),
+          },
+        ],
+      })
+    ).encoding,
+    'utf8',
+  );
+  assert.equal(
+    (
+      await composeMessage(message(), {
+        dkim: { signatures: [{ ...signature, signingDomain: '한글.example' }] },
+      })
+    ).encoding,
+    'utf8',
+  );
+  await assert.rejects(
+    composeMessage(message(), {
+      dkim: { signatures: [{ ...signature, signingDomain: 'x'.repeat(1000) }] },
+    }),
+    RangeError,
+  );
+});
+
+test('invalid derived envelope uses core raw validation', async () => {
+  await assert.rejects(
+    composeMessage({ ...message(), recipients: [] }),
+    (error) => error instanceof RawMessageValidationError && error.field === 'envelope',
+  );
+});
diff --git a/tests/unit/mime-dkim-body-hash.test.js b/tests/unit/mime-dkim-body-hash.test.js
new file mode 100644
index 0000000..351577a
--- /dev/null
+++ b/tests/unit/mime-dkim-body-hash.test.js
@@ -0,0 +1,64 @@
+// Ported from upyo v0.7.0 (packages/mime/src/dkim/body-hash.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createHash } = require('node:crypto');
+const { BodyHasher } = require('../../src/mime/dkim/body-hash.js');
+const {
+  canonicalizeBodyRelaxed,
+  canonicalizeBodySimple,
+} = require('../../src/mime/dkim/canonicalize.js');
+
+test('incremental body hashes match canonicalization at every split', () => {
+  const bodies = [
+    '',
+    '\r\n',
+    '\r\n\r\n',
+    ' a \t b\t \r\n\r\n',
+    'a\r\nb',
+    '\r\na\r\n \t\r\n',
+    'a\rb\nc\r',
+    'a\r\r\nb\t\rc\n d\r\n\r\n',
+    ' \t',
+    'a' + ' '.repeat(100000) + '\r\n',
+    '\r\n \t' + 'a'.repeat(131073) + '\t\r\nb\r\n\r\n',
+    ('A'.repeat(76) + '\r\n').repeat(2000),
+  ];
+  for (const mode of ['simple', 'relaxed']) {
+    for (const body of bodies) {
+      const bytes = new TextEncoder().encode(body);
+      const canonical =
+        mode === 'simple' ? canonicalizeBodySimple(body) : canonicalizeBodyRelaxed(body);
+      const expected = createHash('sha256').update(canonical).digest('base64');
+      for (const width of [1, 2, 3, 57, 65536, 200000]) {
+        const hash = new BodyHasher(mode);
+        for (let offset = 0; offset < bytes.length; offset += width) {
+          hash.update(bytes.subarray(offset, offset + width));
+        }
+        assert.equal(hash.digest(), expected, `${mode}, width ${width}`);
+      }
+    }
+  }
+});
+
+test('body hash span boundaries preserve pending CR and whitespace', () => {
+  const bodies = ['\r\n\r\nabc \tdef\t \r\n\r\n', ' \tabc\r\r\ndef\n\tghi\r', 'abc\r\n \t\r\n\r\n'];
+  for (const mode of ['simple', 'relaxed']) {
+    for (const body of bodies) {
+      const bytes = new TextEncoder().encode(body);
+      const canonical =
+        mode === 'simple' ? canonicalizeBodySimple(body) : canonicalizeBodyRelaxed(body);
+      const expected = createHash('sha256').update(canonical).digest('base64');
+      for (let first = 0; first <= bytes.length; first++) {
+        for (let second = first; second <= bytes.length; second++) {
+          const hash = new BodyHasher(mode);
+          hash.update(bytes.subarray(0, first));
+          hash.update(bytes.subarray(first, second));
+          hash.update(bytes.subarray(second));
+          assert.equal(hash.digest(), expected, `${mode}: ${first}, ${second}`);
+        }
+      }
+    }
+  }
+});
diff --git a/tests/unit/mime-dkim-canonicalize.test.js b/tests/unit/mime-dkim-canonicalize.test.js
new file mode 100644
index 0000000..945c79f
--- /dev/null
+++ b/tests/unit/mime-dkim-canonicalize.test.js
@@ -0,0 +1,160 @@
+// Ported from upyo v0.7.0 (packages/mime/src/dkim/canonicalize.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const {
+  canonicalizeBodyRelaxed,
+  canonicalizeBodySimple,
+  canonicalizeHeaderRelaxed,
+  canonicalizeHeaderSimple,
+} = require('../../src/mime/dkim/canonicalize.js');
+
+describe('DKIM Canonicalization', () => {
+  describe('canonicalizeHeaderSimple', () => {
+    it('should not modify header at all', () => {
+      const result = canonicalizeHeaderSimple('Subject', 'Hello World');
+      assert.strictEqual(result, 'Subject:Hello World');
+    });
+
+    it('should preserve original case', () => {
+      const result = canonicalizeHeaderSimple('Content-Type', 'text/plain; charset=UTF-8');
+      assert.strictEqual(result, 'Content-Type:text/plain; charset=UTF-8');
+    });
+
+    it('should preserve whitespace in value', () => {
+      const result = canonicalizeHeaderSimple('Subject', '  Hello   World  ');
+      assert.strictEqual(result, 'Subject:  Hello   World  ');
+    });
+
+    it('should handle folded headers (multi-line)', () => {
+      const result = canonicalizeHeaderSimple('Subject', 'Hello\r\n World');
+      assert.strictEqual(result, 'Subject:Hello\r\n World');
+    });
+  });
+
+  describe('canonicalizeHeaderRelaxed', () => {
+    it('should lowercase header name', () => {
+      const result = canonicalizeHeaderRelaxed('Subject', 'Hello World');
+      assert.strictEqual(result, 'subject:Hello World');
+    });
+
+    it('should lowercase mixed case header name', () => {
+      const result = canonicalizeHeaderRelaxed('Content-Type', 'text/plain');
+      assert.strictEqual(result, 'content-type:text/plain');
+    });
+
+    it('should collapse whitespace in value to single space', () => {
+      const result = canonicalizeHeaderRelaxed('Subject', 'Hello    World');
+      assert.strictEqual(result, 'subject:Hello World');
+    });
+
+    it('should remove leading whitespace from value', () => {
+      const result = canonicalizeHeaderRelaxed('Subject', '   Hello World');
+      assert.strictEqual(result, 'subject:Hello World');
+    });
+
+    it('should remove trailing whitespace from value', () => {
+      const result = canonicalizeHeaderRelaxed('Subject', 'Hello World   ');
+      assert.strictEqual(result, 'subject:Hello World');
+    });
+
+    it('should unfold multi-line headers', () => {
+      const result = canonicalizeHeaderRelaxed('Subject', 'Hello\r\n World');
+      assert.strictEqual(result, 'subject:Hello World');
+    });
+
+    it('should handle tabs as whitespace', () => {
+      const result = canonicalizeHeaderRelaxed('Subject', 'Hello\t\tWorld');
+      assert.strictEqual(result, 'subject:Hello World');
+    });
+
+    it('should handle mixed whitespace', () => {
+      const result = canonicalizeHeaderRelaxed('Subject', '  Hello \t\r\n  World  ');
+      assert.strictEqual(result, 'subject:Hello World');
+    });
+  });
+
+  describe('canonicalizeBodySimple', () => {
+    it('should return CRLF for empty body', () => {
+      const result = canonicalizeBodySimple('');
+      assert.strictEqual(result, '\r\n');
+    });
+
+    it("should add CRLF if body doesn't end with CRLF", () => {
+      const result = canonicalizeBodySimple('Hello World');
+      assert.strictEqual(result, 'Hello World\r\n');
+    });
+
+    it('should preserve single trailing CRLF', () => {
+      const result = canonicalizeBodySimple('Hello World\r\n');
+      assert.strictEqual(result, 'Hello World\r\n');
+    });
+
+    it('should reduce multiple trailing CRLFs to single CRLF', () => {
+      const result = canonicalizeBodySimple('Hello World\r\n\r\n\r\n');
+      assert.strictEqual(result, 'Hello World\r\n');
+    });
+
+    it('should preserve internal empty lines', () => {
+      const result = canonicalizeBodySimple('Hello\r\n\r\nWorld\r\n');
+      assert.strictEqual(result, 'Hello\r\n\r\nWorld\r\n');
+    });
+
+    it('should preserve whitespace in lines', () => {
+      const result = canonicalizeBodySimple('Hello   World\r\n');
+      assert.strictEqual(result, 'Hello   World\r\n');
+    });
+  });
+
+  describe('canonicalizeBodyRelaxed', () => {
+    it('should return empty string for empty body', () => {
+      const result = canonicalizeBodyRelaxed('');
+      assert.strictEqual(result, '');
+    });
+
+    it('should remove trailing whitespace from lines', () => {
+      const result = canonicalizeBodyRelaxed('Hello World   \r\n');
+      assert.strictEqual(result, 'Hello World\r\n');
+    });
+
+    it('should collapse whitespace within lines to single space', () => {
+      const result = canonicalizeBodyRelaxed('Hello    World\r\n');
+      assert.strictEqual(result, 'Hello World\r\n');
+    });
+
+    it('should remove trailing empty lines', () => {
+      const result = canonicalizeBodyRelaxed('Hello World\r\n\r\n\r\n');
+      assert.strictEqual(result, 'Hello World\r\n');
+    });
+
+    it('should preserve internal empty lines', () => {
+      const result = canonicalizeBodyRelaxed('Hello\r\n\r\nWorld\r\n');
+      assert.strictEqual(result, 'Hello\r\n\r\nWorld\r\n');
+    });
+
+    it('should handle tabs as whitespace', () => {
+      const result = canonicalizeBodyRelaxed('Hello\t\tWorld\r\n');
+      assert.strictEqual(result, 'Hello World\r\n');
+    });
+
+    it('should handle lines with only whitespace', () => {
+      const result = canonicalizeBodyRelaxed('Hello\r\n   \r\nWorld\r\n');
+      assert.strictEqual(result, 'Hello\r\n\r\nWorld\r\n');
+    });
+
+    it('should handle complex multi-line body', () => {
+      // oxlint-disable-next-line no-useless-concat -- upstream
+      const input = 'Line 1   \r\n' + 'Line   2\r\n' + '\r\n' + 'Line 3\t\t\r\n' + '\r\n' + '\r\n';
+      // oxlint-disable-next-line no-useless-concat -- upstream
+      const expected = 'Line 1\r\n' + 'Line 2\r\n' + '\r\n' + 'Line 3\r\n';
+      const result = canonicalizeBodyRelaxed(input);
+      assert.strictEqual(result, expected);
+    });
+
+    it('should handle body without trailing CRLF', () => {
+      const result = canonicalizeBodyRelaxed('Hello World');
+      assert.strictEqual(result, 'Hello World\r\n');
+    });
+  });
+});
diff --git a/tests/unit/mime-dkim-sign.test.js b/tests/unit/mime-dkim-sign.test.js
new file mode 100644
index 0000000..ffe3e88
--- /dev/null
+++ b/tests/unit/mime-dkim-sign.test.js
@@ -0,0 +1,350 @@
+// Ported from upyo v0.7.0 (packages/mime/src/dkim/sign.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { createHash, verify } = require('node:crypto');
+const { describe, it } = require('node:test');
+const {
+  TEST_DKIM_DOMAIN,
+  TEST_DKIM_ED25519_PRIVATE_KEY,
+  TEST_DKIM_ED25519_PUBLIC_KEY,
+  TEST_DKIM_ED25519_SELECTOR,
+  TEST_DKIM_PRIVATE_KEY,
+  TEST_DKIM_PUBLIC_KEY,
+  TEST_DKIM_SELECTOR,
+} = require('../helpers/mime/dkim-test-keys.js');
+const { signMessage } = require('../../src/mime/dkim/sign.js');
+
+describe('DKIM Signing', () => {
+  const simpleMessage =
+    'From: sender@example.com\r\n' +
+    'To: recipient@example.com\r\n' +
+    'Subject: Test Email\r\n' +
+    'Date: Thu, 01 Jan 2025 00:00:00 +0000\r\n' +
+    'MIME-Version: 1.0\r\n' +
+    'Content-Type: text/plain; charset=utf-8\r\n' +
+    '\r\n' +
+    'Hello, World!\r\n';
+
+  describe('signMessage', () => {
+    for (const algorithm of ['rsa-sha256', 'ed25519-sha256']) {
+      for (const headerMode of ['simple', 'relaxed']) {
+        it(`verifies ${algorithm} with ${headerMode} wire headers`, async () => {
+          const from = 'FrOm: sender@example.com';
+          const subject = 'SuBjEcT: A folded\r\n\tsubject';
+          const body = 'Hello\r\n';
+          const result = await signMessage(`${from}\r\n${subject}\r\n\r\n${body}`, {
+            signingDomain: TEST_DKIM_DOMAIN,
+            selector: TEST_DKIM_SELECTOR,
+            privateKey:
+              algorithm === 'rsa-sha256' ? TEST_DKIM_PRIVATE_KEY : TEST_DKIM_ED25519_PRIVATE_KEY,
+            algorithm,
+            canonicalization: `${headerMode}/simple`,
+            headerFields: ['from', 'SUBJECT'],
+          });
+          const signature = /(?:^|;\s*)b=([^;]+)$/.exec(result.signature);
+          assert.ok(signature);
+          assert.ok(
+            result.signature.includes(`bh=${createHash('sha256').update(body).digest('base64')};`),
+          );
+          const unsignedHeader =
+            'DKIM-Signature: ' + result.signature.slice(0, -signature[1].length);
+          // Construct verification input from the actual wire headers,
+          // independently of the signer's parser and canonicalizers.
+          const headers =
+            headerMode === 'simple'
+              ? [from, subject, unsignedHeader]
+              : [
+                  'from:sender@example.com',
+                  'subject:A folded subject',
+                  'dkim-signature:' + unsignedHeader.slice(16).trim(),
+                ];
+          const input = new TextEncoder().encode(headers.join('\r\n'));
+          assert.ok(
+            verify(
+              algorithm === 'rsa-sha256' ? 'RSA-SHA256' : null,
+              algorithm === 'rsa-sha256' ? input : createHash('sha256').update(input).digest(),
+              algorithm === 'rsa-sha256' ? TEST_DKIM_PUBLIC_KEY : TEST_DKIM_ED25519_PUBLIC_KEY,
+              Uint8Array.from(atob(signature[1]), (c) => c.charCodeAt(0)),
+            ),
+          );
+        });
+      }
+    }
+
+    it('should generate a valid DKIM-Signature header', async () => {
+      const result = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+      });
+
+      assert.strictEqual(result.headerName, 'DKIM-Signature');
+      assert.ok(result.signature.includes('v=1'));
+      assert.ok(result.signature.includes('a=rsa-sha256'));
+      assert.ok(result.signature.includes(`d=${TEST_DKIM_DOMAIN}`));
+      assert.ok(result.signature.includes(`s=${TEST_DKIM_SELECTOR}`));
+      assert.ok(result.signature.includes('bh='));
+      assert.ok(result.signature.includes('b='));
+      assert.ok(result.signature.includes('h='));
+    });
+
+    it('should include specified header fields in h= tag', async () => {
+      const result = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+        headerFields: ['from', 'to', 'subject'],
+      });
+
+      assert.ok(result.signature.includes('h=from:to:subject'));
+    });
+
+    it('should use default header fields if not specified', async () => {
+      const result = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+      });
+
+      // Default headers: from, to, subject, date
+      assert.ok(result.signature.includes('h=from:to:subject:date'));
+    });
+
+    it('should use specified canonicalization method', async () => {
+      const result = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+        canonicalization: 'simple/simple',
+      });
+
+      assert.ok(result.signature.includes('c=simple/simple'));
+    });
+
+    it('should default to relaxed/relaxed canonicalization', async () => {
+      const result = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+      });
+
+      assert.ok(result.signature.includes('c=relaxed/relaxed'));
+    });
+
+    it('should generate different signatures for different messages', async () => {
+      const message1 =
+        'From: sender@example.com\r\n' +
+        'To: recipient@example.com\r\n' +
+        'Subject: Test 1\r\n' +
+        'Date: Thu, 01 Jan 2025 00:00:00 +0000\r\n' +
+        '\r\n' +
+        'Body 1\r\n';
+
+      const message2 =
+        'From: sender@example.com\r\n' +
+        'To: recipient@example.com\r\n' +
+        'Subject: Test 2\r\n' +
+        'Date: Thu, 01 Jan 2025 00:00:00 +0000\r\n' +
+        '\r\n' +
+        'Body 2\r\n';
+
+      const result1 = await signMessage(message1, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+      });
+
+      const result2 = await signMessage(message2, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+      });
+
+      // Both body hash and signature should be different
+      const bh1 = result1.signature.match(/bh=([^;]+)/)?.[1];
+      const bh2 = result2.signature.match(/bh=([^;]+)/)?.[1];
+      const b1 = result1.signature.match(/b=([^;]+)/)?.[1];
+      const b2 = result2.signature.match(/b=([^;]+)/)?.[1];
+
+      assert.notStrictEqual(bh1, bh2, 'Body hashes should differ');
+      assert.notStrictEqual(b1, b2, 'Signatures should differ');
+    });
+
+    it('should handle messages with empty body', async () => {
+      const emptyBodyMessage =
+        'From: sender@example.com\r\n' +
+        'To: recipient@example.com\r\n' +
+        'Subject: Empty Body Test\r\n' +
+        'Date: Thu, 01 Jan 2025 00:00:00 +0000\r\n' +
+        '\r\n';
+
+      const result = await signMessage(emptyBodyMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+      });
+
+      assert.strictEqual(result.headerName, 'DKIM-Signature');
+      assert.ok(result.signature.includes('bh='));
+    });
+
+    it('should handle messages with multipart content', async () => {
+      const multipartMessage =
+        'From: sender@example.com\r\n' +
+        'To: recipient@example.com\r\n' +
+        'Subject: Multipart Test\r\n' +
+        'Date: Thu, 01 Jan 2025 00:00:00 +0000\r\n' +
+        'MIME-Version: 1.0\r\n' +
+        'Content-Type: multipart/alternative; boundary=boundary123\r\n' +
+        '\r\n' +
+        '--boundary123\r\n' +
+        'Content-Type: text/plain\r\n' +
+        '\r\n' +
+        'Plain text\r\n' +
+        '--boundary123\r\n' +
+        'Content-Type: text/html\r\n' +
+        '\r\n' +
+        '<p>HTML</p>\r\n' +
+        '--boundary123--\r\n';
+
+      const result = await signMessage(multipartMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+      });
+
+      assert.strictEqual(result.headerName, 'DKIM-Signature');
+      assert.ok(result.signature.includes('v=1'));
+    });
+
+    it('should handle non-ASCII characters in headers', async () => {
+      const unicodeMessage =
+        'From: =?UTF-8?B?7YWM7Iqk7Yq4?= <sender@example.com>\r\n' +
+        'To: recipient@example.com\r\n' +
+        'Subject: =?UTF-8?B?7ZWc6riA7Ja0IO2FjOyKpO2KuA==?=\r\n' +
+        'Date: Thu, 01 Jan 2025 00:00:00 +0000\r\n' +
+        '\r\n' +
+        'Hello\r\n';
+
+      const result = await signMessage(unicodeMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+      });
+
+      assert.strictEqual(result.headerName, 'DKIM-Signature');
+      assert.ok(result.signature.includes('v=1'));
+    });
+
+    it('should throw error for invalid private key', async () => {
+      await assert.rejects(async () => {
+        await signMessage(simpleMessage, {
+          signingDomain: TEST_DKIM_DOMAIN,
+          selector: TEST_DKIM_SELECTOR,
+          privateKey: 'invalid-key',
+        });
+      }, /Failed to import private key|invalid/i);
+    });
+
+    it('should sign with Ed25519 algorithm', async () => {
+      const result = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_ED25519_SELECTOR,
+        privateKey: TEST_DKIM_ED25519_PRIVATE_KEY,
+        algorithm: 'ed25519-sha256',
+      });
+
+      assert.strictEqual(result.headerName, 'DKIM-Signature');
+      assert.ok(result.signature.includes('v=1'));
+      assert.ok(result.signature.includes('a=ed25519-sha256'));
+      assert.ok(result.signature.includes(`d=${TEST_DKIM_DOMAIN}`));
+      assert.ok(result.signature.includes(`s=${TEST_DKIM_ED25519_SELECTOR}`));
+      assert.ok(result.signature.includes('bh='));
+      assert.ok(result.signature.includes('b='));
+    });
+
+    it('should accept CryptoKey for RSA signing', async () => {
+      // Import the private key first
+      const pemContents = TEST_DKIM_PRIVATE_KEY.replace(/-----BEGIN (?:RSA )?PRIVATE KEY-----/, '')
+        .replace(/-----END (?:RSA )?PRIVATE KEY-----/, '')
+        .replace(/\s/g, '');
+      const binaryString = atob(pemContents);
+      const bytes = new Uint8Array(binaryString.length);
+      for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+      }
+      const cryptoKey = await crypto.subtle.importKey(
+        'pkcs8',
+        bytes,
+        { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+        false,
+        ['sign'],
+      );
+
+      const result = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: cryptoKey,
+      });
+
+      assert.strictEqual(result.headerName, 'DKIM-Signature');
+      assert.ok(result.signature.includes('v=1'));
+      assert.ok(result.signature.includes('a=rsa-sha256'));
+    });
+
+    it('should accept CryptoKey for Ed25519 signing', async () => {
+      // Import the Ed25519 private key first
+      const pemContents = TEST_DKIM_ED25519_PRIVATE_KEY.replace(/-----BEGIN PRIVATE KEY-----/, '')
+        .replace(/-----END PRIVATE KEY-----/, '')
+        .replace(/\s/g, '');
+      const binaryString = atob(pemContents);
+      const bytes = new Uint8Array(binaryString.length);
+      for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+      }
+      const cryptoKey = await crypto.subtle.importKey('pkcs8', bytes, { name: 'Ed25519' }, false, [
+        'sign',
+      ]);
+
+      const result = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_ED25519_SELECTOR,
+        privateKey: cryptoKey,
+        algorithm: 'ed25519-sha256',
+      });
+
+      assert.strictEqual(result.headerName, 'DKIM-Signature');
+      assert.ok(result.signature.includes('v=1'));
+      assert.ok(result.signature.includes('a=ed25519-sha256'));
+    });
+
+    it('should generate different signatures for Ed25519 vs RSA', async () => {
+      const rsaResult = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+        algorithm: 'rsa-sha256',
+      });
+
+      const ed25519Result = await signMessage(simpleMessage, {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_ED25519_SELECTOR,
+        privateKey: TEST_DKIM_ED25519_PRIVATE_KEY,
+        algorithm: 'ed25519-sha256',
+      });
+
+      // The signatures should be different (different algorithms)
+      const rsaSig = rsaResult.signature.match(/b=([^;]+)/)?.[1];
+      const ed25519Sig = ed25519Result.signature.match(/b=([^;]+)/)?.[1];
+
+      assert.ok(rsaSig, 'RSA signature should exist');
+      assert.ok(ed25519Sig, 'Ed25519 signature should exist');
+      assert.notStrictEqual(rsaSig, ed25519Sig, 'Signatures should differ');
+
+      // Ed25519 signatures are shorter (64 bytes = ~88 base64 chars)
+      // RSA-2048 signatures are 256 bytes = ~344 base64 chars
+      assert.ok(ed25519Sig.length < rsaSig.length, 'Ed25519 signature should be shorter than RSA');
+    });
+  });
+});
diff --git a/tests/unit/mime-header-validation.test.js b/tests/unit/mime-header-validation.test.js
new file mode 100644
index 0000000..2f80ba8
--- /dev/null
+++ b/tests/unit/mime-header-validation.test.js
@@ -0,0 +1,57 @@
+// Ported from upyo v0.7.0 (packages/mime/src/header-validation.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const { composeMessage } = require('../../src/mime/index.js');
+const { prepareMimeMessage } = require('../../src/mime/message.js');
+
+const message = createMessage({
+  from: 'from@example.com',
+  to: 'to@example.com',
+  subject: 'Test',
+  content: { text: 'Hello' },
+});
+
+for (const address of [
+  'reply@example.com\r\nBcc: injected@example.com',
+  'reply@example.com\r',
+  'reply@example.com\n',
+]) {
+  test(`reject address line endings: ${JSON.stringify(address)}`, async () => {
+    const direct = {
+      ...message,
+      replyRecipients: [{ address }],
+    };
+    assert.throws(() => prepareMimeMessage(direct), TypeError);
+    await assert.rejects(composeMessage(direct), TypeError);
+  });
+}
+
+class DirectHeaders extends Headers {
+  field;
+
+  constructor(field) {
+    super();
+    this.field = field;
+  }
+  *[Symbol.iterator]() {
+    yield [this.field, 'value'];
+  }
+}
+
+for (const field of ['X-Test\r\nBcc', 'X-Test: Bcc', 'X Test', '', 'X-한글', 'X-Test\n']) {
+  test(`reject invalid custom field name: ${JSON.stringify(field)}`, async () => {
+    const direct = { ...message, headers: new DirectHeaders(field) };
+    assert.throws(() => prepareMimeMessage(direct), TypeError);
+    await assert.rejects(composeMessage(direct), TypeError);
+  });
+}
+
+test('accept the full printable ASCII field-name range except colon', async () => {
+  const field = Array.from({ length: 94 }, (_, index) => String.fromCharCode(index + 33))
+    .join('')
+    .replace(':', '');
+  await composeMessage({ ...message, headers: new DirectHeaders(field) });
+});
diff --git a/tests/unit/mime-stream.test.js b/tests/unit/mime-stream.test.js
new file mode 100644
index 0000000..e558cf1
--- /dev/null
+++ b/tests/unit/mime-stream.test.js
@@ -0,0 +1,72 @@
+// Ported from upyo v0.7.0 (packages/mime/src/mime-stream.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { Buffer } = require('node:buffer');
+const { createMessage } = require('../../src/core/message.js');
+const { prepareMimeMessage } = require('../../src/mime/message.js');
+
+for (const length of [0, 1, 2, 3, 56, 57, 58, 114, 65537, 256 * 1024]) {
+  test(`streams and sizes ${length} attachment bytes`, async () => {
+    const bytes = Uint8Array.from({ length }, (_, i) => i % 251);
+    let opened = 0;
+    const message = createMessage({
+      from: 'from@example.com',
+      to: 'to@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+      attachments: {
+        filename: 'data.bin',
+        contentType: 'application/octet-stream',
+        inline: false,
+        contentId: 'data',
+        content: bytes,
+      },
+    });
+    const plan = prepareMimeMessage(message);
+    const expectedSize = await plan.size();
+    const chunks = [];
+    for await (const chunk of plan.body()) {
+      assert.ok(chunk.length <= 65536);
+      chunks.push(chunk);
+    }
+    const body = Buffer.concat(chunks).toString();
+    assert.equal(Buffer.byteLength(plan.headers) + Buffer.byteLength(body), expectedSize);
+    const payload = body
+      .split('Content-Transfer-Encoding: base64\r\n')[1]
+      .split('\r\n\r\n')[1]
+      .split('\r\n--')[0];
+    assert.equal(
+      payload,
+      Buffer.from(bytes)
+        .toString('base64')
+        .replace(/(.{76})(?=.)/g, '$1\r\n'),
+    );
+    const streamed = prepareMimeMessage({
+      ...message,
+      attachments: [
+        {
+          ...message.attachments[0],
+          content: async function* () {
+            opened++;
+            for (let i = 0; i < bytes.length; i += 37) {
+              yield bytes.subarray(i, i + 37);
+            }
+          },
+        },
+      ],
+    });
+    assert.equal(await streamed.size(), undefined);
+    assert.equal(opened, 0);
+    const parts = [];
+    for await (const chunk of streamed.body()) parts.push(chunk);
+    const streamedPayload = Buffer.concat(parts)
+      .toString()
+      .split('Content-Transfer-Encoding: base64\r\n')[1]
+      .split('\r\n\r\n')[1]
+      .split('\r\n--')[0];
+    assert.equal(streamedPayload, payload);
+    assert.equal(opened, 1);
+  });
+}
diff --git a/tests/unit/mime.test.js b/tests/unit/mime.test.js
new file mode 100644
index 0000000..26a53ab
--- /dev/null
+++ b/tests/unit/mime.test.js
@@ -0,0 +1,141 @@
+// Paths of the ported MIME builder (src/mime/) that upstream's mime suites
+// leave out (upstream reaches them through the SMTP suites). Each message is
+// read back with postal-mime, an independent parser, not only matched against
+// this library's own output.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const PostalMime = require('postal-mime');
+const { createMessage, readAttachmentContent } = require('../../index.js');
+const { composeMessage } = require('../../src/mime/index.js');
+
+const base = { from: 'alex@example.com', to: 'bob@example.com', content: { text: 'Hi' } };
+
+const wire = async (message, options) => {
+  const composed = await composeMessage(message, options);
+  return new TextDecoder().decode(await readAttachmentContent(composed.content));
+};
+const headerBlock = (text) => text.slice(0, text.indexOf('\r\n\r\n'));
+
+test('MIME: non-ASCII names, subjects and filenames round-trip through encoded words', async () => {
+  const subject =
+    'Дуже довга тема листа, яка точно не вміститься в одне закодоване слово і має бути ' +
+    'розбита на кілька';
+  const filename = 'звіт за жовтень дві тисячі двадцять шостого року.pdf';
+  const message = createMessage({
+    from: { name: 'Алекс Долід', address: 'alex@example.com' },
+    to: 'bob@example.com',
+    cc: 'carol@example.com',
+    subject,
+    content: {},
+    attachments: [
+      {
+        inline: false,
+        filename,
+        content: new Uint8Array([1, 2, 3]),
+        contentType: 'application/pdf',
+        contentId: '',
+      },
+    ],
+  });
+  const text = await wire(message);
+  // RFC 5322's hard limit; upstream puts the first encoded word next to the field
+  // name, past the 76 characters of RFC 2047 (CLAUDE.md, known upstream bugs).
+  for (const line of headerBlock(text).split('\r\n')) assert.ok(line.length <= 998, line);
+  const parsed = await PostalMime.parse(text);
+  assert.strictEqual(parsed.subject, subject);
+  assert.deepStrictEqual(parsed.from, { address: 'alex@example.com', name: 'Алекс Долід' });
+  assert.deepStrictEqual(
+    parsed.cc.map(({ address }) => address),
+    ['carol@example.com'],
+  );
+  assert.deepStrictEqual(
+    parsed.attachments.map((attachment) => attachment.filename),
+    [filename],
+  );
+});
+
+test('MIME: a message without content gets an empty text part', async () => {
+  const parsed = await PostalMime.parse(
+    await wire(createMessage({ ...base, subject: 'Empty', content: {} })),
+  );
+  assert.strictEqual(parsed.subject, 'Empty');
+  assert.strictEqual(parsed.text.trim(), '');
+});
+
+test('MIME: priority maps to X-Priority and X-MSMail-Priority', async () => {
+  const low = headerBlock(await wire(createMessage({ ...base, subject: 'a', priority: 'low' })));
+  assert.match(low, /^X-Priority: 5$/m);
+  assert.match(low, /^X-MSMail-Priority: Low$/m);
+  const high = headerBlock(await wire(createMessage({ ...base, subject: 'a', priority: 'high' })));
+  assert.match(high, /^X-Priority: 1$/m);
+  assert.match(high, /^X-MSMail-Priority: High$/m);
+});
+
+test('MIME: long headers fold at whitespace and unfold to the original', async () => {
+  const subject = 'word '.repeat(60).trim();
+  const text = await wire(createMessage({ ...base, subject }));
+  const lines = headerBlock(text).split('\r\n');
+  assert.ok(lines.every((line) => line.length <= 78));
+  assert.ok(lines.filter((line) => line.startsWith(' word')).length >= 3);
+  assert.strictEqual((await PostalMime.parse(text)).subject, subject);
+});
+
+test('MIME: a token too long to fold is refused', async () => {
+  const message = createMessage({ ...base, subject: 'a', headers: { 'X-Long': 'y'.repeat(1200) } });
+  await assert.rejects(wire(message), {
+    name: 'RangeError',
+    message: 'Header field x-long contains a token too long to fold.',
+  });
+});
+
+test('MIME: the Message-ID comes from the message, then from a custom header', async () => {
+  const own = await wire(createMessage({ ...base, subject: 'a', messageId: '<own@example.com>' }));
+  assert.match(headerBlock(own), /^Message-ID: <own@example.com>$/m);
+  const custom = await wire(
+    createMessage({ ...base, subject: 'a', headers: { 'Message-ID': '<custom@example.com>' } }),
+  );
+  assert.match(headerBlock(custom), /^Message-ID: <custom@example.com>$/m);
+});
+
+test('MIME: a CR or LF in the subject cannot forge a header field', async () => {
+  const text = await wire(createMessage({ ...base, subject: 'Hello\r\nBcc: eve@example.com' }));
+  assert.doesNotMatch(headerBlock(text), /^Bcc:/m);
+  assert.strictEqual((await PostalMime.parse(text)).bcc, undefined);
+});
+
+test('MIME: a large attachment is encoded in full', async () => {
+  const content = new Uint8Array(1.5 * 1024 * 1024).fill(0x61);
+  const message = createMessage({
+    ...base,
+    subject: 'Large',
+    attachments: [
+      {
+        inline: false,
+        filename: 'a.bin',
+        content,
+        contentType: 'application/octet-stream',
+        contentId: '',
+      },
+    ],
+  });
+  const parsed = await PostalMime.parse(await wire(message));
+  assert.strictEqual(parsed.attachments[0].content.byteLength, content.length);
+});
+
+test('MIME: a DKIM failure throws, or sends unsigned when asked to', async (t) => {
+  const message = createMessage({ ...base, subject: 'Signed' });
+  const signatures = [{ signingDomain: 'example.com', selector: 's', privateKey: 'not a key' }];
+  await assert.rejects(wire(message, { dkim: { signatures } }), /Failed to import private key/);
+
+  const warnings = [];
+  t.mock.method(console, 'warn', (...args) => warnings.push(args));
+  const text = await wire(message, { dkim: { signatures, onSigningFailure: 'send-unsigned' } });
+  assert.doesNotMatch(headerBlock(text), /^DKIM-Signature:/m);
+  assert.strictEqual(warnings.length, 1);
+  assert.strictEqual(warnings[0][0], 'DKIM signing failed, sending unsigned:');
+
+  await assert.rejects(composeMessage(message, { dkim: { signatures, bodyMode: 'eager' } }), {
+    name: 'TypeError',
+    message: 'Expected DKIM bodyMode to be buffered or streaming.',
+  });
+});

From 23693f69f716c85f5aea9305a2c54460581b51c8 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:00:43 +0300
Subject: [PATCH 005/158] feat(smtp): port the SMTP transport from upyo 0.7.0

./smtp exports SmtpTransport (send, sendRaw, sendMany, verify, async
dispose) on node:net and node:tls: a connection pool, implicit TLS and
STARTTLS (required when requireTls is set), AUTH PLAIN, LOGIN, XOAUTH2 and
OAUTHBEARER with token refresh, PIPELINING, SIZE, DSN, SMTPUTF8 and
8BITMIME, dot-stuffing with backpressure, and DKIM through ./mime. Its errors
and receipt helpers come with it; its d.ts re-exports the DKIM types.

Upstream's suites run against the local mock SMTP server; the Mailpit and
OAuth e2e suites move to tests/mailpit and tests/e2e behind the new
test:mailpit and test:e2e scripts, with Mailpit's compose file and the test
certificate (now in tests/fixtures/smtp).

Changes to the tests, not to the transport:
- the mock server no longer turns a client's connection reset into an
  unhandled 'error' event: macOS and Windows send an RST where Linux, which
  upstream's CI runs on, sends a FIN, and three upstream tests fail there;
- the transport suite dials a released local port instead of 1025 (Mailpit's
  port) and 9999;
- a receiver check allows the globalThis of sloppy-mode CommonJS.

tests/unit/smtp.test.js covers what upstream reached only through Mailpit:
broken connections, AUTH LOGIN rejections, a rejected DATA and the DATA
writer's guards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |    2 +-
 package.json                                  |    6 +
 src/smtp/config.js                            |   37 +
 src/smtp/data-stream.js                       |  204 +++
 src/smtp/delivery-status.js                   |  166 ++
 src/smtp/envelope.js                          |   72 +
 src/smtp/index.d.ts                           |  865 +++++++++
 src/smtp/index.js                             |   27 +
 src/smtp/message-converter.js                 |   45 +
 src/smtp/message-stream.js                    |   50 +
 src/smtp/oauth2.js                            |  404 +++++
 src/smtp/raw-message.js                       |   63 +
 src/smtp/smtp-connection.js                   | 1245 +++++++++++++
 src/smtp/smtp-receipt.js                      |   21 +
 src/smtp/smtp-status-code.js                  |   31 +
 src/smtp/smtp-transport.js                    |  913 ++++++++++
 tests/e2e/smtp-transport.oauth2.e2e.test.js   |   56 +
 tests/fixtures/smtp/README.md                 |    8 +
 tests/fixtures/smtp/server-cert.pem           |   21 +
 tests/fixtures/smtp/server-key.pem            |   28 +
 tests/helpers/smtp/dkim-test-keys.js          |  105 ++
 tests/helpers/smtp/mailpit-client.js          |  188 ++
 tests/helpers/smtp/mailpit-delivery-utils.js  |  144 ++
 tests/helpers/smtp/mock-smtp-server.js        |  493 ++++++
 tests/helpers/smtp/test-config.js             |  149 ++
 tests/mailpit/docker-compose.yml              |   35 +
 .../smtp-transport.dkim.mailpit.test.js       |  378 ++++
 tests/mailpit/smtp-transport.mailpit.test.js  |  533 ++++++
 tests/types/smtp.test-d.ts                    |   45 +
 tests/unit/graph.test.js                      |   10 +-
 ...smtp-attachment-stream.integration.test.js |  263 +++
 .../smtp-attachment-tls.integration.test.js   |  121 ++
 tests/unit/smtp-config.test.js                |   64 +
 tests/unit/smtp-connection-lifecycle.test.js  |   72 +
 .../unit/smtp-connection.integration.test.js  | 1471 ++++++++++++++++
 ...smtp-connection.oauth2.integration.test.js |  267 +++
 tests/unit/smtp-data-stream.test.js           |   89 +
 tests/unit/smtp-delivery-status.test.js       |  122 ++
 tests/unit/smtp-envelope.test.js              |   84 +
 .../smtp-large-attachment.integration.test.js |  195 +++
 ...smtp-message-converter.integration.test.js | 1478 ++++++++++++++++
 tests/unit/smtp-message-stream.test.js        |  260 +++
 tests/unit/smtp-mime-regression.test.js       |   48 +
 tests/unit/smtp-oauth2.test.js                |  443 +++++
 .../unit/smtp-raw-message.integration.test.js |  481 +++++
 tests/unit/smtp-transport.dkim.test.js        |  433 +++++
 tests/unit/smtp-transport.integration.test.js | 1552 +++++++++++++++++
 .../smtp-transport.oauth2.integration.test.js |  140 ++
 .../smtp-transport.pool.integration.test.js   |  451 +++++
 tests/unit/smtp-transport.test.js             |  553 ++++++
 .../unit/smtp-verify-tls.integration.test.js  |  158 ++
 tests/unit/smtp-verify.integration.test.js    |  333 ++++
 tests/unit/smtp.test.js                       |  188 ++
 53 files changed, 15608 insertions(+), 2 deletions(-)
 create mode 100644 src/smtp/config.js
 create mode 100644 src/smtp/data-stream.js
 create mode 100644 src/smtp/delivery-status.js
 create mode 100644 src/smtp/envelope.js
 create mode 100644 src/smtp/index.d.ts
 create mode 100644 src/smtp/index.js
 create mode 100644 src/smtp/message-converter.js
 create mode 100644 src/smtp/message-stream.js
 create mode 100644 src/smtp/oauth2.js
 create mode 100644 src/smtp/raw-message.js
 create mode 100644 src/smtp/smtp-connection.js
 create mode 100644 src/smtp/smtp-receipt.js
 create mode 100644 src/smtp/smtp-status-code.js
 create mode 100644 src/smtp/smtp-transport.js
 create mode 100644 tests/e2e/smtp-transport.oauth2.e2e.test.js
 create mode 100644 tests/fixtures/smtp/README.md
 create mode 100644 tests/fixtures/smtp/server-cert.pem
 create mode 100644 tests/fixtures/smtp/server-key.pem
 create mode 100644 tests/helpers/smtp/dkim-test-keys.js
 create mode 100644 tests/helpers/smtp/mailpit-client.js
 create mode 100644 tests/helpers/smtp/mailpit-delivery-utils.js
 create mode 100644 tests/helpers/smtp/mock-smtp-server.js
 create mode 100644 tests/helpers/smtp/test-config.js
 create mode 100644 tests/mailpit/docker-compose.yml
 create mode 100644 tests/mailpit/smtp-transport.dkim.mailpit.test.js
 create mode 100644 tests/mailpit/smtp-transport.mailpit.test.js
 create mode 100644 tests/types/smtp.test-d.ts
 create mode 100644 tests/unit/smtp-attachment-stream.integration.test.js
 create mode 100644 tests/unit/smtp-attachment-tls.integration.test.js
 create mode 100644 tests/unit/smtp-config.test.js
 create mode 100644 tests/unit/smtp-connection-lifecycle.test.js
 create mode 100644 tests/unit/smtp-connection.integration.test.js
 create mode 100644 tests/unit/smtp-connection.oauth2.integration.test.js
 create mode 100644 tests/unit/smtp-data-stream.test.js
 create mode 100644 tests/unit/smtp-delivery-status.test.js
 create mode 100644 tests/unit/smtp-envelope.test.js
 create mode 100644 tests/unit/smtp-large-attachment.integration.test.js
 create mode 100644 tests/unit/smtp-message-converter.integration.test.js
 create mode 100644 tests/unit/smtp-message-stream.test.js
 create mode 100644 tests/unit/smtp-mime-regression.test.js
 create mode 100644 tests/unit/smtp-oauth2.test.js
 create mode 100644 tests/unit/smtp-raw-message.integration.test.js
 create mode 100644 tests/unit/smtp-transport.dkim.test.js
 create mode 100644 tests/unit/smtp-transport.integration.test.js
 create mode 100644 tests/unit/smtp-transport.oauth2.integration.test.js
 create mode 100644 tests/unit/smtp-transport.pool.integration.test.js
 create mode 100644 tests/unit/smtp-transport.test.js
 create mode 100644 tests/unit/smtp-verify-tls.integration.test.js
 create mode 100644 tests/unit/smtp-verify.integration.test.js
 create mode 100644 tests/unit/smtp.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 529167b..5227ee8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 02fda8e..764804a 100644
--- a/package.json
+++ b/package.json
@@ -28,6 +28,10 @@
       "types": "./src/mime/index.d.ts",
       "default": "./src/mime/index.js"
     },
+    "./smtp": {
+      "types": "./src/smtp/index.d.ts",
+      "default": "./src/smtp/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
@@ -50,6 +54,8 @@
   },
   "scripts": {
     "test": "node --test tests/unit/*.test.js",
+    "test:mailpit": "node --test --test-concurrency=1 tests/mailpit/*.test.js",
+    "test:e2e": "node --test --test-concurrency=1 tests/e2e/*.test.js",
     "test:coverage": "c8 --all --include 'src/**' --check-coverage --lines 98 --statements 98 --branches 90 --functions 100 --reporter text --reporter lcov node --test tests/unit/*.test.js",
     "test:types": "tsd",
     "check:dts": "node scripts/check-dts.js",
diff --git a/src/smtp/config.js b/src/smtp/config.js
new file mode 100644
index 0000000..c7cc7eb
--- /dev/null
+++ b/src/smtp/config.js
@@ -0,0 +1,37 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { validateDkimBodyMode } = require('../mime/dkim/types.js');
+
+/**
+ * Creates a resolved SMTP configuration by applying default values to optional fields.
+ *
+ * This function takes a partial SMTP configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the SMTP transport.
+ *
+ * @param config - The SMTP configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ * @internal
+ */
+const createSmtpConfig = (config) => {
+  validateDkimBodyMode(config.dkim);
+  const port = config.port ?? 587;
+
+  return {
+    host: config.host,
+    port,
+    secure: config.secure ?? port === 465,
+    requireTls: config.requireTls ?? false,
+    auth: config.auth,
+    tls: config.tls,
+    connectionTimeout: config.connectionTimeout ?? 60000,
+    socketTimeout: config.socketTimeout ?? 60000,
+    localName: config.localName ?? 'localhost',
+    pool: config.pool ?? true,
+    poolSize: config.poolSize ?? 5,
+    dkim: config.dkim,
+  };
+};
+
+module.exports = { createSmtpConfig };
diff --git a/src/smtp/data-stream.js b/src/smtp/data-stream.js
new file mode 100644
index 0000000..922a1e3
--- /dev/null
+++ b/src/smtp/data-stream.js
@@ -0,0 +1,204 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/data-stream.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { Buffer } = require('node:buffer');
+
+/** Races preparation against source inactivity and remote socket termination. */
+const prepareOnSocket = async (socket, timeoutMs, prepare, signal) => {
+  const controller = new AbortController();
+  const combined = combineSignals(controller.signal, signal);
+  const fail = (error) => controller.abort(error);
+  const closed = () => fail(new TypeError('SMTP connection closed during message preparation.'));
+  const data = () => fail(new TypeError('Unexpected SMTP reply during message preparation.'));
+  let timer;
+  const progress = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fail(new TypeError('SMTP message preparation timeout.')), timeoutMs);
+  };
+  socket.on('error', fail);
+  socket.on('close', closed);
+  socket.on('data', data);
+  progress();
+  try {
+    if (socket.destroyed || !socket.writable) closed();
+    combined.signal.throwIfAborted();
+    return await abortable(prepare(combined.signal, progress), combined.signal);
+  } catch (error) {
+    const interrupted = combined.signal.aborted;
+    controller.abort(error);
+    if (interrupted) socket.destroy();
+    signal?.throwIfAborted();
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    socket.off('error', fail);
+    socket.off('close', closed);
+    socket.off('data', data);
+    combined.cleanup();
+  }
+};
+
+const abortable = (promise, signal) => {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    if (signal.aborted) abort();
+  });
+};
+
+/** Writes one DATA body with bounded transparency buffers and backpressure. */
+const writeMessageData = async (socket, source, timeoutMs, checkSize, signal) => {
+  const controller = new AbortController();
+  const combined = combineSignals(controller.signal, signal);
+  const owned = combined.signal;
+  let terminated = false;
+  let complete = false;
+  let replyBytes = 0;
+  let buffer = '';
+  const lines = [];
+  let resolveReply;
+  const reply = new Promise((resolve) => (resolveReply = resolve));
+  const fail = (error) => {
+    if (!owned.aborted) controller.abort(error);
+    socket.destroy();
+  };
+  const close = () => fail(new TypeError('SMTP connection closed during DATA.'));
+  const onAbort = () => socket.destroy();
+  let timer;
+  const progress = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fail(new TypeError('SMTP DATA timeout.')), timeoutMs);
+  };
+  const data = (chunk) => {
+    replyBytes += chunk.length;
+    if (replyBytes > 65536) {
+      fail(new RangeError('SMTP DATA reply exceeds 64 KiB.'));
+      return;
+    }
+    buffer += Buffer.from(chunk).toString('utf8');
+    let end;
+    while ((end = buffer.indexOf('\r\n')) >= 0) {
+      const line = buffer.slice(0, end);
+      buffer = buffer.slice(end + 2);
+      lines.push(line);
+      if (/^\d{3} /.test(line)) {
+        if (!terminated) {
+          fail(new TypeError(`Premature SMTP DATA reply: ${line}`));
+        } else {
+          resolveReply({
+            code: Number(line.slice(0, 3)),
+            message: line.slice(4),
+            raw: lines.join('\r\n'),
+          });
+        }
+        return;
+      }
+    }
+  };
+  socket.on('error', fail);
+  socket.on('close', close);
+  socket.on('data', data);
+  owned.addEventListener('abort', onAbort, { once: true });
+  progress();
+  let iterator;
+  const write = async (bytes) => {
+    owned.throwIfAborted();
+    await abortable(
+      new Promise((resolve, reject) => {
+        let written = false;
+        let drained = false;
+        let returned = false;
+        const cleanup = () => {
+          socket.off('drain', drain);
+          owned.removeEventListener('abort', cleanup);
+        };
+        const finish = () => {
+          if (returned && written && drained) {
+            cleanup();
+            progress();
+            resolve();
+          }
+        };
+        const drain = () => {
+          drained = true;
+          finish();
+        };
+        socket.once('drain', drain);
+        owned.addEventListener('abort', cleanup, { once: true });
+        try {
+          const accepted = socket.write(bytes, (error) => {
+            if (error != null) {
+              cleanup();
+              reject(error);
+              return;
+            }
+            written = true;
+            finish();
+          });
+          drained = accepted || drained;
+          returned = true;
+          finish();
+        } catch (error) {
+          cleanup();
+          reject(error);
+        }
+      }),
+      owned,
+    );
+  };
+  try {
+    iterator = source(owned, progress)[Symbol.asyncIterator]();
+    if (socket.destroyed || !socket.writable) close();
+    let lineStart = true;
+    let size = 0;
+    while (true) {
+      owned.throwIfAborted();
+      const item = await abortable(Promise.resolve(iterator.next()), owned);
+      if (item.done) break;
+      const chunk = item.value;
+      for (let offset = 0; offset < chunk.length; offset += 32768) {
+        const window = chunk.subarray(offset, offset + 32768);
+        size += window.length;
+        checkSize(size);
+        progress();
+        const output = Buffer.allocUnsafe(window.length * 2);
+        let length = 0;
+        for (const byte of window) {
+          if (lineStart && byte === 46) output[length++] = 46;
+          output[length++] = byte;
+          lineStart = byte === 10;
+        }
+        await write(output.subarray(0, length));
+      }
+    }
+    owned.throwIfAborted();
+    terminated = true;
+    await write(Buffer.from('.\r\n'));
+    const result = await abortable(reply, owned);
+    owned.throwIfAborted();
+    complete = true;
+    return result;
+  } catch (error) {
+    fail(error);
+    signal?.throwIfAborted();
+    throw owned.reason;
+  } finally {
+    if (!complete) {
+      try {
+        Promise.resolve(iterator?.return?.()).catch(() => {});
+      } catch {
+        /* Preserve the send failure. */
+      }
+    }
+    clearTimeout(timer);
+    socket.off('error', fail);
+    socket.off('close', close);
+    socket.off('data', data);
+    owned.removeEventListener('abort', onAbort);
+    combined.cleanup();
+  }
+};
+
+module.exports = { prepareOnSocket, writeMessageData };
diff --git a/src/smtp/delivery-status.js b/src/smtp/delivery-status.js
new file mode 100644
index 0000000..ed80b55
--- /dev/null
+++ b/src/smtp/delivery-status.js
@@ -0,0 +1,166 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/delivery-status.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Error produced when SMTP delivery status notification settings are invalid.
+ */
+class SmtpDsnValidationError extends TypeError {
+  /**
+   * Creates a delivery status notification validation error.
+   *
+   * @param message A description of the invalid setting.
+   */
+  constructor(message) {
+    super(message);
+    this.name = 'SmtpDsnValidationError';
+  }
+}
+
+/**
+ * Error produced when delivery status notifications were requested from an
+ * SMTP server that did not advertise the RFC 3461 `DSN` extension.
+ */
+class SmtpDsnUnsupportedError extends Error {
+  /** Creates an error for a server without the `DSN` extension. */
+  constructor() {
+    super(
+      'Delivery status notifications were requested, but the server does ' +
+        'not advertise the DSN extension.',
+    );
+    this.name = 'SmtpDsnUnsupportedError';
+  }
+}
+
+const NOTIFICATION_CONDITIONS = new Set(['never', 'success', 'failure', 'delay']);
+
+/**
+ * Validates and serializes the RFC 3461 envelope parameters for a message.
+ *
+ * @param envelope The effective SMTP envelope that will carry the parameters.
+ * @param dsn The caller-supplied delivery status notification settings.
+ * @returns Serialized parameters, or `undefined` when none were requested.
+ * @throws {SmtpDsnValidationError} If any setting violates RFC 3461 or does
+ * not correspond to the message envelope.
+ * @internal
+ */
+const resolveSmtpDsn = (envelope, dsn) => {
+  if (dsn == null) return undefined;
+  if (typeof dsn !== 'object' || Array.isArray(dsn)) {
+    throw new SmtpDsnValidationError('DSN options must be an object.');
+  }
+
+  const mailParameters = [];
+  if (dsn.return != null) {
+    if (dsn.return !== 'full' && dsn.return !== 'headers') {
+      throw new SmtpDsnValidationError(`Unsupported DSN return value: ${String(dsn.return)}`);
+    }
+    mailParameters.push(`RET=${dsn.return === 'full' ? 'FULL' : 'HDRS'}`);
+  }
+
+  if (dsn.envelopeId != null) {
+    if (dsn.envelopeId === '') {
+      throw new SmtpDsnValidationError('DSN envelope ID must not be empty.');
+    }
+    const encoded = encodeXtext(dsn.envelopeId, 'DSN envelope ID');
+    const parameter = `ENVID=${encoded}`;
+    assertParameterLength(parameter, 100, 'ENVID');
+    mailParameters.push(parameter);
+  }
+
+  const envelopeRecipients = envelope.to;
+  const envelopeRecipientSet = new Set(envelopeRecipients);
+  const configuredRecipients = dsn.recipients;
+  if (
+    configuredRecipients != null &&
+    (typeof configuredRecipients !== 'object' || Array.isArray(configuredRecipients))
+  ) {
+    throw new SmtpDsnValidationError('DSN recipient options must be an object.');
+  }
+
+  const serializedByAddress = new Map();
+  for (const [address, options] of Object.entries(configuredRecipients ?? {})) {
+    if (!envelopeRecipientSet.has(address)) {
+      throw new SmtpDsnValidationError(`DSN recipient ${address} is not an envelope recipient.`);
+    }
+    if (options == null || typeof options !== 'object' || Array.isArray(options)) {
+      throw new SmtpDsnValidationError(`DSN options for ${address} must be an object.`);
+    }
+
+    const parameters = [];
+    if (options.notify != null) {
+      const notify = options.notify;
+      if (!Array.isArray(notify) || notify.length === 0) {
+        throw new SmtpDsnValidationError(
+          `DSN notification conditions for ${address} must be a non-empty array.`,
+        );
+      }
+      for (const condition of notify) {
+        if (typeof condition !== 'string' || !NOTIFICATION_CONDITIONS.has(condition)) {
+          throw new SmtpDsnValidationError(
+            `Unsupported DSN notification condition: ${String(condition)}`,
+          );
+        }
+      }
+      if (notify.includes('never') && notify.length !== 1) {
+        throw new SmtpDsnValidationError(
+          'The DSN notification condition NEVER must appear by itself.',
+        );
+      }
+      parameters.push(`NOTIFY=${notify.map((condition) => condition.toUpperCase()).join(',')}`);
+    }
+
+    if (options.originalRecipient != null) {
+      const encoded = encodeXtext(
+        options.originalRecipient,
+        `DSN original recipient for ${address}`,
+      );
+      if (options.originalRecipient !== address) {
+        throw new SmtpDsnValidationError(
+          // oxlint-disable-next-line no-useless-concat -- upstream
+          `DSN original recipient for ${address} must match the envelope ` + 'recipient address.',
+        );
+      }
+      const parameter = `ORCPT=rfc822;${encoded}`;
+      assertParameterLength(parameter, 500, 'ORCPT');
+      parameters.push(parameter);
+    }
+    serializedByAddress.set(address, parameters);
+  }
+
+  const recipientParameters = envelopeRecipients.map(
+    (address) => serializedByAddress.get(address) ?? [],
+  );
+  const requested =
+    mailParameters.length > 0 || recipientParameters.some((parameters) => parameters.length > 0);
+  return requested ? { mailParameters, recipientParameters } : undefined;
+};
+
+const encodeXtext = (value, name) => {
+  if (typeof value !== 'string') {
+    throw new SmtpDsnValidationError(`${name} must be a string.`);
+  }
+
+  let encoded = '';
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code < 0x20 || code > 0x7e) {
+      throw new SmtpDsnValidationError(`${name} must contain only printable US-ASCII characters.`);
+    }
+    if (code >= 0x21 && code <= 0x7e && code !== 0x2b && code !== 0x3d) {
+      encoded += value[index];
+    } else {
+      encoded += `+${code.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+  }
+  return encoded;
+};
+
+const assertParameterLength = (parameter, maximum, name) => {
+  if (parameter.length > maximum) {
+    throw new SmtpDsnValidationError(
+      `${name} parameter exceeds the RFC 3461 limit of ${maximum} characters.`,
+    );
+  }
+};
+
+module.exports = { SmtpDsnValidationError, SmtpDsnUnsupportedError, resolveSmtpDsn };
diff --git a/src/smtp/envelope.js b/src/smtp/envelope.js
new file mode 100644
index 0000000..2ca2c0e
--- /dev/null
+++ b/src/smtp/envelope.js
@@ -0,0 +1,72 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/envelope.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isEmailAddress } = require('../core/address.js');
+
+/**
+ * Error produced when an effective SMTP envelope is invalid.
+ */
+class SmtpEnvelopeValidationError extends TypeError {
+  /**
+   * Creates an SMTP envelope validation error.
+   *
+   * @param message A description of the invalid envelope.
+   */
+  constructor(message) {
+    super(message);
+    this.name = 'SmtpEnvelopeValidationError';
+  }
+}
+
+/**
+ * Resolves and validates the SMTP envelope for a message.
+ *
+ * @param message The message that supplies fields without an override.
+ * @param override Optional sender and recipient overrides.
+ * @returns The validated effective SMTP envelope.
+ * @throws {SmtpEnvelopeValidationError} If the override or any effective
+ * address is invalid, or if the effective recipient list is empty.
+ * @internal
+ */
+const resolveSmtpEnvelope = (message, override) => {
+  if (
+    override !== undefined &&
+    (override === null || typeof override !== 'object' || Array.isArray(override))
+  ) {
+    throw new SmtpEnvelopeValidationError('SMTP envelope options must be an object.');
+  }
+
+  const from = override?.from === undefined ? message.sender.address : override.from;
+  if (from !== null && !isEmailAddress(from)) {
+    throw new SmtpEnvelopeValidationError(
+      'SMTP envelope sender must be a valid email address or null.',
+    );
+  }
+
+  const recipients =
+    override?.to === undefined
+      ? [
+          ...message.recipients.map((recipient) => recipient.address),
+          ...message.ccRecipients.map((recipient) => recipient.address),
+          ...message.bccRecipients.map((recipient) => recipient.address),
+        ]
+      : override.to;
+  if (!Array.isArray(recipients)) {
+    throw new SmtpEnvelopeValidationError('SMTP envelope recipients must be an array.');
+  }
+  if (recipients.length === 0) {
+    throw new SmtpEnvelopeValidationError('SMTP envelope must contain at least one recipient.');
+  }
+
+  for (const [index, recipient] of recipients.entries()) {
+    if (!isEmailAddress(recipient)) {
+      throw new SmtpEnvelopeValidationError(
+        `SMTP envelope recipient at index ${index} must be a valid email address.`,
+      );
+    }
+  }
+
+  return { from, to: [...recipients] };
+};
+
+module.exports = { SmtpEnvelopeValidationError, resolveSmtpEnvelope };
diff --git a/src/smtp/index.d.ts b/src/smtp/index.d.ts
new file mode 100644
index 0000000..7ef6e97
--- /dev/null
+++ b/src/smtp/index.d.ts
@@ -0,0 +1,865 @@
+// Types ported from upyo v0.7.0 (packages/smtp/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/// <reference lib="esnext.disposable" />
+
+import type {
+  EmailAddress,
+  Message,
+  RawMessage,
+  RawTransport,
+  Receipt,
+  TransportOptions,
+  VerifiableTransport,
+} from '../../index.js';
+import type { DkimConfig } from '../mime/index.js';
+
+export type {
+  DkimAlgorithm,
+  DkimBodyMode,
+  DkimCanonicalization,
+  DkimConfig,
+  DkimSignature,
+  DkimSigningFailureAction,
+} from '../mime/index.js';
+
+/**
+ * Configuration interface for SMTP transport connection settings.
+ *
+ * This interface defines all available options for configuring an SMTP
+ * connection including server details, authentication, security, and
+ * connection pooling settings.
+ *
+ * @example
+ * ```typescript
+ * const config: SmtpConfig = {
+ *   host: 'smtp.gmail.com',
+ *   port: 465,
+ *   secure: true, // Use TLS from start
+ *   auth: {
+ *     user: 'user@gmail.com',
+ *     pass: 'app-password'
+ *   },
+ *   connectionTimeout: 30000,
+ *   poolSize: 10
+ * };
+ * ```
+ */
+export interface SmtpConfig {
+  /**
+   * The SMTP server hostname or IP address.
+   */
+  readonly host: string;
+  /**
+   * The SMTP server port number.
+   * @default 587
+   */
+  readonly port?: number;
+  /**
+   * Whether to use implicit TLS from the start of the connection.
+   * @default `true` on port 465; otherwise `false`
+   */
+  readonly secure?: boolean;
+  /**
+   * Whether to require a successful STARTTLS upgrade for connections that do
+   * not use implicit TLS.  When enabled, the client issues `STARTTLS` even if
+   * the server does not advertise the capability and fails the connection if
+   * the upgrade does not succeed.
+   * @default false
+   */
+  readonly requireTls?: boolean;
+  /**
+   * Authentication configuration for the SMTP server.
+   */
+  readonly auth?: SmtpAuth;
+  /**
+   * TLS configuration options.
+   */
+  readonly tls?: SmtpTlsOptions;
+  /**
+   * Connection timeout in milliseconds.
+   * @default 60000
+   */
+  readonly connectionTimeout?: number;
+  /**
+   * Socket timeout in milliseconds.
+   * @default 60000
+   */
+  readonly socketTimeout?: number;
+  /**
+   * The name to use for the local hostname in the HELO/EHLO command.
+   */
+  readonly localName?: string;
+  /**
+   * Pool connections to reuse them.
+   * @default true
+   */
+  readonly pool?: boolean;
+  /**
+   * Maximum number of SMTP connections the transport may have open at once.
+   *
+   * The limit counts every connection the transport owns: connections that are
+   * being established, connections that are currently sending, and idle
+   * connections retained for reuse.  It therefore applies whether or not
+   * {@link SmtpConfig.pool} is enabled.  When the limit is reached, `send()`
+   * `sendMany()`, `sendRaw()`, and `verify()` wait for a connection to become available instead of
+   * opening another one, so this value can be matched to a provider's
+   * simultaneous-connection limit.
+   *
+   * Must be a positive integer, or `Infinity` to leave the number of
+   * connections unbounded.
+   *
+   * @default 5
+   */
+  readonly poolSize?: number;
+  /**
+   * DKIM signing configuration.
+   * When provided, all outgoing emails will be signed with DKIM.
+   */
+  readonly dkim?: DkimConfig;
+}
+/**
+ * Authentication configuration for SMTP connections.
+ *
+ * This is a discriminated union of the supported authentication strategies:
+ *
+ *  -  {@link SmtpUserPassAuth}: traditional username/password authentication
+ *     (SASL `PLAIN`, `LOGIN`, …), discriminated by the `pass` field.
+ *  -  {@link SmtpOAuth2TokenAuth}: OAuth 2.0 authentication using a static or
+ *     dynamically provided access token, discriminated by the `accessToken`
+ *     field.
+ *  -  {@link SmtpOAuth2RefreshAuth}: OAuth 2.0 authentication using the built-in
+ *     `refresh_token` grant flow, discriminated by the `refreshToken` field.
+ *
+ * @example
+ * ```typescript
+ * // Username/password
+ * const passwordAuth: SmtpAuth = {
+ *   user: 'username@domain.com',
+ *   pass: 'password',
+ *   method: 'plain' // or 'login', 'cram-md5'
+ * };
+ *
+ * // OAuth 2.0 with a (possibly refreshing) access token
+ * const tokenAuth: SmtpAuth = {
+ *   user: 'username@gmail.com',
+ *   accessToken: 'ya29.a0Af…',
+ *   method: 'xoauth2' // or 'oauthbearer'
+ * };
+ * ```
+ */
+export type SmtpAuth = SmtpUserPassAuth | SmtpOAuth2TokenAuth | SmtpOAuth2RefreshAuth;
+/**
+ * OAuth 2.0 access token aggregate that supplies access tokens on demand.
+ *
+ * The transport invokes the provider each time it needs to authenticate a new
+ * connection, which lets the caller plug in an external OAuth client (e.g.,
+ * `google-auth-library` or `msal-node`) and refresh expired tokens
+ * transparently.
+ *
+ * @param signal An optional {@link AbortSignal} to cancel token acquisition.
+ * @returns The OAuth 2.0 access token (bearer token), or a promise of it.
+ */
+export type OAuth2TokenProvider = (signal?: AbortSignal) => string | Promise<string>;
+/**
+ * Username/password authentication configuration for SMTP connections.
+ *
+ * Defines the credentials and SASL method to use when connecting to an SMTP
+ * server that requires password-based authentication.
+ *
+ * @example
+ * ```typescript
+ * const auth: SmtpUserPassAuth = {
+ *   user: 'username@domain.com',
+ *   pass: 'password',
+ *   method: 'plain' // or 'login', 'cram-md5'
+ * };
+ * ```
+ */
+export interface SmtpUserPassAuth {
+  /**
+   * Username for authentication.
+   */
+  readonly user: string;
+  /**
+   * Password for authentication.
+   */
+  readonly pass: string;
+  /**
+   * Authentication method.
+   * @default "plain"
+   */
+  readonly method?: 'plain' | 'login' | 'cram-md5';
+}
+/**
+ * OAuth 2.0 authentication configuration using a directly supplied access
+ * token.
+ *
+ * The `accessToken` may be a static string or an {@link OAuth2TokenProvider}
+ * callback that returns a fresh token on demand.  Use the callback form to
+ * integrate an external OAuth client (such as `google-auth-library` or
+ * `msal-node`) so that expired tokens are refreshed automatically.
+ *
+ * @example
+ * ```typescript
+ * const auth: SmtpOAuth2TokenAuth = {
+ *   user: 'username@gmail.com',
+ *   accessToken: async () => await getFreshAccessToken(),
+ *   method: 'xoauth2',
+ * };
+ * ```
+ */
+export interface SmtpOAuth2TokenAuth {
+  /**
+   * The user (email address) to authenticate as.
+   */
+  readonly user: string;
+  /**
+   * The OAuth 2.0 access token, or a provider callback returning one.
+   *
+   * When a callback is given, it is invoked every time a new connection is
+   * authenticated, allowing the caller to refresh expired tokens.
+   */
+  readonly accessToken: string | OAuth2TokenProvider;
+  /**
+   * The SASL mechanism to use.  When omitted, the mechanism is chosen
+   * automatically based on the server's advertised capabilities, preferring
+   * `xoauth2`.
+   * @default "xoauth2"
+   */
+  readonly method?: 'xoauth2' | 'oauthbearer';
+}
+/**
+ * OAuth 2.0 authentication configuration using the built-in `refresh_token`
+ * grant flow.
+ *
+ * The transport exchanges the refresh token for an access token at the given
+ * token endpoint and caches it until shortly before it expires, refreshing it
+ * automatically as needed.  No external OAuth library is required.
+ *
+ * @example
+ * ```typescript
+ * const auth: SmtpOAuth2RefreshAuth = {
+ *   user: 'username@gmail.com',
+ *   clientId: '…apps.googleusercontent.com',
+ *   clientSecret: '…',
+ *   refreshToken: '1//…',
+ *   tokenEndpoint: 'https://oauth2.googleapis.com/token',
+ * };
+ * ```
+ */
+export interface SmtpOAuth2RefreshAuth {
+  /**
+   * The user (email address) to authenticate as.
+   */
+  readonly user: string;
+  /**
+   * The OAuth 2.0 client identifier.
+   */
+  readonly clientId: string;
+  /**
+   * The OAuth 2.0 client secret.  May be omitted for public clients (e.g.,
+   * clients using PKCE) that have no secret.
+   */
+  readonly clientSecret?: string;
+  /**
+   * The OAuth 2.0 refresh token used to obtain access tokens.
+   */
+  readonly refreshToken: string;
+  /**
+   * The token endpoint URL where the refresh token is exchanged for an access
+   * token (e.g., `https://oauth2.googleapis.com/token`).
+   */
+  readonly tokenEndpoint: string;
+  /**
+   * An optional space-delimited list of OAuth 2.0 scopes to request.
+   */
+  readonly scope?: string;
+  /**
+   * The SASL mechanism to use.  When omitted, the mechanism is chosen
+   * automatically based on the server's advertised capabilities, preferring
+   * `xoauth2`.
+   * @default "xoauth2"
+   */
+  readonly method?: 'xoauth2' | 'oauthbearer';
+}
+/**
+ * OAuth 2.0 authentication configuration for SMTP connections.
+ *
+ * A union of the OAuth 2.0 authentication strategies: a directly supplied
+ * (or callback-provided) access token ({@link SmtpOAuth2TokenAuth}) or the
+ * built-in `refresh_token` grant flow ({@link SmtpOAuth2RefreshAuth}).
+ */
+export type SmtpOAuth2Auth = SmtpOAuth2TokenAuth | SmtpOAuth2RefreshAuth;
+/**
+ * TLS/SSL configuration options for secure SMTP connections.
+ *
+ * These options control the behavior of TLS encryption when connecting
+ * to SMTP servers, including certificate validation and client authentication.
+ *
+ * @example
+ * ```typescript
+ * const tlsOptions: SmtpTlsOptions = {
+ *   rejectUnauthorized: true,
+ *   minVersion: 'TLSv1.2',
+ *   ca: [fs.readFileSync('ca-cert.pem', 'utf8')]
+ * };
+ * ```
+ */
+export interface SmtpTlsOptions {
+  /**
+   * Whether to reject unauthorized certificates.
+   * @default true
+   */
+  readonly rejectUnauthorized?: boolean;
+  /**
+   * List of trusted certificates.
+   */
+  readonly ca?: string[];
+  /**
+   * Private key for client certificate authentication.
+   */
+  readonly key?: string;
+  /**
+   * Certificate for client certificate authentication.
+   */
+  readonly cert?: string;
+  /**
+   * Minimum TLS version to accept.
+   * @default "TLSv1.2"
+   */
+  readonly minVersion?: 'TLSv1' | 'TLSv1.1' | 'TLSv1.2' | 'TLSv1.3';
+  /**
+   * Maximum TLS version to accept.
+   * @default "TLSv1.3"
+   */
+  readonly maxVersion?: 'TLSv1' | 'TLSv1.1' | 'TLSv1.2' | 'TLSv1.3';
+}
+/**
+ * Resolved SMTP configuration with all optional fields filled with default values.
+ *
+ * This type represents the final configuration after applying defaults,
+ * used internally by the SMTP transport implementation.
+ */
+
+/**
+ * Overrides for the SMTP envelope of one message.
+ *
+ * Omitted fields are derived from the corresponding message fields.  A `null`
+ * sender produces the null reverse-path used for delivery notifications.
+ */
+export interface SmtpEnvelopeOptions {
+  /**
+   * The address for `MAIL FROM`, or `null` for `MAIL FROM:<>`.
+   *
+   * When omitted, the message sender is used.
+   */
+  readonly from?: EmailAddress | null;
+  /**
+   * The addresses for `RCPT TO`.
+   *
+   * When omitted, the message's To, Cc, and Bcc addresses are used.
+   */
+  readonly to?: readonly EmailAddress[];
+}
+/**
+ * Resolves an SMTP envelope override for one message in a batch.
+ *
+ * @param message The message whose envelope is being resolved.
+ * @param index The zero-based position of the message in the send operation.
+ * @returns The envelope override, or `undefined` to derive the envelope from
+ * the message.
+ */
+export type SmtpEnvelopeResolver = (
+  message: Message,
+  index: number,
+) => SmtpEnvelopeOptions | undefined;
+/**
+ * Error produced when an effective SMTP envelope is invalid.
+ */
+export declare class SmtpEnvelopeValidationError extends TypeError {
+  /**
+   * Creates an SMTP envelope validation error.
+   *
+   * @param message A description of the invalid envelope.
+   */
+  constructor(message: string);
+}
+/** @internal */
+
+/**
+ * A condition under which an SMTP server should issue a delivery status
+ * notification for a recipient.
+ *
+ * `"never"` must be the only condition when it is used.
+ */
+export type SmtpDsnNotification = 'never' | 'success' | 'failure' | 'delay';
+/**
+ * Delivery status notification settings for one SMTP envelope recipient.
+ */
+export interface SmtpDsnRecipientOptions {
+  /**
+   * Conditions under which the server should issue a notification.
+   *
+   * `"never"` must appear by itself.  When omitted, the server applies its
+   * default behavior, which is normally equivalent to `"failure"` or to
+   * `"failure"` together with `"delay"`.
+   */
+  readonly notify?: readonly SmtpDsnNotification[];
+  /**
+   * The original Internet mail address to identify in notifications.
+   *
+   * Upyo serializes this as an RFC 3461 `ORCPT` parameter with the `rfc822`
+   * address type.  For an initial submission, RFC 3461 requires this value to
+   * equal the corresponding envelope recipient address.
+   */
+  readonly originalRecipient?: string;
+}
+/**
+ * SMTP delivery status notification settings for one message.
+ *
+ * These settings are serialized as SMTP envelope parameters and are not added
+ * to the message headers.
+ */
+export interface SmtpDsnOptions {
+  /**
+   * An identifier that will be returned in delivery status notifications.
+   * Serialized as the RFC 3461 `ENVID` parameter.  The identifier must not be
+   * empty.
+   */
+  readonly envelopeId?: string;
+  /**
+   * How much of the original message a failure notification should return.
+   * Serialized as `RET=FULL` or `RET=HDRS`.
+   */
+  readonly return?: 'full' | 'headers';
+  /**
+   * Per-recipient notification settings, keyed by exact envelope address.
+   */
+  readonly recipients?: Readonly<Record<string, SmtpDsnRecipientOptions>>;
+}
+/**
+ * SMTP-specific options for sending messages.
+ */
+export interface SmtpTransportOptions extends TransportOptions {
+  /**
+   * SMTP envelope overrides for this send operation.
+   *
+   * A resolver can return a different envelope for each message passed to
+   * {@link SmtpTransport.sendMany}.
+   */
+  readonly envelope?: SmtpEnvelopeOptions | SmtpEnvelopeResolver;
+  /** Delivery status notification settings for this SMTP transaction. */
+  readonly dsn?: SmtpDsnOptions;
+}
+/**
+ * Error produced when SMTP delivery status notification settings are invalid.
+ */
+export declare class SmtpDsnValidationError extends TypeError {
+  /**
+   * Creates a delivery status notification validation error.
+   *
+   * @param message A description of the invalid setting.
+   */
+  constructor(message: string);
+}
+/**
+ * Error produced when delivery status notifications were requested from an
+ * SMTP server that did not advertise the RFC 3461 `DSN` extension.
+ */
+export declare class SmtpDsnUnsupportedError extends Error {
+  /** Creates an error for a server without the `DSN` extension. */
+  constructor();
+}
+/** @internal */
+
+/** Options for raw SMTP delivery. @since 0.6.0 */
+export interface SmtpRawTransportOptions extends TransportOptions {
+  /** Optional delivery status notifications for the explicit raw envelope. */
+  readonly dsn?: SmtpDsnOptions;
+  /** The envelope must be specified on the raw message itself. */
+  readonly envelope?: never;
+}
+
+/**
+ * A machine-readable enhanced SMTP status code defined by RFC 3463.
+ */
+export interface SmtpEnhancedStatusCode {
+  /** The complete enhanced status code. */
+  readonly code: string;
+  /** The delivery result class: success, transient failure, or permanent failure. */
+  readonly class: 2 | 4 | 5;
+  /** The subject identifying the probable source of the condition. */
+  readonly subject: number;
+  /** The detail identifying the precise condition. */
+  readonly detail: number;
+}
+/**
+ * An SMTP envelope recipient that the server rejected during an otherwise
+ * successful delivery.
+ */
+export interface SmtpRejectedRecipient {
+  /** The rejected recipient address. */
+  readonly recipient: string;
+  /** The three-digit SMTP reply code. */
+  readonly code: number;
+  /** The SMTP server's reply text. */
+  readonly response: string;
+  /** Whether retrying delivery to this recipient may succeed. */
+  readonly retryable: boolean;
+  /**
+   * The enhanced status code returned for this recipient, when valid.
+   */
+  readonly enhancedStatusCode?: SmtpEnhancedStatusCode;
+}
+/**
+ * Provider details for a failure returned by an SMTP server.
+ */
+export interface SmtpResponseProviderDetails {
+  /** The SMTP command that failed. */
+  readonly command: string;
+  /** The text from the SMTP server's final reply line. */
+  readonly response: string;
+  /** Recipient-level failures collected for the transaction. */
+  readonly rejectedRecipients?: readonly SmtpRejectedRecipient[];
+  /** The enhanced status code in the server reply, when valid. */
+  readonly enhancedStatusCode?: SmtpEnhancedStatusCode;
+}
+/**
+ * Checks whether provider details came from an SMTP server response.
+ *
+ * @param value Provider details from an SMTP receipt error.
+ * @returns Whether the value contains SMTP response details.
+ */
+export declare function isSmtpResponseProviderDetails(
+  value: unknown,
+): value is SmtpResponseProviderDetails;
+/**
+ * Provider details for a locally rejected oversized message.
+ */
+export interface SmtpMessageSizeProviderDetails {
+  /** The encoded message size in octets. */
+  readonly actualSize: number;
+  /** The server's advertised maximum size in octets. */
+  readonly maximumSize: string;
+}
+/**
+ * Provider details for a missing internationalization capability.
+ */
+export interface SmtpUtf8ProviderDetails {
+  /** The SMTP extension required by the message. */
+  readonly missingCapability: 'SMTPUTF8' | '8BITMIME';
+}
+/**
+ * Provider-specific details attached to SMTP receipt errors.
+ */
+export type SmtpProviderDetails =
+  | SmtpResponseProviderDetails
+  | SmtpMessageSizeProviderDetails
+  | SmtpUtf8ProviderDetails;
+/**
+ * A receipt returned by {@link SmtpTransport}.
+ *
+ * Successful receipts list any recipients rejected before the message was
+ * delivered to the remaining accepted recipients.  Callers can retry delivery
+ * to entries marked as retryable without redelivering to accepted recipients.
+ */
+export type SmtpReceipt =
+  | (Extract<
+      Receipt<'smtp'>,
+      {
+        readonly successful: true;
+      }
+    > & {
+      /** Recipients excluded from an otherwise successful delivery. */
+      readonly rejectedRecipients: readonly SmtpRejectedRecipient[];
+    })
+  | Extract<
+      Receipt<'smtp'>,
+      {
+        readonly successful: false;
+      }
+    >;
+
+/**
+ * SMTP transport implementation for sending emails via SMTP protocol.
+ *
+ * This transport provides efficient email delivery with connection pooling,
+ * support for authentication, TLS/SSL encryption, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { SmtpTransport } from '@alexify/mailer/smtp';
+ *
+ * // Automatic resource cleanup with using statement
+ * await using transport = new SmtpTransport({
+ *   host: 'smtp.gmail.com',
+ *   port: 465,
+ *   secure: true, // Use TLS from start
+ *   auth: {
+ *     user: 'user@gmail.com',
+ *     pass: 'app-password'
+ *   }
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * // Connections are automatically closed here
+ *
+ * // Or manual management
+ * const transport2 = new SmtpTransport(config);
+ * try {
+ *   await transport2.send(message);
+ * } finally {
+ *   await transport2.closeAllConnections();
+ * }
+ * ```
+ */
+export declare class SmtpTransport
+  implements RawTransport<'smtp'>, VerifiableTransport<'smtp'>, AsyncDisposable
+{
+  readonly id = 'smtp';
+  /**
+   * The SMTP configuration used by this transport.
+   */
+  config: SmtpConfig;
+  /**
+   * The maximum number of SMTP connections this transport may have open at
+   * once.  The limit covers connections that are being established,
+   * connections that are currently sending, and idle connections retained for
+   * reuse, so it holds whether or not pooling is enabled.  A caller that needs
+   * a connection while the limit is reached waits until one becomes available.
+   * `Infinity` leaves the number of connections unbounded.
+   */
+  poolSize: number;
+  /**
+   * Creates a new SMTP transport instance.
+   *
+   * @param config SMTP configuration including server details, authentication,
+   *               and options.
+   * @throws {RangeError} If `config.poolSize` is neither a positive integer nor
+   *                        `Infinity`.
+   */
+  constructor(config: SmtpConfig);
+  /**
+   * Checks a fresh SMTP connection, TLS policy, and configured authentication
+   * without sending mail. Uses the shared connection limit and closes the
+   * verification connection afterward, even when pooling is enabled.
+   * Success does not guarantee acceptance of a sender, recipient, or message.
+   * @param options Optional cancellation signal, including while waiting for capacity.
+   * @returns A promise that resolves after successful verification and cleanup.
+   * @throws {SmtpResponseError} If greeting, EHLO/HELO, or STARTTLS is rejected.
+   * @throws {SmtpAuthError} If authentication fails.
+   * @throws {Error} If a connection, TLS, or timeout error occurs.
+   * @throws The caller's abort reason if cancelled.
+   */
+  verify(options?: TransportOptions): Promise<void>;
+  /**
+   * Sends a single email message via SMTP.
+   *
+   * This method converts the message to SMTP format, establishes a connection
+   * to the SMTP server, sends the message, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' }
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent with ID:', receipt.messageId);
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional SMTP envelope, delivery status, and cancellation
+   *                settings.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   * @throws {DOMException} If the operation is aborted through
+   *                        `options.signal`.
+   */
+  send(message: Message, options?: SmtpTransportOptions): Promise<SmtpReceipt>;
+  /**
+   * Delivers serialized MIME unchanged, apart from SMTP dot-stuffing.
+   * Configured DKIM signing and message composition are bypassed.
+   * @param message Original MIME bytes and explicit delivery envelope.
+   * @param options Optional DSN and cancellation settings.
+   * @returns An SMTP receipt, including any rejected recipients.
+   * @throws {Error} If cancellation is requested.
+   */
+  sendRaw(message: RawMessage, options?: SmtpRawTransportOptions): Promise<SmtpReceipt>;
+  /**
+   * Sends multiple email messages efficiently using a single SMTP connection.
+   *
+   * This method is optimized for bulk email sending by reusing a single SMTP
+   * connection for all messages, which significantly improves performance
+   * compared to sending each message individually.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   { subject: 'Message 1', recipients: [{ address: 'user1@example.com' }], ... },
+   *   { subject: 'Message 2', recipients: [{ address: 'user2@example.com' }], ... }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional SMTP envelope, delivery status, and cancellation
+   *                settings.
+   * @returns An async iterable of receipts, one for each message.
+   * @throws {DOMException} If the operation is aborted through
+   *                        `options.signal`.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: SmtpTransportOptions,
+  ): AsyncIterable<SmtpReceipt>;
+  /**
+   * Closes idle connections and drains sends and verification admitted before
+   * this call.
+   *
+   * Resolves once those sends have released their connections and all their
+   * sockets have closed.  Delivery is not interrupted, including sends waiting
+   * for capacity or connection setup.  A started `sendMany()` iteration must
+   * finish or be returned by its consumer before shutdown can complete.
+   *
+   * Concurrent close calls share the shutdown. New sends and verification wait for it to
+   * finish (and can cancel that wait through their abort signal); the transport
+   * can be reused afterward.
+   *
+   * @returns A promise that resolves after the admitted work is drained.
+   *
+   * @example
+   * ```typescript
+   * // At application shutdown
+   * await transport.closeAllConnections();
+   * ```
+   */
+  closeAllConnections(): Promise<void>;
+  /**
+   * Implements AsyncDisposable interface for automatic resource cleanup.
+   *
+   * This method is called automatically when using the `using` keyword,
+   * ensuring that all SMTP connections are properly closed when the
+   * transport goes out of scope.  Like {@link closeAllConnections}, it waits
+   * for admitted sends and started batch iterations to release their connections.
+   *
+   * @example
+   * ```typescript
+   * // Automatic cleanup with using statement
+   * await using transport = new SmtpTransport(config);
+   * await transport.send(message);
+   * // Connections are automatically closed here
+   * ```
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/** A replayable attachment changed between DKIM body reads. @since 0.6.0 */
+export declare class SmtpAttachmentReplayError extends TypeError {
+  /** Creates a replay validation failure. */
+  constructor();
+}
+/** The final bytes and known size of an SMTP DATA transaction. */
+
+/** Missing support for explicitly declared 8-bit MIME bodies. @since 0.6.0 */
+export declare class Smtp8BitMimeUnsupportedError extends TypeError {
+  /** Creates an error for a server without 8BITMIME. */
+  constructor();
+}
+/** @internal */
+
+/**
+ * An error thrown when SMTP authentication fails, including OAuth 2.0 token
+ * acquisition and SASL exchange failures.
+ */
+export declare class SmtpAuthError extends Error {
+  /**
+   * Creates a new {@link SmtpAuthError}.
+   * @param message A human-readable description of the failure.
+   */
+  constructor(message: string);
+}
+/**
+ * Builds the SASL `XOAUTH2` initial client response for SMTP authentication.
+ *
+ * The unencoded payload follows Google's XOAUTH2 format
+ * (`user=<user>^Aauth=Bearer <token>^A^A`, where `^A` is the `0x01` control
+ * character) and is returned Base64-encoded, ready to be sent as the argument
+ * of `AUTH XOAUTH2`.
+ *
+ * @param user The user (email address) to authenticate as.
+ * @param accessToken The OAuth 2.0 access token.
+ * @returns The Base64-encoded XOAUTH2 initial client response.
+ */
+
+/**
+ * An authentication failure backed by an SMTP server reply.
+ *
+ * This keeps {@link SmtpAuthError} as the public authentication error while
+ * retaining the reply fields needed to build structured transport receipts.
+ */
+export declare class SmtpAuthResponseError extends SmtpAuthError {
+  /** The numeric SMTP reply code returned by the server. */
+  readonly code: number;
+  /** The authentication command that produced the reply. */
+  readonly command: string;
+  /** The textual SMTP reply returned by the server. */
+  readonly response: string;
+  /**
+   * Creates an authentication response error.
+   *
+   * @param message A human-readable description of the authentication failure.
+   * @param code The numeric SMTP reply code.
+   * @param command The authentication command that produced the reply.
+   * @param response The textual SMTP reply returned by the server.
+   */
+  constructor(message: string, code: number, command: string, response: string);
+}
+/**
+ * Error thrown when an SMTP command receives an unsuccessful server reply.
+ */
+export declare class SmtpResponseError extends Error {
+  /**
+   * The numeric SMTP reply code returned by the server.
+   */
+  readonly code: number;
+  /**
+   * The SMTP command that produced the reply.
+   */
+  readonly command: string;
+  /**
+   * The textual SMTP reply returned by the server.
+   */
+  readonly response: string;
+  /** Recipient-level failures collected for an unsuccessful transaction. */
+  readonly rejectedRecipients?: readonly SmtpRejectedRecipient[];
+  /**
+   * Creates an SMTP response error.
+   *
+   * @param message Human-readable error message.
+   * @param code The numeric SMTP reply code.
+   * @param command The SMTP command that produced the reply.
+   * @param response The textual SMTP reply returned by the server.
+   * @param rejectedRecipients Recipient-level failures collected for the
+   *                           transaction.
+   */
+  constructor(
+    message: string,
+    code: number,
+    command: string,
+    response: string,
+    rejectedRecipients?: readonly SmtpRejectedRecipient[],
+  );
+}
diff --git a/src/smtp/index.js b/src/smtp/index.js
new file mode 100644
index 0000000..9d59c11
--- /dev/null
+++ b/src/smtp/index.js
@@ -0,0 +1,27 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { SmtpTransport } = require('./smtp-transport.js');
+const { SmtpAuthResponseError, SmtpResponseError } = require('./smtp-connection.js');
+
+const { SmtpAuthError } = require('./oauth2.js');
+const { SmtpEnvelopeValidationError } = require('./envelope.js');
+
+const { SmtpDsnUnsupportedError, SmtpDsnValidationError } = require('./delivery-status.js');
+const { isSmtpResponseProviderDetails } = require('./smtp-receipt.js');
+
+const { SmtpAttachmentReplayError } = require('./message-stream.js');
+const { Smtp8BitMimeUnsupportedError } = require('./raw-message.js');
+
+module.exports = {
+  SmtpTransport,
+  SmtpAuthResponseError,
+  SmtpResponseError,
+  SmtpAuthError,
+  SmtpEnvelopeValidationError,
+  SmtpDsnUnsupportedError,
+  SmtpDsnValidationError,
+  isSmtpResponseProviderDetails,
+  SmtpAttachmentReplayError,
+  Smtp8BitMimeUnsupportedError,
+};
diff --git a/src/smtp/message-converter.js b/src/smtp/message-converter.js
new file mode 100644
index 0000000..461c67d
--- /dev/null
+++ b/src/smtp/message-converter.js
@@ -0,0 +1,45 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { readAttachmentContent } = require('../core/attachment.js');
+const { prepareMimeMessage } = require('../mime/message.js');
+const { prepareMimeStream } = require('../mime/stream.js');
+const { resolveSmtpEnvelope } = require('./envelope.js');
+
+/** Snapshots MIME metadata and preserves the effective SMTP envelope. */
+const prepareMessage = (
+  message,
+  dkimConfig,
+  dsn,
+  resolvedEnvelope = resolveSmtpEnvelope(message),
+) => {
+  const plan = prepareMimeMessage(message, dkimConfig);
+  const envelope = { ...resolvedEnvelope, dsn };
+  return {
+    ...plan,
+    envelope,
+    requiresSmtpUtf8:
+      plan.encoding === 'utf8' ||
+      [envelope.from ?? '', ...envelope.to].some((address) => /[\u0080-\uffff]/.test(address)),
+  };
+};
+/** Collects the shared stream using the historical internal trailing-CRLF convention. */
+const convertMessage = async (
+  message,
+  dkimConfig,
+  dsn,
+  resolvedEnvelope = resolveSmtpEnvelope(message),
+  signal,
+) => {
+  const plan = prepareMessage(message, dkimConfig, dsn, resolvedEnvelope);
+  const stream = await prepareMimeStream(plan, { signal });
+  // oxlint-disable-next-line no-shadow -- upstream
+  const bytes = await readAttachmentContent((signal) => stream.read(signal), signal);
+  return {
+    envelope: plan.envelope,
+    raw: new TextDecoder().decode(bytes).slice(0, -2),
+    requiresSmtpUtf8: plan.requiresSmtpUtf8 || stream.encoding === 'utf8',
+  };
+};
+
+module.exports = { prepareMessage, convertMessage };
diff --git a/src/smtp/message-stream.js b/src/smtp/message-stream.js
new file mode 100644
index 0000000..2d8c14d
--- /dev/null
+++ b/src/smtp/message-stream.js
@@ -0,0 +1,50 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/message-stream.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { MimeAttachmentReplayError, prepareMimeStream } = require('../mime/stream.js');
+
+/** A replayable attachment changed between DKIM body reads. @since 0.6.0 */
+class SmtpAttachmentReplayError extends TypeError {
+  /** Creates a replay validation failure. */
+  constructor() {
+    super('Attachment content changed between DKIM body reads.');
+    this.name = 'SmtpAttachmentReplayError';
+  }
+}
+
+/** Prepares signatures and sizes under the SMTP preparation timeout. */
+const prepareMessageStream = async (plan, checkSize, progress, signal) => {
+  try {
+    const knownSize = await plan.size(signal, checkSize);
+    const stream = await prepareMimeStream(plan, {
+      knownSize,
+      checkSize,
+      progress,
+      signal,
+    });
+    return {
+      size: stream.size,
+      encoding: stream.encoding,
+      // oxlint-disable-next-line no-shadow -- upstream
+      async *read(signal, progress) {
+        try {
+          yield* stream.read(signal, progress);
+        } catch (error) {
+          signal?.throwIfAborted();
+          if (error instanceof MimeAttachmentReplayError) {
+            throw new SmtpAttachmentReplayError();
+          }
+          throw error;
+        }
+      },
+    };
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (error instanceof MimeAttachmentReplayError) {
+      throw new SmtpAttachmentReplayError();
+    }
+    throw error;
+  }
+};
+
+module.exports = { SmtpAttachmentReplayError, prepareMessageStream };
diff --git a/src/smtp/oauth2.js b/src/smtp/oauth2.js
new file mode 100644
index 0000000..fd7ffb4
--- /dev/null
+++ b/src/smtp/oauth2.js
@@ -0,0 +1,404 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/oauth2.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * An error thrown when SMTP authentication fails, including OAuth 2.0 token
+ * acquisition and SASL exchange failures.
+ */
+class SmtpAuthError extends Error {
+  /**
+   * Creates a new {@link SmtpAuthError}.
+   * @param message A human-readable description of the failure.
+   */
+  constructor(message) {
+    super(message);
+    this.name = 'SmtpAuthError';
+  }
+}
+
+/**
+ * Encodes a string as Base64 in a cross-runtime, UTF-8-safe manner.
+ *
+ * Unlike calling `btoa()` directly, this first encodes the input as UTF-8 so
+ * that non-ASCII characters (e.g., in an internationalized address) do not
+ * throw.
+ *
+ * @param input The string to encode.
+ * @returns The Base64-encoded representation of the UTF-8 bytes of `input`.
+ */
+const toBase64 = (input) => {
+  const bytes = new TextEncoder().encode(input);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+};
+
+/**
+ * Builds the SASL `XOAUTH2` initial client response for SMTP authentication.
+ *
+ * The unencoded payload follows Google's XOAUTH2 format
+ * (`user=<user>^Aauth=Bearer <token>^A^A`, where `^A` is the `0x01` control
+ * character) and is returned Base64-encoded, ready to be sent as the argument
+ * of `AUTH XOAUTH2`.
+ *
+ * @param user The user (email address) to authenticate as.
+ * @param accessToken The OAuth 2.0 access token.
+ * @returns The Base64-encoded XOAUTH2 initial client response.
+ */
+const formatXoauth2 = (user, accessToken) => {
+  return toBase64(`user=${user}\x01auth=Bearer ${accessToken}\x01\x01`);
+};
+
+/**
+ * Builds the SASL `OAUTHBEARER` initial client response for SMTP
+ * authentication, as defined by [RFC 7628].
+ *
+ * The unencoded payload is
+ * `n,a=<user>,^A[host=<host>^A][port=<port>^A]auth=Bearer <token>^A^A`
+ * (where `^A` is the `0x01` control character) and is returned Base64-encoded,
+ * ready to be sent as the argument of `AUTH OAUTHBEARER`.
+ *
+ * [RFC 7628]: https://www.rfc-editor.org/rfc/rfc7628
+ *
+ * @param user The user (email address) to authenticate as.
+ * @param accessToken The OAuth 2.0 access token.
+ * @param host The server host to include as the `host` key/value, if any.
+ * @param port The server port to include as the `port` key/value, if any.
+ * @returns The Base64-encoded OAUTHBEARER initial client response.
+ */
+const formatOauthbearer = (user, accessToken, host, port) => {
+  let response = `n,a=${escapeSaslName(user)},\x01`;
+  if (host != null) response += `host=${host}\x01`;
+  if (port != null) response += `port=${port}\x01`;
+  response += `auth=Bearer ${accessToken}\x01\x01`;
+  return toBase64(response);
+};
+
+/**
+ * Escapes a SASL name (GS2 `authzid`) per RFC 5801, encoding `,` as `=2C` and
+ * `=` as `=3D` so that identities containing those characters do not corrupt
+ * the GS2 header.
+ *
+ * @param name The SASL name to escape.
+ * @returns The escaped SASL name.
+ */
+const escapeSaslName = (name) => {
+  return name.replace(/=/g, '=3D').replace(/,/g, '=2C');
+};
+
+/**
+ * Chooses an OAuth 2.0 SASL mechanism based on the mechanisms advertised by the
+ * server in its `AUTH` capability line.
+ *
+ * `XOAUTH2` is preferred when available (it is the de-facto standard supported
+ * by Gmail and Outlook); otherwise `OAUTHBEARER` is used when advertised.  When
+ * neither is advertised, `xoauth2` is returned as a best-effort default.
+ *
+ * @param capabilities The capability lines parsed from the server's EHLO
+ *                     response.
+ * @returns The selected mechanism, either `"xoauth2"` or `"oauthbearer"`.
+ */
+const selectOAuth2Mechanism = (capabilities) => {
+  const authLine = capabilities.find((cap) => cap.toUpperCase().startsWith('AUTH'));
+  // Normalize "=" to whitespace so the older `AUTH=XOAUTH2 ...` form (where the
+  // first mechanism is glued to the AUTH keyword) is parsed like `AUTH XOAUTH2`.
+  const mechanisms =
+    authLine == null ? [] : authLine.toUpperCase().replace(/=/g, ' ').split(/\s+/).slice(1);
+  if (mechanisms.includes('XOAUTH2')) return 'xoauth2';
+  if (mechanisms.includes('OAUTHBEARER')) return 'oauthbearer';
+  return 'xoauth2';
+};
+
+/**
+ * Validates that an OAuth 2.0 token endpoint is safe to send client credentials
+ * to, requiring HTTPS except for loopback addresses (for local testing).
+ *
+ * @param endpoint The token endpoint URL to validate.
+ * @throws {TypeError} If the URL is malformed or uses an insecure scheme.
+ */
+const assertSecureTokenEndpoint = (endpoint) => {
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    throw new TypeError(`Invalid OAuth 2.0 token endpoint URL: ${endpoint}`);
+  }
+  if (url.protocol === 'https:') return;
+  const isLoopback =
+    url.hostname === 'localhost' ||
+    url.hostname === '127.0.0.1' ||
+    url.hostname === '[::1]' ||
+    url.hostname === '::1';
+  if (url.protocol === 'http:' && isLoopback) return;
+  throw new TypeError(
+    'OAuth 2.0 token endpoint must use HTTPS to protect client credentials: ' + endpoint,
+  );
+};
+
+/**
+ * The number of milliseconds before a cached access token's expiry at which it
+ * is considered stale and eligible for refresh.
+ */
+const REFRESH_SAFETY_MARGIN_MS = 60_000;
+
+/**
+ * The default access token lifetime (in seconds) assumed when the token
+ * endpoint omits `expires_in`.
+ */
+const DEFAULT_EXPIRES_IN = 3600;
+
+/**
+ * How long to wait for the token endpoint before aborting the request, so a
+ * stalled endpoint cannot block authentication indefinitely.
+ */
+const TOKEN_REQUEST_TIMEOUT_MS = 60_000;
+
+/** Maximum number of response-body characters to include in error messages. */
+const MAX_ERROR_BODY_LENGTH = 500;
+
+/**
+ * Truncates a token-endpoint response body so an oversized payload (e.g. a
+ * large proxy/CDN error page) does not bloat error messages and logs.
+ *
+ * @param text The response body text.
+ * @returns The text, truncated with an ellipsis if it exceeds the limit.
+ */
+const truncateErrorBody = (text) => {
+  return text.length > MAX_ERROR_BODY_LENGTH ? `${text.slice(0, MAX_ERROR_BODY_LENGTH)}…` : text;
+};
+
+/**
+ * Mirrors a promise but rejects early if the given abort signal fires, without
+ * cancelling the underlying promise.  This lets a single waiter abort its own
+ * wait on a shared operation without affecting other waiters.
+ *
+ * @param promise The promise to await.
+ * @param signal An optional abort signal that rejects the returned promise.
+ * @returns A promise that settles with `promise`, or rejects when `signal`
+ *          aborts.
+ */
+const abortable = (promise, signal) => {
+  if (signal == null) return promise;
+  return new Promise((resolve, reject) => {
+    // Fall back to a standard AbortError when the signal has no reason (e.g.
+    // aborted without one, or a runtime that does not populate `reason`), so the
+    // promise never rejects with `undefined`.
+    const abortReason = () =>
+      signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+    const onAbort = () => {
+      signal.removeEventListener('abort', onAbort);
+      reject(abortReason());
+    };
+    if (signal.aborted) {
+      reject(abortReason());
+    } else {
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+    // Always attach to the underlying promise so its settlement is observed
+    // (avoiding unhandled rejections) even after an abort wins the race.
+    promise.then(
+      // oxlint-disable-next-line promise/always-return -- upstream
+      (value) => {
+        signal.removeEventListener('abort', onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener('abort', onAbort);
+        reject(error);
+      },
+    );
+  });
+};
+
+/**
+ * Acquires and caches OAuth 2.0 access tokens for SMTP authentication.
+ *
+ * Depending on the {@link SmtpOAuth2Auth} configuration, the manager either
+ * returns a static token, invokes a provider callback on every request, or
+ * exchanges a refresh token for an access token at the configured token
+ * endpoint and caches it until shortly before it expires.  A single manager is
+ * shared across all pooled connections of a transport so that the refresh-token
+ * exchange happens at most once per token lifetime.
+ */
+class OAuth2TokenManager {
+  auth;
+  fetchFn;
+  cached;
+  pending;
+
+  /**
+   * Creates a new {@link OAuth2TokenManager}.
+   *
+   * @param auth The OAuth 2.0 authentication configuration.
+   * @param fetchFn The `fetch` implementation to use for the refresh-token
+   *                exchange.  Defaults to the global `fetch`; primarily
+   *                overridden in tests.
+   * @throws {TypeError} If a refresh-token configuration has an insecure
+   *                     (non-HTTPS) token endpoint.
+   */
+  constructor(auth, fetchFn = fetch) {
+    if ('refreshToken' in auth) {
+      assertSecureTokenEndpoint(auth.tokenEndpoint);
+    }
+    this.auth = auth;
+    this.fetchFn = fetchFn;
+  }
+
+  /**
+   * Returns a valid OAuth 2.0 access token, acquiring or refreshing it as
+   * needed.
+   *
+   * @param signal An optional {@link AbortSignal} to cancel token acquisition.
+   * @returns The current access token.
+   * @throws {SmtpAuthError} If a refresh-token exchange fails or returns an
+   *                         unexpected response.
+   */
+  async getAccessToken(signal) {
+    signal?.throwIfAborted();
+
+    const auth = this.auth;
+    if ('accessToken' in auth) {
+      return typeof auth.accessToken === 'function'
+        ? await abortable(Promise.resolve(auth.accessToken(signal)), signal)
+        : auth.accessToken;
+    }
+
+    const cached = this.cached;
+    if (cached != null && cached.expiresAt > Date.now()) {
+      return cached.accessToken;
+    }
+
+    // Coalesce concurrent refreshes so the token endpoint is hit at most once
+    // per token lifetime.  The shared request is not tied to any single caller's
+    // abort signal; each caller instead races it against its own signal so that
+    // one caller's cancellation cannot fail the others.
+    this.pending ??= this.refresh(auth)
+      .then((result) => {
+        // Populate the cache before `finally` clears `pending`, so a concurrent
+        // caller in the microtask gap finds the fresh token instead of starting
+        // a duplicate refresh.  Refresh slightly before expiry; cap the safety
+        // margin at half the lifetime so short-lived tokens are not treated as
+        // already expired (which would refresh on every connection).
+        const lifetimeMs = result.expiresIn * 1000;
+        const safetyMargin = Math.min(REFRESH_SAFETY_MARGIN_MS, lifetimeMs / 2);
+        this.cached = {
+          accessToken: result.accessToken,
+          expiresAt: Date.now() + lifetimeMs - safetyMargin,
+        };
+        return result;
+      })
+      .finally(() => {
+        this.pending = undefined;
+      });
+
+    const { accessToken } = await abortable(this.pending, signal);
+    return accessToken;
+  }
+
+  /**
+   * Exchanges the configured refresh token for a fresh access token.
+   *
+   * The request deliberately runs without a caller-specific abort signal; it is
+   * shared across concurrent callers, each of which applies its own
+   * cancellation separately (see {@link getAccessToken}).
+   *
+   * @param auth The refresh-token authentication configuration.
+   * @returns The new access token and its lifetime in seconds.
+   * @throws {SmtpAuthError} If the request fails or the response is invalid.
+   */
+  async refresh(auth) {
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      client_id: auth.clientId,
+      refresh_token: auth.refreshToken,
+    });
+    if (auth.clientSecret != null) body.set('client_secret', auth.clientSecret);
+    if (auth.scope != null) body.set('scope', auth.scope);
+
+    // Bound the request with an internal timeout so a stalled endpoint cannot
+    // leave the shared `pending` promise unresolved forever.
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+      controller.abort(new Error('OAuth 2.0 token request timed out'));
+    }, TOKEN_REQUEST_TIMEOUT_MS);
+
+    let response;
+    let text;
+    // Call through a local variable so the global `fetch` is not invoked as a
+    // method of this manager, which throws "Illegal invocation" in some
+    // runtimes (the native `fetch` requires a `globalThis`/undefined receiver).
+    const fetchFn = this.fetchFn;
+    try {
+      response = await fetchFn(auth.tokenEndpoint, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/x-www-form-urlencoded',
+          accept: 'application/json',
+        },
+        body,
+        signal: controller.signal,
+      });
+      // Read the body under the same timeout: an endpoint that returns headers
+      // but stalls on the body must not leave `pending` unresolved forever.
+      text = await response.text();
+    } catch (cause) {
+      throw new SmtpAuthError(
+        `Failed to request an OAuth 2.0 access token from ` +
+          `${auth.tokenEndpoint}: ` +
+          `${cause instanceof Error ? cause.message : String(cause)}`,
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    const safeText = truncateErrorBody(text);
+    if (!response.ok) {
+      throw new SmtpAuthError(
+        `OAuth 2.0 token endpoint responded with HTTP ${response.status}: ${safeText}`,
+      );
+    }
+
+    let json;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new SmtpAuthError(`OAuth 2.0 token endpoint returned a non-JSON response: ${safeText}`);
+    }
+
+    if (typeof json !== 'object' || json == null || typeof json.access_token !== 'string') {
+      throw new SmtpAuthError(
+        `OAuth 2.0 token endpoint response did not include an access_token: ${safeText}`,
+      );
+    }
+
+    const record = json;
+    // Accept `expires_in` only as a finite, non-negative number of seconds.
+    // Some providers send it as a numeric string; `Number()` (unlike
+    // `parseInt`) rejects partial parses like "100abc".  Negative, NaN, and
+    // Infinity values fall back to the default lifetime.
+    const rawExpiresIn = record.expires_in;
+    let parsedExpiresIn;
+    if (typeof rawExpiresIn === 'number') {
+      parsedExpiresIn = rawExpiresIn;
+    } else if (typeof rawExpiresIn === 'string' && rawExpiresIn.trim() !== '') {
+      parsedExpiresIn = Number(rawExpiresIn);
+    } else {
+      parsedExpiresIn = NaN;
+    }
+    const expiresIn =
+      Number.isFinite(parsedExpiresIn) && parsedExpiresIn >= 0
+        ? parsedExpiresIn
+        : DEFAULT_EXPIRES_IN;
+    return { accessToken: record.access_token, expiresIn };
+  }
+}
+
+module.exports = {
+  SmtpAuthError,
+  formatXoauth2,
+  formatOauthbearer,
+  selectOAuth2Mechanism,
+  OAuth2TokenManager,
+};
diff --git a/src/smtp/raw-message.js b/src/smtp/raw-message.js
new file mode 100644
index 0000000..d975d85
--- /dev/null
+++ b/src/smtp/raw-message.js
@@ -0,0 +1,63 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/raw-message.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { analyzeRawMessage, iterateRawMessage } = require('../core/raw-message.js');
+const { readAttachmentContent } = require('../core/attachment.js');
+
+/** Missing support for explicitly declared 8-bit MIME bodies. @since 0.6.0 */
+class Smtp8BitMimeUnsupportedError extends TypeError {
+  /** Creates an error for a server without 8BITMIME. */
+  constructor() {
+    super('SMTP server does not support 8BITMIME.');
+    this.name = 'Smtp8BitMimeUnsupportedError';
+  }
+}
+
+/** @internal */
+const prepareRawSmtpMessage = (plan, dsn) => {
+  return {
+    rawMessage: plan,
+    envelope: { ...plan.envelope, dsn },
+    requiresSmtpUtf8:
+      [plan.envelope.from ?? '', ...plan.envelope.to].some((address) =>
+        Array.from(address).some((character) => character.charCodeAt(0) > 127),
+      ) || plan.encoding === 'utf8',
+  };
+};
+
+/** @internal */
+const prepareRawSmtpStream = async (source, negotiate, checkSize, progress, signal) => {
+  let plan = source;
+  // Resolve promised bytes within the socket preparation timeout and reuse
+  // their identity for the transmission pass, without copying or composing.
+  if (plan.content instanceof Promise) {
+    const content = await readAttachmentContent(plan.content, signal);
+    plan = { ...plan, content, size: content.byteLength };
+    progress();
+  }
+  if (plan.size !== undefined) checkSize(plan.size);
+  const analysis =
+    plan.encoding === undefined
+      ? await analyzeRawMessage(plan, signal, (info) => {
+          progress();
+          negotiate(info.encoding);
+          checkSize(info.size);
+        })
+      : { size: plan.size, encoding: plan.encoding };
+  signal?.throwIfAborted();
+  negotiate(analysis.encoding);
+  return {
+    size: analysis.size,
+    // oxlint-disable-next-line no-shadow -- upstream
+    read(signal, progress) {
+      return iterateRawMessage(plan, {
+        signal,
+        encoding: analysis.encoding,
+        expectedSize: analysis.size,
+        onProgress: () => progress?.(),
+      });
+    },
+  };
+};
+
+module.exports = { Smtp8BitMimeUnsupportedError, prepareRawSmtpMessage, prepareRawSmtpStream };
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
new file mode 100644
index 0000000..b6278b2
--- /dev/null
+++ b/src/smtp/smtp-connection.js
@@ -0,0 +1,1245 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-connection.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { prepareRawSmtpStream, Smtp8BitMimeUnsupportedError } = require('./raw-message.js');
+const { Buffer } = require('node:buffer');
+const { Socket } = require('node:net');
+const { connect: tlsConnect, TLSSocket } = require('node:tls');
+const { createSmtpConfig } = require('./config.js');
+const { SmtpDsnUnsupportedError } = require('./delivery-status.js');
+const {
+  formatOauthbearer,
+  formatXoauth2,
+  OAuth2TokenManager,
+  selectOAuth2Mechanism,
+  SmtpAuthError,
+} = require('./oauth2.js');
+const { prepareMessageStream } = require('./message-stream.js');
+const { prepareOnSocket, writeMessageData } = require('./data-stream.js');
+const { parseEnhancedSmtpStatusCode } = require('./smtp-status-code.js');
+
+/**
+ * Error thrown when a message exceeds the fixed limit advertised through the
+ * SMTP SIZE extension.
+ *
+ * Known sizes are checked before `MAIL FROM`. Unknown source sizes are also
+ * checked while writing DATA; those failures make the connection unusable.
+ */
+class SmtpMessageSizeError extends RangeError {
+  /** Exact known size, or the octets counted when an unknown source is stopped. */
+  actualSize;
+
+  /** The fixed maximum advertised by the SMTP server. */
+  maximumSize;
+
+  /** Whether the failure occurred before or during DATA. */
+  phase;
+
+  /**
+   * Creates an SMTP message-size error.
+   *
+   * @param actualSize The encoded message size in octets.
+   * @param maximumSize The fixed maximum advertised by the SMTP server.
+   * @param phase Whether the failure occurred before or during DATA.
+   */
+  constructor(actualSize, maximumSize, phase = 'preflight') {
+    super(
+      `Message size ${actualSize} octets exceeds the server's maximum of ` +
+        `${maximumSize} octets.`,
+    );
+    this.phase = phase;
+    this.name = 'SmtpMessageSizeError';
+    this.actualSize = actualSize;
+    this.maximumSize = maximumSize;
+  }
+}
+
+/**
+ * Error thrown when an internationalized message requires an SMTP extension
+ * that the server did not advertise.
+ *
+ * The check happens before `MAIL FROM`, so the SMTP connection remains usable
+ * for another message.
+ */
+class SmtpUtf8UnsupportedError extends Error {
+  /** The required SMTP extension that the server did not advertise. */
+  missingCapability;
+
+  /**
+   * Creates an SMTPUTF8 support error.
+   *
+   * @param missingCapability The required extension that was not advertised.
+   */
+  constructor(missingCapability) {
+    super(
+      missingCapability === 'SMTPUTF8'
+        ? 'The SMTP server does not advertise SMTPUTF8.'
+        : // oxlint-disable-next-line no-useless-concat -- upstream
+          'The SMTP server advertises SMTPUTF8 without the required ' + '8BITMIME capability.',
+    );
+    this.name = 'SmtpUtf8UnsupportedError';
+    this.missingCapability = missingCapability;
+  }
+}
+
+class SmtpPipelineTerminatedError extends Error {
+  responseIndex;
+  response;
+
+  constructor(responseIndex, response) {
+    super('SMTP pipeline terminated by the server.');
+    this.name = 'SmtpPipelineTerminatedError';
+    this.responseIndex = responseIndex;
+    this.response = response;
+  }
+}
+
+/**
+ * An authentication failure backed by an SMTP server reply.
+ *
+ * This keeps {@link SmtpAuthError} as the public authentication error while
+ * retaining the reply fields needed to build structured transport receipts.
+ */
+class SmtpAuthResponseError extends SmtpAuthError {
+  /** The numeric SMTP reply code returned by the server. */
+  code;
+
+  /** The authentication command that produced the reply. */
+  command;
+
+  /** The textual SMTP reply returned by the server. */
+  response;
+
+  /**
+   * Creates an authentication response error.
+   *
+   * @param message A human-readable description of the authentication failure.
+   * @param code The numeric SMTP reply code.
+   * @param command The authentication command that produced the reply.
+   * @param response The textual SMTP reply returned by the server.
+   */
+  constructor(message, code, command, response) {
+    super(message);
+    this.name = 'SmtpAuthResponseError';
+    this.code = code;
+    this.command = command;
+    this.response = response;
+  }
+}
+
+/**
+ * The maximum length of an SMTP command line, including the terminating CRLF,
+ * as specified by RFC 5321 §4.5.3.1.4.
+ */
+const MAX_COMMAND_LINE_LENGTH = 512;
+
+/** The length of the CRLF terminator appended to every command. */
+const CRLF_LENGTH = 2;
+
+/**
+ * Finds the RFC 1870 SIZE extension and its optional fixed maximum.
+ *
+ * A zero maximum and an omitted maximum both mean that no fixed limit is in
+ * force.  A malformed parameter does not prevent use of the extension, but it
+ * cannot be used as a local limit.
+ *
+ * @param capabilities The extension lines returned by EHLO.
+ * @returns The SIZE capability, or `null` when it was not advertised.
+ */
+const parseSizeCapability = (capabilities) => {
+  const capability = capabilities.find((value) => /^SIZE(?:[ \t]|$)/i.test(value));
+  if (capability == null) return null;
+
+  const match = /^SIZE(?:[ \t]+([0-9]+))?[ \t]*$/i.exec(capability);
+  if (match?.[1] == null) return { maximum: null };
+
+  const maximum = BigInt(match[1]);
+  return { maximum: maximum === 0n ? null : maximum };
+};
+
+/**
+ * How long, in milliseconds, to wait for the graceful `QUIT` to flush during
+ * teardown before giving up, so an unresponsive server cannot block shutdown
+ * for the full socket timeout.
+ */
+const QUIT_TIMEOUT_MS = 5000;
+
+/**
+ * Parse an IPv4 address into its four octets.
+ *
+ * @param address The IPv4 address to parse.
+ * @returns The parsed octets, or `null` if the address is invalid.
+ */
+const parseIpv4Address = (address) => {
+  const octets = address.split('.');
+  if (
+    octets.length !== 4 ||
+    !octets.every((octet) => /^(?:0|[1-9]\d{0,2})$/.test(octet) && Number(octet) <= 255)
+  ) {
+    return null;
+  }
+
+  return octets.map(Number);
+};
+
+/**
+ * Parse an IPv6 address into its eight 16-bit groups.
+ *
+ * @param address The IPv6 address to parse.
+ * @returns The parsed groups, or `null` if the address is invalid.
+ */
+const parseIpv6Address = (address) => {
+  const compressionParts = address.split('::');
+  if (compressionParts.length > 2) return null;
+
+  const parseGroups = (part) => {
+    if (part === '') return [];
+
+    const tokens = part.split(':');
+    const groups = [];
+    for (const [index, token] of tokens.entries()) {
+      if (token.includes('.')) {
+        if (index !== tokens.length - 1) return null;
+        const octets = parseIpv4Address(token);
+        if (octets == null) return null;
+        groups.push((octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]);
+      } else if (/^[0-9a-f]{1,4}$/.test(token)) {
+        groups.push(Number.parseInt(token, 16));
+      } else {
+        return null;
+      }
+    }
+    return groups;
+  };
+
+  const left = parseGroups(compressionParts[0]);
+  const right = parseGroups(compressionParts[1] ?? '');
+  if (left == null || right == null) return null;
+
+  if (compressionParts.length === 1) {
+    return left.length === 8 ? left : null;
+  }
+
+  const omittedGroups = 8 - left.length - right.length;
+  if (omittedGroups < 1) return null;
+  return [...left, ...Array.from({ length: omittedGroups }, () => 0), ...right];
+};
+
+/**
+ * Whether an IP address refers to the local loopback interface.
+ *
+ * @param address The IPv4 or IPv6 address to check.
+ * @returns `true` if the address is a loopback address.
+ */
+const isLoopbackAddress = (address) => {
+  let normalized = address.toLowerCase();
+  if (normalized.startsWith('[') && normalized.endsWith(']')) {
+    normalized = normalized.slice(1, -1);
+  }
+  const zoneIndex = normalized.indexOf('%');
+  if (zoneIndex >= 0) normalized = normalized.slice(0, zoneIndex);
+
+  const ipv4Octets = parseIpv4Address(normalized);
+  if (ipv4Octets != null) return ipv4Octets[0] === 127;
+
+  const ipv6Groups = parseIpv6Address(normalized);
+  if (ipv6Groups == null) return false;
+  return (
+    (ipv6Groups.slice(0, 7).every((group) => group === 0) && ipv6Groups[7] === 1) ||
+    (ipv6Groups.slice(0, 5).every((group) => group === 0) &&
+      ipv6Groups[5] === 0xffff &&
+      ipv6Groups[6] >> 8 === 127)
+  );
+};
+
+/**
+ * Whether a configured host name or address represents a loopback endpoint.
+ *
+ * This is a fallback for sockets that do not expose their connected peer
+ * address.  A connected peer address takes precedence so a misleading host
+ * name cannot bypass the TLS requirement.
+ *
+ * @param host The configured SMTP host.
+ * @returns `true` if the host represents a loopback endpoint.
+ */
+const isLoopbackHost = (host) => {
+  const normalized = host.toLowerCase().replace(/\.$/, '');
+  return (
+    normalized === 'localhost' || normalized.endsWith('.localhost') || isLoopbackAddress(normalized)
+  );
+};
+
+/**
+ * Whether the SMTP connection is local enough to permit cleartext
+ * authentication during development.
+ *
+ * @param socket The connected SMTP socket, if available.
+ * @param host The configured SMTP host.
+ * @returns `true` if the connected peer or fallback host is loopback.
+ */
+const isLoopbackConnection = (socket, host) => {
+  const remoteAddress = socket?.remoteAddress;
+  return remoteAddress == null ? isLoopbackHost(host) : isLoopbackAddress(remoteAddress);
+};
+
+class SmtpConnection {
+  socket = null;
+  config;
+  authenticated = false;
+  capabilities = [];
+  tokenManager;
+  active = false;
+
+  get usable() {
+    return this.socket != null && !this.socket.destroyed && this.socket.writable;
+  }
+
+  observeSocket(socket) {
+    socket.on('error', () => socket.destroy());
+    socket.on('timeout', () => {
+      if (!this.active) socket.destroy();
+    });
+  }
+
+  constructor(config, tokenManager) {
+    this.config = createSmtpConfig(config);
+    this.tokenManager = tokenManager ?? null;
+  }
+
+  connect(signal) {
+    if (this.socket) {
+      throw new Error('Connection already established');
+    }
+
+    signal?.throwIfAborted();
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        onError(new TypeError('Connection timeout.'));
+        this.socket?.destroy();
+      }, this.config.connectionTimeout);
+
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.socket?.off('connect', onConnect);
+        this.socket?.off('error', onError);
+        this.socket?.off('close', onClose);
+        this.socket?.off('timeout', onTimeout);
+        signal?.removeEventListener('abort', onAbort);
+      };
+
+      const onAbort = () => {
+        cleanup();
+        this.socket?.destroy();
+        reject(signal?.reason);
+      };
+
+      const onConnect = () => {
+        cleanup();
+        resolve();
+      };
+
+      const onError = (error) => {
+        cleanup();
+        reject(error);
+      };
+      const onClose = () => {
+        onError(new TypeError('SMTP connection closed before establishment.'));
+      };
+      const onTimeout = () => {
+        onError(new TypeError('Socket timeout.'));
+        this.socket?.destroy();
+      };
+
+      try {
+        if (this.config.secure) {
+          this.socket = tlsConnect({
+            host: this.config.host,
+            port: this.config.port,
+            rejectUnauthorized: this.config.tls?.rejectUnauthorized ?? true,
+            ca: this.config.tls?.ca,
+            key: this.config.tls?.key,
+            cert: this.config.tls?.cert,
+            minVersion: this.config.tls?.minVersion,
+            maxVersion: this.config.tls?.maxVersion,
+          });
+        } else {
+          this.socket = new Socket();
+          this.socket.connect(this.config.port, this.config.host);
+        }
+
+        this.socket.setTimeout(this.config.socketTimeout);
+        this.observeSocket(this.socket);
+        this.socket.once('connect', onConnect);
+        this.socket.once('error', onError);
+        this.socket.once('close', onClose);
+        this.socket.once('timeout', onTimeout);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted) onAbort();
+      } catch (error) {
+        cleanup();
+        this.socket?.destroy();
+        reject(error);
+      }
+    });
+  }
+
+  sendCommand(command, signal) {
+    return this.sendCommands([command], signal).then((responses) => responses[0]);
+  }
+
+  /**
+   * Sends a group of commands in one write and reads one reply per command.
+   *
+   * SMTP multiline replies are kept together and complete replies are matched
+   * to commands by their position in the returned array, as required for
+   * command pipelining by RFC 2920.
+   */
+  sendCommands(commands, signal) {
+    if (!this.socket) {
+      throw new Error('Not connected');
+    }
+
+    signal?.throwIfAborted();
+
+    return new Promise((resolve, reject) => {
+      let buffer = '';
+      let responseLines = [];
+      const responses = [];
+      const startTimeout = () =>
+        setTimeout(() => {
+          cleanup();
+          reject(new Error('Command timeout'));
+        }, this.config.socketTimeout);
+      let timeout = startTimeout();
+      const resetTimeout = () => {
+        clearTimeout(timeout);
+        timeout = startTimeout();
+      };
+
+      const onData = (data) => {
+        buffer += data.toString();
+        const lines = buffer.split('\r\n');
+
+        // Keep incomplete line in buffer
+        const incompleteLine = lines.pop() || '';
+
+        for (const [lineIndex, line] of lines.entries()) {
+          responseLines.push(line);
+          if (line.length >= 4 && line[3] === ' ') {
+            const code = parseInt(line.substring(0, 3), 10);
+            const message = line.substring(4);
+            const response = {
+              code,
+              message,
+              raw: responseLines.join('\r\n'),
+            };
+            const responseIndex = responses.length;
+            responses.push(response);
+            responseLines = [];
+
+            if (responses.length === commands.length) {
+              cleanup();
+              if (
+                commands[0] === 'DATA' &&
+                (lineIndex + 1 < lines.length || incompleteLine.length > 0)
+              ) {
+                this.socket?.destroy();
+                reject(new TypeError('Premature SMTP reply after DATA readiness.'));
+                return;
+              }
+              resolve(responses);
+              return;
+            }
+
+            if (response.code === 421) {
+              cleanup();
+              reject(new SmtpPipelineTerminatedError(responseIndex, response));
+              return;
+            }
+
+            resetTimeout();
+          }
+        }
+
+        // Update buffer with incomplete line
+        buffer = incompleteLine;
+      };
+
+      const onError = (error) => {
+        cleanup();
+        reject(error);
+      };
+
+      const onClose = () => {
+        cleanup();
+        const responseIndex = responses.findIndex(
+          (response, index) => response.code === 421 || (index === 0 && response.code >= 400),
+        );
+        if (responseIndex >= 0) {
+          reject(new SmtpPipelineTerminatedError(responseIndex, responses[responseIndex]));
+          return;
+        }
+        const completedFailures = responses.flatMap((response, index) =>
+          response.code >= 400 ? [`${commands[index]}: ${response.code} ${response.message}`] : [],
+        );
+        const failureDetails =
+          completedFailures.length > 0
+            ? ` Completed failures: ${completedFailures.join('; ')}.`
+            : '';
+        reject(new Error(`Connection closed before all command responses.${failureDetails}`));
+      };
+
+      const onAbort = () => {
+        cleanup();
+        try {
+          signal?.throwIfAborted();
+        } catch (error) {
+          reject(error);
+        }
+      };
+
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.socket?.off('data', onData);
+        this.socket?.off('error', onError);
+        this.socket?.off('close', onClose);
+        signal?.removeEventListener('abort', onAbort);
+      };
+
+      this.socket.on('data', onData);
+      this.socket.on('error', onError);
+      this.socket.on('close', onClose);
+      signal?.addEventListener('abort', onAbort, { once: true });
+      this.socket.write(commands.map((command) => `${command}\r\n`).join(''));
+    });
+  }
+
+  greeting(signal) {
+    if (!this.socket) {
+      throw new Error('Not connected');
+    }
+
+    signal?.throwIfAborted();
+
+    return new Promise((resolve, reject) => {
+      let buffer = '';
+      const timeout = setTimeout(() => {
+        onError(new Error('Greeting timeout.'));
+      }, this.config.socketTimeout);
+
+      const onData = (data) => {
+        buffer += data.toString();
+        const lines = buffer.split('\r\n');
+
+        for (const line of lines) {
+          if (line.length >= 4 && line[3] === ' ') {
+            const code = parseInt(line.substring(0, 3), 10);
+            const message = line.substring(4);
+
+            cleanup();
+            resolve({ code, message, raw: buffer });
+            return;
+          }
+        }
+      };
+
+      const onError = (error) => {
+        cleanup();
+        reject(error);
+      };
+
+      const onClose = () => onError(new TypeError('SMTP connection closed before greeting.'));
+      const onAbort = () => {
+        cleanup();
+        this.socket?.destroy();
+        reject(signal?.reason);
+      };
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.socket?.off('data', onData);
+        this.socket?.off('error', onError);
+        this.socket?.off('close', onClose);
+        signal?.removeEventListener('abort', onAbort);
+      };
+
+      this.socket.on('data', onData);
+      this.socket.on('error', onError);
+      this.socket.on('close', onClose);
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+    });
+  }
+
+  async ehlo(signal) {
+    const response = await this.sendCommand(`EHLO ${this.config.localName}`, signal);
+    if (response.code === 500 || response.code === 502) {
+      const heloResponse = await this.sendCommand(`HELO ${this.config.localName}`, signal);
+      if (heloResponse.code !== 250) {
+        throw new SmtpResponseError(
+          `HELO failed: ${heloResponse.message}`,
+          heloResponse.code,
+          'HELO',
+          heloResponse.message,
+        );
+      }
+      this.capabilities = [];
+      return;
+    }
+    if (response.code !== 250) {
+      throw new SmtpResponseError(
+        `EHLO failed: ${response.message}`,
+        response.code,
+        'EHLO',
+        response.message,
+      );
+    }
+
+    // Parse capabilities
+    this.capabilities = response.raw
+      .split('\r\n')
+      .filter((line) => line.startsWith('250-') || line.startsWith('250 '))
+      .slice(1)
+      .map((line) => line.substring(4))
+      .filter((line) => line.length > 0);
+  }
+
+  async starttls(signal) {
+    if (!this.socket) {
+      throw new Error('Not connected');
+    }
+
+    if (this.socket instanceof TLSSocket) {
+      throw new Error('Connection is already using TLS');
+    }
+
+    signal?.throwIfAborted();
+
+    // Send STARTTLS command
+    const response = await this.sendCommand('STARTTLS', signal);
+    if (response.code !== 220) {
+      throw new SmtpResponseError(
+        `STARTTLS failed: ${response.message}`,
+        response.code,
+        'STARTTLS',
+        response.message,
+      );
+    }
+
+    signal?.throwIfAborted();
+
+    // Own the upgraded socket throughout its handshake, including cancellation.
+    const plainSocket = this.socket;
+    plainSocket.setTimeout(0);
+    const tlsSocket = tlsConnect({
+      socket: plainSocket,
+      host: this.config.host,
+      rejectUnauthorized: this.config.tls?.rejectUnauthorized ?? true,
+      ca: this.config.tls?.ca,
+      key: this.config.tls?.key,
+      cert: this.config.tls?.cert,
+      minVersion: this.config.tls?.minVersion,
+      maxVersion: this.config.tls?.maxVersion,
+    });
+    this.socket = tlsSocket;
+    this.observeSocket(tlsSocket);
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(
+        () => fail(new Error('STARTTLS upgrade timeout.')),
+        this.config.connectionTimeout,
+      );
+      const cleanup = () => {
+        clearTimeout(timeout);
+        tlsSocket.off('secureConnect', onSecureConnect);
+        tlsSocket.off('error', fail);
+        tlsSocket.off('close', onClose);
+        signal?.removeEventListener('abort', onAbort);
+      };
+      const fail = (error) => {
+        cleanup();
+        tlsSocket.destroy();
+        reject(error);
+      };
+      const onAbort = () => fail(signal?.reason);
+      // Node's TLSSocket reports a peer that leaves during the handshake as an
+      // error before the close, so this guard does not run on Node.
+      /* c8 ignore next */
+      const onClose = () => fail(new TypeError('SMTP connection closed during STARTTLS.'));
+      const onSecureConnect = () => {
+        cleanup();
+        tlsSocket.setTimeout(this.config.socketTimeout);
+        resolve();
+      };
+      tlsSocket.once('secureConnect', onSecureConnect);
+      tlsSocket.once('error', fail);
+      tlsSocket.once('close', onClose);
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+    });
+  }
+
+  async authenticate(signal) {
+    const auth = this.config.auth;
+    if (!auth) {
+      return;
+    }
+
+    if (this.authenticated) {
+      return;
+    }
+
+    if (!this.capabilities.some((cap) => cap.toUpperCase().startsWith('AUTH'))) {
+      throw new SmtpAuthError('Server does not support authentication.');
+    }
+
+    // Refuse to send credentials over a cleartext connection.  Loopback hosts
+    // are excepted for local testing and development.
+    if (
+      !(this.socket instanceof TLSSocket) &&
+      !isLoopbackConnection(this.socket, this.config.host)
+    ) {
+      throw new SmtpAuthError(
+        'SMTP authentication requires a TLS-secured connection to protect ' +
+          'credentials; use `secure: true` or STARTTLS.',
+      );
+    }
+
+    if ('accessToken' in auth || 'refreshToken' in auth) {
+      const mechanism = auth.method ?? selectOAuth2Mechanism(this.capabilities);
+      switch (mechanism) {
+        case 'xoauth2':
+          await this.authXoauth2(auth, signal);
+          break;
+        case 'oauthbearer':
+          await this.authOauthbearer(auth, signal);
+          break;
+        default:
+          throw new SmtpAuthError(`Unsupported authentication method: ${mechanism}`);
+      }
+    } else {
+      const method = auth.method ?? 'plain';
+      switch (method) {
+        case 'plain':
+          await this.authPlain(auth, signal);
+          break;
+        case 'login':
+          await this.authLogin(auth, signal);
+          break;
+        default:
+          throw new Error(`Unsupported authentication method: ${method}`);
+      }
+    }
+
+    this.authenticated = true;
+  }
+
+  async authPlain(auth, signal) {
+    const { user, pass } = auth;
+    const credentials = btoa(`\0${user}\0${pass}`);
+    const response = await this.sendCommand(`AUTH PLAIN ${credentials}`, signal);
+
+    if (response.code !== 235) {
+      throw new SmtpAuthResponseError(
+        `Authentication failed: ${response.message}`,
+        response.code,
+        'AUTH PLAIN',
+        response.message,
+      );
+    }
+  }
+
+  async authLogin(auth, signal) {
+    const { user, pass } = auth;
+
+    let response = await this.sendCommand('AUTH LOGIN', signal);
+    if (response.code !== 334) {
+      throw new SmtpAuthResponseError(
+        `AUTH LOGIN failed: ${response.message}`,
+        response.code,
+        'AUTH LOGIN',
+        response.message,
+      );
+    }
+
+    response = await this.sendCommand(btoa(user), signal);
+    if (response.code !== 334) {
+      throw new SmtpAuthResponseError(
+        `Username authentication failed: ${response.message}`,
+        response.code,
+        'AUTH LOGIN',
+        response.message,
+      );
+    }
+
+    response = await this.sendCommand(btoa(pass), signal);
+    if (response.code !== 235) {
+      throw new SmtpAuthResponseError(
+        `Password authentication failed: ${response.message}`,
+        response.code,
+        'AUTH LOGIN',
+        response.message,
+      );
+    }
+  }
+
+  /**
+   * Resolves an OAuth 2.0 access token via the connection's token manager,
+   * creating a standalone manager from the auth config if none was injected.
+   */
+  async getOAuth2Token(auth, signal) {
+    this.tokenManager ??= new OAuth2TokenManager(auth);
+    return await this.tokenManager.getAccessToken(signal);
+  }
+
+  async authXoauth2(auth, signal) {
+    const token = await this.getOAuth2Token(auth, signal);
+    const initialResponse = formatXoauth2(auth.user, token);
+    const response = await this.sendSaslAuth('XOAUTH2', initialResponse, signal);
+    // On failure XOAUTH2 servers send a 334 challenge; the client replies with
+    // an empty line to receive the final failure response.
+    await this.finishOAuth2(response, 'XOAUTH2', '', signal);
+  }
+
+  async authOauthbearer(auth, signal) {
+    const token = await this.getOAuth2Token(auth, signal);
+    const initialResponse = formatOauthbearer(auth.user, token, this.config.host, this.config.port);
+    const response = await this.sendSaslAuth('OAUTHBEARER', initialResponse, signal);
+    // RFC 7628: on failure the client replies with a single 0x01 ("AQ==") to
+    // receive the final failure response.
+    await this.finishOAuth2(response, 'OAUTHBEARER', 'AQ==', signal);
+  }
+
+  /**
+   * Sends a SASL `AUTH` command with its Base64 initial response.
+   *
+   * When the resulting command line would exceed the SMTP command-line length
+   * limit (e.g. a long Outlook JWT access token), RFC 4954 requires the client
+   * to omit the initial response and send it on its own line after the server's
+   * `334` challenge.  This method transparently falls back to that two-step
+   * form, since some servers reject the over-long single-line command outright.
+   *
+   * @param mechanism The SASL mechanism name (e.g. `XOAUTH2`).
+   * @param initialResponse The Base64-encoded initial client response.
+   * @param signal An optional {@link AbortSignal}.
+   * @returns The server's response to the initial response.
+   */
+  async sendSaslAuth(mechanism, initialResponse, signal) {
+    const inlineCommand = `AUTH ${mechanism} ${initialResponse}`;
+    if (inlineCommand.length + CRLF_LENGTH <= MAX_COMMAND_LINE_LENGTH) {
+      return await this.sendCommand(inlineCommand, signal);
+    }
+
+    const challenge = await this.sendCommand(`AUTH ${mechanism}`, signal);
+    if (challenge.code !== 334) {
+      return challenge;
+    }
+    return await this.sendCommand(initialResponse, signal);
+  }
+
+  /**
+   * Interprets the server's reply to an OAuth SASL initial response, draining
+   * the failure challenge continuation when authentication is rejected.
+   *
+   * @throws {SmtpAuthError} If authentication did not succeed.
+   */
+  async finishOAuth2(response, mechanism, continuation, signal) {
+    if (response.code === 235) {
+      return;
+    }
+    if (response.code === 334) {
+      let finalResponse;
+      let finalMessage = '';
+      try {
+        finalResponse = await this.sendCommand(continuation, signal);
+        finalMessage = ` (${finalResponse.message})`;
+      } catch {
+        // Some servers close the connection after rejecting authentication, so
+        // sending the continuation fails; keep the decoded challenge as the
+        // error detail rather than masking it with a socket error.
+        signal?.throwIfAborted();
+      }
+      const message =
+        `${mechanism} authentication failed: ` +
+        `${decodeOAuth2Challenge(response.message)}${finalMessage}`;
+      if (finalResponse != null) {
+        throw new SmtpAuthResponseError(
+          message,
+          finalResponse.code,
+          `AUTH ${mechanism}`,
+          finalResponse.message,
+        );
+      }
+      throw new SmtpAuthError(message);
+    }
+    throw new SmtpAuthResponseError(
+      `${mechanism} authentication failed: ${response.message}`,
+      response.code,
+      `AUTH ${mechanism}`,
+      response.message,
+    );
+  }
+
+  async sendMessage(message, signal) {
+    this.active = true;
+    this.socket?.setTimeout(0);
+    try {
+      return await this.sendPreparedMessage(message, signal);
+    } finally {
+      this.active = false;
+      if (this.usable) this.socket?.setTimeout(this.config.socketTimeout);
+    }
+  }
+
+  async sendPreparedMessage(message, signal) {
+    signal?.throwIfAborted();
+
+    let smtpUtf8Parameters = '';
+    const negotiate = (encoding) => {
+      const supports = (name) =>
+        this.capabilities.some((capability) =>
+          new RegExp(`^${name}(?:[ \t]|$)`, 'i').test(capability),
+        );
+      if (message.requiresSmtpUtf8 || encoding === 'utf8') {
+        if (!supports('SMTPUTF8')) {
+          throw new SmtpUtf8UnsupportedError('SMTPUTF8');
+        }
+        if (!supports('8BITMIME')) {
+          throw new SmtpUtf8UnsupportedError('8BITMIME');
+        }
+        smtpUtf8Parameters = ' BODY=8BITMIME SMTPUTF8';
+      } else if (encoding === '8bit') {
+        if (!supports('8BITMIME')) throw new Smtp8BitMimeUnsupportedError();
+        smtpUtf8Parameters = ' BODY=8BITMIME';
+      }
+    };
+    negotiate('rawMessage' in message ? message.rawMessage.encoding : undefined);
+
+    const sizeCapability = parseSizeCapability(this.capabilities);
+    let sizeParameter = '';
+
+    const dsn = message.envelope.dsn;
+    if (dsn != null && !this.capabilities.some((capability) => /^DSN[ \t]*$/i.test(capability))) {
+      throw new SmtpDsnUnsupportedError();
+    }
+    const mailDsnParameters =
+      dsn == null || dsn.mailParameters.length === 0 ? '' : ` ${dsn.mailParameters.join(' ')}`;
+
+    const checkSize = (size, phase = 'preflight') => {
+      if (!Number.isSafeInteger(size)) {
+        throw new RangeError('Message size exceeds the safe integer range.');
+      }
+      if (sizeCapability?.maximum != null && BigInt(size) > sizeCapability.maximum) {
+        throw new SmtpMessageSizeError(size, sizeCapability.maximum, phase);
+      }
+    };
+    if (!this.socket || !this.usable) {
+      throw new TypeError('SMTP connection is closed.');
+    }
+    const stream =
+      'rawMessage' in message
+        ? await prepareOnSocket(
+            this.socket,
+            this.config.socketTimeout,
+            // oxlint-disable-next-line no-shadow -- upstream
+            (signal, progress) =>
+              prepareRawSmtpStream(message.rawMessage, negotiate, checkSize, progress, signal),
+            signal,
+          )
+        : 'raw' in message
+          ? {
+              size: Buffer.byteLength(message.raw) + 2,
+              // oxlint-disable-next-line no-shadow -- upstream
+              async *read(signal) {
+                signal?.throwIfAborted();
+                yield Buffer.from(message.raw + '\r\n');
+              },
+            }
+          : await prepareOnSocket(
+              this.socket,
+              this.config.socketTimeout,
+              // oxlint-disable-next-line no-shadow -- upstream
+              (signal, progress) => prepareMessageStream(message, checkSize, progress, signal),
+              signal,
+            );
+    negotiate(stream.encoding);
+    if (stream.size != null) {
+      checkSize(stream.size);
+      if (sizeCapability != null) sizeParameter = ` SIZE=${stream.size}`;
+    }
+
+    const mailCommand =
+      `MAIL FROM:<${message.envelope.from ?? ''}>` +
+      `${sizeParameter}${smtpUtf8Parameters}${mailDsnParameters}`;
+    const recipientCommands = message.envelope.to.map((recipient, index) => {
+      const parameters = dsn?.recipientParameters[index] ?? [];
+      const suffix = parameters.length === 0 ? '' : ` ${parameters.join(' ')}`;
+      return `RCPT TO:<${recipient}>${suffix}`;
+    });
+    const pipelining = this.capabilities.some((capability) =>
+      /^PIPELINING(?:\s|$)/i.test(capability),
+    );
+
+    let mailResponse;
+    let recipientResponses;
+    if (pipelining) {
+      try {
+        const envelopeResponses = await this.sendCommands(
+          [mailCommand, ...recipientCommands],
+          signal,
+        );
+        mailResponse = envelopeResponses[0];
+        recipientResponses = envelopeResponses.slice(1);
+      } catch (error) {
+        if (!(error instanceof SmtpPipelineTerminatedError)) {
+          throw error;
+        }
+
+        const { response, responseIndex } = error;
+        if (responseIndex === 0) {
+          throw new SmtpResponseError(
+            `MAIL FROM failed: ${response.message}`,
+            response.code,
+            'MAIL FROM',
+            response.message,
+          );
+        }
+
+        const recipient = message.envelope.to[responseIndex - 1];
+        throw new SmtpResponseError(
+          `RCPT TO failed for ${recipient}: ${response.message}`,
+          response.code,
+          'RCPT TO',
+          response.message,
+        );
+      }
+    } else {
+      mailResponse = await this.sendCommand(mailCommand, signal);
+      recipientResponses = [];
+    }
+
+    if (mailResponse.code !== 250) {
+      throw new SmtpResponseError(
+        `MAIL FROM failed: ${mailResponse.message}`,
+        mailResponse.code,
+        'MAIL FROM',
+        mailResponse.message,
+      );
+    }
+
+    // RCPT TO
+    const rejectedRecipients = [];
+    for (const [index, recipient] of message.envelope.to.entries()) {
+      signal?.throwIfAborted();
+      const rcptResponse = pipelining
+        ? recipientResponses[index]
+        : await this.sendCommand(recipientCommands[index], signal);
+      if (rcptResponse.code === 421) {
+        throw new SmtpResponseError(
+          `RCPT TO failed for ${recipient}: ${rcptResponse.message}`,
+          rcptResponse.code,
+          'RCPT TO',
+          rcptResponse.message,
+        );
+      }
+      if (rcptResponse.code !== 250 && rcptResponse.code !== 251) {
+        const enhancedStatusCode = parseEnhancedSmtpStatusCode(
+          rcptResponse.code,
+          rcptResponse.message,
+        );
+        rejectedRecipients.push({
+          recipient,
+          code: rcptResponse.code,
+          response: rcptResponse.message,
+          retryable: rcptResponse.code >= 400 && rcptResponse.code < 500,
+          ...(enhancedStatusCode == null ? {} : { enhancedStatusCode }),
+        });
+      }
+    }
+
+    if (rejectedRecipients.length > 0 && rejectedRecipients.length === message.envelope.to.length) {
+      const rejection = rejectedRecipients.find((item) => item.retryable) ?? rejectedRecipients[0];
+      const details = rejectedRecipients
+        .map((item) => `${item.recipient}: ${item.code} ${item.response}`)
+        .join('; ');
+      throw new SmtpResponseError(
+        `RCPT TO failed for every recipient: ${details}`,
+        rejection.code,
+        'RCPT TO',
+        rejection.response,
+        rejectedRecipients,
+      );
+    }
+
+    // DATA
+    const dataResponse = await this.sendCommand('DATA', signal);
+    if (dataResponse.code !== 354) {
+      throw new SmtpResponseError(
+        `DATA failed: ${dataResponse.message}`,
+        dataResponse.code,
+        'DATA',
+        dataResponse.message,
+      );
+    }
+
+    // Message content
+    const finalResponse = await writeMessageData(
+      this.socket,
+      // oxlint-disable-next-line no-shadow -- upstream
+      (signal, progress) => stream.read(signal, progress),
+      this.config.socketTimeout,
+      (size) => checkSize(size, 'data'),
+      signal,
+    );
+    if (finalResponse.code !== 250) {
+      throw new SmtpResponseError(
+        `Message send failed: ${finalResponse.message}`,
+        finalResponse.code,
+        'DATA_END',
+        finalResponse.message,
+      );
+    }
+
+    // Extract message ID from response
+    const messageId = this.extractMessageId(finalResponse.message);
+    return { messageId, rejectedRecipients };
+  }
+
+  extractMessageId(response) {
+    const match = response.match(/(?:Message-ID:|id=)[\s<]*([^>\s]+)/i);
+    return match ? match[1] : `smtp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  async quit(signal) {
+    const socket = this.socket;
+    if (!socket) {
+      return;
+    }
+
+    // Only attempt a graceful QUIT on a writable socket; a socket that never
+    // finished connecting (e.g. a refused or timed-out connection) would
+    // otherwise error or leave a dangling command timeout.
+    if (socket.writable && !signal?.aborted) {
+      // Send QUIT best-effort and wait only until it has been flushed (bounded
+      // by QUIT_TIMEOUT_MS) rather than for the server's reply, so an
+      // unresponsive server cannot block teardown for the full socket timeout.
+      await new Promise((resolve) => {
+        const done = () => {
+          clearTimeout(timer);
+          socket.off('error', done);
+          socket.off('close', done);
+          signal?.removeEventListener('abort', onAbort);
+          resolve();
+        };
+        const onAbort = () => {
+          socket.destroy();
+          done();
+        };
+        const timer = setTimeout(done, QUIT_TIMEOUT_MS);
+        // Teardown is best-effort: an asynchronous socket error or close must
+        // not surface as an unhandled error event, so settle on those too.
+        socket.once('error', done);
+        socket.once('close', done);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted) {
+          onAbort();
+          return;
+        }
+        try {
+          socket.write('QUIT\r\n', done);
+        } catch {
+          done();
+        }
+      });
+    }
+
+    try {
+      socket.destroy();
+    } catch {
+      // Ignore errors while tearing down the socket
+    }
+    this.socket = null;
+    this.authenticated = false;
+    this.capabilities = [];
+  }
+
+  async reset(signal) {
+    if (!this.socket) {
+      throw new Error('Not connected');
+    }
+
+    const response = await this.sendCommand('RSET', signal);
+    if (response.code !== 250) {
+      throw new Error(`RESET failed: ${response.message}`);
+    }
+  }
+}
+
+/**
+ * Error thrown when an SMTP command receives an unsuccessful server reply.
+ */
+class SmtpResponseError extends Error {
+  /**
+   * The numeric SMTP reply code returned by the server.
+   */
+  code;
+
+  /**
+   * The SMTP command that produced the reply.
+   */
+  command;
+
+  /**
+   * The textual SMTP reply returned by the server.
+   */
+  response;
+
+  /** Recipient-level failures collected for an unsuccessful transaction. */
+  rejectedRecipients;
+
+  /**
+   * Creates an SMTP response error.
+   *
+   * @param message Human-readable error message.
+   * @param code The numeric SMTP reply code.
+   * @param command The SMTP command that produced the reply.
+   * @param response The textual SMTP reply returned by the server.
+   * @param rejectedRecipients Recipient-level failures collected for the
+   *                           transaction.
+   */
+  constructor(message, code, command, response, rejectedRecipients) {
+    super(message);
+    this.name = 'SmtpResponseError';
+    this.code = code;
+    this.command = command;
+    this.response = response;
+    this.rejectedRecipients = rejectedRecipients;
+  }
+}
+
+/**
+ * Decodes the Base64 JSON error challenge a server sends after a failed OAuth
+ * SASL exchange, falling back to the raw message when it is not valid Base64.
+ *
+ * The bytes are decoded as UTF-8 (via `TextDecoder`) so non-ASCII challenge
+ * messages are not corrupted, unlike decoding `atob`'s Latin-1 output directly.
+ *
+ * @param message The challenge text from the server's 334 response.
+ * @returns A human-readable description of the failure.
+ */
+const decodeOAuth2Challenge = (message) => {
+  try {
+    const binary = atob(message.trim());
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return message;
+  }
+};
+
+module.exports = {
+  SmtpMessageSizeError,
+  SmtpUtf8UnsupportedError,
+  SmtpAuthResponseError,
+  SmtpConnection,
+  SmtpResponseError,
+};
diff --git a/src/smtp/smtp-receipt.js b/src/smtp/smtp-receipt.js
new file mode 100644
index 0000000..9352258
--- /dev/null
+++ b/src/smtp/smtp-receipt.js
@@ -0,0 +1,21 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-receipt.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Checks whether provider details came from an SMTP server response.
+ *
+ * @param value Provider details from an SMTP receipt error.
+ * @returns Whether the value contains SMTP response details.
+ */
+const isSmtpResponseProviderDetails = (value) => {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    'command' in value &&
+    typeof value.command === 'string' &&
+    'response' in value &&
+    typeof value.response === 'string'
+  );
+};
+
+module.exports = { isSmtpResponseProviderDetails };
diff --git a/src/smtp/smtp-status-code.js b/src/smtp/smtp-status-code.js
new file mode 100644
index 0000000..1bcbf3f
--- /dev/null
+++ b/src/smtp/smtp-status-code.js
@@ -0,0 +1,31 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-status-code.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Parses an enhanced SMTP status code from the beginning of reply text.
+ *
+ * RFC 2034 requires the enhanced class to agree with the three-digit SMTP
+ * reply class.  RFC 3463 also prohibits leading zeroes and limits the subject
+ * and detail fields to three digits.
+ *
+ * @param replyCode The three-digit SMTP reply code.
+ * @param response The textual part of the SMTP reply.
+ * @returns The parsed enhanced status code, or `undefined` when the reply does
+ *          not begin with a valid, consistent code.
+ */
+const parseEnhancedSmtpStatusCode = (replyCode, response) => {
+  const match = /^([245])\.((?:0|[1-9][0-9]{0,2}))\.((?:0|[1-9][0-9]{0,2})) +/.exec(response);
+  if (match == null) return undefined;
+
+  const statusClass = Number(match[1]);
+  if (Math.trunc(replyCode / 100) !== statusClass) return undefined;
+
+  return {
+    code: `${match[1]}.${match[2]}.${match[3]}`,
+    class: statusClass,
+    subject: Number(match[2]),
+    detail: Number(match[3]),
+  };
+};
+
+module.exports = { parseEnhancedSmtpStatusCode };
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
new file mode 100644
index 0000000..d2d74bb
--- /dev/null
+++ b/src/smtp/smtp-transport.js
@@ -0,0 +1,913 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { prepareRawSmtpMessage, Smtp8BitMimeUnsupportedError } = require('./raw-message.js');
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createRawMessagePlan, RawMessageValidationError } = require('../core/raw-message.js');
+const {
+  resolveSmtpDsn,
+  SmtpDsnUnsupportedError,
+  SmtpDsnValidationError,
+} = require('./delivery-status.js');
+const {
+  SmtpAuthResponseError,
+  SmtpConnection,
+  SmtpMessageSizeError,
+  SmtpResponseError,
+  SmtpUtf8UnsupportedError,
+} = require('./smtp-connection.js');
+const { resolveSmtpEnvelope, SmtpEnvelopeValidationError } = require('./envelope.js');
+const { OAuth2TokenManager } = require('./oauth2.js');
+const { prepareMessage } = require('./message-converter.js');
+const { SmtpAttachmentReplayError } = require('./message-stream.js');
+const { validateDkimBodyMode } = require('../mime/dkim/types.js');
+const { parseEnhancedSmtpStatusCode } = require('./smtp-status-code.js');
+
+/**
+ * SMTP transport implementation for sending emails via SMTP protocol.
+ *
+ * This transport provides efficient email delivery with connection pooling,
+ * support for authentication, TLS/SSL encryption, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { SmtpTransport } from '@alexify/mailer/smtp';
+ *
+ * // Automatic resource cleanup with using statement
+ * await using transport = new SmtpTransport({
+ *   host: 'smtp.gmail.com',
+ *   port: 465,
+ *   secure: true, // Use TLS from start
+ *   auth: {
+ *     user: 'user@gmail.com',
+ *     pass: 'app-password'
+ *   }
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * // Connections are automatically closed here
+ *
+ * // Or manual management
+ * const transport2 = new SmtpTransport(config);
+ * try {
+ *   await transport2.send(message);
+ * } finally {
+ *   await transport2.closeAllConnections();
+ * }
+ * ```
+ */
+class SmtpTransport {
+  id = 'smtp';
+
+  /**
+   * The SMTP configuration used by this transport.
+   */
+  config;
+
+  /**
+   * The maximum number of SMTP connections this transport may have open at
+   * once.  The limit covers connections that are being established,
+   * connections that are currently sending, and idle connections retained for
+   * reuse, so it holds whether or not pooling is enabled.  A caller that needs
+   * a connection while the limit is reached waits until one becomes available.
+   * `Infinity` leaves the number of connections unbounded.
+   */
+  poolSize;
+
+  /**
+   * Idle connections retained for reuse.  Every connection in here also counts
+   * towards {@link openConnectionCount}, so the pool can never grow past
+   * {@link poolSize}.
+   */
+  connectionPool = [];
+
+  /**
+   * The number of connections this transport currently owns: connections being
+   * established, connections checked out by a caller, and idle connections in
+   * {@link connectionPool}.  Never exceeds {@link poolSize}.
+   */
+  openConnectionCount = 0;
+
+  /**
+   * Callers waiting for a connection to become available, in arrival order.
+   */
+  capacityWaiters = [];
+
+  /** The current shutdown barrier; new callers wait until it completes. */
+  closing;
+  pendingAcquisitions = 0;
+  onDrained;
+
+  /**
+   * A token manager shared across all pooled connections, present only when the
+   * configured authentication uses OAuth 2.0.  Sharing it ensures the
+   * refresh-token exchange happens at most once per token lifetime instead of
+   * once per connection.
+   */
+  tokenManager;
+
+  /**
+   * Creates a new SMTP transport instance.
+   *
+   * @param config SMTP configuration including server details, authentication,
+   *               and options.
+   * @throws {RangeError} If `config.poolSize` is neither a positive integer nor
+   *                        `Infinity`.
+   */
+  constructor(config) {
+    validateDkimBodyMode(config.dkim);
+    this.config = config;
+    const poolSize = config.poolSize ?? 5;
+    if (
+      Number.isNaN(poolSize) ||
+      poolSize < 1 ||
+      (Number.isFinite(poolSize) && !Number.isInteger(poolSize))
+    ) {
+      throw new RangeError(`poolSize must be a positive integer or Infinity: ${poolSize}`);
+    }
+    this.poolSize = poolSize;
+    const auth = config.auth;
+    this.tokenManager =
+      auth != null && ('accessToken' in auth || 'refreshToken' in auth)
+        ? new OAuth2TokenManager(auth)
+        : undefined;
+  }
+
+  /**
+   * Checks a fresh SMTP connection, TLS policy, and configured authentication
+   * without sending mail. Uses the shared connection limit and closes the
+   * verification connection afterward, even when pooling is enabled.
+   * Success does not guarantee acceptance of a sender, recipient, or message.
+   * @param options Optional cancellation signal, including while waiting for capacity.
+   * @returns A promise that resolves after successful verification and cleanup.
+   * @throws {SmtpResponseError} If greeting, EHLO/HELO, or STARTTLS is rejected.
+   * @throws {SmtpAuthError} If authentication fails.
+   * @throws {Error} If a connection, TLS, or timeout error occurs.
+   * @throws The caller's abort reason if cancelled.
+   */
+  async verify(options) {
+    const signal = options?.signal;
+    signal?.throwIfAborted();
+    let connection;
+    try {
+      connection = await this.getConnection(signal, true);
+      signal?.throwIfAborted();
+    } catch (error) {
+      signal?.throwIfAborted();
+      throw error;
+    } finally {
+      if (connection != null) await this.discardConnection(connection, signal);
+    }
+    signal?.throwIfAborted();
+  }
+
+  /**
+   * Sends a single email message via SMTP.
+   *
+   * This method converts the message to SMTP format, establishes a connection
+   * to the SMTP server, sends the message, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' }
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent with ID:', receipt.messageId);
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional SMTP envelope, delivery status, and cancellation
+   *                settings.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   * @throws {DOMException} If the operation is aborted through
+   *                        `options.signal`.
+   */
+  async send(message, options) {
+    options?.signal?.throwIfAborted();
+
+    let connection;
+
+    try {
+      const envelope = resolveEnvelopeOption(message, options?.envelope, 0);
+      const dsn = resolveSmtpDsn(envelope, options?.dsn);
+
+      // Establishing the connection—including authentication, e.g. acquiring an
+      // OAuth 2.0 access token—is part of delivery, so setup failures are
+      // reported as a failed receipt rather than thrown.  (Cancellation via the
+      // abort signal still rejects: an already-aborted signal is caught by the
+      // guard above, before this method does any work.)
+      connection = await this.getConnection(options?.signal);
+
+      options?.signal?.throwIfAborted();
+
+      const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
+
+      options?.signal?.throwIfAborted();
+
+      const result = await connection.sendMessage(smtpMessage, options?.signal);
+
+      await this.returnConnection(connection);
+      // Cleared so the catch below cannot hand the same connection back twice.
+      connection = undefined;
+
+      return {
+        successful: true,
+        messageId: result.messageId,
+        provider: 'smtp',
+        rejectedRecipients: result.rejectedRecipients,
+      };
+    } catch (error) {
+      if (connection != null) {
+        if (connection.usable && isReusableLocalFailure(error)) {
+          await this.returnConnection(connection);
+        } else {
+          await this.discardConnection(connection);
+        }
+      }
+
+      // Cancellation rejects rather than producing a receipt.
+      options?.signal?.throwIfAborted();
+
+      return createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+    }
+  }
+
+  /**
+   * Delivers serialized MIME unchanged, apart from SMTP dot-stuffing.
+   * Configured DKIM signing and message composition are bypassed.
+   * @param message Original MIME bytes and explicit delivery envelope.
+   * @param options Optional DSN and cancellation settings.
+   * @returns An SMTP receipt, including any rejected recipients.
+   * @throws {Error} If cancellation is requested.
+   */
+  async sendRaw(message, options) {
+    if (message?.content instanceof Promise) message.content.catch(() => {});
+    options?.signal?.throwIfAborted();
+    let connection;
+    try {
+      const plan = createRawMessagePlan(message);
+      if (options?.envelope !== undefined) {
+        throw new SmtpEnvelopeValidationError('Raw message envelopes cannot be overridden.');
+      }
+      const dsn = resolveSmtpDsn(plan.envelope, options?.dsn);
+      connection = await this.getConnection(options?.signal);
+      const result = await connection.sendMessage(
+        prepareRawSmtpMessage(plan, dsn),
+        options?.signal,
+      );
+      await this.returnConnection(connection);
+      connection = undefined;
+      return {
+        successful: true,
+        provider: 'smtp',
+        messageId: result.messageId,
+        rejectedRecipients: result.rejectedRecipients,
+      };
+    } catch (error) {
+      if (connection != null) {
+        if (connection.usable && isReusableLocalFailure(error)) {
+          await this.returnConnection(connection);
+        } else {
+          await this.discardConnection(connection);
+        }
+      }
+      options?.signal?.throwIfAborted();
+      return createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+    }
+  }
+
+  /**
+   * Sends multiple email messages efficiently using a single SMTP connection.
+   *
+   * This method is optimized for bulk email sending by reusing a single SMTP
+   * connection for all messages, which significantly improves performance
+   * compared to sending each message individually.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   { subject: 'Message 1', recipients: [{ address: 'user1@example.com' }], ... },
+   *   { subject: 'Message 2', recipients: [{ address: 'user2@example.com' }], ... }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional SMTP envelope, delivery status, and cancellation
+   *                settings.
+   * @returns An async iterable of receipts, one for each message.
+   * @throws {DOMException} If the operation is aborted through
+   *                        `options.signal`.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    let connection;
+    try {
+      connection = await this.getConnection(options?.signal);
+    } catch (error) {
+      // Cancellation rejects rather than producing receipts.
+      options?.signal?.throwIfAborted();
+
+      // Connection setup (including authentication) failed, so no message can
+      // be delivered.  Report a failed receipt for each message rather than
+      // throwing.
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      // oxlint-disable-next-line no-unused-vars -- upstream
+      for await (const _ of messages) {
+        options?.signal?.throwIfAborted();
+        yield createSmtpFailure(errorMessage, error);
+      }
+      return;
+    }
+
+    let connectionValid = true;
+    let connectionReleased = false;
+
+    const releaseConnection = async () => {
+      if (connectionReleased) return;
+      connectionReleased = true;
+      if (connectionValid) {
+        await this.returnConnection(connection);
+      } else {
+        await this.discardConnection(connection);
+      }
+    };
+
+    try {
+      const isAsyncIterable = Symbol.asyncIterator in messages;
+
+      if (isAsyncIterable) {
+        let index = 0;
+        for await (const message of messages) {
+          options?.signal?.throwIfAborted();
+
+          if (!connectionValid) {
+            yield createSmtpFailure('Connection is no longer valid');
+            continue;
+          }
+
+          try {
+            const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
+            const dsn = resolveSmtpDsn(envelope, options?.dsn);
+            const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
+            options?.signal?.throwIfAborted();
+
+            const result = await connection.sendMessage(smtpMessage, options?.signal);
+
+            yield {
+              successful: true,
+              messageId: result.messageId,
+              provider: 'smtp',
+              rejectedRecipients: result.rejectedRecipients,
+            };
+          } catch (error) {
+            // Cancellation rejects rather than producing a receipt.
+            options?.signal?.throwIfAborted();
+
+            if (!connection.usable || !isReusableLocalFailure(error)) {
+              connectionValid = false;
+            }
+
+            yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+          }
+        }
+      } else {
+        let index = 0;
+        for (const message of messages) {
+          options?.signal?.throwIfAborted();
+
+          if (!connectionValid) {
+            yield createSmtpFailure('Connection is no longer valid');
+            continue;
+          }
+
+          try {
+            const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
+            const dsn = resolveSmtpDsn(envelope, options?.dsn);
+            const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
+            options?.signal?.throwIfAborted();
+
+            const result = await connection.sendMessage(smtpMessage, options?.signal);
+
+            yield {
+              successful: true,
+              messageId: result.messageId,
+              provider: 'smtp',
+              rejectedRecipients: result.rejectedRecipients,
+            };
+          } catch (error) {
+            // Cancellation rejects rather than producing a receipt.
+            options?.signal?.throwIfAborted();
+
+            if (!connection.usable || !isReusableLocalFailure(error)) {
+              connectionValid = false;
+            }
+
+            yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+          }
+        }
+      }
+    } catch (error) {
+      // Error during iteration setup or while reading the messages
+      connectionValid = false;
+      throw error;
+    } finally {
+      // Runs on normal completion, on error, and when the consumer abandons
+      // the iteration early with `break` or `return`.  Without it an abandoned
+      // iteration would hold its connection slot forever.
+      await releaseConnection();
+    }
+  }
+
+  /**
+   * Checks out a connection, waiting when {@link poolSize} connections are
+   * already open.  The returned connection holds one of those slots until it is
+   * handed back through {@link returnConnection} or {@link discardConnection}.
+   *
+   * @param signal Signal that cancels the wait for a free connection.
+   * @param fresh Whether setup must run on a new connection.
+   * @returns A connection ready to send.
+   * @throws {DOMException} If `signal` is aborted before a connection is
+   *                        obtained.
+   */
+  async getConnection(signal, fresh = false) {
+    signal?.throwIfAborted();
+    while (this.closing != null) {
+      await this.waitForShutdown(this.closing, signal);
+      signal?.throwIfAborted();
+    }
+    this.pendingAcquisitions++;
+    try {
+      return await this.acquireConnection(signal, fresh);
+    } finally {
+      this.pendingAcquisitions--;
+      this.notifyDrained();
+    }
+  }
+
+  waitForShutdown(closing, signal) {
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        signal?.removeEventListener('abort', onAbort);
+        reject(signal?.reason);
+      };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      // oxlint-disable-next-line promise/always-return -- upstream
+      closing.then(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+      });
+    });
+  }
+
+  notifyDrained() {
+    if (this.openConnectionCount === 0 && this.pendingAcquisitions === 0) {
+      this.onDrained?.();
+    }
+  }
+
+  async acquireConnection(signal, fresh = false) {
+    while (true) {
+      signal?.throwIfAborted();
+      if (fresh && this.openConnectionCount >= this.poolSize) {
+        const idle = this.connectionPool.pop();
+        if (idle != null) {
+          // Transfer this slot without waking a competing acquisition.
+          await this.closeConnection(idle, signal);
+          return await this.setupReservedConnection(signal);
+        }
+      }
+      // Reuse an idle connection when the pool has one.  It already holds a
+      // slot, so nothing else needs to be reserved.
+      let pooled = fresh ? undefined : this.connectionPool.pop();
+      while (pooled != null) {
+        if (pooled.usable) return pooled;
+        // Dropping a connection that went stale in the pool frees its slot.
+        await this.discardConnection(pooled);
+        pooled = this.connectionPool.pop();
+      }
+
+      if (this.openConnectionCount < this.poolSize) {
+        // Reserve the slot before connecting so that connections still being
+        // established count towards the limit.
+        this.openConnectionCount++;
+        return await this.setupReservedConnection(signal);
+      }
+
+      // Every slot is taken, so wait for one to come back.
+      await this.waitForCapacity(signal);
+      try {
+        signal?.throwIfAborted();
+      } catch (error) {
+        // This caller consumed a wake-up it can no longer use; pass it on so
+        // that a waiter behind it is not stranded.
+        this.wakeCapacityWaiter();
+        throw error;
+      }
+    }
+  }
+
+  /** Establishes a connection using a slot already owned by this acquisition. */
+  async setupReservedConnection(signal) {
+    let connection;
+    try {
+      signal?.throwIfAborted();
+      connection = new SmtpConnection(this.config, this.tokenManager);
+      await this.connectAndSetup(connection, signal);
+      signal?.throwIfAborted();
+      return connection;
+    } catch (error) {
+      if (connection != null) await this.closeConnection(connection, signal);
+      this.releaseConnectionSlot();
+      throw error;
+    }
+  }
+
+  /**
+   * Waits until {@link wakeCapacityWaiter} reports that a connection or a free
+   * slot may be available.
+   *
+   * @param signal Signal that cancels the wait.
+   * @returns A promise that resolves when the caller should retry.
+   * @throws {DOMException} If `signal` is aborted while waiting.
+   */
+  waitForCapacity(signal) {
+    return new Promise((resolve, reject) => {
+      const waiters = this.capacityWaiters;
+      const onAbort = () => {
+        // Dropping the waiter from the queue before rejecting keeps it from
+        // consuming a wake-up meant for someone still waiting.
+        const index = waiters.indexOf(waiter);
+        if (index >= 0) waiters.splice(index, 1);
+        waiter.reject(signal?.reason);
+      };
+      const waiter = {
+        resolve: () => {
+          signal?.removeEventListener('abort', onAbort);
+          resolve();
+        },
+        reject: (reason) => {
+          signal?.removeEventListener('abort', onAbort);
+          reject(reason);
+        },
+      };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      waiters.push(waiter);
+    });
+  }
+
+  /** Wakes the caller that has been waiting longest, if there is one. */
+  wakeCapacityWaiter() {
+    this.capacityWaiters.shift()?.resolve();
+  }
+
+  /**
+   * Gives up the slot held by a connection that is no longer open, letting a
+   * waiting caller take its place.
+   */
+  releaseConnectionSlot() {
+    this.openConnectionCount--;
+    this.wakeCapacityWaiter();
+    this.notifyDrained();
+  }
+
+  async connectAndSetup(connection, signal) {
+    signal?.throwIfAborted();
+
+    await connection.connect(signal);
+
+    signal?.throwIfAborted();
+
+    // Wait for server greeting
+    const greeting = await connection.greeting(signal);
+    if (greeting.code !== 220) {
+      throw new SmtpResponseError(
+        `Server greeting failed: ${greeting.message}`,
+        greeting.code,
+        'GREETING',
+        greeting.message,
+      );
+    }
+
+    signal?.throwIfAborted();
+
+    // Send EHLO
+    await connection.ehlo(signal);
+
+    signal?.throwIfAborted();
+
+    // Perform STARTTLS for plaintext connections when either the server
+    // advertises it or the caller requires it.  A required upgrade is attempted
+    // even without the capability so STARTTLS stripping fails closed.
+    if (
+      connection.config.secure === false &&
+      (connection.config.requireTls === true ||
+        connection.capabilities.some((cap) => cap.toUpperCase().startsWith('STARTTLS')))
+    ) {
+      await connection.starttls(signal);
+
+      signal?.throwIfAborted();
+
+      // RFC 3207: Client SHOULD send EHLO after successful TLS negotiation
+      // to get updated capabilities (including AUTH)
+      await connection.ehlo(signal);
+
+      signal?.throwIfAborted();
+    }
+
+    // Authenticate if needed
+    await connection.authenticate(signal);
+  }
+
+  /**
+   * Hands a connection back after a successful send, either retaining it for
+   * reuse or closing it.  Either way the slot it occupies is passed on to a
+   * waiting caller.
+   */
+  async returnConnection(connection) {
+    if (!connection.usable || !connection.config.pool || this.closing != null) {
+      await this.discardConnection(connection);
+      return;
+    }
+
+    try {
+      await connection.reset();
+    } catch {
+      // A connection that cannot be reset is not safe to reuse.
+      await this.discardConnection(connection);
+      return;
+    }
+
+    // Shutdown may have started while RSET was awaiting its reply.
+    if (this.closing != null) {
+      await this.discardConnection(connection);
+      return;
+    }
+
+    // The connection keeps its slot while it sits idle, so no separate check
+    // against `poolSize` is needed here: at most `poolSize` connections can be
+    // checked out at once, hence at most `poolSize` can ever be returned.
+    this.connectionPool.push(connection);
+    this.wakeCapacityWaiter();
+  }
+
+  /**
+   * Closes a connection without giving up the caller's reserved slot.
+   */
+  async closeConnection(connection, signal) {
+    try {
+      await connection.quit(signal);
+    } catch {
+      // Ignore errors during cleanup
+    }
+  }
+
+  /** Closes a connection and releases its slot exactly once. */
+  async discardConnection(connection, signal) {
+    await this.closeConnection(connection, signal);
+    this.releaseConnectionSlot();
+  }
+
+  /**
+   * Closes idle connections and drains sends and verification admitted before
+   * this call.
+   *
+   * Resolves once those sends have released their connections and all their
+   * sockets have closed.  Delivery is not interrupted, including sends waiting
+   * for capacity or connection setup.  A started `sendMany()` iteration must
+   * finish or be returned by its consumer before shutdown can complete.
+   *
+   * Concurrent close calls share the shutdown. New sends and verification wait for it to
+   * finish (and can cancel that wait through their abort signal); the transport
+   * can be reused afterward.
+   *
+   * @returns A promise that resolves after the admitted work is drained.
+   *
+   * @example
+   * ```typescript
+   * // At application shutdown
+   * await transport.closeAllConnections();
+   * ```
+   */
+  async closeAllConnections() {
+    if (this.closing != null) return this.closing;
+
+    let drained;
+    const shutdown = new Promise((resolve) => {
+      drained = resolve;
+    });
+    this.onDrained = drained;
+    // oxlint-disable-next-line promise/always-return -- upstream
+    this.closing = shutdown.then(() => {
+      this.onDrained = undefined;
+      this.closing = undefined;
+    });
+    const closing = this.closing;
+    const connections = this.connectionPool;
+    this.connectionPool = [];
+
+    // Slots remain reserved until their sockets close.  Previously admitted
+    // capacity waiters may then send, but must discard their connections too.
+    await Promise.all(connections.map((connection) => this.discardConnection(connection)));
+    this.notifyDrained();
+    await closing;
+  }
+
+  /**
+   * Implements AsyncDisposable interface for automatic resource cleanup.
+   *
+   * This method is called automatically when using the `using` keyword,
+   * ensuring that all SMTP connections are properly closed when the
+   * transport goes out of scope.  Like {@link closeAllConnections}, it waits
+   * for admitted sends and started batch iterations to release their connections.
+   *
+   * @example
+   * ```typescript
+   * // Automatic cleanup with using statement
+   * await using transport = new SmtpTransport(config);
+   * await transport.send(message);
+   * // Connections are automatically closed here
+   * ```
+   */
+  async [Symbol.asyncDispose]() {
+    await this.closeAllConnections();
+  }
+}
+
+const createSmtpFailure = (message, error) => {
+  if (error instanceof RawMessageValidationError) {
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      category: 'validation',
+      retryable: false,
+      attempts: 1,
+      code: error.field === 'envelope' ? 'smtp.envelope-invalid' : 'smtp.raw-message-invalid',
+    });
+  }
+  if (error instanceof Smtp8BitMimeUnsupportedError) {
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      category: 'configuration',
+      retryable: false,
+      attempts: 1,
+      code: 'smtp.8bitmime-unsupported',
+      providerDetails: { missingCapability: '8BITMIME' },
+    });
+  }
+  if (error instanceof SmtpEnvelopeValidationError) {
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      code: 'smtp.envelope-invalid',
+      category: 'validation',
+      retryable: false,
+      attempts: 1,
+    });
+  }
+
+  if (error instanceof SmtpDsnValidationError) {
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      code: 'smtp.dsn-invalid',
+      category: 'validation',
+      retryable: false,
+      attempts: 1,
+    });
+  }
+
+  if (error instanceof SmtpDsnUnsupportedError) {
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      code: 'smtp.dsn-unsupported',
+      category: 'configuration',
+      retryable: false,
+      attempts: 1,
+    });
+  }
+
+  if (error instanceof SmtpAttachmentReplayError) {
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      code: 'smtp.attachment-replay-mismatch',
+      category: 'validation',
+      retryable: false,
+      attempts: 1,
+    });
+  }
+
+  if (error instanceof SmtpMessageSizeError) {
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      code: 'smtp.message-size-exceeded',
+      category: 'rejected',
+      retryable: false,
+      attempts: 1,
+      providerDetails: {
+        actualSize: error.actualSize,
+        maximumSize: error.maximumSize.toString(),
+      },
+    });
+  }
+
+  if (error instanceof SmtpUtf8UnsupportedError) {
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      code: 'smtp.smtputf8-unsupported',
+      category: 'configuration',
+      retryable: false,
+      attempts: 1,
+      providerDetails: {
+        missingCapability: error.missingCapability,
+      },
+    });
+  }
+
+  if (error instanceof SmtpResponseError || error instanceof SmtpAuthResponseError) {
+    const enhancedStatusCode = parseEnhancedSmtpStatusCode(error.code, error.response);
+    const classification = classifySmtpReply(error.code, enhancedStatusCode);
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      code: `smtp.${error.code}`,
+      category: classification.category,
+      retryable: classification.retryable,
+      attempts: 1,
+      providerDetails: {
+        command: error.command,
+        response: error.response,
+        rejectedRecipients:
+          error instanceof SmtpResponseError ? error.rejectedRecipients : undefined,
+        ...(enhancedStatusCode == null ? {} : { enhancedStatusCode }),
+      },
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'smtp',
+    attempts: 1,
+  });
+};
+
+const isReusableLocalFailure = (error) => {
+  return (
+    (error instanceof SmtpMessageSizeError && error.phase === 'preflight') ||
+    error instanceof SmtpUtf8UnsupportedError ||
+    error instanceof Smtp8BitMimeUnsupportedError ||
+    error instanceof RawMessageValidationError ||
+    error instanceof SmtpEnvelopeValidationError ||
+    error instanceof SmtpDsnValidationError ||
+    error instanceof SmtpDsnUnsupportedError
+  );
+};
+
+const resolveEnvelopeOption = (message, option, index) => {
+  let override;
+  if (typeof option === 'function') {
+    try {
+      override = option(message, index);
+    } catch (error) {
+      const failure = new SmtpEnvelopeValidationError(
+        `SMTP envelope resolver failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      failure.cause = error;
+      throw failure;
+    }
+  } else {
+    override = option;
+  }
+  return resolveSmtpEnvelope(message, override);
+};
+
+const classifySmtpReply = (code, enhancedStatusCode) => {
+  const retryable =
+    enhancedStatusCode == null ? code >= 400 && code < 500 : enhancedStatusCode.class === 4;
+
+  if (enhancedStatusCode?.subject === 1 || enhancedStatusCode?.subject === 6) {
+    return { category: 'validation', retryable };
+  }
+  if (enhancedStatusCode?.subject === 4) {
+    return { category: 'network', retryable };
+  }
+  if (code >= 400 && code < 500) {
+    return { category: 'service-unavailable', retryable };
+  }
+  if (code >= 500 && code < 600) {
+    return { category: 'rejected', retryable };
+  }
+  return { category: 'unknown', retryable: false };
+};
+
+module.exports = { SmtpTransport };
diff --git a/tests/e2e/smtp-transport.oauth2.e2e.test.js b/tests/e2e/smtp-transport.oauth2.e2e.test.js
new file mode 100644
index 0000000..14ef92b
--- /dev/null
+++ b/tests/e2e/smtp-transport.oauth2.e2e.test.js
@@ -0,0 +1,56 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-transport.oauth2.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { SmtpTransport } = require('../../src/smtp/smtp-transport.js');
+const {
+  createTestMessage,
+  getOAuth2TestConfig,
+  isOAuth2TestingEnabled,
+} = require('../helpers/smtp/test-config.js');
+
+// These tests run against a real OAuth 2.0-enabled SMTP server (e.g. Gmail or
+// Outlook).  They are skipped unless the SMTP_OAUTH2_* environment variables
+// are configured.  See packages/smtp/README.md for the required variables and
+// how to mint a token with google-auth-library / msal-node.
+describe('SmtpTransport OAuth 2.0 E2E', { skip: !isOAuth2TestingEnabled() }, () => {
+  if (!isOAuth2TestingEnabled()) return;
+
+  test('sends a real message authenticated via OAuth 2.0', async () => {
+    const { smtp, from, to } = getOAuth2TestConfig();
+    const transport = new SmtpTransport(smtp);
+    try {
+      const receipt = await transport.send(
+        createTestMessage({ senderEmail: from, recipientEmail: to }),
+      );
+      assert.ok(
+        receipt.successful,
+        receipt.successful ? undefined : receipt.errorMessages.join('; '),
+      );
+    } finally {
+      await transport.closeAllConnections();
+    }
+  });
+
+  test('reuses a cached token across multiple sends', async (t) => {
+    const { smtp, from, to, usesRefreshFlow } = getOAuth2TestConfig();
+    if (!usesRefreshFlow) {
+      t.skip('requires refresh-token auth to exercise token caching');
+      return;
+    }
+    const transport = new SmtpTransport(smtp);
+    try {
+      const first = await transport.send(
+        createTestMessage({ senderEmail: from, recipientEmail: to }),
+      );
+      const second = await transport.send(
+        createTestMessage({ senderEmail: from, recipientEmail: to }),
+      );
+      assert.ok(first.successful);
+      assert.ok(second.successful);
+    } finally {
+      await transport.closeAllConnections();
+    }
+  });
+});
diff --git a/tests/fixtures/smtp/README.md b/tests/fixtures/smtp/README.md
new file mode 100644
index 0000000..71f5a18
--- /dev/null
+++ b/tests/fixtures/smtp/README.md
@@ -0,0 +1,8 @@
+<!-- Ported from upyo v0.7.0 (packages/smtp/test-certs/README.md) -->
+
+SMTP test certificate
+=====================
+
+These files are public test fixtures for a TLS-enabled local Mailpit instance.
+The private key is intentionally committed and must never be used outside the
+test environment.
diff --git a/tests/fixtures/smtp/server-cert.pem b/tests/fixtures/smtp/server-cert.pem
new file mode 100644
index 0000000..2a9ff9d
--- /dev/null
+++ b/tests/fixtures/smtp/server-cert.pem
@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDXTCCAkWgAwIBAgIUC2KLaz0XIylbnu0EPhBpmu8/xiEwDQYJKoZIhvcNAQEL
+BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MCAXDTI2MDgyNzA4NDIwNFoYDzIxMjYw
+ODAzMDg0MjA0WjAUMRIwEAYDVQQDDAlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEB
+AQUAA4IBDwAwggEKAoIBAQCqNgoqaoK/hCH3BT9TeS2qxBjX18I1oBDEM2LuwI61
+5Nt0QPicVYzW9pYeISfGgcBE4gDhszGvN+6gGAO/sdmzXlqPLupDeuV++RyjVSFl
+FJphN+MYVedaFeIzmY+5ryxtYl4BJBOKNdxpcgte1dgRLEjT5VRCoUxgFgGYZa6P
+L5zglnEHiU6Girt+7Xl3hbUMM2p1BvkNoUluD4BCgHeeJwoF+eNBMiXpJRhqH3HP
+JosYNgZSpnsqEzeqRSjWk8aV+UwMfbFA8gXGDMuyyGSxmNrPKg+gM2SEc4UPJccL
+e0AzKj3YSjKWfiSbmsAZcIPIXh7c+t/4Qi49Dzhck5DPAgMBAAGjgaQwgaEwHQYD
+VR0OBBYEFJQBDujZ2gM/Bap24gLADAE2o9+JMB8GA1UdIwQYMBaAFJQBDujZ2gM/
+Bap24gLADAE2o9+JMCwGA1UdEQQlMCOCCWxvY2FsaG9zdIcEfwAAAYcQAAAAAAAA
+AAAAAAAAAAAAATAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIFoDATBgNVHSUE
+DDAKBggrBgEFBQcDATANBgkqhkiG9w0BAQsFAAOCAQEAFvFR5h+b5m1XabfxKjuH
++MCHqK0IrHYnVZynwNQeQnRT/W2PU6NwA67Z7WejN0jBv1Ph16vsBYo8ckPtyeEL
+oQbgTlLdzGETbWvNv0ShuKVWeyR8mvQW+RKDqsIsXMsPxFinn9W11tzrR03YcjUD
+9SiOv8dqN3RtigJJ2d9QqrQZoQ0b+LryesnAEjSEJH2pE7JwUSwBN4qlwed82QEA
+m2rMWDKzBce+QMil/XD2jMQwucsEH5O/MIc3Ox1kzgBDyTIWm/PaJxSCJYSANIjw
+T5FB/XkXWnCcO759y5I2RLz2r0XphqbTnbPtkrqZ7aqoCoWvrinIbOaaNyV+IRUF
+8w==
+-----END CERTIFICATE-----
diff --git a/tests/fixtures/smtp/server-key.pem b/tests/fixtures/smtp/server-key.pem
new file mode 100644
index 0000000..288599c
--- /dev/null
+++ b/tests/fixtures/smtp/server-key.pem
@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCqNgoqaoK/hCH3
+BT9TeS2qxBjX18I1oBDEM2LuwI615Nt0QPicVYzW9pYeISfGgcBE4gDhszGvN+6g
+GAO/sdmzXlqPLupDeuV++RyjVSFlFJphN+MYVedaFeIzmY+5ryxtYl4BJBOKNdxp
+cgte1dgRLEjT5VRCoUxgFgGYZa6PL5zglnEHiU6Girt+7Xl3hbUMM2p1BvkNoUlu
+D4BCgHeeJwoF+eNBMiXpJRhqH3HPJosYNgZSpnsqEzeqRSjWk8aV+UwMfbFA8gXG
+DMuyyGSxmNrPKg+gM2SEc4UPJccLe0AzKj3YSjKWfiSbmsAZcIPIXh7c+t/4Qi49
+Dzhck5DPAgMBAAECggEAAcMrjp9CZbK25BXYekgNu5KRroNfvhG1j6gLeez/VKsy
+2IGnQBskqTfBaBVNuXmSOWu/VjR2b+OqtzOREcE/GDvbI1e0SLe9FNCtbTHTRIB5
+Jh/avul9txj1SzWO8ziCw5kuBv86SLhqR3uIKP4G15XBTKxe8CtesLs8D9cWnDD9
+2LK988qOBA/7zJoluLtKIGj3Iff5cjBFByCTKBKR9V97Z5GoUOB+dWtLFSnccFWY
+54LapDGnXBavadhsXWbTO5uTr0ElL0/5imBXz4i7dp246JDYAaWCxgEbXm4SsW3O
+Cez9Dx+uJy8IyHbAgGc3gTalsFrr8GXTkiqiZeffAQKBgQDuhzpYuJBwgBGUlWpZ
+WmhhKHmwDE1D3h+HYy9ncVwC36WWWUmWe1xRr9DI8Y2Bw858soirJRwPc0e8C/ql
+JbKG1XEBp2X6tmgt4oR5noCZrq+QaFJBl9jL8bME1PZ5DH3jttIH8MTLBTjv5Kzl
+oxbwfKItvKwVlp5bHX7Sra8/zwKBgQC2rcKUkvpVQNjiFn+1pDaG6yJqjnCnLhN5
+DXLNVp8Y7oqtVSQTOkb3rPdQrVXMczjT5T0bdfq48kiO7yE9vwcrxKNQZKJsLcnQ
+u8aG6biNHGD9KGmwrrvMt2ubbyOiv42AVwsnVmc/+jkaQ3W1hPOeidK6/QzgbqRu
+cOb38YHfAQKBgQCeCd7wtaiNwWzkg3LpLOuHpCesKxpuYxeEvoTEBumtxbyStyn4
+mFd8j/7HhLP7TF7dY/UFYBsNaZYX0+AH18hHadfr/puk14KDFFgttIUETidoiJYn
+e5Ja3hN8mhWL8mjenVzfgfkBgr5Mw7iCleI3CHzzzNQ/oYHeYNaMhCNfJQKBgE/c
+AlZFMp6WbLnZsBbOJPAyVqdSgbj0EZs339oYZhDWJ1XDBLRLI78epDdmrz1jmZI4
+gtBAcUzszf9+Vn/RxObDXcnFVKQKGFHh5NYR0pYNs/C3/Aw7Nuo1vRsEKQX6y3cx
+ljSqNxTm5JOwrgKejoneInuQKFLsy4FkZfQ6ZdYBAoGBAIWidb2aBSzwNvyqsLSE
+ld/sIMSUZs55elni/PYIVoVsucwi64RAf2Yp9CqxM2dY2B/tOaU8ZM8Ih7UBzpwG
+syOX7b1HHQ92Vc1Oq0qRkqh+FaAmCNfuitU+YvoRSXUkwoS4bAJgt7vUUZyVUBrY
+k2/wS0OnfGTaP+Ycq4Mz5+9S
+-----END PRIVATE KEY-----
diff --git a/tests/helpers/smtp/dkim-test-keys.js b/tests/helpers/smtp/dkim-test-keys.js
new file mode 100644
index 0000000..900dab7
--- /dev/null
+++ b/tests/helpers/smtp/dkim-test-keys.js
@@ -0,0 +1,105 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/test-utils/dkim-test-keys.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Test key pairs for DKIM signing tests.
+ *
+ * WARNING: These keys are for testing purposes only.
+ * Never use these keys in production environments.
+ */
+
+// =============================================================================
+// RSA Keys (2048-bit)
+// =============================================================================
+
+/**
+ * Test RSA private key in PKCS#8 PEM format (2048-bit).
+ * For testing DKIM signing functionality only.
+ */
+const TEST_DKIM_PRIVATE_KEY = `-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCqNgoqaoK/hCH3
+BT9TeS2qxBjX18I1oBDEM2LuwI615Nt0QPicVYzW9pYeISfGgcBE4gDhszGvN+6g
+GAO/sdmzXlqPLupDeuV++RyjVSFlFJphN+MYVedaFeIzmY+5ryxtYl4BJBOKNdxp
+cgte1dgRLEjT5VRCoUxgFgGYZa6PL5zglnEHiU6Girt+7Xl3hbUMM2p1BvkNoUlu
+D4BCgHeeJwoF+eNBMiXpJRhqH3HPJosYNgZSpnsqEzeqRSjWk8aV+UwMfbFA8gXG
+DMuyyGSxmNrPKg+gM2SEc4UPJccLe0AzKj3YSjKWfiSbmsAZcIPIXh7c+t/4Qi49
+Dzhck5DPAgMBAAECggEAAcMrjp9CZbK25BXYekgNu5KRroNfvhG1j6gLeez/VKsy
+2IGnQBskqTfBaBVNuXmSOWu/VjR2b+OqtzOREcE/GDvbI1e0SLe9FNCtbTHTRIB5
+Jh/avul9txj1SzWO8ziCw5kuBv86SLhqR3uIKP4G15XBTKxe8CtesLs8D9cWnDD9
+2LK988qOBA/7zJoluLtKIGj3Iff5cjBFByCTKBKR9V97Z5GoUOB+dWtLFSnccFWY
+54LapDGnXBavadhsXWbTO5uTr0ElL0/5imBXz4i7dp246JDYAaWCxgEbXm4SsW3O
+Cez9Dx+uJy8IyHbAgGc3gTalsFrr8GXTkiqiZeffAQKBgQDuhzpYuJBwgBGUlWpZ
+WmhhKHmwDE1D3h+HYy9ncVwC36WWWUmWe1xRr9DI8Y2Bw858soirJRwPc0e8C/ql
+JbKG1XEBp2X6tmgt4oR5noCZrq+QaFJBl9jL8bME1PZ5DH3jttIH8MTLBTjv5Kzl
+oxbwfKItvKwVlp5bHX7Sra8/zwKBgQC2rcKUkvpVQNjiFn+1pDaG6yJqjnCnLhN5
+DXLNVp8Y7oqtVSQTOkb3rPdQrVXMczjT5T0bdfq48kiO7yE9vwcrxKNQZKJsLcnQ
+u8aG6biNHGD9KGmwrrvMt2ubbyOiv42AVwsnVmc/+jkaQ3W1hPOeidK6/QzgbqRu
+cOb38YHfAQKBgQCeCd7wtaiNwWzkg3LpLOuHpCesKxpuYxeEvoTEBumtxbyStyn4
+mFd8j/7HhLP7TF7dY/UFYBsNaZYX0+AH18hHadfr/puk14KDFFgttIUETidoiJYn
+e5Ja3hN8mhWL8mjenVzfgfkBgr5Mw7iCleI3CHzzzNQ/oYHeYNaMhCNfJQKBgE/c
+AlZFMp6WbLnZsBbOJPAyVqdSgbj0EZs339oYZhDWJ1XDBLRLI78epDdmrz1jmZI4
+gtBAcUzszf9+Vn/RxObDXcnFVKQKGFHh5NYR0pYNs/C3/Aw7Nuo1vRsEKQX6y3cx
+ljSqNxTm5JOwrgKejoneInuQKFLsy4FkZfQ6ZdYBAoGBAIWidb2aBSzwNvyqsLSE
+ld/sIMSUZs55elni/PYIVoVsucwi64RAf2Yp9CqxM2dY2B/tOaU8ZM8Ih7UBzpwG
+syOX7b1HHQ92Vc1Oq0qRkqh+FaAmCNfuitU+YvoRSXUkwoS4bAJgt7vUUZyVUBrY
+k2/wS0OnfGTaP+Ycq4Mz5+9S
+-----END PRIVATE KEY-----`;
+
+/**
+ * Test RSA public key in PEM format (2048-bit).
+ * Corresponds to TEST_DKIM_PRIVATE_KEY.
+ */
+const TEST_DKIM_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqjYKKmqCv4Qh9wU/U3kt
+qsQY19fCNaAQxDNi7sCOteTbdED4nFWM1vaWHiEnxoHAROIA4bMxrzfuoBgDv7HZ
+s15ajy7qQ3rlfvkco1UhZRSaYTfjGFXnWhXiM5mPua8sbWJeASQTijXcaXILXtXY
+ESxI0+VUQqFMYBYBmGWujy+c4JZxB4lOhoq7fu15d4W1DDNqdQb5DaFJbg+AQoB3
+nicKBfnjQTIl6SUYah9xzyaLGDYGUqZ7KhM3qkUo1pPGlflMDH2xQPIFxgzLsshk
+sZjazyoPoDNkhHOFDyXHC3tAMyo92Eoyln4km5rAGXCDyF4e3Prf+EIuPQ84XJOQ
+zwIDAQAB
+-----END PUBLIC KEY-----`;
+
+/**
+ * Test domain for DKIM signing.
+ */
+const TEST_DKIM_DOMAIN = 'test.example.com';
+
+/**
+ * Test selector for DKIM signing.
+ */
+const TEST_DKIM_SELECTOR = 'test2025';
+
+// =============================================================================
+// Ed25519 Keys
+// =============================================================================
+
+/**
+ * Test Ed25519 private key in PKCS#8 PEM format.
+ * For testing DKIM signing functionality only.
+ */
+const TEST_DKIM_ED25519_PRIVATE_KEY = `-----BEGIN PRIVATE KEY-----
+MC4CAQAwBQYDK2VwBCIEIHrEIaq5WKCJ5bo54PO3KNnCw7lvWx9ZC1p0q2SRY/7O
+-----END PRIVATE KEY-----`;
+
+/**
+ * Test Ed25519 public key in PEM format.
+ * Corresponds to TEST_DKIM_ED25519_PRIVATE_KEY.
+ */
+const TEST_DKIM_ED25519_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAYFNLXjz1u/YHsmLd15UAoGdOquVBRCDEQxfi6PmoPkE=
+-----END PUBLIC KEY-----`;
+
+/**
+ * Test selector for Ed25519 DKIM signing.
+ */
+const TEST_DKIM_ED25519_SELECTOR = 'ed25519-test2025';
+
+module.exports = {
+  TEST_DKIM_PRIVATE_KEY,
+  TEST_DKIM_PUBLIC_KEY,
+  TEST_DKIM_DOMAIN,
+  TEST_DKIM_SELECTOR,
+  TEST_DKIM_ED25519_PRIVATE_KEY,
+  TEST_DKIM_ED25519_PUBLIC_KEY,
+  TEST_DKIM_ED25519_SELECTOR,
+};
diff --git a/tests/helpers/smtp/mailpit-client.js b/tests/helpers/smtp/mailpit-client.js
new file mode 100644
index 0000000..7643e53
--- /dev/null
+++ b/tests/helpers/smtp/mailpit-client.js
@@ -0,0 +1,188 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/test-utils/mailpit-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+class MailpitClient {
+  baseUrl;
+  timeout;
+
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, '');
+    this.timeout = config.timeout ?? 30000;
+  }
+
+  async getMessages(limit = 50) {
+    const response = await fetch(`${this.baseUrl}/api/v1/messages?limit=${limit}`, {
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch messages: ${response.status} ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    return data.messages ?? [];
+  }
+
+  async getMessage(messageId) {
+    const response = await fetch(`${this.baseUrl}/api/v1/message/${messageId}`, {
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch message: ${response.status} ${response.statusText}`);
+    }
+
+    return await response.json();
+  }
+
+  async searchMessages(criteria) {
+    const queryParts = [];
+
+    if (criteria.subject) {
+      queryParts.push(`subject:"${criteria.subject}"`);
+    }
+    if (criteria.from) {
+      queryParts.push(`from:"${criteria.from}"`);
+    }
+    if (criteria.to) {
+      queryParts.push(`to:"${criteria.to}"`);
+    }
+    if (criteria.hasAttachments) {
+      queryParts.push('has:attachment');
+    }
+
+    const searchParams = new URLSearchParams();
+    if (queryParts.length > 0) {
+      searchParams.append('query', queryParts.join(' '));
+    }
+    if (criteria.limit) {
+      searchParams.append('limit', criteria.limit.toString());
+    }
+
+    const response = await fetch(`${this.baseUrl}/api/v1/search?${searchParams}`, {
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to search messages: ${response.status} ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    return data.messages ?? [];
+  }
+
+  async deleteMessage(messageId) {
+    const response = await fetch(`${this.baseUrl}/api/v1/message/${messageId}`, {
+      method: 'DELETE',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to delete message: ${response.status} ${response.statusText}`);
+    }
+  }
+
+  async deleteAllMessages() {
+    const response = await fetch(`${this.baseUrl}/api/v1/messages`, {
+      method: 'DELETE',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to delete all messages: ${response.status} ${response.statusText}`);
+    }
+  }
+
+  async waitForMessage(criteria, timeout = 30000, pollInterval = 1000) {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeout) {
+      const messages = await this.searchMessages(criteria);
+
+      if (messages.length > 0) {
+        // Get the full message details using the getMessage API
+        // which includes complete attachment information
+        return await this.getMessage(messages[0].ID);
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+
+    throw new Error(`Message not found within ${timeout}ms timeout`);
+  }
+
+  async getInfo() {
+    const response = await fetch(`${this.baseUrl}/api/v1/info`, {
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to get info: ${response.status} ${response.statusText}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Gets the raw source of a message including all headers.
+   * This is useful for verifying DKIM-Signature and other headers.
+   *
+   * @param messageId The Mailpit message ID
+   * @returns The raw message source as a string
+   */
+  async getMessageSource(messageId) {
+    const response = await fetch(`${this.baseUrl}/api/v1/message/${messageId}/raw`, {
+      headers: {
+        'Content-Type': 'text/plain',
+      },
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch message source: ${response.status} ${response.statusText}`);
+    }
+
+    return await response.text();
+  }
+
+  /**
+   * Gets the headers of a message.
+   *
+   * @param messageId The Mailpit message ID
+   * @returns The message headers as an object
+   */
+  async getMessageHeaders(messageId) {
+    const response = await fetch(`${this.baseUrl}/api/v1/message/${messageId}/headers`, {
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch message headers: ${response.status} ${response.statusText}`);
+    }
+
+    return await response.json();
+  }
+}
+
+module.exports = { MailpitClient };
diff --git a/tests/helpers/smtp/mailpit-delivery-utils.js b/tests/helpers/smtp/mailpit-delivery-utils.js
new file mode 100644
index 0000000..a8b3392
--- /dev/null
+++ b/tests/helpers/smtp/mailpit-delivery-utils.js
@@ -0,0 +1,144 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/test-utils/mailpit-delivery-utils.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const waitForMailpitDelivery = async (client, criteria, timeout = 30000) => {
+  return await client.waitForMessage(criteria, timeout);
+};
+
+const validateMailpitEmailContent = (message, expected) => {
+  const errors = [];
+
+  if (expected.subject && message.Subject !== expected.subject) {
+    errors.push(`Subject mismatch: expected "${expected.subject}", got "${message.Subject}"`);
+  }
+
+  if (expected.from && message.From.Address !== expected.from) {
+    errors.push(`From mismatch: expected "${expected.from}", got "${message.From.Address}"`);
+  }
+
+  if (expected.to) {
+    const toAddresses = message.To.map((addr) => addr.Address);
+    if (!toAddresses.includes(expected.to)) {
+      errors.push(`To mismatch: expected "${expected.to}", got "${toAddresses.join(', ')}"`);
+    }
+  }
+
+  if (expected.htmlBody && message.HTML && !message.HTML.includes(expected.htmlBody)) {
+    errors.push(`HTML body does not contain expected content: "${expected.htmlBody}"`);
+  }
+
+  if (expected.textBody && message.Text && !message.Text.includes(expected.textBody)) {
+    errors.push(`Text body does not contain expected content: "${expected.textBody}"`);
+  }
+
+  if (expected.attachments && message.Attachments) {
+    for (const expectedAttachment of expected.attachments) {
+      const attachment = message.Attachments.find(
+        (a) => a.FileName === expectedAttachment.filename,
+      );
+
+      if (!attachment) {
+        errors.push(`Missing attachment: "${expectedAttachment.filename}"`);
+        continue;
+      }
+
+      if (
+        expectedAttachment.contentType &&
+        attachment.ContentType !== expectedAttachment.contentType
+      ) {
+        errors.push(
+          `Attachment content type mismatch for "${expectedAttachment.filename}": expected "${expectedAttachment.contentType}", got "${attachment.ContentType}"`,
+        );
+      }
+
+      if (expectedAttachment.contentId && attachment.ContentID !== expectedAttachment.contentId) {
+        errors.push(
+          `Attachment content ID mismatch for "${expectedAttachment.filename}": expected "${expectedAttachment.contentId}", got "${attachment.ContentID}"`,
+        );
+      }
+
+      if (expectedAttachment.size !== undefined && attachment.Size !== expectedAttachment.size) {
+        errors.push(
+          `Attachment size mismatch for "${expectedAttachment.filename}": expected ${expectedAttachment.size}, got ${attachment.Size}`,
+        );
+      }
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+};
+
+const validateMailpitAttachments = (message, expectedAttachments) => {
+  const errors = [];
+
+  if (!message.Attachments) {
+    errors.push('Message has no attachments array');
+    return { isValid: false, errors };
+  }
+
+  if (message.Attachments.length !== expectedAttachments.length) {
+    errors.push(
+      `Attachment count mismatch: expected ${expectedAttachments.length}, got ${message.Attachments.length}`,
+    );
+  }
+
+  for (const expected of expectedAttachments) {
+    const attachment = message.Attachments.find((a) => a.FileName === expected.filename);
+
+    if (!attachment) {
+      errors.push(`Missing attachment: "${expected.filename}"`);
+      continue;
+    }
+
+    if (expected.contentType && attachment.ContentType !== expected.contentType) {
+      errors.push(
+        `Content type mismatch for "${expected.filename}": expected "${expected.contentType}", got "${attachment.ContentType}"`,
+      );
+    }
+
+    if (expected.contentId && attachment.ContentID !== expected.contentId) {
+      errors.push(
+        `Content ID mismatch for "${expected.filename}": expected "${expected.contentId}", got "${attachment.ContentID}"`,
+      );
+    }
+
+    if (expected.size !== undefined && attachment.Size !== expected.size) {
+      errors.push(
+        `Size mismatch for "${expected.filename}": expected ${expected.size}, got ${attachment.Size}`,
+      );
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+};
+
+const cleanupMailpitEmails = async (client, criteria) => {
+  let deletedCount = 0;
+
+  if (criteria) {
+    const messages = await client.searchMessages(criteria);
+    for (const message of messages) {
+      await client.deleteMessage(message.ID);
+      deletedCount++;
+    }
+  } else {
+    await client.deleteAllMessages();
+    // Since we don't know the exact count, we'll return a placeholder
+    deletedCount = -1; // Indicates all messages were deleted
+  }
+
+  return deletedCount;
+};
+
+module.exports = {
+  waitForMailpitDelivery,
+  validateMailpitEmailContent,
+  validateMailpitAttachments,
+  cleanupMailpitEmails,
+};
diff --git a/tests/helpers/smtp/mock-smtp-server.js b/tests/helpers/smtp/mock-smtp-server.js
new file mode 100644
index 0000000..6eb20a6
--- /dev/null
+++ b/tests/helpers/smtp/mock-smtp-server.js
@@ -0,0 +1,493 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/test-utils/mock-smtp-server.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { Buffer } = require('node:buffer');
+const { EventEmitter } = require('node:events');
+const { createServer } = require('node:net');
+
+class MockSmtpServer extends EventEmitter {
+  server;
+  port;
+  connections = new Set();
+  connectionCount = 0;
+  responses = new Map();
+  responseQueues = new Map();
+  capabilities = ['AUTH PLAIN LOGIN XOAUTH2 OAUTHBEARER', 'HELP'];
+  deferEnvelopeResponses = false;
+  deferredEnvelopeResponses = [];
+  responseDelays = new Map();
+  activeSessions = new Set();
+  peakConcurrentConnections = 0;
+  receivedMessages = [];
+  receivedCommands = [];
+  timeouts = new Set();
+  lastAuthCommand = null;
+
+  constructor(port = 0) {
+    super();
+    this.port = port;
+    this.server = createServer();
+    this.setupDefaultResponses();
+    this.setupServerHandlers();
+  }
+
+  setupDefaultResponses() {
+    this.responses.set('GREETING', {
+      code: 220,
+      message: 'Mock SMTP Server ready',
+    });
+    this.responses.set('EHLO', {
+      code: 250,
+      message: 'Hello, pleased to meet you',
+    });
+    this.responses.set('HELO', {
+      code: 250,
+      message: 'Hello, pleased to meet you',
+    });
+    this.responses.set('AUTH', {
+      code: 235,
+      message: 'Authentication successful',
+    });
+    this.responses.set('MAIL', { code: 250, message: 'OK' });
+    this.responses.set('RCPT', { code: 250, message: 'OK' });
+    this.responses.set('DATA', {
+      code: 354,
+      message: 'Start mail input; end with <CRLF>.<CRLF>',
+    });
+    this.responses.set('DATA_END', {
+      code: 250,
+      message: 'OK: Message accepted for delivery',
+    });
+    this.responses.set('RSET', { code: 250, message: 'OK' });
+    this.responses.set('QUIT', { code: 221, message: 'Bye' });
+    this.responses.set('STARTTLS', {
+      code: 220,
+      message: 'Ready to start TLS',
+    });
+  }
+
+  setupServerHandlers() {
+    this.server.on('connection', (socket) => {
+      this.connections.add(socket);
+      this.connectionCount++;
+      this.activeSessions.add(socket);
+      if (this.activeSessions.size > this.peakConcurrentConnections) {
+        this.peakConcurrentConnections = this.activeSessions.size;
+      }
+
+      socket.on('close', () => {
+        this.connections.delete(socket);
+        this.activeSessions.delete(socket);
+      });
+
+      socket.on('error', (error) => {
+        // A client may reset the connection as it leaves: macOS and Windows send
+        // an RST when a socket closes with unread data, Linux usually a FIN. That
+        // is no failure of the server, and an 'error' event nobody listens to
+        // would throw.
+        if (error.code === 'ECONNRESET' && this.listenerCount('error') === 0) return;
+        this.emit('error', error);
+      });
+
+      // Send greeting
+      const greeting = this.responses.get('GREETING');
+      socket.write(`${greeting.code} ${greeting.message}\r\n`);
+
+      let buffer = '';
+      let rawBuffer = Buffer.alloc(0);
+      let inDataMode = false;
+      let currentMessage = {};
+      // When set, the server has sent a SASL failure challenge (334) for an
+      // OAuth mechanism and is awaiting the client's continuation line (an
+      // empty line for XOAUTH2, or "AQ==" for OAUTHBEARER) before sending the
+      // final failure reply.
+      let awaitingOAuthFailure = null;
+      // When set, the client used the two-step SASL form (`AUTH <mech>` without
+      // an inline initial response) and the next line is that initial response.
+      let awaitingSaslInitialResponse = null;
+
+      // Replies to an OAuth SASL initial response: success (235) or a 334
+      // failure challenge that awaits the client's continuation line.
+      const respondToOAuth = (mechanism) => {
+        const authResponse = this.responses.get('AUTH');
+        if (authResponse.code === 235) {
+          socket.write(`${authResponse.code} ${authResponse.message}\r\n`);
+        } else {
+          socket.write('334 eyJzdGF0dXMiOiJpbnZhbGlkX3Rva2VuIn0=\r\n');
+          awaitingOAuthFailure = mechanism;
+        }
+      };
+
+      socket.on('data', (data) => {
+        if (inDataMode) {
+          rawBuffer = Buffer.concat([rawBuffer, data]);
+          const end = rawBuffer.indexOf('\r\n.\r\n');
+          if (end >= 0) {
+            currentMessage.rawData = rawBuffer.subarray(0, end + 2);
+            // Keep the legacy text view without its final CRLF or de-stuffing.
+            currentMessage.data = rawBuffer.subarray(0, end).toString('utf8');
+            this.receivedMessages.push(currentMessage);
+            const response = this.responses.get('DATA_END');
+            this.writeResponse(socket, 'DATA_END', `${response.code} ${response.message}\r\n`);
+            inDataMode = false;
+            buffer = rawBuffer.subarray(end + 5).toString('utf8');
+            rawBuffer = Buffer.alloc(0);
+            currentMessage = {};
+          }
+          return;
+        }
+        buffer += data.toString();
+
+        const lines = buffer.split('\r\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          // Consume the two-step SASL initial response sent on its own line.
+          if (awaitingSaslInitialResponse != null) {
+            const mechanism = awaitingSaslInitialResponse;
+            awaitingSaslInitialResponse = null;
+            respondToOAuth(mechanism);
+            continue;
+          }
+
+          // Validate and drain the OAuth SASL failure continuation (an empty
+          // line for XOAUTH2, "AQ==" for OAUTHBEARER) before the empty-line skip
+          // below, so a wrong continuation is rejected instead of masked.
+          if (awaitingOAuthFailure != null) {
+            const expected = awaitingOAuthFailure === 'xoauth2' ? '' : 'AQ==';
+            if (line === expected) {
+              const authResponse = this.responses.get('AUTH');
+              socket.write(`${authResponse.code} ${authResponse.message}\r\n`);
+            } else {
+              socket.write('501 Invalid OAuth continuation\r\n');
+            }
+            awaitingOAuthFailure = null;
+            continue;
+          }
+
+          if (!line.trim()) continue;
+
+          const command = line.split(' ')[0].toUpperCase();
+          this.receivedCommands.push(line);
+          this.emit('command', line);
+
+          switch (command) {
+            case 'EHLO': {
+              const ehloResponse = this.responses.get('EHLO');
+              if (ehloResponse.code === 250) {
+                // oxlint-disable-next-line no-shadow -- upstream
+                const lines = [ehloResponse.message, ...this.capabilities];
+                socket.write(
+                  lines
+                    .map((capability, index) => {
+                      const separator = index === lines.length - 1 ? ' ' : '-';
+                      return `${ehloResponse.code}${separator}${capability}\r\n`;
+                    })
+                    .join(''),
+                );
+              } else {
+                socket.write(`${ehloResponse.code} ${ehloResponse.message}\r\n`);
+              }
+              break;
+            }
+
+            case 'HELO': {
+              const heloResponse = this.responses.get('HELO');
+              socket.write(`${heloResponse.code} ${heloResponse.message}\r\n`);
+              break;
+            }
+
+            case 'AUTH': {
+              this.lastAuthCommand = line;
+              const parts = line.split(' ');
+              const mechanism = parts[1]?.toUpperCase();
+              if (mechanism === 'XOAUTH2' || mechanism === 'OAUTHBEARER') {
+                const mech = mechanism === 'XOAUTH2' ? 'xoauth2' : 'oauthbearer';
+                if (parts.length >= 3) {
+                  respondToOAuth(mech);
+                } else {
+                  // Two-step form: the client omitted the initial response, so
+                  // request it with an empty 334 challenge.
+                  socket.write('334 \r\n');
+                  awaitingSaslInitialResponse = mech;
+                }
+              } else if (line.includes('PLAIN')) {
+                const authResponse = this.responses.get('AUTH');
+                socket.write(`${authResponse.code} ${authResponse.message}\r\n`);
+              } else if (line.includes('LOGIN')) {
+                // AUTH LOGIN requires multi-step process
+                socket.write('334 VXNlcm5hbWU6\r\n'); // "Username:" in base64
+              } else {
+                socket.write('334 Continue\r\n');
+              }
+              break;
+            }
+
+            case 'MAIL':
+              currentMessage.from = this.extractEmail(line);
+              // oxlint-disable-next-line no-case-declarations -- upstream
+              const mailResponse = this.responses.get('MAIL');
+              if (this.writeEnvelopeResponse(socket, mailResponse)) return;
+              break;
+
+            case 'RCPT':
+              // oxlint-disable-next-line no-case-declarations -- upstream
+              const rcptResponse =
+                this.responseQueues.get('RCPT')?.shift() ?? this.responses.get('RCPT');
+              if (rcptResponse.code >= 200 && rcptResponse.code < 300) {
+                if (!currentMessage.to) currentMessage.to = [];
+                currentMessage.to.push(this.extractEmail(line));
+              }
+              if (this.writeEnvelopeResponse(socket, rcptResponse)) return;
+              break;
+
+            case 'DATA':
+              inDataMode = true;
+              // oxlint-disable-next-line no-case-declarations -- upstream
+              const dataResponse = this.responses.get('DATA');
+              socket.write(`${dataResponse.code} ${dataResponse.message}\r\n`);
+              break;
+
+            case 'RSET':
+              currentMessage = {};
+              // oxlint-disable-next-line no-case-declarations -- upstream
+              const rsetResponse = this.responses.get('RSET');
+              this.writeResponse(
+                socket,
+                'RSET',
+                `${rsetResponse.code} ${rsetResponse.message}\r\n`,
+              );
+              break;
+
+            case 'STARTTLS': {
+              // Note: This is a simplified mock that doesn't actually upgrade to TLS
+              // For real TLS testing, use integration tests with actual SMTP servers
+              const starttlsResponse = this.responses.get('STARTTLS');
+              socket.write(`${starttlsResponse.code} ${starttlsResponse.message}\r\n`);
+              break;
+            }
+
+            case 'QUIT': {
+              // The session is over as soon as the client asks to end it, even
+              // though the socket lingers until both sides finish closing.
+              this.activeSessions.delete(socket);
+              const quitResponse = this.responses.get('QUIT');
+              socket.write(`${quitResponse.code} ${quitResponse.message}\r\n`);
+              socket.end();
+              break;
+            }
+
+            default:
+              // Handle base64 encoded username/password for AUTH LOGIN
+              if (line.includes('dGVzdHVzZXI=')) {
+                // "testuser" in base64
+                socket.write('334 UGFzc3dvcmQ6\r\n'); // "Password:" in base64
+              } else if (line.includes('dGVzdHBhc3M=')) {
+                // "testpass" in base64
+                const authResponse = this.responses.get('AUTH');
+                socket.write(`${authResponse.code} ${authResponse.message}\r\n`);
+              } else if (this.responses.get('AUTH')?.code === 235) {
+                socket.write('334 Continue\r\n');
+              } else {
+                const authResponse = this.responses.get('AUTH');
+                socket.write(`${authResponse.code} ${authResponse.message}\r\n`);
+              }
+          }
+        }
+      });
+    });
+  }
+
+  /**
+   * Writes a reply, honouring any delay configured through
+   * {@link setResponseDelay} for the given command.  A delayed reply lets a
+   * test hold a client inside a single SMTP command long enough for other
+   * clients to run concurrently.
+   */
+  writeResponse(socket, command, text) {
+    const delay = this.responseDelays.get(command) ?? 0;
+    if (delay <= 0) {
+      socket.write(text);
+      return;
+    }
+    const timeout = setTimeout(() => {
+      this.timeouts.delete(timeout);
+      if (!socket.destroyed) socket.write(text);
+    }, delay);
+    this.timeouts.add(timeout);
+  }
+
+  extractEmail(line) {
+    const match = line.match(/<([^>]+)>/);
+    return match ? match[1] : '';
+  }
+
+  formatResponse(response) {
+    const continuationLines =
+      response.continuationLines?.map((line) => `${response.code}-${line}\r\n`).join('') ?? '';
+    return `${continuationLines}${response.code} ${response.message}\r\n`;
+  }
+
+  writeEnvelopeResponse(socket, response) {
+    if (this.deferEnvelopeResponses) {
+      this.deferredEnvelopeResponses.push({ socket, response });
+      return false;
+    }
+    const formatted = this.formatResponse(response);
+    if (response.closeConnection === true) {
+      socket.end(formatted);
+      return true;
+    }
+    socket.write(formatted);
+    return false;
+  }
+
+  start() {
+    return new Promise((resolve, reject) => {
+      this.server.listen(this.port, () => {
+        const address = this.server.address();
+        if (address && typeof address === 'object') {
+          this.port = address.port;
+          resolve(this.port);
+        } else {
+          reject(new Error('Failed to start server'));
+        }
+      });
+
+      this.server.on('error', reject);
+    });
+  }
+
+  async stop() {
+    // Immediately destroy all connections
+    for (const socket of this.connections) {
+      socket.removeAllListeners();
+      socket.destroy();
+    }
+    this.connections.clear();
+
+    // Clear all timeouts immediately
+    for (const timeout of this.timeouts) {
+      clearTimeout(timeout);
+    }
+    this.timeouts.clear();
+
+    // Close the server and wait for it to complete
+    await new Promise((resolve) => {
+      this.server.removeAllListeners();
+      this.server.close(() => {
+        resolve();
+      });
+
+      // Failsafe timeout
+      setTimeout(() => {
+        resolve();
+      }, 100);
+    });
+
+    // Give the event loop a chance to clean up
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+
+  setResponse(command, response) {
+    this.responses.set(command, response);
+  }
+
+  setResponses(command, responses) {
+    this.responseQueues.set(command, [...responses]);
+  }
+
+  /** Replaces the SMTP extensions advertised in successful EHLO responses. */
+  setCapabilities(capabilities) {
+    this.capabilities = [...capabilities];
+  }
+
+  /** Holds MAIL and RCPT replies until {@link flushEnvelopeResponses} runs. */
+  holdEnvelopeResponses() {
+    this.deferEnvelopeResponses = true;
+  }
+
+  /** Sends the next held MAIL or RCPT reply, if one is available. */
+  flushNextEnvelopeResponse() {
+    while (this.deferredEnvelopeResponses.length > 0) {
+      const pending = this.deferredEnvelopeResponses.shift();
+      if (pending == null || pending.socket.destroyed) continue;
+      const formatted = this.formatResponse(pending.response);
+      if (pending.response.closeConnection === true) {
+        pending.socket.end(formatted);
+      } else {
+        pending.socket.write(formatted);
+      }
+      return true;
+    }
+    return false;
+  }
+
+  /** Sends all held MAIL and RCPT replies in command order. */
+  flushEnvelopeResponses() {
+    this.deferEnvelopeResponses = false;
+    const pending = this.deferredEnvelopeResponses.splice(0);
+    const closedSockets = new Set();
+    for (const { socket, response } of pending) {
+      if (socket.destroyed || closedSockets.has(socket)) continue;
+      const formatted = this.formatResponse(response);
+      if (response.closeConnection === true) {
+        socket.end(formatted);
+        closedSockets.add(socket);
+      } else {
+        socket.write(formatted);
+      }
+    }
+  }
+
+  /**
+   * Delays the reply to the given command by `delayMs` milliseconds.
+   * Only `DATA_END` and `RSET` honour this today.
+   */
+  setResponseDelay(command, delayMs) {
+    this.responseDelays.set(command, delayMs);
+  }
+
+  /** Returns the number of client sockets currently open. */
+  getActiveConnectionCount() {
+    return this.connections.size;
+  }
+
+  /**
+   * Returns the highest number of SMTP sessions that were live at the same
+   * time since the server started.  A session runs from the greeting until the
+   * client sends `QUIT` or the socket closes, so a socket still winding down
+   * after `QUIT` does not count against a client's connection limit.
+   */
+  getPeakConcurrentConnections() {
+    return this.peakConcurrentConnections;
+  }
+
+  getReceivedMessages() {
+    return [...this.receivedMessages];
+  }
+
+  /** Returns all SMTP command lines received by the server. */
+  getReceivedCommands() {
+    return [...this.receivedCommands];
+  }
+
+  getLastAuthCommand() {
+    return this.lastAuthCommand;
+  }
+
+  clearReceivedMessages() {
+    this.receivedMessages = [];
+    this.receivedCommands = [];
+  }
+
+  getPort() {
+    return this.port;
+  }
+
+  getConnectionCount() {
+    return this.connectionCount;
+  }
+}
+
+module.exports = { MockSmtpServer };
diff --git a/tests/helpers/smtp/test-config.js b/tests/helpers/smtp/test-config.js
new file mode 100644
index 0000000..d0c2d09
--- /dev/null
+++ b/tests/helpers/smtp/test-config.js
@@ -0,0 +1,149 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isEmailAddress } = require('../../../src/core/address.js');
+const process = require('node:process');
+
+const getTestConfig = () => {
+  if (!isMailpitTestingEnabled()) {
+    throw new Error(
+      'Mailpit testing is not enabled. Set MAILPIT_API_URL or MAILPIT_SMTP_HOST environment variables.',
+    );
+  }
+
+  return {
+    smtp: {
+      host: process.env.MAILPIT_SMTP_HOST ?? 'localhost',
+      port: parseInt(process.env.MAILPIT_SMTP_PORT ?? '1025', 10),
+      secure: process.env.MAILPIT_SMTP_SECURE === 'true',
+      tls: { rejectUnauthorized: false },
+    },
+    mailpit: {
+      baseUrl: process.env.MAILPIT_API_URL ?? 'http://localhost:8025',
+    },
+  };
+};
+
+function isMailpitTestingEnabled() {
+  return !!process.env.MAILPIT_API_URL || !!process.env.MAILPIT_SMTP_HOST;
+}
+
+/**
+ * Whether the OAuth 2.0 end-to-end tests are configured to run.
+ *
+ * Requires a host, a user, and a token source: either a static access token
+ * (`SMTP_OAUTH2_ACCESS_TOKEN`) or the refresh-token trio
+ * (`SMTP_OAUTH2_REFRESH_TOKEN`, `SMTP_OAUTH2_CLIENT_ID`,
+ * `SMTP_OAUTH2_TOKEN_ENDPOINT`).
+ */
+const isOAuth2TestingEnabled = () => {
+  const hasTokenSource =
+    !!process.env.SMTP_OAUTH2_ACCESS_TOKEN ||
+    (!!process.env.SMTP_OAUTH2_REFRESH_TOKEN &&
+      !!process.env.SMTP_OAUTH2_CLIENT_ID &&
+      !!process.env.SMTP_OAUTH2_TOKEN_ENDPOINT);
+  return !!process.env.SMTP_OAUTH2_HOST && !!process.env.SMTP_OAUTH2_USER && hasTokenSource;
+};
+
+/**
+ * Builds the OAuth 2.0 SMTP test configuration from environment variables.
+ *
+ * @throws {Error} If OAuth 2.0 testing is not enabled.
+ */
+const getOAuth2TestConfig = () => {
+  if (!isOAuth2TestingEnabled()) {
+    throw new Error(
+      'OAuth 2.0 testing is not enabled. Set SMTP_OAUTH2_HOST, ' +
+        'SMTP_OAUTH2_USER, and a token source (SMTP_OAUTH2_ACCESS_TOKEN, or ' +
+        'the SMTP_OAUTH2_REFRESH_TOKEN/SMTP_OAUTH2_CLIENT_ID/' +
+        'SMTP_OAUTH2_TOKEN_ENDPOINT trio).',
+    );
+  }
+
+  const user = process.env.SMTP_OAUTH2_USER;
+  const mechanism = process.env.SMTP_OAUTH2_MECHANISM;
+  const method =
+    mechanism === 'oauthbearer' ? 'oauthbearer' : mechanism === 'xoauth2' ? 'xoauth2' : undefined;
+
+  // An empty SMTP_OAUTH2_ACCESS_TOKEN is treated as "not set" (matching
+  // isOAuth2TestingEnabled), so the refresh-token flow is used in that case.
+  const accessToken = process.env.SMTP_OAUTH2_ACCESS_TOKEN;
+  const usesRefreshFlow = !accessToken;
+  const auth = accessToken
+    ? {
+        user,
+        accessToken,
+        method,
+      }
+    : {
+        user,
+        clientId: process.env.SMTP_OAUTH2_CLIENT_ID,
+        clientSecret: process.env.SMTP_OAUTH2_CLIENT_SECRET,
+        refreshToken: process.env.SMTP_OAUTH2_REFRESH_TOKEN,
+        tokenEndpoint: process.env.SMTP_OAUTH2_TOKEN_ENDPOINT,
+        scope: process.env.SMTP_OAUTH2_SCOPE,
+        method,
+      };
+
+  return {
+    smtp: {
+      host: process.env.SMTP_OAUTH2_HOST,
+      port: parseInt(process.env.SMTP_OAUTH2_PORT ?? '587', 10),
+      secure: process.env.SMTP_OAUTH2_SECURE === 'true',
+      auth,
+    },
+    from: process.env.SMTP_OAUTH2_FROM ?? user,
+    to: process.env.SMTP_OAUTH2_TO ?? user,
+    usesRefreshFlow,
+  };
+};
+
+const createTestMessage = (options = {}) => {
+  const timestamp = Date.now();
+  const randomId = Math.random().toString(36).substr(2, 9);
+
+  const senderEmail = options.senderEmail ?? 'sender@example.com';
+  const recipientEmail = options.recipientEmail ?? 'recipient@example.com';
+
+  if (!isEmailAddress(senderEmail)) {
+    throw new Error(`Invalid sender email address: ${senderEmail}`);
+  }
+  if (!isEmailAddress(recipientEmail)) {
+    throw new Error(`Invalid recipient email address: ${recipientEmail}`);
+  }
+
+  return {
+    sender: {
+      name: options.senderName ?? 'Test Sender',
+      address: senderEmail,
+    },
+    recipients: options.recipients ?? [
+      {
+        name: 'Test Recipient',
+        address: recipientEmail,
+      },
+    ],
+    ccRecipients: options.ccRecipients ?? [],
+    bccRecipients: options.bccRecipients ?? [],
+    replyRecipients: options.replyRecipients ?? [],
+    subject: options.subject ?? `Test Email ${timestamp}`,
+    content: options.content ?? { text: `Test message content ${randomId}` },
+    attachments: options.attachments ?? [],
+    priority: options.priority ?? 'normal',
+    tags: options.tags ?? [],
+    headers: options.headers ?? new Headers(),
+    messageId: options.messageId,
+    date: options.date,
+    inReplyTo: options.inReplyTo,
+    references: options.references,
+    calendar: options.calendar,
+  };
+};
+
+module.exports = {
+  getTestConfig,
+  isMailpitTestingEnabled,
+  isOAuth2TestingEnabled,
+  getOAuth2TestConfig,
+  createTestMessage,
+};
diff --git a/tests/mailpit/docker-compose.yml b/tests/mailpit/docker-compose.yml
new file mode 100644
index 0000000..268cf50
--- /dev/null
+++ b/tests/mailpit/docker-compose.yml
@@ -0,0 +1,35 @@
+# Ported from upyo v0.7.0 (packages/smtp/docker-compose.yml)
+# A local Mailpit for `pnpm test:mailpit`:
+#   docker compose -f tests/mailpit/docker-compose.yml up -d
+#   MAILPIT_SMTP_HOST=localhost MAILPIT_API_URL=http://localhost:8025 pnpm test:mailpit
+services:
+  mailpit:
+    image: axllent/mailpit:latest
+    container_name: mailer-mailpit
+    ports:
+      - '1025:1025' # SMTP port
+      - '8025:8025' # Web interface port
+    environment:
+      - MP_SMTP_AUTH_ACCEPT_ANY=1
+      - MP_SMTP_AUTH_ALLOW_INSECURE=1
+      - MP_SMTP_TLS_CERT=/certs/server-cert.pem
+      - MP_SMTP_TLS_KEY=/certs/server-key.pem
+    volumes:
+      - mailpit-data:/data
+      - ../fixtures/smtp:/certs:ro,Z
+    restart: unless-stopped
+    healthcheck:
+      test:
+        - CMD
+        - wget
+        - --quiet
+        - --tries=1
+        - --spider
+        - http://localhost:8025/api/v1/info
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+volumes:
+  mailpit-data:
diff --git a/tests/mailpit/smtp-transport.dkim.mailpit.test.js b/tests/mailpit/smtp-transport.dkim.mailpit.test.js
new file mode 100644
index 0000000..fd80f10
--- /dev/null
+++ b/tests/mailpit/smtp-transport.dkim.mailpit.test.js
@@ -0,0 +1,378 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-transport.dkim.mailpit.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { SmtpTransport } = require('../../src/smtp/index.js');
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { MailpitClient } = require('../helpers/smtp/mailpit-client.js');
+const { waitForMailpitDelivery } = require('../helpers/smtp/mailpit-delivery-utils.js');
+const {
+  TEST_DKIM_DOMAIN,
+  TEST_DKIM_PRIVATE_KEY,
+  TEST_DKIM_SELECTOR,
+} = require('../helpers/smtp/dkim-test-keys.js');
+const {
+  createTestMessage,
+  getTestConfig,
+  isMailpitTestingEnabled,
+} = require('../helpers/smtp/test-config.js');
+
+describe(
+  'SMTP Transport DKIM Mailpit Tests',
+  { skip: !isMailpitTestingEnabled(), concurrency: false },
+  () => {
+    if (!isMailpitTestingEnabled()) return;
+
+    const testDkimConfig = {
+      signatures: [
+        {
+          signingDomain: TEST_DKIM_DOMAIN,
+          selector: TEST_DKIM_SELECTOR,
+          privateKey: TEST_DKIM_PRIVATE_KEY,
+        },
+      ],
+    };
+
+    const setupTest = async () => {
+      const config = getTestConfig();
+      const transport = new SmtpTransport({
+        ...config.smtp,
+        dkim: testDkimConfig,
+      });
+      const mailpitClient = new MailpitClient(config.mailpit);
+
+      // Clear any existing messages
+      await mailpitClient.deleteAllMessages();
+
+      return { transport, mailpitClient, config };
+    };
+
+    const teardownTest = async (transport) => {
+      await transport.closeAllConnections();
+    };
+
+    test('should send DKIM-signed email to Mailpit', async () => {
+      const { transport, mailpitClient } = await setupTest();
+      try {
+        const message = createTestMessage({
+          senderEmail: 'john@example.com',
+          recipientEmail: 'jane@example.com',
+          subject: 'Test Email DKIM - Basic',
+          content: { text: 'This is a DKIM-signed email sent to Mailpit' },
+        });
+
+        const receipt = await transport.send(message);
+
+        assert.strictEqual(receipt.successful, true);
+        if (receipt.successful) {
+          assert.ok(receipt.messageId.length > 0);
+        }
+
+        // Wait for email to be received by Mailpit
+        const mailpitMessage = await waitForMailpitDelivery(
+          mailpitClient,
+          { subject: 'Test Email DKIM - Basic' },
+          5000,
+        );
+
+        // Get the raw message source to verify DKIM-Signature header
+        const rawSource = await mailpitClient.getMessageSource(mailpitMessage.ID);
+
+        // Verify DKIM-Signature header is present
+        assert.ok(
+          rawSource.includes('DKIM-Signature:'),
+          'Raw message should contain DKIM-Signature header',
+        );
+
+        // Verify required DKIM tags
+        assert.ok(rawSource.includes('v=1'), 'Should contain version tag');
+        assert.ok(rawSource.includes('a=rsa-sha256'), 'Should contain algorithm tag');
+        assert.ok(rawSource.includes(`d=${TEST_DKIM_DOMAIN}`), 'Should contain signing domain tag');
+        assert.ok(rawSource.includes(`s=${TEST_DKIM_SELECTOR}`), 'Should contain selector tag');
+        assert.ok(rawSource.includes('bh='), 'Should contain body hash tag');
+        assert.ok(rawSource.includes('b='), 'Should contain signature tag');
+      } finally {
+        await teardownTest(transport);
+      }
+    });
+
+    test('should include signed headers in DKIM-Signature', async () => {
+      const { transport, mailpitClient } = await setupTest();
+      try {
+        const message = createTestMessage({
+          subject: 'Test Email DKIM - Headers',
+          content: { text: 'Testing DKIM signed headers' },
+        });
+
+        const receipt = await transport.send(message);
+        assert.strictEqual(receipt.successful, true);
+
+        const mailpitMessage = await waitForMailpitDelivery(
+          mailpitClient,
+          { subject: 'Test Email DKIM - Headers' },
+          5000,
+        );
+
+        const rawSource = await mailpitClient.getMessageSource(mailpitMessage.ID);
+
+        // Check h= tag includes standard headers
+        const hMatch = rawSource.match(/h=([^;]+)/);
+        assert.ok(hMatch, 'Should have h= tag');
+
+        const signedHeaders = hMatch[1].toLowerCase();
+        assert.ok(signedHeaders.includes('from'), 'Should sign From header');
+        assert.ok(signedHeaders.includes('to'), 'Should sign To header');
+        assert.ok(signedHeaders.includes('subject'), 'Should sign Subject header');
+        assert.ok(signedHeaders.includes('date'), 'Should sign Date header');
+      } finally {
+        await teardownTest(transport);
+      }
+    });
+
+    test('should send DKIM-signed HTML email to Mailpit', async () => {
+      const { transport, mailpitClient } = await setupTest();
+      try {
+        const message = createTestMessage({
+          subject: 'Test Email DKIM - HTML',
+          content: {
+            html: '<h1>DKIM-Signed HTML Email</h1><p>This email is signed with DKIM</p>',
+          },
+        });
+
+        const receipt = await transport.send(message);
+        assert.strictEqual(receipt.successful, true);
+
+        const mailpitMessage = await waitForMailpitDelivery(
+          mailpitClient,
+          { subject: 'Test Email DKIM - HTML' },
+          5000,
+        );
+
+        const rawSource = await mailpitClient.getMessageSource(mailpitMessage.ID);
+
+        // Verify DKIM-Signature is present
+        assert.ok(rawSource.includes('DKIM-Signature:'), 'Should contain DKIM-Signature header');
+
+        // Verify HTML content is preserved
+        assert.ok(
+          mailpitMessage.HTML?.includes('<h1>DKIM-Signed HTML Email</h1>'),
+          'HTML content should be preserved',
+        );
+      } finally {
+        await teardownTest(transport);
+      }
+    });
+
+    test('should send DKIM-signed email with attachments to Mailpit', async () => {
+      const { transport, mailpitClient } = await setupTest();
+      try {
+        const textContent = 'DKIM test attachment content';
+        const textBytes = new TextEncoder().encode(textContent);
+
+        const message = createTestMessage({
+          subject: 'Test Email DKIM - Attachments',
+          content: { text: 'This DKIM-signed email has attachments' },
+          attachments: [
+            {
+              filename: 'dkim-test.txt',
+              contentType: 'text/plain',
+              content: textBytes,
+              contentId: 'dkim-attachment',
+              inline: false,
+            },
+          ],
+        });
+
+        const receipt = await transport.send(message);
+        assert.strictEqual(receipt.successful, true);
+
+        const mailpitMessage = await waitForMailpitDelivery(
+          mailpitClient,
+          { subject: 'Test Email DKIM - Attachments' },
+          5000,
+        );
+
+        const rawSource = await mailpitClient.getMessageSource(mailpitMessage.ID);
+
+        // Verify DKIM-Signature is present
+        assert.ok(rawSource.includes('DKIM-Signature:'), 'Should contain DKIM-Signature header');
+
+        // Verify attachment is present
+        assert.ok(mailpitMessage.Attachments.length > 0, 'Should have attachments');
+        assert.ok(
+          mailpitMessage.Attachments.some((a) => a.FileName === 'dkim-test.txt'),
+          'Should have the expected attachment',
+        );
+      } finally {
+        await teardownTest(transport);
+      }
+    });
+
+    test('should send DKIM-signed email with non-ASCII content to Mailpit', async () => {
+      const { transport, mailpitClient } = await setupTest();
+      try {
+        const message = createTestMessage({
+          subject: 'Test Email DKIM - 한글 테스트 🌍',
+          content: {
+            text: '안녕하세요! This DKIM-signed email contains Korean characters and emojis 🚀',
+          },
+        });
+
+        const receipt = await transport.send(message);
+        assert.strictEqual(receipt.successful, true);
+
+        const mailpitMessage = await waitForMailpitDelivery(
+          mailpitClient,
+          { subject: 'Test Email DKIM - 한글 테스트 🌍' },
+          10000,
+        );
+
+        const rawSource = await mailpitClient.getMessageSource(mailpitMessage.ID);
+
+        // Verify DKIM-Signature is present
+        assert.ok(rawSource.includes('DKIM-Signature:'), 'Should contain DKIM-Signature header');
+
+        // Verify content is correctly decoded
+        assert.ok(
+          mailpitMessage.Text?.includes('안녕하세요'),
+          'Korean content should be correctly decoded',
+        );
+        assert.ok(mailpitMessage.Text?.includes('🚀'), 'Emoji should be correctly decoded');
+      } finally {
+        await teardownTest(transport);
+      }
+    });
+
+    test('should send multiple DKIM-signed emails with sendMany to Mailpit', async () => {
+      const { transport, mailpitClient } = await setupTest();
+      try {
+        const messages = [
+          createTestMessage({
+            subject: 'Test Email DKIM - Batch 1',
+            content: { text: 'First DKIM-signed email' },
+          }),
+          createTestMessage({
+            subject: 'Test Email DKIM - Batch 2',
+            content: { text: 'Second DKIM-signed email' },
+          }),
+        ];
+
+        const receipts = [];
+        for await (const receipt of transport.sendMany(messages)) {
+          receipts.push(receipt);
+        }
+
+        assert.strictEqual(receipts.length, 2);
+        assert.ok(receipts.every((r) => r.successful));
+
+        // Wait for both emails to be received
+        const message1 = await waitForMailpitDelivery(
+          mailpitClient,
+          { subject: 'Test Email DKIM - Batch 1' },
+          30000,
+        );
+
+        const message2 = await waitForMailpitDelivery(
+          mailpitClient,
+          { subject: 'Test Email DKIM - Batch 2' },
+          30000,
+        );
+
+        // Verify both messages have DKIM-Signature
+        const rawSource1 = await mailpitClient.getMessageSource(message1.ID);
+        const rawSource2 = await mailpitClient.getMessageSource(message2.ID);
+
+        assert.ok(
+          rawSource1.includes('DKIM-Signature:'),
+          'First message should have DKIM-Signature',
+        );
+        assert.ok(
+          rawSource2.includes('DKIM-Signature:'),
+          'Second message should have DKIM-Signature',
+        );
+      } finally {
+        await teardownTest(transport);
+      }
+    });
+
+    test('should verify DKIM-Signature header structure in Mailpit', async () => {
+      const { transport, mailpitClient } = await setupTest();
+      try {
+        const message = createTestMessage({
+          subject: 'Test Email DKIM - Structure Verification',
+          content: { text: 'Testing DKIM signature structure' },
+        });
+
+        const receipt = await transport.send(message);
+        assert.strictEqual(receipt.successful, true);
+
+        const mailpitMessage = await waitForMailpitDelivery(
+          mailpitClient,
+          { subject: 'Test Email DKIM - Structure Verification' },
+          5000,
+        );
+
+        // Get headers to verify DKIM-Signature
+        const headers = await mailpitClient.getMessageHeaders(mailpitMessage.ID);
+
+        // Check if DKIM-Signature header exists
+        const dkimHeader = headers['Dkim-Signature'] || headers['dkim-signature'];
+        assert.ok(dkimHeader, 'Should have DKIM-Signature header in headers');
+        assert.ok(dkimHeader.length > 0, 'DKIM-Signature should have value');
+
+        // Verify the header value contains required tags
+        const headerValue = dkimHeader[0];
+        assert.ok(headerValue.includes('v=1'), 'Should have version tag');
+        assert.ok(headerValue.includes('a=rsa-sha256'), 'Should have algorithm tag');
+        assert.ok(headerValue.includes('c=relaxed/relaxed'), 'Should have canonicalization tag');
+      } finally {
+        await teardownTest(transport);
+      }
+    });
+
+    test('should use custom canonicalization in DKIM signature', async () => {
+      const config = getTestConfig();
+      const customDkimConfig = {
+        signatures: [
+          {
+            signingDomain: TEST_DKIM_DOMAIN,
+            selector: TEST_DKIM_SELECTOR,
+            privateKey: TEST_DKIM_PRIVATE_KEY,
+            canonicalization: 'simple/simple',
+          },
+        ],
+      };
+
+      const transport = new SmtpTransport({
+        ...config.smtp,
+        dkim: customDkimConfig,
+      });
+      const mailpitClient = new MailpitClient(config.mailpit);
+
+      await mailpitClient.deleteAllMessages();
+
+      try {
+        const message = createTestMessage({
+          subject: 'Test Email DKIM - Custom Canonicalization',
+          content: { text: 'Testing custom canonicalization' },
+        });
+
+        const receipt = await transport.send(message);
+        assert.strictEqual(receipt.successful, true);
+
+        const mailpitMessage = await waitForMailpitDelivery(
+          mailpitClient,
+          { subject: 'Test Email DKIM - Custom Canonicalization' },
+          5000,
+        );
+
+        const rawSource = await mailpitClient.getMessageSource(mailpitMessage.ID);
+
+        // Verify custom canonicalization is used
+        assert.ok(rawSource.includes('c=simple/simple'), 'Should use custom canonicalization');
+      } finally {
+        await teardownTest(transport);
+      }
+    });
+  },
+);
diff --git a/tests/mailpit/smtp-transport.mailpit.test.js b/tests/mailpit/smtp-transport.mailpit.test.js
new file mode 100644
index 0000000..6a82ef0
--- /dev/null
+++ b/tests/mailpit/smtp-transport.mailpit.test.js
@@ -0,0 +1,533 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-transport.mailpit.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { SmtpTransport } = require('../../src/smtp/index.js');
+const assert = require('node:assert/strict');
+const { Buffer } = require('node:buffer');
+const { describe, test } = require('node:test');
+const { MailpitClient } = require('../helpers/smtp/mailpit-client.js');
+const {
+  validateMailpitAttachments,
+  validateMailpitEmailContent,
+  waitForMailpitDelivery,
+} = require('../helpers/smtp/mailpit-delivery-utils.js');
+const {
+  createTestMessage,
+  getTestConfig,
+  isMailpitTestingEnabled,
+} = require('../helpers/smtp/test-config.js');
+
+describe('SMTP Transport Mailpit Tests', { skip: !isMailpitTestingEnabled() }, () => {
+  if (!isMailpitTestingEnabled()) return;
+
+  const setupTest = async (overrides = {}) => {
+    const config = getTestConfig();
+    const transport = new SmtpTransport({
+      ...config.smtp,
+      ...overrides,
+    });
+    const mailpitClient = new MailpitClient(config.mailpit);
+
+    // Clear any existing messages
+    await mailpitClient.deleteAllMessages();
+
+    return { transport, mailpitClient, config };
+  };
+
+  const teardownTest = async (transport) => {
+    await transport.closeAllConnections();
+  };
+
+  test('should deliver original raw MIME through Mailpit', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    const subject = 'Raw MIME Mailpit delivery';
+    const raw = `From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: ${subject}\r\nMessage-ID: <raw-mailpit@example.com>\r\nX-Preserved: first\r\n second\r\n\r\n.leading dot\r\n`;
+    try {
+      const receipt = await transport.sendRaw({
+        envelope: {
+          from: 'sender@example.com',
+          to: ['recipient@example.com'],
+        },
+        content: Buffer.from(raw),
+        encoding: '7bit',
+      });
+      assert.ok(receipt.successful, JSON.stringify(receipt));
+      const delivered = await waitForMailpitDelivery(mailpitClient, {
+        subject,
+      });
+      const source = await mailpitClient.getMessageSource(delivered.ID);
+      assert.ok(source.endsWith(raw), source);
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should deliver the identity and threading fields', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    try {
+      const subject = 'Test Email Mailpit - Identity';
+      const message = createTestMessage({
+        subject,
+        content: { text: 'Correlating a reply back to a conversation.' },
+        messageId: 'ticket-4821@example.com',
+        date: new Date('2026-09-01T10:00:00Z'),
+        inReplyTo: ['122@example.com'],
+        references: ['120@example.com', '121@example.com'],
+      });
+
+      const receipt = await transport.send(message);
+      assert.ok(receipt.successful);
+
+      const delivered = await waitForMailpitDelivery(mailpitClient, { subject });
+      const source = await mailpitClient.getMessageSource(delivered.ID);
+
+      assert.strictEqual(delivered.MessageID, 'ticket-4821@example.com');
+      assert.ok(
+        source.includes('Message-ID: <ticket-4821@example.com>'),
+        'the supplied identifier should reach the server unchanged',
+      );
+      assert.ok(source.includes('Date: Tue, 01 Sep 2026 10:00:00 +0000'));
+      assert.ok(source.includes('In-Reply-To: <122@example.com>'));
+      assert.ok(source.includes('References: <120@example.com> <121@example.com>'));
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should deliver a calendar invitation Mailpit can parse', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    try {
+      const subject = 'Test Email Mailpit - Calendar';
+      const ics =
+        [
+          'BEGIN:VCALENDAR',
+          'VERSION:2.0',
+          'PRODID:-//Upyo//Mailpit//EN',
+          'METHOD:REQUEST',
+          'BEGIN:VEVENT',
+          'UID:mailpit-calendar@example.com',
+          'DTSTAMP:20260901T100000Z',
+          'DTSTART:20260902T120000Z',
+          'SUMMARY:점심 식사',
+          'END:VEVENT',
+          'END:VCALENDAR',
+        ].join('\r\n') + '\r\n';
+
+      const receipt = await transport.send(
+        createTestMessage({
+          subject,
+          content: { text: 'Lunch on Wednesday.' },
+          calendar: { method: 'REQUEST', content: ics },
+        }),
+      );
+      assert.ok(receipt.successful);
+
+      const delivered = await waitForMailpitDelivery(mailpitClient, { subject });
+      const source = await mailpitClient.getMessageSource(delivered.ID);
+
+      assert.ok(
+        source.includes('Content-Type: text/calendar; charset=utf-8; method=REQUEST'),
+        'the calendar part should keep its method parameter',
+      );
+      assert.ok(source.includes('Content-Type: multipart/alternative'));
+
+      // The Base64 payload has to decode back to the object as written,
+      // including the multi-byte SUMMARY and the CRLF line endings.
+      const marker = source.indexOf('Content-Type: text/calendar');
+      const bodyStart = source.indexOf('\r\n\r\n', marker) + 4;
+      const bodyEnd = source.indexOf('\r\n--', bodyStart);
+      const payload = source.slice(bodyStart, bodyEnd).replace(/\r\n/g, '');
+      assert.equal(Buffer.from(payload, 'base64').toString('utf8'), ics);
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should send a basic email to Mailpit', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    try {
+      const message = createTestMessage({
+        senderEmail: 'john@example.com',
+        recipientEmail: 'jane@example.com',
+        subject: 'Test Email Mailpit - Basic',
+        content: { text: 'This is a test email sent to Mailpit' },
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+      if (receipt.successful) {
+        assert.ok(receipt.messageId.length > 0);
+      }
+
+      // Wait for email to be received by Mailpit
+      const mailpitMessage = await waitForMailpitDelivery(
+        mailpitClient,
+        { subject: 'Test Email Mailpit - Basic' },
+        5000,
+      );
+
+      validateMailpitEmailContent(mailpitMessage, {
+        from: 'john@example.com',
+        to: 'jane@example.com',
+        subject: 'Test Email Mailpit - Basic',
+        textBody: 'This is a test email sent to Mailpit',
+      });
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should send email with HTML content to Mailpit', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    try {
+      const message = createTestMessage({
+        senderEmail: 'john@example.com',
+        recipientEmail: 'jane@example.com',
+        subject: 'Test Email Mailpit - HTML',
+        content: {
+          html: '<h1>HTML Email</h1><p>This is an <strong>HTML</strong> email sent to Mailpit</p>',
+        },
+      });
+
+      const receipt = await transport.send(message);
+      assert.strictEqual(receipt.successful, true);
+
+      const mailpitMessage = await waitForMailpitDelivery(
+        mailpitClient,
+        { subject: 'Test Email Mailpit - HTML' },
+        5000,
+      );
+
+      validateMailpitEmailContent(mailpitMessage, {
+        from: 'john@example.com',
+        to: 'jane@example.com',
+        subject: 'Test Email Mailpit - HTML',
+        htmlBody:
+          '<h1>HTML Email</h1><p>This is an <strong>HTML</strong> email sent to Mailpit</p>',
+      });
+
+      assert.ok(mailpitMessage.HTML?.includes('<h1>HTML Email</h1>'));
+      assert.ok(mailpitMessage.HTML?.includes('<strong>HTML</strong>'));
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should send email with attachments to Mailpit', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    try {
+      const textContent = 'Hello from attachment test!';
+      const textBytes = new TextEncoder().encode(textContent);
+
+      const message = createTestMessage({
+        subject: 'Test Email Mailpit - Attachments',
+        content: { text: 'This email has attachments' },
+        attachments: [
+          {
+            filename: 'test.txt',
+            contentType: 'text/plain',
+            content: textBytes,
+            contentId: 'test-attachment',
+            inline: false,
+          },
+        ],
+      });
+
+      const receipt = await transport.send(message);
+      assert.strictEqual(receipt.successful, true);
+
+      const mailpitMessage = await waitForMailpitDelivery(
+        mailpitClient,
+        { subject: 'Test Email Mailpit - Attachments' },
+        5000,
+      );
+
+      validateMailpitEmailContent(mailpitMessage, {
+        from: 'john@example.com',
+        to: 'jane@example.com',
+        subject: 'Test Email Mailpit - Attachments',
+        textBody: 'This email has attachments',
+      });
+
+      validateMailpitAttachments(mailpitMessage, [
+        {
+          filename: 'test.txt',
+          contentType: 'text/plain',
+        },
+      ]);
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should send email with multiple recipients to Mailpit', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    try {
+      const message = createTestMessage({
+        subject: 'Test Email Mailpit - Multiple Recipients',
+        recipients: [{ address: 'recipient1@example.com' }, { address: 'recipient2@example.com' }],
+        ccRecipients: [{ address: 'cc@example.com' }],
+        content: { text: 'This email has multiple recipients' },
+      });
+
+      const receipt = await transport.send(message);
+      assert.strictEqual(receipt.successful, true);
+
+      const mailpitMessage = await waitForMailpitDelivery(
+        mailpitClient,
+        { subject: 'Test Email Mailpit - Multiple Recipients' },
+        5000,
+      );
+
+      // Verify that all recipients are present
+      const allRecipients = [...(mailpitMessage.To || []), ...(mailpitMessage.Cc || [])].map(
+        (addr) => addr.Address,
+      );
+
+      assert.ok(allRecipients.includes('recipient1@example.com'));
+      assert.ok(allRecipients.includes('recipient2@example.com'));
+      assert.ok(allRecipients.includes('cc@example.com'));
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should handle non-ASCII characters in Mailpit', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    try {
+      const message = createTestMessage({
+        subject: 'Test Email Mailpit - 한글 테스트 🌍',
+        content: {
+          text: '안녕하세요! This email contains Korean characters and emojis 🚀',
+        },
+      });
+
+      const receipt = await transport.send(message);
+      assert.strictEqual(receipt.successful, true);
+
+      const mailpitMessage = await waitForMailpitDelivery(
+        mailpitClient,
+        { subject: 'Test Email Mailpit - 한글 테스트 🌍' },
+        5000,
+      );
+
+      validateMailpitEmailContent(mailpitMessage, {
+        from: 'john@example.com',
+        to: 'jane@example.com',
+        subject: 'Test Email Mailpit - 한글 테스트 🌍',
+        textBody: '안녕하세요! This email contains Korean characters and emojis 🚀',
+      });
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should send multiple emails with sendMany to Mailpit', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    try {
+      const messages = [
+        createTestMessage({
+          subject: 'Test Email Mailpit - Batch 1',
+          content: { text: 'First email' },
+        }),
+        createTestMessage({
+          subject: 'Test Email Mailpit - Batch 2',
+          content: { text: 'Second email' },
+        }),
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.strictEqual(receipts.length, 2);
+      assert.ok(receipts.every((r) => r.successful));
+
+      // Wait for both emails to be received
+      const message1 = await waitForMailpitDelivery(
+        mailpitClient,
+        { subject: 'Test Email Mailpit - Batch 1' },
+        30000,
+      );
+
+      const message2 = await waitForMailpitDelivery(
+        mailpitClient,
+        { subject: 'Test Email Mailpit - Batch 2' },
+        30000,
+      );
+
+      assert.ok(message1.Text && message1.Text.includes('First email'));
+      assert.ok(message2.Text && message2.Text.includes('Second email'));
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should send email with required STARTTLS', async () => {
+    const { transport, mailpitClient, config } = await setupTest({
+      requireTls: true,
+    });
+    try {
+      // The test Mailpit instance is configured with a self-signed
+      // certificate and advertises STARTTLS.
+      const message = createTestMessage({
+        subject: 'Test Email Mailpit - STARTTLS',
+        content: {
+          text: 'This email was sent using STARTTLS for secure connection upgrade',
+        },
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.ok(
+        receipt.successful,
+        receipt.successful ? undefined : receipt.errorMessages.join(' '),
+      );
+      if (receipt.successful) {
+        assert.ok(receipt.messageId.length > 0);
+      }
+
+      // Wait for email to be received by Mailpit
+      const mailpitMessage = await waitForMailpitDelivery(
+        mailpitClient,
+        { subject: 'Test Email Mailpit - STARTTLS' },
+        5000,
+      );
+
+      validateMailpitEmailContent(mailpitMessage, {
+        from: 'sender@example.com',
+        to: 'recipient@example.com',
+        subject: 'Test Email Mailpit - STARTTLS',
+        textBody: 'This email was sent using STARTTLS for secure connection upgrade',
+      });
+
+      // Verify that the connection config doesn't have secure=true
+      // (meaning it started as plaintext and upgraded via STARTTLS)
+      assert.strictEqual(
+        config.smtp.secure,
+        false,
+        'Connection should start as plaintext before STARTTLS upgrade',
+      );
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+
+  test('should handle long CJK text with quoted-printable encoding in Mailpit', async () => {
+    const { transport, mailpitClient } = await setupTest();
+    try {
+      // Create long Korean text that will trigger quoted-printable line breaks
+      const longKoreanText = [
+        '안녕하세요! 이것은 매우 긴 한국어 텍스트입니다.',
+        'quoted-printable 인코딩이 제대로 작동하는지 확인하기 위해 작성된 테스트입니다.',
+        '이 텍스트는 76자 제한을 초과하여 소프트 라인 브레이크가 적용되어야 합니다.',
+        '한국어, 일본어(こんにちは), 중국어(你好) 등 다양한 CJK 문자들이 포함되어 있습니다.',
+        '이모지도 포함됩니다: 👋 🌍 💬 🚀 ✨',
+        '이 모든 문자들이 이메일 클라이언트에서 올바르게 표시되어야 합니다.',
+      ].join(' ');
+
+      const longJapaneseText = [
+        'こんにちは！これは非常に長い日本語のテキストです。',
+        'quoted-printableエンコーディングが正しく動作するかを確認するために作成されたテストです。',
+        'このテキストは76文字制限を超えてソフトラインブレークが適用されるはずです。',
+        '日本語、韓国語(안녕하세요), 中国語(你好)など様々なCJK文字が含まれています。',
+      ].join(' ');
+
+      const message = createTestMessage({
+        senderName: '김테스트',
+        senderEmail: 'test@example.com',
+        recipients: [{ name: '田中太郎', address: 'tanaka@example.com' }],
+        subject: '긴 CJK 텍스트 테스트 - Long CJK Text Test - 長いCJKテキストテスト',
+        content: {
+          text: longKoreanText,
+          html: `
+              <h1>긴 CJK 텍스트 테스트</h1>
+              <h2>한국어 텍스트</h2>
+              <p>${longKoreanText}</p>
+              <h2>일본어 텍스트</h2>
+              <p>${longJapaneseText}</p>
+              <h2>중국어 텍스트</h2>
+              <p>你好！这是一个很长的中文文本测试。我们需要确保quoted-printable编码能够正确处理这些字符。</p>
+              <h2>이모지 테스트</h2>
+              <p>🌟 ✨ 🎉 🚀 💻 📧 🔧 ⚡ 🌍 🇰🇷 🇯🇵 🇨🇳</p>
+            `,
+        },
+      });
+
+      const receipt = await transport.send(message);
+      assert.strictEqual(receipt.successful, true);
+
+      const mailpitMessage = await waitForMailpitDelivery(
+        mailpitClient,
+        {
+          subject: '긴 CJK 텍스트 테스트 - Long CJK Text Test - 長いCJKテキストテスト',
+        },
+        10000,
+      );
+
+      // Verify that the subject and content are correctly decoded
+      assert.ok(
+        mailpitMessage.Subject.includes('긴 CJK 텍스트 테스트'),
+        'Korean subject should be correctly decoded',
+      );
+      assert.ok(
+        mailpitMessage.Subject.includes('Long CJK Text Test'),
+        'English subject should be correctly decoded',
+      );
+      assert.ok(
+        mailpitMessage.Subject.includes('長いCJKテキストテスト'),
+        'Japanese subject should be correctly decoded',
+      );
+
+      // Verify text content
+      assert.ok(
+        mailpitMessage.Text?.includes('quoted-printable 인코딩이 제대로 작동하는지'),
+        'Korean text should be correctly decoded',
+      );
+      assert.ok(
+        mailpitMessage.Text?.includes('다양한 CJK 문자들이 포함되어 있습니다'),
+        'Korean text should be correctly decoded',
+      );
+      assert.ok(
+        mailpitMessage.Text?.includes('👋 🌍 💬 🚀 ✨'),
+        'Emoji should be correctly decoded',
+      );
+
+      // Verify HTML content
+      assert.ok(
+        mailpitMessage.HTML?.includes('<h1>긴 CJK 텍스트 테스트</h1>'),
+        'Korean HTML should be correctly decoded',
+      );
+      assert.ok(
+        mailpitMessage.HTML?.includes('quoted-printableエンコーディングが正しく動作するか'),
+        'Japanese HTML should be correctly decoded',
+      );
+      assert.ok(
+        mailpitMessage.HTML?.includes('quoted-printable编码能够正确处理这些字符'),
+        'Chinese HTML should be correctly decoded',
+      );
+      assert.ok(
+        mailpitMessage.HTML?.includes('🌟 ✨ 🎉 🚀 💻 📧 🔧 ⚡ 🌍 🇰🇷 🇯🇵 🇨🇳'),
+        'Emoji in HTML should be correctly decoded',
+      );
+
+      // Verify sender and recipient names are correctly decoded
+      // Note: Mailpit may parse encoded headers differently, so we check if the Korean name is present
+      assert.ok(
+        mailpitMessage.From?.Name?.includes('김테스트') ||
+          mailpitMessage.From?.Address?.includes('김테스트'),
+        'Korean sender name should be correctly decoded and present in From field',
+      );
+      assert.ok(
+        mailpitMessage.To?.some(
+          (to) => to.Name?.includes('田中太郎') || to.Address?.includes('田中太郎'),
+        ) || mailpitMessage.To?.length === 0, // Mailpit might not populate To array correctly
+        'Japanese recipient name should be correctly decoded or To field handling may vary',
+      );
+    } finally {
+      await teardownTest(transport);
+    }
+  });
+});
diff --git a/tests/types/smtp.test-d.ts b/tests/types/smtp.test-d.ts
new file mode 100644
index 0000000..32c1499
--- /dev/null
+++ b/tests/types/smtp.test-d.ts
@@ -0,0 +1,45 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import {
+  createMessage,
+  type RawTransport,
+  type Receipt,
+  type VerifiableTransport,
+} from '../../index.js';
+import {
+  SmtpTransport,
+  SmtpResponseError,
+  isSmtpResponseProviderDetails,
+  type DkimConfig,
+  type SmtpConfig,
+} from '../../src/smtp/index.js';
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  auth: { user: 'alex', pass: 'secret', method: 'login' },
+  tls: { rejectUnauthorized: true, minVersion: 'TLSv1.2' },
+});
+expectAssignable<RawTransport<'smtp'>>(transport);
+expectAssignable<VerifiableTransport<'smtp'>>(transport);
+expectAssignable<AsyncDisposable>(transport);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<void>>(transport.verify());
+expectAssignable<Promise<Receipt<'smtp'>>>(transport.send(message));
+expectType<Promise<void>>(transport.closeAllConnections());
+
+expectAssignable<SmtpConfig>({
+  host: 'smtp.example.com',
+  auth: { user: 'alex', accessToken: 'token' },
+  dkim: { signatures: [] } satisfies DkimConfig,
+});
+expectAssignable<Error>(new SmtpResponseError('Rejected', 550, 'RCPT', 'No such user'));
+expectType<boolean>(isSmtpResponseProviderDetails(undefined));
+
+expectError(new SmtpTransport({ port: 25 }));
+expectError(new SmtpTransport({ host: 'smtp.example.com', port: '25' }));
diff --git a/tests/unit/graph.test.js b/tests/unit/graph.test.js
index c68bdca..adb455f 100644
--- a/tests/unit/graph.test.js
+++ b/tests/unit/graph.test.js
@@ -81,7 +81,15 @@ test('Graph: the modules of src/ require each other without a cycle', () => {
 const SUBPATHS = Object.keys(pkg.exports)
   .filter((subpath) => subpath !== '.')
   .map((subpath) => pkg.exports[subpath].default.split('/')[2]);
-const SUBPATH_EDGES = [];
+// ./smtp renders and signs through the internal modules of ./mime, which
+// upstream exported as @upyo/mime/internal.
+const SUBPATH_EDGES = [
+  'smtp/config.js -> mime/dkim/types.js',
+  'smtp/message-converter.js -> mime/message.js',
+  'smtp/message-converter.js -> mime/stream.js',
+  'smtp/message-stream.js -> mime/stream.js',
+  'smtp/smtp-transport.js -> mime/dkim/types.js',
+];
 
 const subpathOf = (name) => {
   const top = name.split('/')[0];
diff --git a/tests/unit/smtp-attachment-stream.integration.test.js b/tests/unit/smtp-attachment-stream.integration.test.js
new file mode 100644
index 0000000..b3e29c7
--- /dev/null
+++ b/tests/unit/smtp-attachment-stream.integration.test.js
@@ -0,0 +1,263 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/attachment-stream.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const { SmtpTransport } = require('../../src/smtp/smtp-transport.js');
+const { createSmtpConfig } = require('../../src/smtp/config.js');
+const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+const { TEST_DKIM_PRIVATE_KEY } = require('../helpers/smtp/dkim-test-keys.js');
+
+const message = (content) => {
+  return createMessage({
+    from: 'from@example.com',
+    to: 'to@example.com',
+    subject: 'Test',
+    content: { text: 'Test' },
+    attachments: {
+      filename: 'a.bin',
+      content,
+      contentType: 'application/octet-stream',
+      contentId: 'a',
+      inline: false,
+    },
+  });
+};
+
+for (const streaming of [false, true]) {
+  test(`nonempty single-byte reads refresh ${streaming ? 'preparation' : 'DATA'} inactivity`, async () => {
+    const server = new MockSmtpServer();
+    server.on('error', () => {});
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port: await server.start(),
+      pool: false,
+      socketTimeout: 180,
+      dkim: streaming
+        ? {
+            bodyMode: 'streaming',
+            signatures: [
+              {
+                signingDomain: 'example.com',
+                selector: 'test',
+                privateKey: TEST_DKIM_PRIVATE_KEY,
+              },
+            ],
+          }
+        : undefined,
+    });
+    try {
+      const receipt = await transport.send(
+        message(async function* () {
+          for (let i = 0; i < 4; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            yield new Uint8Array([i]);
+          }
+        }),
+      );
+      assert.ok(receipt.successful, JSON.stringify(receipt));
+    } finally {
+      await transport.closeAllConnections();
+      await server.stop();
+    }
+  });
+}
+
+test('rejects invalid DKIM body modes eagerly', () => {
+  const config = {
+    host: 'localhost',
+    dkim: { signatures: [], bodyMode: 'invalid' },
+  };
+  // @ts-expect-error Exercise an invalid JavaScript configuration.
+  assert.throws(() => new SmtpTransport(config), TypeError);
+  // @ts-expect-error Exercise an invalid JavaScript configuration.
+  assert.throws(() => createSmtpConfig(config), TypeError);
+});
+
+for (const asynchronous of [false, true]) {
+  test(`does not reuse failed DATA in ${asynchronous ? 'async' : 'sync'} sendMany`, async () => {
+    const server = new MockSmtpServer();
+    server.on('error', () => {});
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port: await server.start(),
+      pool: true,
+    });
+    let secondReads = 0;
+    const messages = [
+      message(async function* () {
+        yield new Uint8Array([1]);
+        throw new TypeError('Read failed.');
+      }),
+      message(async function* () {
+        secondReads++;
+        yield new Uint8Array([2]);
+      }),
+    ];
+    try {
+      const source = asynchronous
+        ? (async function* () {
+            yield* messages;
+          })()
+        : messages;
+      const receipts = [];
+      for await (const receipt of transport.sendMany(source)) {
+        receipts.push(receipt);
+      }
+      assert.equal(receipts.length, 2);
+      assert.ok(receipts.every((receipt) => !receipt.successful));
+      assert.equal(secondReads, 0);
+      assert.equal(server.getReceivedMessages().length, 0);
+    } finally {
+      await transport.closeAllConnections();
+      await server.stop();
+    }
+  });
+}
+
+test('unsigned sources open after DATA and replay on repeated sends', async () => {
+  const server = new MockSmtpServer();
+  server.on('error', () => {});
+  server.setCapabilities(['SIZE 100000']);
+  const transport = new SmtpTransport({
+    host: 'localhost',
+    port: await server.start(),
+    pool: true,
+  });
+  let reads = 0;
+  const mail = message(async function* () {
+    assert.equal(server.getReceivedCommands().at(-1), 'DATA');
+    reads++;
+    yield new Uint8Array([1, 2, 3]);
+  });
+  try {
+    assert.ok((await transport.send(mail)).successful);
+    assert.ok((await transport.send(mail)).successful);
+    assert.equal(reads, 2);
+    assert.ok(
+      server
+        .getReceivedCommands()
+        .filter((c) => c.startsWith('MAIL '))
+        .every((c) => !c.includes('SIZE=')),
+    );
+    assert.ok(server.getReceivedMessages()[0].data.includes('AQID'));
+  } finally {
+    await transport.closeAllConnections();
+    await server.stop();
+  }
+});
+
+test('unknown oversized sources poison DATA but not the next pooled send', async () => {
+  const server = new MockSmtpServer();
+  server.on('error', () => {});
+  server.setCapabilities(['SIZE 1000']);
+  const transport = new SmtpTransport({
+    host: 'localhost',
+    port: await server.start(),
+    pool: true,
+  });
+  let closed = false;
+  try {
+    const result = await transport.send(
+      message(async function* () {
+        try {
+          while (true) yield new Uint8Array(1024);
+        } finally {
+          closed = true;
+        }
+      }),
+    );
+    assert.ok(!result.successful);
+    if (!result.successful) {
+      assert.equal(result.errors?.[0].code, 'smtp.message-size-exceeded');
+    }
+    assert.equal(server.getReceivedMessages().length, 0);
+    assert.ok(closed);
+    assert.ok((await transport.send(message(new Uint8Array([1])))).successful);
+  } finally {
+    await transport.closeAllConnections();
+    await server.stop();
+  }
+});
+
+test('a changed DKIM replay never sends a DATA terminator', async () => {
+  const server = new MockSmtpServer();
+  server.on('error', () => {});
+  const transport = new SmtpTransport({
+    host: 'localhost',
+    port: await server.start(),
+    pool: false,
+    dkim: {
+      bodyMode: 'streaming',
+      signatures: [
+        {
+          signingDomain: 'example.com',
+          selector: 'test',
+          privateKey: TEST_DKIM_PRIVATE_KEY,
+        },
+      ],
+    },
+  });
+  let reads = 0;
+  try {
+    const result = await transport.send(
+      message(async function* () {
+        yield new Uint8Array([++reads]);
+      }),
+    );
+    assert.ok(!result.successful);
+    if (!result.successful) {
+      assert.equal(result.errors?.[0].code, 'smtp.attachment-replay-mismatch');
+    }
+    assert.equal(reads, 2);
+    assert.equal(server.getReceivedMessages().length, 0);
+  } finally {
+    await transport.closeAllConnections();
+    await server.stop();
+  }
+});
+
+for (const streaming of [false, true]) {
+  test(`times out a stalled source ${streaming ? 'before' : 'during'} DATA`, async () => {
+    const server = new MockSmtpServer();
+    server.on('error', () => {});
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port: await server.start(),
+      pool: false,
+      socketTimeout: 100,
+      dkim: streaming
+        ? {
+            bodyMode: 'streaming',
+            signatures: [
+              {
+                signingDomain: 'example.com',
+                selector: 'test',
+                privateKey: TEST_DKIM_PRIVATE_KEY,
+              },
+            ],
+          }
+        : undefined,
+    });
+    let sourceSignal;
+    try {
+      const result = await transport.send(
+        message((signal) => {
+          sourceSignal = signal;
+          return {
+            [Symbol.asyncIterator]() {
+              return { next: () => new Promise(() => {}) };
+            },
+          };
+        }),
+      );
+      assert.ok(!result.successful);
+      assert.ok(sourceSignal?.aborted);
+      assert.equal(server.getReceivedMessages().length, 0);
+    } finally {
+      await transport.closeAllConnections();
+      await server.stop();
+    }
+  });
+}
diff --git a/tests/unit/smtp-attachment-tls.integration.test.js b/tests/unit/smtp-attachment-tls.integration.test.js
new file mode 100644
index 0000000..37dcc95
--- /dev/null
+++ b/tests/unit/smtp-attachment-tls.integration.test.js
@@ -0,0 +1,121 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/attachment-tls.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { readFileSync } = require('node:fs');
+const path = require('node:path');
+const { createServer } = require('node:net');
+const { createSecureContext, createServer: createTlsServer, TLSSocket } = require('node:tls');
+const { createMessage } = require('../../src/core/message.js');
+const { SmtpTransport } = require('../../src/smtp/smtp-transport.js');
+
+const credentials = {
+  key: readFileSync(path.join(__dirname, '../fixtures/smtp/server-key.pem')),
+  cert: readFileSync(path.join(__dirname, '../fixtures/smtp/server-cert.pem')),
+};
+
+for (const implicit of [false, true]) {
+  for (const cancel of [false, true]) {
+    test(`${implicit ? 'implicit TLS' : 'STARTTLS'} ${cancel ? 'cancels' : 'streams'} attachment reads`, async () => {
+      const sockets = new Set();
+      let received = '';
+      let accepted = false;
+      const controller = new AbortController();
+      const handle = (socket, upgraded = false) => {
+        sockets.add(socket);
+        socket.on('error', () => {});
+        socket.on('close', () => sockets.delete(socket));
+        if (!upgraded) socket.write('220 ready\r\n');
+        let buffer = '';
+        let data = false;
+        const onData = (bytes) => {
+          buffer += Buffer.from(bytes).toString();
+          let end;
+          while ((end = buffer.indexOf('\r\n')) >= 0) {
+            const line = buffer.slice(0, end);
+            buffer = buffer.slice(end + 2);
+            if (data) {
+              if (line === '.') {
+                data = false;
+                accepted = true;
+                socket.write('250 accepted\r\n');
+              } else received += line + '\r\n';
+            } else if (line.startsWith('EHLO')) {
+              socket.write(
+                implicit || upgraded ? '250 ready\r\n' : '250-ready\r\n250 STARTTLS\r\n',
+              );
+            } else if (line === 'STARTTLS') {
+              socket.off('data', onData);
+              socket.write('220 upgrade\r\n');
+              const tls = new TLSSocket(socket, {
+                isServer: true,
+                secureContext: createSecureContext(credentials),
+              });
+              handle(tls, true);
+              return;
+            } else if (line === 'DATA') {
+              data = true;
+              socket.write('354 go\r\n');
+            } else if (line === 'QUIT') socket.end('221 bye\r\n');
+            else socket.write('250 OK\r\n');
+          }
+        };
+        socket.on('data', onData);
+      };
+      const server = implicit ? createTlsServer(credentials, handle) : createServer(handle);
+      await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+      const address = server.address();
+      assert.ok(address && typeof address !== 'string');
+      const transport = new SmtpTransport({
+        host: '127.0.0.1',
+        port: address.port,
+        secure: implicit,
+        requireTls: !implicit,
+        tls: { rejectUnauthorized: false },
+        pool: false,
+        socketTimeout: 2000,
+      });
+      let closed = false;
+      try {
+        const pending = transport.send(
+          createMessage({
+            from: 'from@example.com',
+            to: 'to@example.com',
+            subject: 'TLS',
+            content: { text: 'Test' },
+            attachments: {
+              filename: 'a.bin',
+              contentId: 'a',
+              inline: false,
+              contentType: 'application/octet-stream',
+              content: async function* (signal) {
+                try {
+                  yield new Uint8Array([1, 2, 3]);
+                  if (cancel) controller.abort(new TypeError('Canceled.'));
+                  signal?.throwIfAborted();
+                  yield new Uint8Array([4, 5, 6]);
+                } finally {
+                  closed = true;
+                }
+              },
+            },
+          }),
+          { signal: controller.signal },
+        );
+        if (cancel) {
+          await assert.rejects(pending, (error) => error === controller.signal.reason);
+        } else {
+          assert.ok((await pending).successful);
+          assert.ok(received.includes('AQIDBAUG'));
+        }
+        assert.equal(accepted, !cancel);
+        assert.ok(closed);
+      } finally {
+        await transport.closeAllConnections();
+        for (const socket of sockets) socket.destroy();
+        await new Promise((resolve) => server.close(() => resolve()));
+      }
+    });
+  }
+}
diff --git a/tests/unit/smtp-config.test.js b/tests/unit/smtp-config.test.js
new file mode 100644
index 0000000..612d949
--- /dev/null
+++ b/tests/unit/smtp-config.test.js
@@ -0,0 +1,64 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { createSmtpConfig } = require('../../src/smtp/config.js');
+
+describe('createSmtpConfig', () => {
+  test('should disable implicit TLS by default on port 587', () => {
+    const config = createSmtpConfig({ host: 'smtp.example.com' });
+
+    assert.equal(config.port, 587);
+    assert.ok(!config.secure);
+  });
+
+  test('should enable implicit TLS by default on port 465', () => {
+    const config = createSmtpConfig({
+      host: 'smtp.example.com',
+      port: 465,
+    });
+
+    assert.ok(config.secure);
+  });
+
+  test('should disable implicit TLS by default on other ports', () => {
+    const config = createSmtpConfig({
+      host: 'smtp.example.com',
+      port: 25,
+    });
+
+    assert.ok(!config.secure);
+  });
+
+  test('should preserve explicit implicit TLS settings', () => {
+    const secureConfig = createSmtpConfig({
+      host: 'smtp.example.com',
+      port: 587,
+      secure: true,
+    });
+    const insecureConfig = createSmtpConfig({
+      host: 'smtp.example.com',
+      port: 465,
+      secure: false,
+    });
+
+    assert.ok(secureConfig.secure);
+    assert.ok(!insecureConfig.secure);
+  });
+
+  test('should not require TLS by default', () => {
+    const config = createSmtpConfig({ host: 'smtp.example.com' });
+
+    assert.ok(!config.requireTls);
+  });
+
+  test('should preserve an explicit TLS requirement', () => {
+    const config = createSmtpConfig({
+      host: 'smtp.example.com',
+      requireTls: true,
+    });
+
+    assert.ok(config.requireTls);
+  });
+});
diff --git a/tests/unit/smtp-connection-lifecycle.test.js b/tests/unit/smtp-connection-lifecycle.test.js
new file mode 100644
index 0000000..5684dd2
--- /dev/null
+++ b/tests/unit/smtp-connection-lifecycle.test.js
@@ -0,0 +1,72 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-connection-lifecycle.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { Socket } = require('node:net');
+const { SmtpConnection } = require('../../src/smtp/smtp-connection.js');
+
+for (const event of ['timeout', 'close']) {
+  test(`settles a stalled TCP connect promptly on ${event}`, async () => {
+    const connection = new SmtpConnection({
+      host: 'localhost',
+      port: 25,
+      connectionTimeout: 1000,
+      socketTimeout: 50,
+    });
+    const connect = Socket.prototype.connect;
+    let pending;
+    // Isolate the handshake without depending on a network blackhole.
+    Socket.prototype.connect = function () {
+      return this;
+    };
+    try {
+      pending = connection.connect();
+    } finally {
+      Socket.prototype.connect = connect;
+    }
+    let settled = false;
+    const checked = assert.rejects(pending, (error) => {
+      assert.ok(error instanceof Error);
+      if (event === 'timeout') assert.match(error.message, /Socket timeout/);
+      settled = true;
+      return true;
+    });
+    connection.socket.emit(event);
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      assert.ok(settled, 'The connect promise still waits for connectionTimeout.');
+    } finally {
+      connection.socket?.destroy();
+      await checked;
+      await connection.quit();
+    }
+  });
+}
+
+test('cancels a stalled TCP connect with the original reason', async () => {
+  const connection = new SmtpConnection({
+    host: 'localhost',
+    port: 25,
+    connectionTimeout: 5000,
+  });
+  const connect = Socket.prototype.connect;
+  const controller = new AbortController();
+  let pending;
+  Socket.prototype.connect = function () {
+    return this;
+  };
+  try {
+    pending = connection.connect(controller.signal);
+  } finally {
+    Socket.prototype.connect = connect;
+  }
+  const checked = assert.rejects(pending, (e) => e === 'cancel TCP');
+  controller.abort('cancel TCP');
+  try {
+    await checked;
+    assert.ok(connection.socket?.destroyed);
+  } finally {
+    await connection.quit();
+  }
+});
diff --git a/tests/unit/smtp-connection.integration.test.js b/tests/unit/smtp-connection.integration.test.js
new file mode 100644
index 0000000..2c19e06
--- /dev/null
+++ b/tests/unit/smtp-connection.integration.test.js
@@ -0,0 +1,1471 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-connection.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { Socket } = require('node:net');
+const { describe, test } = require('node:test');
+const {
+  SmtpConnection,
+  SmtpMessageSizeError,
+  SmtpResponseError,
+  SmtpUtf8UnsupportedError,
+} = require('../../src/smtp/smtp-connection.js');
+const { SmtpAuthError } = require('../../src/smtp/oauth2.js');
+const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+
+describe('SMTP Connection Integration Tests', () => {
+  const setupTest = async (configOverrides = {}, signal) => {
+    signal?.throwIfAborted();
+
+    const server = new MockSmtpServer();
+    await server.start();
+    if (signal?.aborted) {
+      await server.stop();
+      signal.throwIfAborted();
+    }
+
+    const config = {
+      host: 'localhost',
+      port: server.getPort(),
+      secure: false,
+      connectionTimeout: 5000,
+      socketTimeout: 5000,
+      localName: 'test.local',
+      ...configOverrides,
+    };
+
+    const connection = new SmtpConnection(config);
+    return { server, connection };
+  };
+
+  const teardownTest = async (server, connection) => {
+    try {
+      await connection.quit();
+    } catch {
+      // Ignore errors during cleanup
+    }
+    await server.stop();
+    // Give the event loop time to clean up resources
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  };
+
+  const waitForCommandCount = (server, count, signal) => {
+    if (server.getReceivedCommands().length >= count) return Promise.resolve();
+
+    return new Promise((resolve, reject) => {
+      signal?.throwIfAborted();
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Timed out waiting for ${count} SMTP commands.`));
+      }, 5000);
+      const onCommand = () => {
+        if (server.getReceivedCommands().length >= count) {
+          cleanup();
+          resolve();
+        }
+      };
+      const onAbort = () => {
+        cleanup();
+        try {
+          signal?.throwIfAborted();
+        } catch (error) {
+          reject(error);
+        }
+      };
+      const cleanup = () => {
+        clearTimeout(timeout);
+        server.off('command', onCommand);
+        signal?.removeEventListener('abort', onAbort);
+      };
+
+      server.on('command', onCommand);
+      signal?.addEventListener('abort', onAbort, { once: true });
+    });
+  };
+
+  describe('Test setup', () => {
+    test('should not start the server when already aborted', async () => {
+      const controller = new AbortController();
+      const reason = new Error('Test setup aborted.');
+      controller.abort(reason);
+
+      const originalStart = MockSmtpServer.prototype.start;
+      let startCalled = false;
+      MockSmtpServer.prototype.start = function () {
+        startCalled = true;
+        return Promise.reject(new Error('Server should not start.'));
+      };
+
+      try {
+        await assert.rejects(
+          () => setupTest({}, controller.signal),
+          (error) => error === reason,
+        );
+      } finally {
+        MockSmtpServer.prototype.start = originalStart;
+      }
+
+      assert.ok(!startCalled);
+    });
+
+    test('should stop the server when aborted during startup', async () => {
+      const controller = new AbortController();
+      const reason = new Error('Test setup aborted.');
+      const originalStart = MockSmtpServer.prototype.start;
+      const originalStop = MockSmtpServer.prototype.stop;
+      let startedServer;
+      let stopCalls = 0;
+
+      MockSmtpServer.prototype.start = async function () {
+        startedServer = this;
+        const port = await originalStart.call(this);
+        controller.abort(reason);
+        return port;
+      };
+      MockSmtpServer.prototype.stop = async function () {
+        stopCalls++;
+        await originalStop.call(this);
+      };
+
+      try {
+        await assert.rejects(
+          () => setupTest({}, controller.signal),
+          (error) => error === reason,
+        );
+      } finally {
+        MockSmtpServer.prototype.start = originalStart;
+        MockSmtpServer.prototype.stop = originalStop;
+        if (startedServer != null && stopCalls === 0) {
+          await originalStop.call(startedServer);
+        }
+      }
+
+      assert.equal(stopCalls, 1);
+    });
+
+    test('should reject an already-aborted command wait', async () => {
+      const { server, connection } = await setupTest();
+      const controller = new AbortController();
+      const reason = new Error('Command wait aborted.');
+      controller.abort(reason);
+
+      try {
+        await assert.rejects(
+          () => waitForCommandCount(server, 1, controller.signal),
+          (error) => error === reason,
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+  });
+
+  describe('Connection Lifecycle', () => {
+    test('should establish connection successfully', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+
+        // Should be connected but not authenticated yet
+        assert.strictEqual(connection.authenticated, false);
+        assert.strictEqual(connection.capabilities.length, 0);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should receive server greeting', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+        const greeting = await connection.greeting();
+
+        assert.strictEqual(greeting.code, 220);
+        assert.ok(greeting.message.includes('Mock SMTP Server'));
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should perform EHLO handshake', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        // Should have received capabilities
+        assert.ok(connection.capabilities.length > 0);
+        assert.ok(connection.capabilities.includes('AUTH PLAIN LOGIN XOAUTH2 OAUTHBEARER'));
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    for (const responseCode of [500, 502]) {
+      test(`should fall back to HELO after EHLO ${responseCode}`, async () => {
+        const { server, connection } = await setupTest();
+        try {
+          server.setResponse('EHLO', {
+            code: responseCode,
+            message: 'Command not recognized',
+          });
+          await connection.connect();
+          await connection.greeting();
+          await connection.ehlo();
+
+          assert.deepStrictEqual(connection.capabilities, []);
+          assert.deepStrictEqual(server.getReceivedCommands().slice(0, 2), [
+            'EHLO test.local',
+            'HELO test.local',
+          ]);
+        } finally {
+          await teardownTest(server, connection);
+        }
+      });
+    }
+
+    test('should fail when the HELO fallback is rejected', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('EHLO', {
+          code: 500,
+          message: 'Command not recognized',
+        });
+        server.setResponse('HELO', {
+          code: 550,
+          message: 'Greeting rejected',
+        });
+        await connection.connect();
+        await connection.greeting();
+
+        await assert.rejects(
+          () => connection.ehlo(),
+          (error) => {
+            assert.ok(error instanceof SmtpResponseError);
+            assert.equal(error.code, 550);
+            assert.equal(error.command, 'HELO');
+            assert.equal(error.response, 'Greeting rejected');
+            return true;
+          },
+        );
+        assert.deepStrictEqual(server.getReceivedCommands().slice(0, 2), [
+          'EHLO test.local',
+          'HELO test.local',
+        ]);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should not fall back to HELO after a transient EHLO failure', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('EHLO', {
+          code: 421,
+          message: 'Service not available',
+        });
+        await connection.connect();
+        await connection.greeting();
+
+        await assert.rejects(
+          () => connection.ehlo(),
+          (error) => {
+            assert.ok(error instanceof SmtpResponseError);
+            assert.equal(error.code, 421);
+            assert.equal(error.command, 'EHLO');
+            assert.equal(error.response, 'Service not available');
+            return true;
+          },
+        );
+        assert.ok(!server.getReceivedCommands().some((command) => command.startsWith('HELO ')));
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should gracefully quit connection', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+        await connection.greeting();
+
+        await connection.quit();
+
+        // Connection should be reset
+        assert.strictEqual(connection.authenticated, false);
+        assert.strictEqual(connection.capabilities.length, 0);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+  });
+
+  describe('Authentication', () => {
+    const setupSimulatedAuthentication = (host, remoteAddress) => {
+      const connection = new SmtpConnection({
+        host,
+        port: 25,
+        secure: false,
+        auth: {
+          user: 'testuser',
+          pass: 'testpass',
+          method: 'plain',
+        },
+      });
+      const socket = new Socket();
+      if (remoteAddress != null) {
+        Object.defineProperty(socket, 'remoteAddress', {
+          configurable: true,
+          value: remoteAddress,
+        });
+      }
+      connection.socket = socket;
+      connection.capabilities = ['AUTH PLAIN LOGIN'];
+      connection.sendCommand = () =>
+        Promise.resolve({
+          code: 235,
+          message: 'Authentication successful',
+          raw: '235 Authentication successful',
+        });
+      return { connection, socket };
+    };
+
+    test('should skip authentication when no credentials provided', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        // Should not throw and should remain unauthenticated
+        await connection.authenticate();
+        assert.strictEqual(connection.authenticated, false);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should authenticate with PLAIN method', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        const authConfig = {
+          host: 'localhost',
+          port: server.getPort(),
+          secure: false,
+          auth: {
+            user: 'testuser',
+            pass: 'testpass',
+            method: 'plain',
+          },
+        };
+
+        const authConnection = new SmtpConnection(authConfig);
+
+        try {
+          await authConnection.connect();
+          await authConnection.greeting();
+          await authConnection.ehlo();
+          await authConnection.authenticate();
+
+          assert.strictEqual(authConnection.authenticated, true);
+        } finally {
+          await authConnection.quit();
+        }
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should authenticate with LOGIN method', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        const authConfig = {
+          host: 'localhost',
+          port: server.getPort(),
+          secure: false,
+          auth: {
+            user: 'testuser',
+            pass: 'testpass',
+            method: 'login',
+          },
+        };
+
+        const authConnection = new SmtpConnection(authConfig);
+
+        try {
+          await authConnection.connect();
+          await authConnection.greeting();
+          await authConnection.ehlo();
+          await authConnection.authenticate();
+
+          assert.strictEqual(authConnection.authenticated, true);
+        } finally {
+          await authConnection.quit();
+        }
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    for (const method of ['plain', 'login']) {
+      test(`should refuse ${method.toUpperCase()} over a cleartext non-loopback connection`, async () => {
+        const connection = new SmtpConnection({
+          host: 'smtp.example.com',
+          port: 25,
+          secure: false,
+          socketTimeout: 10,
+          auth: {
+            user: 'testuser',
+            pass: 'testpass',
+            method,
+          },
+        });
+        // Simulate a post-EHLO plaintext connection without dialing out.  The
+        // TLS guard must reject before either credential-bearing AUTH exchange
+        // can use the socket.
+        const socket = new Socket();
+        connection.socket = socket;
+        connection.capabilities = ['AUTH PLAIN LOGIN'];
+        try {
+          await assert.rejects(
+            connection.authenticate(),
+            (error) => error instanceof SmtpAuthError && /TLS/.test(error.message),
+          );
+          assert.ok(!connection.authenticated);
+        } finally {
+          socket.destroy();
+        }
+      });
+    }
+
+    for (const host of [
+      'LOCALHOST',
+      'localhost.',
+      'smtp.localhost',
+      '127.0.0.2',
+      '0::1',
+      '0:0:0:0:0:0::1',
+      '0:0:0:0:0:0:0:1',
+      '[::1]',
+      '[::0001]',
+    ]) {
+      test(`should recognize configured loopback host ${host}`, async () => {
+        const { connection, socket } = setupSimulatedAuthentication(host);
+        try {
+          await connection.authenticate();
+          assert.ok(connection.authenticated);
+        } finally {
+          socket.destroy();
+        }
+      });
+    }
+
+    for (const remoteAddress of [
+      '127.0.0.2',
+      '::1',
+      '0:0::1',
+      '0:0:0:0:0:0:0:1',
+      '::ffff:127.0.0.2',
+      '::ffff:7f00:2',
+      '0:0::ffff:127.0.0.2',
+    ]) {
+      test(`should recognize connected loopback address ${remoteAddress}`, async () => {
+        const { connection, socket } = setupSimulatedAuthentication(
+          'smtp.example.com',
+          remoteAddress,
+        );
+        try {
+          await connection.authenticate();
+          assert.ok(connection.authenticated);
+        } finally {
+          socket.destroy();
+        }
+      });
+    }
+
+    test('should prefer the connected address over the configured host', async () => {
+      const { connection, socket } = setupSimulatedAuthentication('localhost', '192.0.2.1');
+      try {
+        await assert.rejects(
+          connection.authenticate(),
+          (error) => error instanceof SmtpAuthError && /TLS/.test(error.message),
+        );
+        assert.ok(!connection.authenticated);
+      } finally {
+        socket.destroy();
+      }
+    });
+
+    test('should reject authentication with invalid credentials', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('AUTH', {
+          code: 535,
+          message: 'Authentication failed',
+        });
+
+        const authConfig = {
+          host: 'localhost',
+          port: server.getPort(),
+          secure: false,
+          auth: {
+            user: 'wronguser',
+            pass: 'wrongpass',
+          },
+        };
+
+        const authConnection = new SmtpConnection(authConfig);
+
+        try {
+          await authConnection.connect();
+          await authConnection.greeting();
+          await authConnection.ehlo();
+
+          await assert.rejects(authConnection.authenticate(), /Authentication failed/);
+
+          assert.strictEqual(authConnection.authenticated, false);
+        } finally {
+          await authConnection.quit();
+        }
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+  });
+
+  describe('STARTTLS', () => {
+    test('should send STARTTLS command successfully', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        // Note: Mock server doesn't actually upgrade to TLS
+        // It just responds with 220 but doesn't perform TLS handshake
+        // This test would timeout, so we skip the actual upgrade
+        // For real TLS testing, use integration tests with actual SMTP servers
+
+        // Just verify we can send the command and get a 220 response
+        const response = await connection.sendCommand('STARTTLS');
+        assert.strictEqual(response.code, 220);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should reject STARTTLS on already TLS socket', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        // This test verifies the logic check in starttls() method
+        // We can't easily test with a real TLS socket via the mock server
+        // but we can verify that calling starttls() checks for TLS socket type
+
+        // First establish a normal connection
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        // We can't easily create a real TLSSocket, so we'll verify
+        // the error check exists by reading the implementation
+        // For now, skip this test as it requires complex TLS mocking
+        // Real TLS servers like Mailpit will be used for integration testing
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should handle STARTTLS rejection', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('STARTTLS', {
+          code: 454,
+          message: 'TLS not available',
+        });
+
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await assert.rejects(connection.starttls(), (error) => {
+          assert.ok(error instanceof SmtpResponseError);
+          assert.equal(error.code, 454);
+          assert.equal(error.command, 'STARTTLS');
+          assert.equal(error.response, 'TLS not available');
+          return true;
+        });
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+  });
+
+  describe('Message Sending', () => {
+    test('should negotiate SMTPUTF8 for an internationalized envelope', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['sMtPuTf8 ignored-parameter', '8bItMiMe']);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await connection.sendMessage({
+          envelope: {
+            from: 'josé@example.com',
+            to: ['用户@example.com'],
+          },
+          raw: 'From: josé@example.com\r\n\r\nMessage',
+          requiresSmtpUtf8: true,
+        });
+
+        assert.ok(
+          server
+            .getReceivedCommands()
+            .includes('MAIL FROM:<josé@example.com> BODY=8BITMIME SMTPUTF8'),
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should reject SMTPUTF8 before MAIL FROM when unsupported', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['8BITMIME']);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await assert.rejects(
+          connection.sendMessage({
+            envelope: {
+              from: 'josé@example.com',
+              to: ['recipient@example.com'],
+            },
+            raw: 'Internationalized message',
+            requiresSmtpUtf8: true,
+          }),
+          SmtpUtf8UnsupportedError,
+        );
+        assert.ok(
+          !server.getReceivedCommands().some((command) => command.startsWith('MAIL FROM:')),
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should require 8BITMIME with SMTPUTF8', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['SMTPUTF8']);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await assert.rejects(
+          connection.sendMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['用户@example.com'],
+            },
+            raw: 'Internationalized message',
+            requiresSmtpUtf8: true,
+          }),
+          /8BITMIME/,
+        );
+        assert.ok(
+          !server.getReceivedCommands().some((command) => command.startsWith('MAIL FROM:')),
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should declare the RFC 1870 message size', async () => {
+      const { server, connection } = await setupTest();
+      const raw = 'Subject: SIZE test\r\n\r\n.안녕하세요';
+      const messageSize = new TextEncoder().encode(`${raw}\r\n`).byteLength;
+      try {
+        server.setCapabilities([`sIzE ${messageSize}`]);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await connection.sendMessage({
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw,
+        });
+
+        assert.ok(
+          server
+            .getReceivedCommands()
+            .includes(`MAIL FROM:<sender@example.com> SIZE=${messageSize}`),
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should reject a message above the advertised SIZE limit', async () => {
+      const { server, connection } = await setupTest();
+      const raw = 'Oversized message';
+      const messageSize = new TextEncoder().encode(`${raw}\r\n`).byteLength;
+      try {
+        server.setCapabilities([`SIZE ${messageSize - 1}`]);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await assert.rejects(
+          connection.sendMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['recipient@example.com'],
+            },
+            raw,
+          }),
+          new SmtpMessageSizeError(messageSize, BigInt(messageSize - 1)),
+        );
+        assert.ok(
+          !server.getReceivedCommands().some((command) => command.startsWith('MAIL FROM:')),
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should declare size when SIZE has no maximum', async () => {
+      const { server, connection } = await setupTest();
+      const raw = 'Message without a fixed maximum';
+      const messageSize = new TextEncoder().encode(`${raw}\r\n`).byteLength;
+      try {
+        server.setCapabilities(['SIZE']);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await connection.sendMessage({
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw,
+        });
+
+        assert.ok(
+          server
+            .getReceivedCommands()
+            .includes(`MAIL FROM:<sender@example.com> SIZE=${messageSize}`),
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should treat a SIZE limit of zero as unlimited', async () => {
+      const { server, connection } = await setupTest();
+      const raw = 'Message with no fixed maximum';
+      const messageSize = new TextEncoder().encode(`${raw}\r\n`).byteLength;
+      try {
+        server.setCapabilities(['SIZE 0']);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await connection.sendMessage({
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw,
+        });
+
+        assert.ok(
+          server
+            .getReceivedCommands()
+            .includes(`MAIL FROM:<sender@example.com> SIZE=${messageSize}`),
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should omit size when SIZE is not advertised', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['HELP']);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await connection.sendMessage({
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw: 'Message for a server without SIZE',
+        });
+
+        assert.ok(server.getReceivedCommands().includes('MAIL FROM:<sender@example.com>'));
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should pipeline envelope commands when advertised', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['AUTH PLAIN', 'pIpElInInG', 'HELP']);
+        server.holdEnvelopeResponses();
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const sending = connection.sendMessage({
+          envelope: {
+            from: 'sender@example.com',
+            to: ['first@example.com', 'second@example.com'],
+          },
+          raw: 'Pipelined message',
+        });
+        // oxlint-disable-next-line no-void -- upstream
+        void sending.catch(() => undefined);
+
+        await waitForCommandCount(server, 4);
+        assert.deepStrictEqual(server.getReceivedCommands().slice(-3), [
+          'MAIL FROM:<sender@example.com>',
+          'RCPT TO:<first@example.com>',
+          'RCPT TO:<second@example.com>',
+        ]);
+
+        server.flushEnvelopeResponses();
+        const result = await sending;
+        assert.ok(result.messageId.length > 0);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should wait for each envelope reply without PIPELINING', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('EHLO', {
+          code: 250,
+          message: 'PIPELINING unavailable',
+        });
+        server.holdEnvelopeResponses();
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const sending = connection.sendMessage({
+          envelope: {
+            from: 'sender@example.com',
+            to: ['first@example.com', 'second@example.com'],
+          },
+          raw: 'Sequential message',
+        });
+        await waitForCommandCount(server, 2);
+        assert.deepStrictEqual(server.getReceivedCommands().slice(-1), [
+          'MAIL FROM:<sender@example.com>',
+        ]);
+
+        server.flushEnvelopeResponses();
+        const result = await sending;
+        assert.ok(result.messageId.length > 0);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should correlate multiline pipelined recipient replies', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['PIPELINING']);
+        server.setResponses('RCPT', [
+          {
+            code: 250,
+            continuationLines: ['2.1.5 Recipient accepted'],
+            message: '2.1.5 Will forward',
+          },
+          { code: 550, message: '5.1.1 No such user' },
+          { code: 251, message: '2.1.5 User not local; will forward' },
+        ]);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const result = await connection.sendMessage({
+          envelope: {
+            from: 'sender@example.com',
+            to: ['first@example.com', 'rejected@example.com', 'forwarded@example.com'],
+          },
+          raw: 'Mixed recipient message',
+        });
+
+        assert.deepStrictEqual(result.rejectedRecipients, [
+          {
+            recipient: 'rejected@example.com',
+            code: 550,
+            response: '5.1.1 No such user',
+            retryable: false,
+            enhancedStatusCode: {
+              code: '5.1.1',
+              class: 5,
+              subject: 1,
+              detail: 1,
+            },
+          },
+        ]);
+        assert.deepStrictEqual(server.getReceivedMessages()[0]?.to, [
+          'first@example.com',
+          'forwarded@example.com',
+        ]);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should treat a pipelined 421 reply as fatal', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['PIPELINING']);
+        server.setResponses('RCPT', [
+          { code: 250, message: '2.1.5 Recipient accepted' },
+          { code: 421, message: '4.3.2 Service shutting down' },
+        ]);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await assert.rejects(
+          connection.sendMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['first@example.com', 'second@example.com'],
+            },
+            raw: 'Connection failure message',
+          }),
+          (error) => {
+            assert.ok(error instanceof SmtpResponseError);
+            assert.strictEqual(error.code, 421);
+            assert.strictEqual(error.command, 'RCPT TO');
+            return true;
+          },
+        );
+        assert.ok(!server.getReceivedCommands().some((command) => command === 'DATA'));
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should preserve MAIL FROM 421 when the server closes', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['PIPELINING']);
+        server.setResponse('MAIL', {
+          code: 421,
+          message: '4.3.2 Service shutting down',
+          closeConnection: true,
+        });
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await assert.rejects(
+          connection.sendMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['first@example.com', 'second@example.com'],
+            },
+            raw: 'Connection failure message',
+          }),
+          (error) => {
+            assert.ok(error instanceof SmtpResponseError);
+            assert.strictEqual(error.code, 421);
+            assert.strictEqual(error.command, 'MAIL FROM');
+            assert.strictEqual(error.response, '4.3.2 Service shutting down');
+            return true;
+          },
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should preserve MAIL FROM 550 when the server closes', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['PIPELINING']);
+        server.setResponse('MAIL', {
+          code: 550,
+          message: '5.7.1 Sender address blocked',
+          closeConnection: true,
+        });
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await assert.rejects(
+          connection.sendMessage({
+            envelope: {
+              from: 'blocked@example.com',
+              to: ['first@example.com', 'second@example.com'],
+            },
+            raw: 'Blocked sender message',
+          }),
+          (error) => {
+            assert.ok(error instanceof SmtpResponseError);
+            assert.strictEqual(error.code, 550);
+            assert.strictEqual(error.command, 'MAIL FROM');
+            assert.strictEqual(error.response, '5.7.1 Sender address blocked');
+            return true;
+          },
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should preserve a non-final RCPT TO 421 on close', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setCapabilities(['PIPELINING']);
+        server.setResponses('RCPT', [
+          { code: 250, message: '2.1.5 Recipient accepted' },
+          {
+            code: 421,
+            message: '4.3.2 Service shutting down',
+            closeConnection: true,
+          },
+          { code: 250, message: '2.1.5 Recipient accepted' },
+        ]);
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await assert.rejects(
+          connection.sendMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['first@example.com', 'second@example.com', 'third@example.com'],
+            },
+            raw: 'Connection failure message',
+          }),
+          (error) => {
+            assert.ok(error instanceof SmtpResponseError);
+            assert.strictEqual(error.code, 421);
+            assert.strictEqual(error.command, 'RCPT TO');
+            assert.strictEqual(error.response, '4.3.2 Service shutting down');
+            assert.match(error.message, /second@example\.com/);
+            return true;
+          },
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should reset the pipeline timeout after each reply', async () => {
+      const { server, connection } = await setupTest({ socketTimeout: 1000 });
+      try {
+        server.setCapabilities(['PIPELINING']);
+        server.holdEnvelopeResponses();
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const sending = connection.sendMessage({
+          envelope: {
+            from: 'sender@example.com',
+            to: ['first@example.com', 'second@example.com'],
+          },
+          raw: 'Slow replies message',
+        });
+        // oxlint-disable-next-line no-void -- upstream
+        void sending.catch(() => undefined);
+
+        await waitForCommandCount(server, 4);
+        assert.ok(server.flushNextEnvelopeResponse());
+        await new Promise((resolve) => setTimeout(resolve, 600));
+        assert.ok(server.flushNextEnvelopeResponse());
+        await new Promise((resolve) => setTimeout(resolve, 600));
+        assert.ok(server.flushNextEnvelopeResponse());
+
+        const result = await sending;
+        assert.ok(result.messageId.length > 0);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should send message successfully', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const testMessage = {
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Test\r\n\r\nHello World!',
+        };
+
+        const result = await connection.sendMessage(testMessage);
+
+        assert.ok(result.messageId.length > 0);
+
+        // Verify message content was received
+        const receivedMessages = server.getReceivedMessages();
+        assert.strictEqual(receivedMessages.length, 1);
+        assert.strictEqual(receivedMessages[0].from, 'sender@example.com');
+        assert.deepStrictEqual(receivedMessages[0].to, ['recipient@example.com']);
+        assert.ok(receivedMessages[0].data.includes('Hello World!'));
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should accept a recipient that will be forwarded', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('RCPT', {
+          code: 251,
+          message: 'User not local; will forward',
+        });
+
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const testMessage = {
+          envelope: {
+            from: 'sender@example.com',
+            to: ['forwarded@example.com'],
+          },
+          raw: 'From: sender@example.com\r\nTo: forwarded@example.com\r\nSubject: Forwarded\r\n\r\nTest message',
+        };
+
+        const result = await connection.sendMessage(testMessage);
+
+        assert.ok(result.messageId.length > 0);
+        assert.strictEqual(server.getReceivedMessages().length, 1);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should send message to multiple recipients', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const testMessage = {
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient1@example.com', 'recipient2@example.com', 'recipient3@example.com'],
+          },
+          raw: 'From: sender@example.com\r\nTo: recipient1@example.com\r\nSubject: Multi-recipient\r\n\r\nMultiple recipients test',
+        };
+
+        const result = await connection.sendMessage(testMessage);
+        assert.ok(result.messageId.length > 0);
+
+        const receivedMessages = server.getReceivedMessages();
+        assert.strictEqual(receivedMessages.length, 1);
+        assert.strictEqual(receivedMessages[0].to.length, 3);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should handle MAIL FROM rejection', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('MAIL', {
+          code: 550,
+          message: 'Sender not allowed',
+        });
+
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const testMessage = {
+          envelope: {
+            from: 'blocked@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw: 'From: blocked@example.com\r\nTo: recipient@example.com\r\nSubject: Test\r\n\r\nTest message',
+        };
+
+        await assert.rejects(
+          connection.sendMessage(testMessage),
+          /MAIL FROM failed.*Sender not allowed/,
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should handle RCPT TO rejection', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('RCPT', {
+          code: 550,
+          message: 'Recipient not found',
+        });
+
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const testMessage = {
+          envelope: {
+            from: 'sender@example.com',
+            to: ['invalid@example.com'],
+          },
+          raw: 'From: sender@example.com\r\nTo: invalid@example.com\r\nSubject: Test\r\n\r\nTest message',
+        };
+
+        await assert.rejects(
+          connection.sendMessage(testMessage),
+          /RCPT TO failed.*Recipient not found/,
+        );
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should handle DATA rejection', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('DATA', { code: 554, message: 'Message rejected' });
+
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const testMessage = {
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Rejected\r\n\r\nThis will be rejected',
+        };
+
+        await assert.rejects(connection.sendMessage(testMessage), /DATA failed.*Message rejected/);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+  });
+
+  describe('Message ID Extraction', () => {
+    test('should extract message ID from server response', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('DATA_END', {
+          code: 250,
+          message: '2.0.0 OK id=abc123def456@mail.example.com queued',
+        });
+
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const testMessage = {
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Test\r\n\r\nTest message',
+        };
+
+        const result = await connection.sendMessage(testMessage);
+        assert.strictEqual(result.messageId, 'abc123def456@mail.example.com');
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should generate fallback message ID when none provided', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('DATA_END', {
+          code: 250,
+          message: 'OK queued for delivery',
+        });
+
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const testMessage = {
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw: 'Simple message',
+        };
+
+        const result = await connection.sendMessage(testMessage);
+
+        assert.ok(result.messageId.startsWith('smtp-'));
+        assert.ok(result.messageId.length > 10);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+  });
+
+  describe('Connection Reset', () => {
+    test('should reset connection state', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        // Send a message first
+        const testMessage = {
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw: 'Test message',
+        };
+
+        await connection.sendMessage(testMessage);
+
+        // Reset the connection
+        await connection.reset();
+
+        // Should be able to send another message
+        await connection.sendMessage(testMessage);
+
+        const receivedMessages = server.getReceivedMessages();
+        assert.strictEqual(receivedMessages.length, 2);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should handle reset failure', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        server.setResponse('RSET', {
+          code: 500,
+          message: 'Reset not supported',
+        });
+
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        await assert.rejects(connection.reset(), /RESET failed.*Reset not supported/);
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+  });
+
+  describe('Error Handling', () => {
+    test('should not allow commands before connection', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        // Create a fresh connection object for this test to ensure clean state
+        const freshConnection = new SmtpConnection({
+          host: 'localhost',
+          port: server.getPort(),
+          secure: false,
+        });
+
+        // Test sendCommand throws
+        try {
+          await freshConnection.sendCommand('EHLO test');
+          assert.fail('Expected sendCommand to throw an error');
+        } catch (error) {
+          assert.strictEqual(error.message, 'Not connected');
+        }
+
+        // Test reset throws
+        try {
+          await freshConnection.reset();
+          assert.fail('Expected reset to throw an error');
+        } catch (error) {
+          assert.strictEqual(error.message, 'Not connected');
+        }
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+
+    test('should prevent double connection', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        // Test with a new connection object
+        const freshConnection = new SmtpConnection({
+          host: 'localhost',
+          port: server.getPort(),
+          secure: false,
+        });
+
+        await freshConnection.connect();
+
+        // Test double connect throws
+        try {
+          await freshConnection.connect();
+          assert.fail('Expected connect to throw an error');
+        } catch (error) {
+          assert.strictEqual(error.message, 'Connection already established');
+        }
+
+        // Cleanup
+        await freshConnection.quit();
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+  });
+
+  describe('Dot Stuffing', () => {
+    test('should properly escape dots in message content', async () => {
+      const { server, connection } = await setupTest();
+      try {
+        await connection.connect();
+        await connection.greeting();
+        await connection.ehlo();
+
+        const testMessage = {
+          envelope: {
+            from: 'sender@example.com',
+            to: ['recipient@example.com'],
+          },
+          raw: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Dot Test\r\n\r\nLine 1\r\n.Hidden line\r\nLine 3',
+        };
+
+        await connection.sendMessage(testMessage);
+
+        // Verify the message was received with proper dot stuffing
+        const receivedMessages = server.getReceivedMessages();
+        assert.strictEqual(receivedMessages.length, 1);
+
+        // The original message should be preserved (server handles unstuffing)
+        assert.ok(receivedMessages[0].data.includes('.Hidden line'));
+      } finally {
+        await teardownTest(server, connection);
+      }
+    });
+  });
+});
diff --git a/tests/unit/smtp-connection.oauth2.integration.test.js b/tests/unit/smtp-connection.oauth2.integration.test.js
new file mode 100644
index 0000000..6b2c89f
--- /dev/null
+++ b/tests/unit/smtp-connection.oauth2.integration.test.js
@@ -0,0 +1,267 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-connection.oauth2.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { Socket } = require('node:net');
+const { describe, test } = require('node:test');
+const { SmtpConnection } = require('../../src/smtp/smtp-connection.js');
+const { SmtpAuthError } = require('../../src/smtp/oauth2.js');
+const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+
+describe('SMTP OAuth 2.0 authentication', () => {
+  const setup = async (auth) => {
+    const server = new MockSmtpServer();
+    await server.start();
+    const config = {
+      host: 'localhost',
+      port: server.getPort(),
+      secure: false,
+      connectionTimeout: 5000,
+      socketTimeout: 5000,
+      localName: 'test.local',
+      auth,
+    };
+    const connection = new SmtpConnection(config);
+    return { server, connection };
+  };
+
+  const teardown = async (server, connection) => {
+    try {
+      await connection.quit();
+    } catch {
+      // Ignore cleanup errors.
+    }
+    await server.stop();
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  };
+
+  const decodeAuthInitialResponse = (authCommand) => {
+    const parts = authCommand.split(' ');
+    return atob(parts[2]);
+  };
+
+  test('authenticates with XOAUTH2 using a static token', async () => {
+    const { server, connection } = await setup({
+      user: 'user@example.com',
+      accessToken: 'the-access-token',
+    });
+    try {
+      await connection.connect();
+      await connection.greeting();
+      await connection.ehlo();
+      await connection.authenticate();
+
+      assert.ok(connection.authenticated);
+      const command = server.getLastAuthCommand();
+      assert.ok(command != null);
+      assert.ok(command.startsWith('AUTH XOAUTH2 '));
+      assert.equal(
+        decodeAuthInitialResponse(command),
+        'user=user@example.com\x01auth=Bearer the-access-token\x01\x01',
+      );
+    } finally {
+      await teardown(server, connection);
+    }
+  });
+
+  test('authenticates with XOAUTH2 using a synchronous token provider', async () => {
+    let called = false;
+    const { server, connection } = await setup({
+      user: 'user@example.com',
+      accessToken: () => {
+        called = true;
+        return 'provided-token';
+      },
+    });
+    try {
+      await connection.connect();
+      await connection.greeting();
+      await connection.ehlo();
+      await connection.authenticate();
+
+      assert.ok(connection.authenticated);
+      assert.ok(called);
+    } finally {
+      await teardown(server, connection);
+    }
+  });
+
+  test('uses the two-step SASL form for an over-long XOAUTH2 token', async () => {
+    // A long token (e.g. an Outlook JWT) overflows the SMTP command-line limit,
+    // so the initial response must be sent on its own line after a 334.
+    const longToken = 'x'.repeat(800);
+    const { server, connection } = await setup({
+      user: 'user@example.com',
+      accessToken: longToken,
+    });
+    try {
+      await connection.connect();
+      await connection.greeting();
+      await connection.ehlo();
+      await connection.authenticate();
+
+      assert.ok(connection.authenticated);
+      // The AUTH command carried no inline initial response.
+      assert.equal(server.getLastAuthCommand(), 'AUTH XOAUTH2');
+    } finally {
+      await teardown(server, connection);
+    }
+  });
+
+  test('authenticates with XOAUTH2 using an asynchronous token provider', async () => {
+    const { server, connection } = await setup({
+      user: 'user@example.com',
+      accessToken: () => Promise.resolve('async-token'),
+    });
+    try {
+      await connection.connect();
+      await connection.greeting();
+      await connection.ehlo();
+      await connection.authenticate();
+
+      assert.ok(connection.authenticated);
+    } finally {
+      await teardown(server, connection);
+    }
+  });
+
+  test('rejects XOAUTH2 failure via the 334 challenge continuation', async () => {
+    const { server, connection } = await setup({
+      user: 'user@example.com',
+      accessToken: 'bad-token',
+    });
+    server.setResponse('AUTH', { code: 535, message: '5.7.8 Bad credentials' });
+    try {
+      await connection.connect();
+      await connection.greeting();
+      await connection.ehlo();
+
+      await assert.rejects(
+        connection.authenticate(),
+        (error) =>
+          error instanceof SmtpAuthError &&
+          /XOAUTH2/.test(error.message) &&
+          // The empty continuation was accepted, so the final server reply is
+          // the real failure rather than a rejected-continuation error.
+          /Bad credentials/.test(error.message),
+      );
+      assert.ok(!connection.authenticated);
+    } finally {
+      await teardown(server, connection);
+    }
+  });
+
+  test('authenticates with OAUTHBEARER including host and port', async () => {
+    const { server, connection } = await setup({
+      user: 'user@example.com',
+      accessToken: 'the-access-token',
+      method: 'oauthbearer',
+    });
+    try {
+      await connection.connect();
+      await connection.greeting();
+      await connection.ehlo();
+      await connection.authenticate();
+
+      assert.ok(connection.authenticated);
+      const command = server.getLastAuthCommand();
+      assert.ok(command != null);
+      assert.ok(command.startsWith('AUTH OAUTHBEARER '));
+      const decoded = decodeAuthInitialResponse(command);
+      assert.ok(decoded.startsWith('n,a=user@example.com,\x01'));
+      assert.ok(decoded.includes('\x01host=localhost\x01'));
+      assert.ok(decoded.includes(`\x01port=${server.getPort()}\x01`));
+      assert.ok(decoded.endsWith('\x01auth=Bearer the-access-token\x01\x01'));
+    } finally {
+      await teardown(server, connection);
+    }
+  });
+
+  test('rejects OAUTHBEARER failure via the 334 challenge continuation', async () => {
+    const { server, connection } = await setup({
+      user: 'user@example.com',
+      accessToken: 'bad-token',
+      method: 'oauthbearer',
+    });
+    server.setResponse('AUTH', { code: 535, message: '5.7.8 Bad credentials' });
+    try {
+      await connection.connect();
+      await connection.greeting();
+      await connection.ehlo();
+
+      await assert.rejects(
+        connection.authenticate(),
+        (error) =>
+          error instanceof SmtpAuthError &&
+          /OAUTHBEARER/.test(error.message) &&
+          // The "AQ==" continuation was accepted, so the final server reply is
+          // the real failure rather than a rejected-continuation error.
+          /Bad credentials/.test(error.message),
+      );
+      assert.ok(!connection.authenticated);
+    } finally {
+      await teardown(server, connection);
+    }
+  });
+
+  test('auto-selects XOAUTH2 when method is omitted', async () => {
+    const { server, connection } = await setup({
+      user: 'user@example.com',
+      accessToken: 'the-access-token',
+    });
+    try {
+      await connection.connect();
+      await connection.greeting();
+      await connection.ehlo();
+      await connection.authenticate();
+
+      const command = server.getLastAuthCommand();
+      assert.ok(command.startsWith('AUTH XOAUTH2 '));
+    } finally {
+      await teardown(server, connection);
+    }
+  });
+
+  test('refuses OAuth over a cleartext non-loopback connection', async () => {
+    const connection = new SmtpConnection({
+      host: 'smtp.example.com',
+      port: 25,
+      secure: false,
+      auth: { user: 'user@example.com', accessToken: 'the-access-token' },
+    });
+    // Simulate a post-EHLO plaintext connection without dialing out; the TLS
+    // guard rejects before the socket is used.
+    const socket = new Socket();
+    connection.socket = socket;
+    connection.capabilities = ['AUTH XOAUTH2'];
+    try {
+      await assert.rejects(
+        connection.authenticate(),
+        (error) => error instanceof SmtpAuthError && /TLS/.test(error.message),
+      );
+      assert.ok(!connection.authenticated);
+    } finally {
+      socket.destroy();
+    }
+  });
+
+  test('throws SmtpAuthError when the server lacks AUTH support', async () => {
+    const connection = new SmtpConnection({
+      host: 'smtp.example.com',
+      port: 465,
+      secure: true,
+      auth: { user: 'user@example.com', accessToken: 'the-access-token' },
+    });
+    const socket = new Socket();
+    connection.socket = socket;
+    connection.capabilities = []; // server advertised no AUTH mechanisms
+    try {
+      await assert.rejects(
+        connection.authenticate(),
+        (error) => error instanceof SmtpAuthError && /does not support/.test(error.message),
+      );
+    } finally {
+      socket.destroy();
+    }
+  });
+});
diff --git a/tests/unit/smtp-data-stream.test.js b/tests/unit/smtp-data-stream.test.js
new file mode 100644
index 0000000..45abaeb
--- /dev/null
+++ b/tests/unit/smtp-data-stream.test.js
@@ -0,0 +1,89 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/data-stream.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { Writable } = require('node:stream');
+const { Buffer } = require('node:buffer');
+const { writeMessageData } = require('../../src/smtp/data-stream.js');
+
+test('does not pull another chunk until a blocked write drains', async () => {
+  let finishWrite;
+  const writes = [];
+  const socket = new Writable({
+    highWaterMark: 1,
+    write(chunk, _encoding, callback) {
+      const value = chunk.toString();
+      writes.push(value);
+      if (value === '.\r\n') {
+        callback();
+        queueMicrotask(() => socket.emit('data', Buffer.from('250 OK\r\n')));
+      } else finishWrite = callback;
+    },
+  });
+  let pulls = 0;
+  const pending = writeMessageData(
+    socket,
+    async function* () {
+      pulls++;
+      yield Buffer.from('.first\r');
+      pulls++;
+      yield Buffer.from('\n.second\r\n');
+    },
+    1000,
+    () => {},
+  );
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  assert.equal(pulls, 1);
+  assert.equal(writes.length, 1);
+  finishWrite();
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  assert.equal(pulls, 2);
+  finishWrite();
+  assert.equal((await pending).code, 250);
+  assert.equal(writes.join(''), '..first\r\n..second\r\n.\r\n');
+  socket.destroy();
+});
+
+for (const failure of ['abort', 'timeout', 'early reply', 'close']) {
+  test(`stops DATA on ${failure} while next is pending`, async () => {
+    const socket = new Writable({
+      write(_chunk, _encoding, callback) {
+        callback();
+      },
+    });
+    const controller = new AbortController();
+    let returns = 0;
+    let owned;
+    const pending = writeMessageData(
+      socket,
+      (signal) => {
+        owned = signal;
+        return {
+          [Symbol.asyncIterator]() {
+            return {
+              next: () => new Promise(() => {}),
+              return: () => {
+                returns++;
+                return new Promise(() => {});
+              },
+            };
+          },
+        };
+      },
+      30,
+      () => {},
+      controller.signal,
+    );
+    const rejected = assert.rejects(pending);
+    if (failure === 'abort') controller.abort(new TypeError('Canceled.'));
+    if (failure === 'early reply') {
+      socket.emit('data', Buffer.from('250 early\r\n'));
+    }
+    if (failure === 'close') socket.destroy();
+    await rejected;
+    assert.ok(owned?.aborted);
+    assert.ok(socket.destroyed);
+    assert.equal(returns, 1);
+  });
+}
diff --git a/tests/unit/smtp-delivery-status.test.js b/tests/unit/smtp-delivery-status.test.js
new file mode 100644
index 0000000..3bde095
--- /dev/null
+++ b/tests/unit/smtp-delivery-status.test.js
@@ -0,0 +1,122 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/delivery-status.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { resolveSmtpDsn, SmtpDsnValidationError } = require('../../src/smtp/delivery-status.js');
+const { resolveSmtpEnvelope } = require('../../src/smtp/envelope.js');
+
+const message = {
+  sender: { address: 'sender@example.com' },
+  recipients: [{ address: 'recipient@example.com' }],
+  ccRecipients: [],
+  bccRecipients: [],
+  replyRecipients: [],
+  subject: 'DSN test',
+  content: { text: 'Hello' },
+  attachments: [],
+  priority: 'normal',
+  tags: [],
+  headers: new Headers(),
+};
+
+// oxlint-disable-next-line no-shadow -- upstream
+const resolveMessageDsn = (message, dsn) => {
+  return resolveSmtpDsn(resolveSmtpEnvelope(message), dsn);
+};
+
+describe('resolveSmtpDsn', () => {
+  test('should omit DSN parameters when no setting is requested', () => {
+    assert.equal(resolveMessageDsn(message, undefined), undefined);
+    assert.equal(resolveMessageDsn(message, {}), undefined);
+    assert.equal(
+      resolveMessageDsn(message, {
+        recipients: { 'recipient@example.com': {} },
+      }),
+      undefined,
+    );
+  });
+
+  test('should accept the RFC 3461 ENVID length limit', () => {
+    const dsn = resolveMessageDsn(message, { envelopeId: 'a'.repeat(94) });
+    assert.equal(dsn?.mailParameters[0].length, 100);
+  });
+
+  test('should reject an empty ENVID', () => {
+    assert.throws(
+      () => resolveMessageDsn(message, { envelopeId: '' }),
+      new SmtpDsnValidationError('DSN envelope ID must not be empty.'),
+    );
+  });
+
+  test('should reject ENVID above the RFC 3461 length limit', () => {
+    assert.throws(
+      () => resolveMessageDsn(message, { envelopeId: 'a'.repeat(95) }),
+      new SmtpDsnValidationError('ENVID parameter exceeds the RFC 3461 limit of 100 characters.'),
+    );
+  });
+
+  test('should accept the RFC 3461 ORCPT length limit', () => {
+    const address = `${'a'.repeat(485)}@b`;
+    const dsn = resolveSmtpDsn(
+      {
+        from: 'sender@example.com',
+        to: [address],
+      },
+      {
+        recipients: {
+          [address]: { originalRecipient: address },
+        },
+      },
+    );
+    assert.equal(dsn?.recipientParameters[0][0].length, 500);
+  });
+
+  test('should reject ORCPT above the RFC 3461 length limit', () => {
+    const address = `${'a'.repeat(486)}@b`;
+    assert.throws(
+      () =>
+        resolveSmtpDsn(
+          {
+            from: 'sender@example.com',
+            to: [address],
+          },
+          {
+            recipients: {
+              [address]: { originalRecipient: address },
+            },
+          },
+        ),
+      new SmtpDsnValidationError('ORCPT parameter exceeds the RFC 3461 limit of 500 characters.'),
+    );
+  });
+
+  test('should reject an ORCPT that differs from its envelope recipient', () => {
+    assert.throws(
+      () =>
+        resolveMessageDsn(message, {
+          recipients: {
+            'recipient@example.com': {
+              originalRecipient: 'forwarded@example.com',
+            },
+          },
+        }),
+      new SmtpDsnValidationError(
+        'DSN original recipient for recipient@example.com must match the ' +
+          'envelope recipient address.',
+      ),
+    );
+  });
+
+  test('should reject an empty notification condition list', () => {
+    assert.throws(
+      () =>
+        resolveMessageDsn(message, {
+          recipients: {
+            'recipient@example.com': { notify: [] },
+          },
+        }),
+      /must be a non-empty array/,
+    );
+  });
+});
diff --git a/tests/unit/smtp-envelope.test.js b/tests/unit/smtp-envelope.test.js
new file mode 100644
index 0000000..489b54a
--- /dev/null
+++ b/tests/unit/smtp-envelope.test.js
@@ -0,0 +1,84 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/envelope.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { resolveSmtpEnvelope, SmtpEnvelopeValidationError } = require('../../src/smtp/envelope.js');
+
+const message = {
+  sender: { address: 'sender@example.com' },
+  recipients: [{ address: 'recipient@example.com' }],
+  ccRecipients: [{ address: 'copy@example.com' }],
+  bccRecipients: [{ address: 'blind@example.com' }],
+  replyRecipients: [],
+  subject: 'Envelope test',
+  content: { text: 'Hello' },
+  attachments: [],
+  priority: 'normal',
+  tags: [],
+  headers: new Headers(),
+};
+
+describe('resolveSmtpEnvelope', () => {
+  test('should derive the envelope when no override is provided', () => {
+    assert.deepEqual(resolveSmtpEnvelope(message), {
+      from: 'sender@example.com',
+      to: ['recipient@example.com', 'copy@example.com', 'blind@example.com'],
+    });
+  });
+
+  test('should override the sender and recipients independently', () => {
+    assert.deepEqual(resolveSmtpEnvelope(message, { from: 'bounce@example.com' }), {
+      from: 'bounce@example.com',
+      to: ['recipient@example.com', 'copy@example.com', 'blind@example.com'],
+    });
+    assert.deepEqual(resolveSmtpEnvelope(message, { to: ['forward@example.net'] }), {
+      from: 'sender@example.com',
+      to: ['forward@example.net'],
+    });
+  });
+
+  test('should preserve an explicit null reverse-path', () => {
+    assert.deepEqual(resolveSmtpEnvelope(message, { from: null }), {
+      from: null,
+      to: ['recipient@example.com', 'copy@example.com', 'blind@example.com'],
+    });
+  });
+
+  test('should reject an empty recipient list', () => {
+    assert.throws(
+      () => resolveSmtpEnvelope(message, { to: [] }),
+      new SmtpEnvelopeValidationError('SMTP envelope must contain at least one recipient.'),
+    );
+  });
+
+  test('should reject invalid sender and recipient addresses', () => {
+    assert.throws(
+      () =>
+        resolveSmtpEnvelope(message, {
+          from: 'sender@example.com\r\nRCPT TO:<root@example.com>',
+        }),
+      /sender must be a valid email address or null/,
+    );
+    assert.throws(
+      () =>
+        resolveSmtpEnvelope(message, {
+          to: ['recipient@example.com\r\nDATA'],
+        }),
+      /recipient at index 0 must be a valid email address/,
+    );
+  });
+
+  test('should validate addresses derived from Message', () => {
+    assert.throws(
+      () =>
+        resolveSmtpEnvelope({
+          ...message,
+          sender: {
+            address: 'sender@example.com\r\nRCPT TO:<root@example.com>',
+          },
+        }),
+      /sender must be a valid email address or null/,
+    );
+  });
+});
diff --git a/tests/unit/smtp-large-attachment.integration.test.js b/tests/unit/smtp-large-attachment.integration.test.js
new file mode 100644
index 0000000..fbbdbe9
--- /dev/null
+++ b/tests/unit/smtp-large-attachment.integration.test.js
@@ -0,0 +1,195 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/large-attachment.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createServer } = require('node:net');
+const { Buffer } = require('node:buffer');
+const { createHash, verify } = require('node:crypto');
+const { createMessage } = require('../../src/core/message.js');
+const { SmtpTransport } = require('../../src/smtp/smtp-transport.js');
+const {
+  TEST_DKIM_PRIVATE_KEY,
+  TEST_DKIM_PUBLIC_KEY,
+} = require('../helpers/smtp/dkim-test-keys.js');
+
+for (const megabytes of [8, 64]) {
+  for (const signed of [false, true]) {
+    test(`streams ${megabytes} MiB to a slow receiver${signed ? ' with DKIM' : ''}`, async () => {
+      const total = megabytes * 1024 * 1024;
+      const payloadHash = createHash('sha256');
+      const bodyHash = createHash('sha256');
+      const expectedHash = createHash('sha256');
+      const bytes = Uint8Array.from({ length: 65536 }, (_, i) => i % 251);
+      for (let offset = 0; offset < total; offset += bytes.length) {
+        expectedHash.update(bytes);
+      }
+      let received = 0;
+      let produced = 0;
+      let maximumAhead = 0;
+      let reads = 0;
+      let socket;
+      let resumeTimer;
+      const headers = [];
+      let serverError;
+      const server = createServer((connection) => {
+        socket = connection;
+        connection.on('error', (error) => {
+          serverError = error;
+        });
+        connection.write('220 ready\r\n');
+        let buffer = '';
+        let data = false;
+        let header = true;
+        let attachmentHeader = false;
+        let payload = false;
+        connection.on('data', (chunk) => {
+          connection.pause();
+          resumeTimer = setTimeout(() => connection.resume(), 1);
+          buffer += chunk.toString('utf8');
+          let end;
+          while ((end = buffer.indexOf('\r\n')) >= 0) {
+            let line = buffer.slice(0, end);
+            buffer = buffer.slice(end + 2);
+            if (!data) {
+              if (line.startsWith('EHLO')) {
+                connection.write('250-test\r\n250 SIZE 200000000\r\n');
+              } else if (line === 'DATA') {
+                data = true;
+                connection.write('354 go\r\n');
+              } else if (line === 'QUIT') connection.end('221 bye\r\n');
+              else connection.write('250 OK\r\n');
+              continue;
+            }
+            if (line === '.') {
+              data = false;
+              connection.write('250 accepted\r\n');
+              continue;
+            }
+            if (line.startsWith('..')) line = line.slice(1);
+            if (header) {
+              if (line === '') header = false;
+              else headers.push(line);
+              continue;
+            }
+            bodyHash.update(line + '\r\n');
+            if (line.startsWith('--')) {
+              payload = false;
+              attachmentHeader = false;
+            }
+            if (payload) {
+              const decoded = Buffer.from(line, 'base64');
+              payloadHash.update(decoded);
+              received += decoded.length;
+              maximumAhead = Math.max(maximumAhead, produced - received);
+            }
+            if (line === 'Content-Transfer-Encoding: base64') {
+              attachmentHeader = true;
+            }
+            if (attachmentHeader && line === '') payload = true;
+          }
+          // The receiver keeps only an incomplete MIME line, never the DATA body.
+          if (buffer.length > 65536) {
+            serverError = new RangeError('Receiver buffer grew unexpectedly.');
+          }
+        });
+      });
+      await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+      const address = server.address();
+      assert.ok(address && typeof address !== 'string');
+      const transport = new SmtpTransport({
+        host: '127.0.0.1',
+        port: address.port,
+        pool: false,
+        socketTimeout: 10000,
+        dkim: signed
+          ? {
+              bodyMode: 'streaming',
+              signatures: [
+                {
+                  signingDomain: 'example.com',
+                  selector: 'test',
+                  canonicalization: 'simple/simple',
+                  privateKey: TEST_DKIM_PRIVATE_KEY,
+                },
+              ],
+            }
+          : undefined,
+      });
+      try {
+        const receipt = await transport.send(
+          createMessage({
+            from: 'from@example.com',
+            to: 'to@example.com',
+            subject: 'Large attachment',
+            content: { text: 'Test' },
+            attachments: {
+              filename: 'large.bin',
+              inline: false,
+              contentType: 'application/octet-stream',
+              contentId: 'large',
+              content: async function* () {
+                reads++;
+                produced = 0;
+                for (let offset = 0; offset < total; offset += bytes.length) {
+                  produced += bytes.length;
+                  yield bytes;
+                }
+              },
+            },
+          }),
+        );
+        assert.ok(receipt.successful, JSON.stringify(receipt));
+        assert.equal(reads, signed ? 2 : 1);
+        assert.equal(received, total);
+        assert.equal(payloadHash.digest('hex'), expectedHash.digest('hex'));
+        assert.ok(maximumAhead < 8 * 1024 * 1024, `Read ahead: ${maximumAhead}`);
+        if (signed) {
+          const signature = headers.find((line) => line.startsWith('DKIM-Signature:'));
+          const tags = new Map(
+            signature
+              .slice(15)
+              .split(';')
+              .map((tag) => {
+                const equal = tag.indexOf('=');
+                return [tag.slice(0, equal).trim(), tag.slice(equal + 1).trim()];
+              }),
+          );
+          assert.equal(tags.get('bh'), bodyHash.digest('base64'));
+          const selected = tags
+            .get('h')
+            .split(':')
+            .map((name) =>
+              headers.find((line) => line.toLowerCase().startsWith(name.toLowerCase() + ':')),
+            );
+          selected.push(signature.replace(/b=[^;]*$/, 'b='));
+          assert.ok(
+            verify(
+              'sha256',
+              Buffer.from(selected.join('\r\n')),
+              TEST_DKIM_PUBLIC_KEY,
+              Buffer.from(tags.get('b'), 'base64'),
+            ),
+          );
+        }
+      } finally {
+        await transport.closeAllConnections();
+        clearTimeout(resumeTimer);
+        socket?.destroy();
+        await new Promise((resolve) => server.close(() => resolve()));
+      }
+      // The client leaving mid-stream resets the connection: ECONNRESET on
+      // Linux and macOS, also ECONNABORTED or EPIPE on Windows.
+      if (
+        serverError &&
+        !(
+          serverError instanceof Error &&
+          'code' in serverError &&
+          ['ECONNRESET', 'ECONNABORTED', 'EPIPE'].includes(serverError.code)
+        )
+      ) {
+        throw serverError;
+      }
+    });
+  }
+}
diff --git a/tests/unit/smtp-message-converter.integration.test.js b/tests/unit/smtp-message-converter.integration.test.js
new file mode 100644
index 0000000..c9f6174
--- /dev/null
+++ b/tests/unit/smtp-message-converter.integration.test.js
@@ -0,0 +1,1478 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/message-converter.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { Buffer } = require('node:buffer');
+const { describe, test } = require('node:test');
+const { convertMessage } = require('../../src/smtp/message-converter.js');
+
+describe('Message Converter Integration Tests', () => {
+  const createTestMessage = (overrides = {}) => ({
+    sender: { name: 'John Doe', address: 'john@example.com' },
+    recipients: [{ name: 'Jane Doe', address: 'jane@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Hello, World!' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  });
+
+  describe('Basic Message Conversion', () => {
+    test('should convert simple text message to SMTP format', async () => {
+      const message = createTestMessage();
+      const result = await convertMessage(message);
+
+      // Test envelope
+      assert.strictEqual(result.envelope.from, 'john@example.com');
+      assert.deepStrictEqual(result.envelope.to, ['jane@example.com']);
+      assert.equal(result.requiresSmtpUtf8, false);
+
+      // Test raw message structure
+      const lines = result.raw.split('\r\n');
+      assert.ok(lines.some((line) => line.startsWith('From: John Doe <john@example.com>')));
+      assert.ok(lines.some((line) => line.startsWith('To: Jane Doe <jane@example.com>')));
+      assert.ok(lines.some((line) => line.startsWith('Subject: Test Subject')));
+      assert.ok(lines.some((line) => line.startsWith('Date:')));
+      assert.ok(lines.some((line) => line.startsWith('Message-ID:')));
+      assert.ok(lines.some((line) => line === 'MIME-Version: 1.0'));
+      assert.ok(result.raw.includes('Hello, World!'));
+    });
+
+    test('should handle multiple recipients in envelope', async () => {
+      const message = createTestMessage({
+        recipients: [{ address: 'jane@example.com' }, { address: 'bob@example.com' }],
+        ccRecipients: [{ address: 'cc@example.com' }],
+        bccRecipients: [{ address: 'bcc@example.com' }],
+      });
+
+      const result = await convertMessage(message);
+
+      // Envelope should include all recipients
+      assert.deepStrictEqual(result.envelope.to, [
+        'jane@example.com',
+        'bob@example.com',
+        'cc@example.com',
+        'bcc@example.com',
+      ]);
+
+      // Raw message should only show To and Cc headers (not BCC)
+      assert.ok(result.raw.includes('To: jane@example.com, bob@example.com'));
+      assert.ok(result.raw.includes('Cc: cc@example.com'));
+      assert.ok(!result.raw.includes('Bcc:')); // BCC should not appear in headers
+    });
+
+    test('should fold long recipient headers', async () => {
+      const recipients = Array.from({ length: 60 }, (_, index) => ({
+        address: `recipient-${index.toString().padStart(3, '0')}@example.com`,
+      }));
+      const result = await convertMessage(createTestMessage({ recipients }));
+      const headerSection = result.raw.split('\r\n\r\n', 1)[0];
+
+      for (const line of headerSection.split('\r\n')) {
+        assert.ok(line.length <= 998, `Header line is ${line.length} characters long.`);
+      }
+
+      const unfoldedHeaders = headerSection.replace(/\r\n[ \t]+/g, ' ');
+      assert.ok(
+        unfoldedHeaders.includes(
+          `To: ${recipients.map((recipient) => recipient.address).join(', ')}`,
+        ),
+      );
+    });
+
+    test('should preserve whitespace when folding headers', async () => {
+      const subject = `${'word  '.repeat(20)}word`;
+      const result = await convertMessage(createTestMessage({ subject }));
+      const subjectHeader = result.raw
+        .split('\r\n\r\n', 1)[0]
+        .split('\r\n')
+        .filter((line) => line.startsWith('Subject: ') || /^[ \t]/.test(line))
+        .join('\r\n');
+
+      assert.equal(subjectHeader.replace(/\r\n/g, ''), `Subject: ${subject}`);
+    });
+
+    test('should not create whitespace-only continuation lines', async () => {
+      const subject = `${'word '.repeat(20)}${' '.repeat(21)}`;
+      const result = await convertMessage(createTestMessage({ subject }));
+      const headerSection = result.raw.split('\r\n\r\n', 1)[0];
+
+      assert.ok(!headerSection.split('\r\n').some((line) => /^\s+$/.test(line)));
+    });
+  });
+
+  describe('Content Type Handling', () => {
+    test('should create single-part HTML message', async () => {
+      const message = createTestMessage({
+        content: { html: '<h1>Hello</h1><p>World!</p>' },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('Content-Type: text/html; charset=utf-8'));
+      assert.ok(result.raw.includes('Content-Transfer-Encoding: quoted-printable'));
+      assert.ok(result.raw.includes('<h1>Hello</h1><p>World!</p>'));
+      assert.ok(!result.raw.includes('multipart'));
+    });
+
+    test('should create multipart/alternative for mixed content', async () => {
+      const message = createTestMessage({
+        content: {
+          text: 'Hello World in plain text',
+          html: '<h1>Hello World</h1><p>in HTML</p>',
+        },
+      });
+
+      const result = await convertMessage(message);
+
+      // Should be multipart/alternative
+      assert.ok(result.raw.includes('Content-Type: multipart/alternative'));
+
+      // Should contain both content types
+      assert.ok(result.raw.includes('Content-Type: text/plain; charset=utf-8'));
+      assert.ok(result.raw.includes('Content-Type: text/html; charset=utf-8'));
+
+      // Should contain both content versions
+      assert.ok(result.raw.includes('Hello World in plain text'));
+      assert.ok(result.raw.includes('<h1>Hello World</h1>'));
+
+      // Should have proper boundary structure
+      const boundaryMatch = result.raw.match(/boundary="([^"]+)"/);
+      assert.ok(boundaryMatch);
+      const boundary = boundaryMatch[1];
+      assert.ok(result.raw.includes(`--${boundary}`));
+      assert.ok(result.raw.includes(`--${boundary}--`));
+    });
+  });
+
+  describe('Attachment Handling', () => {
+    test('should create multipart/mixed with single attachment', async () => {
+      const attachmentContent = new TextEncoder().encode('File content here');
+      const message = createTestMessage({
+        attachments: [
+          {
+            filename: 'test.txt',
+            content: attachmentContent,
+            contentType: 'text/plain',
+            contentId: 'test-file',
+            inline: false,
+          },
+        ],
+      });
+
+      const result = await convertMessage(message);
+
+      // Should be multipart/mixed
+      assert.ok(result.raw.includes('Content-Type: multipart/mixed'));
+
+      // Should contain attachment headers
+      assert.ok(result.raw.includes('Content-Type: text/plain; name="test.txt"'));
+      assert.ok(result.raw.includes('Content-Transfer-Encoding: base64'));
+      assert.ok(result.raw.includes('Content-Disposition: attachment; filename="test.txt"'));
+
+      // Should contain base64 encoded content
+      const expectedBase64 = btoa(String.fromCharCode(...attachmentContent));
+      assert.ok(result.raw.includes(expectedBase64));
+    });
+
+    test('should handle inline attachments with Content-ID', async () => {
+      const imageContent = new Uint8Array([0x89, 0x50, 0x4e, 0x47]); // PNG signature
+      const message = createTestMessage({
+        attachments: [
+          {
+            filename: 'image.png',
+            content: imageContent,
+            contentType: 'image/png',
+            contentId: 'embedded-image',
+            inline: true,
+          },
+        ],
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('Content-Type: image/png; name="image.png"'));
+      assert.ok(result.raw.includes('Content-Disposition: inline; filename="image.png"'));
+      assert.ok(result.raw.includes('Content-ID: <embedded-image>'));
+    });
+
+    test('should handle mixed content with attachments', async () => {
+      const attachmentContent = new TextEncoder().encode('Attachment data');
+      const message = createTestMessage({
+        content: {
+          text: 'Text version',
+          html: '<p>HTML version</p>',
+        },
+        attachments: [
+          {
+            filename: 'document.pdf',
+            content: attachmentContent,
+            contentType: 'application/pdf',
+            contentId: 'doc',
+            inline: false,
+          },
+        ],
+      });
+
+      const result = await convertMessage(message);
+
+      // Should be multipart/mixed at top level
+      assert.ok(result.raw.includes('Content-Type: multipart/mixed'));
+
+      // Should contain nested multipart/alternative for content
+      assert.ok(result.raw.includes('Content-Type: multipart/alternative'));
+
+      // Should contain all parts
+      assert.ok(result.raw.includes('Text version'));
+      assert.ok(result.raw.includes('<p>HTML version</p>'));
+      assert.ok(result.raw.includes('Content-Type: application/pdf; name="document.pdf"'));
+    });
+
+    test('should fold MIME parameters for long filenames', async () => {
+      const filename = `${'long-file-name-'.repeat(90)}.txt`;
+      const result = await convertMessage(
+        createTestMessage({
+          attachments: [
+            {
+              filename,
+              content: new Uint8Array([1, 2, 3]),
+              contentType: 'application/octet-stream',
+              contentId: 'long-filename',
+              inline: false,
+            },
+          ],
+        }),
+      );
+
+      for (const line of result.raw.split('\r\n')) {
+        assert.ok(line.length <= 998, `Message line is ${line.length} characters long.`);
+      }
+      assert.ok(result.raw.includes("name*0*=UTF-8''"));
+      assert.ok(result.raw.includes("filename*0*=UTF-8''"));
+    });
+  });
+
+  describe('Header Encoding', () => {
+    test('should detect internationalized mailbox addresses', async () => {
+      const sender = await convertMessage(
+        createTestMessage({
+          sender: { address: 'josé@example.com' },
+        }),
+      );
+      const recipient = await convertMessage(
+        createTestMessage({
+          bccRecipients: [{ address: '用户@example.com' }],
+        }),
+      );
+      const replyTo = await convertMessage(
+        createTestMessage({
+          replyRecipients: [{ address: 'support@例え.テスト' }],
+        }),
+      );
+
+      assert.equal(sender.requiresSmtpUtf8, true);
+      assert.equal(recipient.requiresSmtpUtf8, true);
+      assert.equal(replyTo.requiresSmtpUtf8, true);
+      assert.ok(sender.raw.includes('From: josé@example.com'));
+    });
+
+    test('should detect a Unicode value in a verbatim header', async () => {
+      const messageId = await convertMessage(
+        createTestMessage({
+          headers: new Headers({ 'Message-ID': '<ünicode@example.com>' }),
+        }),
+      );
+      const references = await convertMessage(
+        createTestMessage({
+          headers: new Headers({ References: '<ünicode@example.com>' }),
+        }),
+      );
+
+      assert.ok(messageId.requiresSmtpUtf8);
+      assert.ok(references.requiresSmtpUtf8);
+      assert.ok(messageId.raw.includes('Message-ID: <ünicode@example.com>'));
+    });
+
+    test('should not require SMTPUTF8 for a Unicode attachment filename', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          attachments: [
+            {
+              inline: false,
+              filename: '보고서.txt',
+              content: new TextEncoder().encode('hi'),
+              contentType: 'text/plain',
+              contentId: 'report@example.com',
+            },
+          ],
+        }),
+      );
+
+      assert.ok(!result.requiresSmtpUtf8);
+    });
+
+    test('should not require SMTPUTF8 for Unicode display names', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          sender: { name: 'José', address: 'jose@example.com' },
+          recipients: [{ name: '用户', address: 'user@example.com' }],
+        }),
+      );
+
+      assert.equal(result.requiresSmtpUtf8, false);
+      assert.ok(result.raw.includes('From: =?UTF-8?B?'));
+      assert.ok(result.raw.includes('To: =?UTF-8?B?'));
+    });
+
+    test('should encode non-ASCII headers with RFC 2047', async () => {
+      const message = createTestMessage({
+        sender: { name: '김철수', address: 'kim@example.com' },
+        recipients: [{ name: '박영희', address: 'park@example.com' }],
+        subject: '한글 제목입니다',
+      });
+
+      const result = await convertMessage(message);
+
+      // Should use RFC 2047 encoding for non-ASCII characters in subject
+      assert.ok(result.raw.includes('Subject: =?UTF-8?B?'));
+    });
+
+    test('should leave ASCII headers unchanged', async () => {
+      const message = createTestMessage({
+        subject: 'Plain ASCII Subject',
+        sender: { name: 'John Doe', address: 'john@example.com' },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('Subject: Plain ASCII Subject'));
+      assert.ok(result.raw.includes('From: John Doe <john@example.com>'));
+      assert.ok(!result.raw.includes('=?UTF-8?B?'));
+    });
+
+    test('should handle very long Korean subject lines', async () => {
+      const longSubject = '이것은 매우 긴 한국어 제목입니다. '.repeat(5) + '테스트 메시지입니다.';
+      const message = createTestMessage({
+        subject: longSubject,
+      });
+
+      const result = await convertMessage(message);
+
+      // Should encode with RFC 2047 and handle long lines
+      assert.ok(result.raw.includes('Subject: =?UTF-8?B?'));
+
+      // Should not exceed recommended line length
+      const subjectLines = result.raw.split('\r\n').filter((line) => line.startsWith('Subject:'));
+      assert.ok(subjectLines.length >= 1);
+    });
+
+    test('should keep UTF-8 characters within one encoded word', async () => {
+      const subject = '😀'.repeat(40);
+      const result = await convertMessage(createTestMessage({ subject }));
+      const unfoldedHeaders = result.raw.split('\r\n\r\n', 1)[0].replace(/\r\n[ \t]+/g, ' ');
+      const subjectLine = unfoldedHeaders
+        .split('\r\n')
+        .find((line) => line.startsWith('Subject: '));
+
+      assert.ok(subjectLine);
+      const encodedWords = [...subjectLine.matchAll(/=\?UTF-8\?B\?([^?]+)\?=/g)];
+      assert.ok(encodedWords.length > 1);
+
+      const decoder = new TextDecoder('utf-8', { fatal: true });
+      const decodedWords = encodedWords.map((match) =>
+        decoder.decode(Buffer.from(match[1], 'base64')),
+      );
+
+      assert.strictEqual(decodedWords.join(''), subject);
+    });
+
+    test('should handle mixed CJK characters in sender names', async () => {
+      const message = createTestMessage({
+        sender: {
+          name: '田中太郎 김철수 Wang Wei',
+          address: 'mixed@example.com',
+        },
+        subject: 'Mixed CJK Test',
+      });
+
+      const result = await convertMessage(message);
+
+      // Should encode sender name with mixed CJK characters
+      assert.ok(result.raw.includes('From: =?UTF-8?B?'));
+      assert.ok(result.raw.includes('Subject: Mixed CJK Test'));
+    });
+
+    test('should handle Japanese characters in headers', async () => {
+      const message = createTestMessage({
+        sender: { name: '田中太郎', address: 'tanaka@example.com' },
+        subject: 'こんにちは、世界！',
+      });
+
+      const result = await convertMessage(message);
+
+      // Should encode Japanese characters
+      assert.ok(result.raw.includes('From: =?UTF-8?B?'));
+      assert.ok(result.raw.includes('Subject: =?UTF-8?B?'));
+    });
+
+    test('should handle Chinese characters in headers', async () => {
+      const message = createTestMessage({
+        sender: { name: '王伟', address: 'wang@example.com' },
+        subject: '你好，世界！',
+      });
+
+      const result = await convertMessage(message);
+
+      // Should encode Chinese characters
+      assert.ok(result.raw.includes('From: =?UTF-8?B?'));
+      assert.ok(result.raw.includes('Subject: =?UTF-8?B?'));
+    });
+
+    test('should handle emoji in headers', async () => {
+      const message = createTestMessage({
+        sender: { name: 'John Doe 😀', address: 'john@example.com' },
+        subject: 'Hello 👋 World 🌍',
+      });
+
+      const result = await convertMessage(message);
+
+      // Should encode emoji characters
+      assert.ok(result.raw.includes('From: =?UTF-8?B?'));
+      assert.ok(result.raw.includes('Subject: =?UTF-8?B?'));
+    });
+
+    test('should handle custom headers with ASCII characters', async () => {
+      const headers = new Headers();
+      headers.set('X-Custom-Header', 'Custom Value');
+      headers.set('X-Mailer', 'Test Mailer');
+      headers.set('X-Custom-Info', 'ASCII Info');
+
+      const message = createTestMessage({ headers });
+      const result = await convertMessage(message);
+
+      // Should include all custom headers without encoding (ASCII only)
+      assert.ok(result.raw.includes('x-custom-header: Custom Value'));
+      assert.ok(result.raw.includes('x-mailer: Test Mailer'));
+      assert.ok(result.raw.includes('x-custom-info: ASCII Info'));
+    });
+
+    test('should preserve long structured ASCII header values', async () => {
+      const messageId = `<${'a'.repeat(100)}@example.com>`;
+      const headers = new Headers({ 'In-Reply-To': messageId });
+      const result = await convertMessage(createTestMessage({ headers }));
+
+      assert.ok(result.raw.includes(`In-Reply-To: ${messageId}`));
+      assert.ok(!result.raw.includes('In-Reply-To: =?UTF-8?B?'));
+    });
+
+    test('should reject custom header tokens beyond the hard limit', async () => {
+      const headers = new Headers({ 'X-Token': 'a'.repeat(1_000) });
+
+      await assert.rejects(() => convertMessage(createTestMessage({ headers })), RangeError);
+    });
+
+    test('should encode only display name in German umlaut addresses', async () => {
+      const message = createTestMessage({
+        sender: { name: 'German ÄÖÜ', address: 'info@example.com' },
+        recipients: [{ name: 'Müller Ümlauts', address: 'user@example.com' }],
+        ccRecipients: [{ name: 'Größer', address: 'cc@example.com' }],
+        replyRecipients: [
+          {
+            name: 'Straße Info',
+            address: 'reply@example.com',
+          },
+        ],
+      });
+
+      const result = await convertMessage(message);
+
+      // Should encode display names but leave email addresses unencoded
+      assert.ok(result.raw.includes('From: =?UTF-8?B?'));
+      assert.ok(result.raw.includes('<info@example.com>'));
+      assert.ok(result.raw.includes('To: =?UTF-8?B?'));
+      assert.ok(result.raw.includes('<user@example.com>'));
+      assert.ok(result.raw.includes('Cc: =?UTF-8?B?'));
+      assert.ok(result.raw.includes('<cc@example.com>'));
+      assert.ok(result.raw.includes('Reply-To: =?UTF-8?B?'));
+      assert.ok(result.raw.includes('<reply@example.com>'));
+
+      // Email addresses should NOT be encoded
+      assert.ok(!result.raw.includes('=?UTF-8?B?aW5mb0BleGFtcGxlLmNvbQ==?=')); // base64 of "info@example.com"
+      assert.ok(!result.raw.includes('=?UTF-8?B?dXNlckBleGFtcGxlLmNvbQ==?=')); // base64 of "user@example.com"
+    });
+
+    test('should not encode addresses without display names', async () => {
+      const message = createTestMessage({
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+      });
+
+      const result = await convertMessage(message);
+
+      // Should not use any encoding for plain email addresses
+      assert.ok(result.raw.includes('From: sender@example.com'));
+      assert.ok(result.raw.includes('To: recipient@example.com'));
+      assert.ok(!result.raw.includes('=?UTF-8?B?'));
+    });
+  });
+
+  describe('Content Encoding', () => {
+    test('should use quoted-printable for text content', async () => {
+      const message = createTestMessage({
+        content: { text: 'Hello, 世界! This contains non-ASCII characters.' },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('Content-Transfer-Encoding: quoted-printable'));
+
+      // Should encode non-ASCII characters as quoted-printable
+      assert.ok(result.raw.includes('=E4=B8=96=E7=95=8C')); // 世界 in UTF-8 quoted-printable
+    });
+
+    test('should handle special characters in quoted-printable', async () => {
+      const message = createTestMessage({
+        content: { text: 'End=' },
+      });
+
+      const result = await convertMessage(message);
+
+      // Should escape equals at end of line
+      assert.ok(result.raw.includes('=3D')); // Escaped equals
+    });
+
+    test('should properly encode Korean characters in content', async () => {
+      const message = createTestMessage({
+        content: { text: '안녕하세요! 이것은 한국어 테스트입니다.' },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('Content-Transfer-Encoding: quoted-printable'));
+
+      // Should encode Korean characters as UTF-8 quoted-printable
+      // 안녕하세요! = EC=95=88=EB=85=95=ED=95=98=EC=84=B8=EC=9A=94!
+      assert.ok(result.raw.includes('=EC=95=88=EB=85=95=ED=95=98=EC=84=B8=EC=9A=94!'));
+    });
+
+    test('should handle mixed ASCII and CJK characters', async () => {
+      const message = createTestMessage({
+        content: {
+          text: 'Hello 안녕하세요! This is a mixed text 한국어 test.',
+        },
+      });
+
+      const result = await convertMessage(message);
+
+      // Should contain both ASCII and encoded CJK characters
+      assert.ok(result.raw.includes('Hello '));
+      assert.ok(result.raw.includes('=EC=95=88=EB=85=95=ED=95=98=EC=84=B8=EC=9A=94!'));
+      assert.ok(result.raw.includes(' This is a mixed text '));
+      assert.ok(result.raw.includes('=ED=95=9C=EA=B5=AD=EC=96=B4'));
+      assert.ok(result.raw.includes(' test.'));
+    });
+
+    test('should handle long lines with CJK characters', async () => {
+      const longKoreanText = '이것은 매우 긴 한국어 텍스트입니다. '.repeat(10);
+      const message = createTestMessage({
+        content: { text: longKoreanText },
+      });
+
+      const result = await convertMessage(message);
+
+      // Should contain soft line breaks for long lines
+      assert.ok(result.raw.includes('=\r\n'));
+
+      // Should properly encode Korean characters
+      assert.ok(result.raw.includes('=EC=9D=B4=EA=B2=83=EC=9D=80')); // 이것은
+    });
+
+    test('should handle Japanese and Chinese characters', async () => {
+      const message = createTestMessage({
+        content: { text: 'こんにちは 你好 안녕하세요' },
+      });
+
+      const result = await convertMessage(message);
+
+      // Should encode Japanese hiragana (こんにちは)
+      assert.ok(result.raw.includes('=E3=81=93=E3=82=93=E3=81=AB=E3=81=A1=E3=81=AF'));
+
+      // Should encode Chinese characters (你好)
+      assert.ok(result.raw.includes('=E4=BD=A0=E5=A5=BD'));
+
+      // Should encode Korean characters (안녕하세요) - may be split across lines due to line length
+      const rawWithoutLineBreaks = result.raw.replace(/=\r\n/g, '');
+      assert.ok(rawWithoutLineBreaks.includes('=EC=95=88=EB=85=95=ED=95=98=EC=84=B8=EC=9A=94'));
+    });
+
+    test('should handle emoji and special Unicode characters', async () => {
+      const message = createTestMessage({
+        content: { text: 'Hello 👋 世界 🌍 한국어 💬' },
+      });
+
+      const result = await convertMessage(message);
+
+      // Should encode emoji properly
+      assert.ok(result.raw.includes('=F0=9F=91=8B')); // 👋
+      assert.ok(result.raw.includes('=F0=9F=8C=8D')); // 🌍
+      assert.ok(result.raw.includes('=F0=9F=92=AC')); // 💬
+    });
+
+    test('should handle line breaks with CJK characters', async () => {
+      const message = createTestMessage({
+        content: { text: '첫 번째 줄\n두 번째 줄\r\n세 번째 줄' },
+      });
+
+      const result = await convertMessage(message);
+
+      // Should preserve line breaks
+      assert.ok(result.raw.includes('\n'));
+      assert.ok(result.raw.includes('\r\n'));
+
+      // Should encode Korean characters properly
+      assert.ok(result.raw.includes('=EC=B2=AB')); // 첫
+      assert.ok(result.raw.includes('=EB=91=90')); // 두
+      assert.ok(result.raw.includes('=EC=84=B8')); // 세
+    });
+  });
+
+  describe('Priority and Custom Headers', () => {
+    test('should add priority headers for high priority', async () => {
+      const message = createTestMessage({
+        priority: 'high',
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('X-Priority: 1'));
+      assert.ok(result.raw.includes('X-MSMail-Priority: High'));
+    });
+
+    test('should add priority headers for low priority', async () => {
+      const message = createTestMessage({
+        priority: 'low',
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('X-Priority: 5'));
+      assert.ok(result.raw.includes('X-MSMail-Priority: Low'));
+    });
+
+    test('should not add priority headers for normal priority', async () => {
+      const message = createTestMessage({
+        priority: 'normal',
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(!result.raw.includes('X-Priority:'));
+      assert.ok(!result.raw.includes('X-MSMail-Priority:'));
+    });
+
+    test('should include custom headers', async () => {
+      const headers = new Headers();
+      headers.set('X-Custom-Header', 'Custom Value');
+      headers.set('X-Mailer', 'Test Mailer');
+      headers.set('X-ASCII-Header', 'ASCII Value');
+
+      const message = createTestMessage({ headers });
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('x-custom-header: Custom Value'));
+      assert.ok(result.raw.includes('x-mailer: Test Mailer'));
+      assert.ok(result.raw.includes('x-ascii-header: ASCII Value'));
+    });
+
+    test('should handle reply-to addresses', async () => {
+      const message = createTestMessage({
+        replyRecipients: [
+          { name: 'Support', address: 'support@example.com' },
+          { address: 'noreply@example.com' },
+        ],
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(
+        result.raw.includes('Reply-To: Support <support@example.com>, noreply@example.com'),
+      );
+    });
+  });
+
+  describe('Header Deduplication', () => {
+    const headerLines = (raw) => raw.split('\r\n\r\n')[0].split('\r\n');
+
+    const occurrences = (raw, name) =>
+      headerLines(raw)
+        .filter((line) => line.toLowerCase().startsWith(`${name.toLowerCase()}:`))
+        .map((line) => line.slice(line.indexOf(':') + 1).trim());
+
+    test('should let custom headers override the generated Message-ID', async () => {
+      const headers = new Headers({ 'Message-ID': '<123@example.com>' });
+      const result = await convertMessage(createTestMessage({ headers }));
+
+      assert.deepStrictEqual(occurrences(result.raw, 'Message-ID'), ['<123@example.com>']);
+      assert.ok(!result.raw.includes('@upyo.local'));
+    });
+
+    test('should let custom headers override the generated Date', async () => {
+      const date = 'Tue, 01 Sep 2026 10:00:00 +0000';
+      const headers = new Headers({ Date: date });
+      const result = await convertMessage(createTestMessage({ headers }));
+
+      assert.deepStrictEqual(occurrences(result.raw, 'Date'), [date]);
+    });
+
+    test('should match overridable headers case-insensitively', async () => {
+      const headers = new Headers({
+        'mEsSaGe-Id': '<456@example.com>',
+        dAtE: 'Wed, 02 Sep 2026 11:00:00 +0000',
+      });
+      const result = await convertMessage(createTestMessage({ headers }));
+
+      assert.deepStrictEqual(occurrences(result.raw, 'Message-ID'), ['<456@example.com>']);
+      assert.deepStrictEqual(occurrences(result.raw, 'Date'), ['Wed, 02 Sep 2026 11:00:00 +0000']);
+    });
+
+    test('should still generate defaults when neither is supplied', async () => {
+      const headers = new Headers({ 'X-Mailer': 'Test Mailer' });
+      const result = await convertMessage(createTestMessage({ headers }));
+
+      const messageIds = occurrences(result.raw, 'Message-ID');
+      assert.strictEqual(messageIds.length, 1);
+      assert.ok(messageIds[0].endsWith('@example.com>'));
+
+      const dates = occurrences(result.raw, 'Date');
+      assert.strictEqual(dates.length, 1);
+      assert.ok(!Number.isNaN(new Date(dates[0]).getTime()));
+    });
+
+    test('should not encode overriding values as RFC 2047 words', async () => {
+      const messageId = `<${'a'.repeat(80)}@example.com>`;
+      const headers = new Headers({ 'Message-ID': messageId });
+      const result = await convertMessage(createTestMessage({ headers }));
+
+      assert.deepStrictEqual(occurrences(result.raw, 'Message-ID'), [messageId]);
+      assert.ok(!result.raw.includes('=?UTF-8?B?'));
+    });
+
+    test('should ignore custom headers owned by structured fields', async () => {
+      const headers = new Headers({
+        From: 'spoofed@example.com',
+        To: 'spoofed@example.net',
+        Cc: 'spoofed@example.org',
+        'Reply-To': 'spoofed@example.io',
+        Subject: 'Overridden',
+      });
+      const result = await convertMessage(createTestMessage({ headers }));
+
+      assert.deepStrictEqual(occurrences(result.raw, 'From'), ['John Doe <john@example.com>']);
+      assert.deepStrictEqual(occurrences(result.raw, 'To'), ['Jane Doe <jane@example.com>']);
+      assert.deepStrictEqual(occurrences(result.raw, 'Subject'), ['Test Subject']);
+      assert.deepStrictEqual(occurrences(result.raw, 'Cc'), []);
+      assert.deepStrictEqual(occurrences(result.raw, 'Reply-To'), []);
+    });
+
+    test('should ignore custom headers owned by the MIME structure', async () => {
+      const headers = new Headers({
+        'MIME-Version': '0.9',
+        'Content-Type': 'text/plain',
+        'Content-Transfer-Encoding': '7bit',
+      });
+      const result = await convertMessage(createTestMessage({ headers }));
+
+      assert.deepStrictEqual(occurrences(result.raw, 'MIME-Version'), ['1.0']);
+      assert.deepStrictEqual(occurrences(result.raw, 'Content-Type'), [
+        'text/plain; charset=utf-8',
+      ]);
+      assert.deepStrictEqual(occurrences(result.raw, 'Content-Transfer-Encoding'), [
+        'quoted-printable',
+      ]);
+    });
+
+    test('should keep the real Content-Type first in multipart messages', async () => {
+      const headers = new Headers({ 'Content-Type': 'text/plain' });
+      const message = createTestMessage({
+        headers,
+        content: { html: '<p>Hi</p>', text: 'Hi' },
+      });
+      const result = await convertMessage(message);
+
+      const contentTypes = occurrences(result.raw, 'Content-Type');
+      assert.strictEqual(contentTypes.length, 1);
+      assert.ok(contentTypes[0].startsWith('multipart/mixed; boundary='));
+    });
+
+    // `ImmutableHeaders` is structural, so a Message may carry an adapter that
+    // is not a platform `Headers` and therefore never rejected CR or LF.
+    const headersWith = (name, value, rest = new Headers()) => ({
+      get: (key) => (key.toLowerCase() === name.toLowerCase() ? value : rest.get(key)),
+      has: (key) => key.toLowerCase() === name.toLowerCase() || rest.has(key),
+      getSetCookie: () => rest.getSetCookie(),
+      forEach: (callback, thisArg) => rest.forEach(callback, thisArg),
+      keys: () => rest.keys(),
+      values: () => rest.values(),
+      entries: () => rest.entries(),
+      [Symbol.iterator]: () => rest.entries(),
+    });
+
+    for (const name of ['Date', 'Message-ID']) {
+      test(`should reject CR or LF in an overriding ${name}`, async () => {
+        const headers = headersWith(name, '<x@example.com>\r\nBcc: victim@example.com');
+
+        await assert.rejects(() => convertMessage(createTestMessage({ headers })), TypeError);
+      });
+    }
+
+    test('should not disclose Bcc recipients through a custom header', async () => {
+      const headers = new Headers({ Bcc: 'hidden@example.com' });
+      const message = createTestMessage({
+        headers,
+        bccRecipients: [{ address: 'hidden@example.com' }],
+      });
+      const result = await convertMessage(message);
+
+      assert.deepStrictEqual(occurrences(result.raw, 'Bcc'), []);
+      assert.ok(!result.raw.toLowerCase().includes('hidden@example.com'));
+      assert.ok(result.envelope.to.includes('hidden@example.com'));
+    });
+
+    for (const { priority, expected } of [
+      { priority: 'high', expected: ['1', 'High'] },
+      { priority: 'low', expected: ['5', 'Low'] },
+    ]) {
+      test(`should keep ${priority} priority headers authoritative`, async () => {
+        const headers = new Headers({
+          'X-Priority': '3',
+          'X-MSMail-Priority': 'Normal',
+        });
+        const message = createTestMessage({ headers, priority });
+        const result = await convertMessage(message);
+
+        assert.deepStrictEqual(occurrences(result.raw, 'X-Priority'), [expected[0]]);
+        assert.deepStrictEqual(occurrences(result.raw, 'X-MSMail-Priority'), [expected[1]]);
+      });
+    }
+
+    test('should pass custom priority headers through at normal priority', async () => {
+      const headers = new Headers({
+        'X-Priority': '3',
+        'X-MSMail-Priority': 'Normal',
+      });
+      const message = createTestMessage({ headers, priority: 'normal' });
+      const result = await convertMessage(message);
+
+      assert.deepStrictEqual(occurrences(result.raw, 'X-Priority'), ['3']);
+      assert.deepStrictEqual(occurrences(result.raw, 'X-MSMail-Priority'), ['Normal']);
+    });
+
+    test('should still emit unrelated custom headers', async () => {
+      const headers = new Headers({
+        'Message-ID': '<789@example.com>',
+        Subject: 'Overridden',
+        'X-Mailer': 'Test Mailer',
+        'In-Reply-To': '<788@example.com>',
+      });
+      const result = await convertMessage(createTestMessage({ headers }));
+
+      assert.ok(result.raw.includes('x-mailer: Test Mailer'));
+      assert.ok(result.raw.includes('In-Reply-To: <788@example.com>'));
+    });
+  });
+
+  describe('Identity and Threading Fields', () => {
+    const headerLines = (raw) => raw.split('\r\n\r\n')[0].split('\r\n');
+
+    // Unfolds continuation lines so a folded value is compared as one string.
+    const occurrences = (raw, name) => {
+      const values = [];
+      let current;
+      for (const line of headerLines(raw)) {
+        if (/^[ \t]/.test(line)) {
+          if (current != null) current += ` ${line.trim()}`;
+          continue;
+        }
+        if (current != null) values.push(current);
+        current = line.toLowerCase().startsWith(`${name.toLowerCase()}:`)
+          ? line.slice(line.indexOf(':') + 1).trim()
+          : undefined;
+      }
+      if (current != null) values.push(current);
+      return values;
+    };
+
+    test('should prefer the typed Message-ID over a custom header', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          messageId: 'typed@example.com',
+          headers: new Headers({ 'Message-ID': '<custom@example.com>' }),
+        }),
+      );
+
+      assert.deepStrictEqual(occurrences(result.raw, 'Message-ID'), ['<typed@example.com>']);
+    });
+
+    test('should prefer the typed date over a custom header', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          date: new Date('2026-09-01T10:00:00Z'),
+          headers: new Headers({ Date: 'Thu, 01 Jan 1970 00:00:00 +0000' }),
+        }),
+      );
+
+      assert.deepStrictEqual(occurrences(result.raw, 'Date'), ['Tue, 01 Sep 2026 10:00:00 +0000']);
+    });
+
+    test('should write the typed threading fields', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          inReplyTo: ['122@example.com'],
+          references: ['120@example.com', '121@example.com'],
+        }),
+      );
+
+      assert.deepStrictEqual(occurrences(result.raw, 'In-Reply-To'), ['<122@example.com>']);
+      assert.deepStrictEqual(occurrences(result.raw, 'References'), [
+        '<120@example.com> <121@example.com>',
+      ]);
+    });
+
+    test('should prefer the typed threading fields over custom headers', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          inReplyTo: ['typed@example.com'],
+          references: ['typed@example.com'],
+          headers: new Headers({
+            'In-Reply-To': '<custom@example.com>',
+            References: '<custom@example.com>',
+          }),
+        }),
+      );
+
+      assert.deepStrictEqual(occurrences(result.raw, 'In-Reply-To'), ['<typed@example.com>']);
+      assert.deepStrictEqual(occurrences(result.raw, 'References'), ['<typed@example.com>']);
+    });
+
+    test('should let an empty list suppress a custom header', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          inReplyTo: [],
+          references: [],
+          headers: new Headers({
+            'In-Reply-To': '<custom@example.com>',
+            References: '<custom@example.com>',
+          }),
+        }),
+      );
+
+      assert.deepStrictEqual(occurrences(result.raw, 'In-Reply-To'), []);
+      assert.deepStrictEqual(occurrences(result.raw, 'References'), []);
+    });
+
+    test('should let a custom threading header through when unset', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          headers: new Headers({
+            'In-Reply-To': '<custom@example.com>',
+            References: '<a@example.com> <b@example.com>',
+          }),
+        }),
+      );
+
+      assert.deepStrictEqual(occurrences(result.raw, 'In-Reply-To'), ['<custom@example.com>']);
+      assert.deepStrictEqual(occurrences(result.raw, 'References'), [
+        '<a@example.com> <b@example.com>',
+      ]);
+    });
+
+    test('should omit the threading headers when nothing is supplied', async () => {
+      const result = await convertMessage(createTestMessage());
+
+      assert.deepStrictEqual(occurrences(result.raw, 'In-Reply-To'), []);
+      assert.deepStrictEqual(occurrences(result.raw, 'References'), []);
+    });
+
+    test('should fold a long references chain without losing entries', async () => {
+      const references = Array.from({ length: 40 }, (_, index) => `message-${index}@example.com`);
+      const result = await convertMessage(createTestMessage({ references }));
+
+      assert.ok(
+        headerLines(result.raw).some((line) => line.startsWith(' <')),
+        'expected the chain to be folded across lines',
+      );
+      assert.deepStrictEqual(occurrences(result.raw, 'References'), [
+        references.map((id) => `<${id}>`).join(' '),
+      ]);
+    });
+
+    test('should keep a Unicode identifier verbatim and require SMTPUTF8', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          messageId: 'ünicode@example.com',
+          references: ['참조@example.com'],
+        }),
+      );
+
+      assert.ok(result.raw.includes('Message-ID: <ünicode@example.com>'));
+      assert.ok(result.raw.includes('References: <참조@example.com>'));
+      assert.ok(!result.raw.includes('=?UTF-8?B?'));
+      assert.ok(result.requiresSmtpUtf8);
+    });
+
+    test('should not require SMTPUTF8 for a suppressed Unicode header', async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          references: [],
+          headers: new Headers({ References: '<ünicode@example.com>' }),
+        }),
+      );
+
+      assert.ok(!result.requiresSmtpUtf8);
+    });
+
+    test('should reject a message identifier a hand-built message carries', async () => {
+      await assert.rejects(
+        () => convertMessage(createTestMessage({ messageId: 'not an identifier' })),
+        { name: 'TypeError', message: /Invalid message ID/ },
+      );
+      await assert.rejects(() => convertMessage(createTestMessage({ references: ['a@b>'] })), {
+        name: 'TypeError',
+        message: /Invalid message ID/,
+      });
+    });
+
+    test('should reject a date a hand-built message carries', async () => {
+      await assert.rejects(
+        () => convertMessage(createTestMessage({ date: new Date('nonsense') })),
+        { name: 'TypeError', message: /Invalid date/ },
+      );
+    });
+
+    test("should root a generated identifier in the sender's domain", async () => {
+      const result = await convertMessage(
+        createTestMessage({
+          sender: { address: 'john@sub.example.org' },
+        }),
+      );
+
+      assert.match(occurrences(result.raw, 'Message-ID')[0], /^<[0-9a-f-]+@sub\.example\.org>$/);
+    });
+
+    test('should read the domain past a quoted local part', async () => {
+      // The at sign inside the quotes is not the separator.
+      const result = await convertMessage(
+        createTestMessage({
+          sender: { address: '"a@b"@example.com' },
+        }),
+      );
+
+      assert.match(occurrences(result.raw, 'Message-ID')[0], /^<[0-9a-f-]+@example\.com>$/);
+    });
+
+    test('should still generate an identifier for an unusual sender domain', async () => {
+      // `parseAddress()` validates domains with `URL`, which accepts spellings
+      // the identifier grammar does not.  Neither may fail the send.
+      const trailingDot = await convertMessage(
+        createTestMessage({
+          sender: { address: 'john@example.com.' },
+        }),
+      );
+      const withPort = await convertMessage(
+        createTestMessage({
+          sender: { address: 'john@example.com:8080' },
+        }),
+      );
+
+      assert.match(occurrences(trailingDot.raw, 'Message-ID')[0], /^<[0-9a-f-]+@example\.com>$/);
+      assert.match(occurrences(withPort.raw, 'Message-ID')[0], /^<[0-9a-f-]+@localhost>$/);
+    });
+
+    test('should write a year beyond four digits', async () => {
+      const date = new Date(0);
+      date.setUTCFullYear(10000, 0, 1);
+      date.setUTCHours(0, 0, 0, 0);
+      const result = await convertMessage(createTestMessage({ date }));
+
+      assert.deepStrictEqual(occurrences(result.raw, 'Date'), ['Sat, 01 Jan 10000 00:00:00 +0000']);
+    });
+  });
+
+  describe('Message ID Generation', () => {
+    test('should generate unique message IDs', async () => {
+      const message = createTestMessage();
+
+      const result1 = await convertMessage(message);
+      const result2 = await convertMessage(message);
+
+      const messageId1 = result1.raw.match(/Message-ID: <([^>]+)>/)?.[1];
+      const messageId2 = result2.raw.match(/Message-ID: <([^>]+)>/)?.[1];
+
+      assert.ok(messageId1);
+      assert.ok(messageId2);
+      assert.notStrictEqual(messageId1, messageId2);
+
+      // Rooted in the sender's domain, as RFC 5322 §3.6.4 recommends
+      assert.ok(messageId1.endsWith('@example.com'));
+      assert.ok(messageId2.endsWith('@example.com'));
+    });
+
+    test('should generate valid date headers', async () => {
+      const message = createTestMessage();
+      const result = await convertMessage(message);
+
+      const dateMatch = result.raw.match(/Date: (.+)/);
+      assert.ok(dateMatch);
+
+      const dateString = dateMatch[1];
+      const parsedDate = new Date(dateString);
+      assert.ok(!isNaN(parsedDate.getTime()));
+
+      // RFC 5322 §3.3 asks for a numeric zone, not the obsolete "GMT"
+      assert.match(dateString, /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} /);
+      assert.ok(dateString.endsWith(' +0000'));
+
+      // Should be recent (within last minute)
+      const now = new Date();
+      const timeDiff = Math.abs(now.getTime() - parsedDate.getTime());
+      assert.ok(timeDiff < 60000); // Less than 1 minute
+    });
+  });
+
+  describe('Base64 Encoding', () => {
+    test('should properly encode binary attachments', async () => {
+      // Create a test binary file (ZIP signature + some data)
+      const binaryContent = new Uint8Array([
+        0x50,
+        0x4b,
+        0x03,
+        0x04, // ZIP signature
+        0x14,
+        0x00,
+        0x00,
+        0x00, // Version, flags
+        0x08,
+        0x00,
+        0x00,
+        0x00, // Compression method, time
+      ]);
+
+      const message = createTestMessage({
+        attachments: [
+          {
+            filename: 'test.zip',
+            content: binaryContent,
+            contentType: 'application/zip',
+            contentId: 'zip-file',
+            inline: false,
+          },
+        ],
+      });
+
+      const result = await convertMessage(message);
+
+      // Should contain base64 encoded content
+      const expectedBase64 = Buffer.from(binaryContent).toString('base64');
+      assert.ok(result.raw.includes(expectedBase64));
+
+      // Should have proper line breaks (76 chars max per line)
+      const base64Lines = result.raw
+        .split('\r\n')
+        .filter((line) => /^[A-Za-z0-9+/]+=*$/.test(line) && line.length > 50);
+
+      if (base64Lines.length > 0) {
+        base64Lines.forEach((line) => {
+          assert.ok(line.length <= 76, `Base64 line too long: ${line.length} chars`);
+        });
+      }
+    });
+
+    test('should handle large attachments without stack overflow', async () => {
+      // Create a large attachment (500KB) to test the fixed encodeBase64 function
+      const largeContent = new Uint8Array(500 * 1024); // 500KB
+      // Fill with some pattern to make it realistic
+      for (let i = 0; i < largeContent.length; i++) {
+        largeContent[i] = i % 256;
+      }
+
+      const message = createTestMessage({
+        attachments: [
+          {
+            filename: 'large-file.pdf',
+            content: largeContent,
+            contentType: 'application/pdf',
+            contentId: 'large-pdf',
+            inline: false,
+          },
+        ],
+      });
+
+      // This should not throw a "Maximum call stack size exceeded" error
+      const result = await convertMessage(message);
+
+      // Should contain multipart structure
+      assert.ok(result.raw.includes('Content-Type: multipart/mixed'));
+      assert.ok(result.raw.includes('Content-Type: application/pdf; name="large-file.pdf"'));
+      assert.ok(result.raw.includes('Content-Transfer-Encoding: base64'));
+
+      // Should have proper line breaks in base64 content (76 chars max per line)
+      const base64Lines = result.raw
+        .split('\r\n')
+        .filter((line) => /^[A-Za-z0-9+/]+=*$/.test(line));
+
+      // Large file should result in many base64 lines
+      assert.ok(base64Lines.length > 100, 'Should have many base64 lines for large file');
+
+      // Each line should be 76 characters or less (except possibly the last line)
+      base64Lines.forEach((line, index) => {
+        if (index < base64Lines.length - 1) {
+          assert.ok(line.length <= 76, `Base64 line ${index} too long: ${line.length} chars`);
+        }
+      });
+    });
+  });
+
+  describe('Edge Cases', () => {
+    test('should handle empty content', async () => {
+      const message = createTestMessage({
+        content: { text: '' },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.strictEqual(result.envelope.from, 'john@example.com');
+      assert.ok(result.raw.includes('Content-Type: text/plain; charset=utf-8'));
+      // Empty content should still result in valid message structure
+      assert.ok(result.raw.includes('MIME-Version: 1.0'));
+    });
+
+    test('should handle message with no To recipients', async () => {
+      const message = createTestMessage({
+        recipients: [], // No To recipients
+        ccRecipients: [{ address: 'cc@example.com' }],
+        bccRecipients: [{ address: 'bcc@example.com' }],
+      });
+
+      const result = await convertMessage(message);
+
+      // Envelope should contain all recipients
+      assert.deepStrictEqual(result.envelope.to, ['cc@example.com', 'bcc@example.com']);
+
+      // Should have Cc header and empty To header (RFC compliant)
+      assert.ok(result.raw.includes('Cc: cc@example.com'));
+      assert.ok(result.raw.includes('To: '));
+    });
+
+    test('should handle very long lines in content', async () => {
+      const longLine = 'A'.repeat(1000);
+      const message = createTestMessage({
+        content: { text: longLine },
+      });
+
+      const result = await convertMessage(message);
+
+      // Should use quoted-printable encoding
+      assert.ok(result.raw.includes('Content-Transfer-Encoding: quoted-printable'));
+
+      // Long lines should be broken with soft line breaks (RFC 2045 requirement)
+      assert.ok(result.raw.includes('=\r\n'));
+
+      // When soft line breaks are removed, should contain the original long line
+      const rawWithoutSoftBreaks = result.raw.replace(/=\r\n/g, '');
+      assert.ok(rawWithoutSoftBreaks.includes(longLine));
+    });
+  });
+
+  describe('Calendar Composition', () => {
+    const ics = (...lines) => lines.join('\r\n') + '\r\n';
+
+    const request = ics(
+      'BEGIN:VCALENDAR',
+      'VERSION:2.0',
+      'METHOD:REQUEST',
+      'BEGIN:VEVENT',
+      'UID:1@example.com',
+      'DTSTAMP:20260901T100000Z',
+      'SUMMARY:Lunch',
+      'END:VEVENT',
+      'END:VCALENDAR',
+    );
+
+    /** Reads back the decoded body of the sole text/calendar part. */
+    const decodeCalendarPart = (raw) => {
+      const marker = raw.indexOf('Content-Type: text/calendar');
+      assert.ok(marker >= 0, 'no text/calendar part');
+      const bodyStart = raw.indexOf('\r\n\r\n', marker) + 4;
+      const bodyEnd = raw.indexOf('\r\n--', bodyStart);
+      const payload = raw.slice(bodyStart, bodyEnd < 0 ? undefined : bodyEnd);
+      return Buffer.from(payload.replace(/\r\n/g, ''), 'base64').toString('utf8');
+    };
+
+    test('should add a text/calendar alternative beside a text body', async () => {
+      const message = createTestMessage({
+        content: { text: 'Lunch on Wednesday.' },
+        calendar: { method: 'REQUEST', content: request },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('Content-Type: multipart/alternative'));
+      assert.ok(result.raw.includes('Content-Type: text/plain; charset=utf-8'));
+      assert.ok(result.raw.includes('Content-Type: text/calendar; charset=utf-8; method=REQUEST'));
+      assert.equal(decodeCalendarPart(result.raw), request);
+    });
+
+    test('should place the calendar after the other alternatives', async () => {
+      const message = createTestMessage({
+        content: { text: 'Lunch on Wednesday.', html: '<p>Lunch</p>' },
+        calendar: { method: 'REQUEST', content: request },
+      });
+
+      const result = await convertMessage(message);
+
+      const plain = result.raw.indexOf('Content-Type: text/plain');
+      const html = result.raw.indexOf('Content-Type: text/html');
+      const calendar = result.raw.indexOf('Content-Type: text/calendar');
+      assert.ok(plain >= 0 && html >= 0 && calendar >= 0);
+      assert.ok(plain < html, 'text/plain should precede text/html');
+      assert.ok(html < calendar, 'text/html should precede text/calendar');
+    });
+
+    test('should compose a calendar beside an HTML-only body', async () => {
+      const message = createTestMessage({
+        content: { html: '<p>Lunch</p>' },
+        calendar: { method: 'REQUEST', content: request },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('Content-Type: multipart/alternative'));
+      assert.ok(result.raw.includes('Content-Type: text/html; charset=utf-8'));
+      assert.ok(result.raw.includes('Content-Type: text/calendar'));
+      assert.ok(!result.raw.includes('Content-Type: text/plain'));
+    });
+
+    test('should encode the calendar part as base64', async () => {
+      const message = createTestMessage({
+        calendar: { method: 'REQUEST', content: request },
+      });
+
+      const result = await convertMessage(message);
+
+      const marker = result.raw.indexOf('Content-Type: text/calendar');
+      const headerEnd = result.raw.indexOf('\r\n\r\n', marker);
+      const partHeaders = result.raw.slice(marker, headerEnd);
+      assert.ok(partHeaders.includes('Content-Transfer-Encoding: base64'));
+    });
+
+    test('should carry the CANCEL method through to the parameter', async () => {
+      const cancel = ics(
+        'BEGIN:VCALENDAR',
+        'METHOD:CANCEL',
+        'BEGIN:VEVENT',
+        'UID:1@example.com',
+        'STATUS:CANCELLED',
+        'END:VEVENT',
+        'END:VCALENDAR',
+      );
+      const message = createTestMessage({
+        calendar: { method: 'CANCEL', content: cancel },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(result.raw.includes('Content-Type: text/calendar; charset=utf-8; method=CANCEL'));
+      assert.equal(decodeCalendarPart(result.raw), cancel);
+    });
+
+    test('should carry non-ASCII calendar content byte for byte', async () => {
+      const unicode = ics(
+        'BEGIN:VCALENDAR',
+        'METHOD:REQUEST',
+        'BEGIN:VEVENT',
+        'UID:1@example.com',
+        'SUMMARY:점심 식사 🍜',
+        'END:VEVENT',
+        'END:VCALENDAR',
+      );
+      const message = createTestMessage({
+        calendar: { method: 'REQUEST', content: unicode },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.equal(decodeCalendarPart(result.raw), unicode);
+      // Base64 keeps the part ASCII, so no SMTPUTF8 is demanded for the body.
+      assert.ok(!result.requiresSmtpUtf8);
+    });
+
+    test('should keep the calendar inside the alternative when attached files exist', async () => {
+      const message = createTestMessage({
+        content: { text: 'Lunch on Wednesday.' },
+        calendar: { method: 'REQUEST', content: request },
+        attachments: [
+          {
+            inline: false,
+            filename: 'agenda.txt',
+            content: new TextEncoder().encode('agenda'),
+            contentType: 'text/plain',
+            contentId: '',
+          },
+        ],
+      });
+
+      const result = await convertMessage(message);
+
+      const alternative = result.raw.indexOf('Content-Type: multipart/alternative');
+      const calendar = result.raw.indexOf('Content-Type: text/calendar');
+      const agenda = result.raw.indexOf('agenda.txt');
+      assert.ok(alternative >= 0 && calendar >= 0 && agenda >= 0);
+      assert.ok(alternative < calendar, 'calendar belongs to the alternative');
+      assert.ok(calendar < agenda, 'the alternative precedes the attachments');
+      assert.equal(decodeCalendarPart(result.raw), request);
+    });
+
+    test('should reject malformed calendar property syntax', async () => {
+      const message = createTestMessage({
+        calendar: {
+          method: 'REQUEST',
+          content: 'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nSUMMARY;BROKEN:Lunch\r\nEND:VCALENDAR\r\n',
+        },
+      });
+      await assert.rejects(() => convertMessage(message), TypeError);
+    });
+
+    test('should reject calendar content that never passed createMessage()', async () => {
+      const message = createTestMessage({
+        calendar: {
+          method: 'REQUEST',
+          content: 'BEGIN:VCALENDAR\r\nMETHOD:X"\r\nEND:VCALENDAR\r\n',
+        },
+      });
+
+      await assert.rejects(() => convertMessage(message), {
+        name: 'TypeError',
+      });
+    });
+
+    test('should not fold a long calendar Content-Type', async () => {
+      const message = createTestMessage({
+        calendar: {
+          method: 'DECLINECOUNTER',
+          content: ics('BEGIN:VCALENDAR', 'METHOD:DECLINECOUNTER', 'END:VCALENDAR'),
+        },
+      });
+
+      const result = await convertMessage(message);
+
+      assert.ok(
+        result.raw.includes('Content-Type: text/calendar; charset=utf-8; method=DECLINECOUNTER'),
+      );
+    });
+  });
+});
diff --git a/tests/unit/smtp-message-stream.test.js b/tests/unit/smtp-message-stream.test.js
new file mode 100644
index 0000000..99372a7
--- /dev/null
+++ b/tests/unit/smtp-message-stream.test.js
@@ -0,0 +1,260 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/message-stream.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { Buffer } = require('node:buffer');
+const { createMessage } = require('../../src/core/message.js');
+const { prepareMessage } = require('../../src/smtp/message-converter.js');
+const {
+  prepareMessageStream,
+  SmtpAttachmentReplayError,
+} = require('../../src/smtp/message-stream.js');
+const { signMessage } = require('../../src/mime/dkim/sign.js');
+const {
+  TEST_DKIM_ED25519_PRIVATE_KEY,
+  TEST_DKIM_PRIVATE_KEY,
+} = require('../helpers/smtp/dkim-test-keys.js');
+
+const collect = async (source, signal) => {
+  const chunks = [];
+  for await (const chunk of source) {
+    signal?.throwIfAborted();
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+};
+
+for (const algorithm of ['rsa-sha256', 'ed25519-sha256']) {
+  for (const canonicalization of [
+    'simple/simple',
+    'relaxed/simple',
+    'simple/relaxed',
+    'relaxed/relaxed',
+  ]) {
+    test(`streamed ${algorithm} ${canonicalization} equals the shared buffered signer`, async () => {
+      let reads = 0;
+      const dkim = {
+        bodyMode: 'streaming',
+        signatures: [
+          {
+            algorithm,
+            canonicalization,
+            selector: 'test',
+            signingDomain: 'example.com',
+            privateKey:
+              algorithm === 'rsa-sha256' ? TEST_DKIM_PRIVATE_KEY : TEST_DKIM_ED25519_PRIVATE_KEY,
+          },
+        ],
+      };
+      const plan = prepareMessage(
+        createMessage({
+          from: 'from@example.com',
+          to: 'to@example.com',
+          subject: 'Test',
+          content: { text: 'Test' },
+          attachments: {
+            filename: 'a.bin',
+            inline: false,
+            contentType: 'application/octet-stream',
+            contentId: 'a',
+            content: async function* () {
+              reads++;
+              yield new Uint8Array([1, 2]);
+              yield new Uint8Array([3, 4]);
+            },
+          },
+        }),
+        dkim,
+      );
+      const prepared = await prepareMessageStream(
+        plan,
+        () => {},
+        () => {},
+      );
+      assert.equal(reads, 1);
+      const raw = await collect(prepared.read());
+      assert.equal(reads, 2);
+      assert.equal(Buffer.byteLength(raw), prepared.size);
+      const unsigned = raw.slice(raw.indexOf('\r\n') + 2);
+      const signature = await signMessage(unsigned, dkim.signatures[0]);
+      assert.equal(raw, `${signature.headerName}: ${signature.signature}\r\n${unsigned}`);
+      const buffered = await prepareMessageStream(
+        { ...plan, dkim: { ...dkim, bodyMode: 'buffered' } },
+        () => {},
+        () => {},
+      );
+      assert.equal(reads, 3);
+      assert.equal(await collect(buffered.read()), raw);
+      assert.equal(reads, 3);
+    });
+  }
+}
+
+test('rejects different replay bytes even after unsigned signing fallback', async () => {
+  let reads = 0;
+  const plan = prepareMessage(
+    createMessage({
+      from: 'from@example.com',
+      to: 'to@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+      attachments: {
+        filename: 'a',
+        inline: false,
+        contentType: 'application/octet-stream',
+        contentId: 'a',
+        content: async function* () {
+          yield new Uint8Array([++reads]);
+        },
+      },
+    }),
+    {
+      bodyMode: 'streaming',
+      onSigningFailure: 'send-unsigned',
+      signatures: [
+        {
+          selector: 'test',
+          signingDomain: 'example.com',
+          privateKey: 'invalid',
+        },
+      ],
+    },
+  );
+  const prepared = await prepareMessageStream(
+    plan,
+    () => {},
+    () => {},
+  );
+  await assert.rejects(collect(prepared.read()), SmtpAttachmentReplayError);
+});
+
+test('multiple signatures share two source reads and preserve prior signatures on failure', async () => {
+  let reads = 0;
+  const signature = {
+    selector: 'test',
+    signingDomain: 'example.com',
+    privateKey: TEST_DKIM_PRIVATE_KEY,
+  };
+  const plan = prepareMessage(
+    createMessage({
+      from: 'from@example.com',
+      to: 'to@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+      attachments: {
+        filename: 'a',
+        inline: false,
+        contentType: 'application/octet-stream',
+        contentId: 'a',
+        content: async function* () {
+          reads++;
+          yield new Uint8Array([1]);
+        },
+      },
+    }),
+    {
+      bodyMode: 'streaming',
+      onSigningFailure: 'send-unsigned',
+      signatures: [
+        signature,
+        {
+          ...signature,
+          canonicalization: 'simple/simple',
+          headerFields: ['from', 'dkim-signature'],
+        },
+        { ...signature, privateKey: 'invalid' },
+      ],
+    },
+  );
+  const prepared = await prepareMessageStream(
+    plan,
+    () => {},
+    () => {},
+  );
+  const raw = await collect(prepared.read());
+  assert.equal(raw.match(/^DKIM-Signature:/gm)?.length, 2);
+  assert.equal(reads, 2);
+});
+
+const CALENDAR_REQUEST =
+  [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'SUMMARY:점심 식사',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+for (const bodyMode of ['buffered', 'streaming']) {
+  test(`a calendar body replays identically under ${bodyMode} DKIM`, async () => {
+    const dkim = {
+      bodyMode,
+      signatures: [
+        {
+          algorithm: 'rsa-sha256',
+          canonicalization: 'relaxed/relaxed',
+          selector: 'test',
+          signingDomain: 'example.com',
+          privateKey: TEST_DKIM_PRIVATE_KEY,
+        },
+      ],
+    };
+    const plan = prepareMessage(
+      createMessage({
+        from: 'from@example.com',
+        to: 'to@example.com',
+        subject: 'Lunch',
+        content: { text: 'Lunch on Wednesday.' },
+        calendar: { method: 'REQUEST', content: CALENDAR_REQUEST },
+      }),
+      dkim,
+    );
+
+    const first = await collect(plan.body());
+    const second = await collect(plan.body());
+
+    assert.equal(first, second);
+    assert.ok(first.includes('method=REQUEST'));
+    assert.equal(
+      Buffer.from(
+        first
+          .slice(first.indexOf('\r\n\r\n', first.indexOf('text/calendar')) + 4)
+          .split('\r\n\r\n')[0]
+          .replace(/\r\n/g, ''),
+        'base64',
+      ).toString('utf8'),
+      CALENDAR_REQUEST,
+    );
+
+    // The signed stream is produced from the very same bytes.
+    const prepared = await prepareMessageStream(
+      plan,
+      () => {},
+      () => {},
+    );
+    const signed = await collect(prepared.read());
+    assert.ok(signed.includes('method=REQUEST'));
+    assert.ok(signed.includes('DKIM-Signature:'));
+  });
+}
+
+test('size() counts the encoded calendar body', async () => {
+  const plan = prepareMessage(
+    createMessage({
+      from: 'from@example.com',
+      to: 'to@example.com',
+      subject: 'Lunch',
+      content: { text: 'Lunch on Wednesday.' },
+      calendar: { method: 'REQUEST', content: CALENDAR_REQUEST },
+    }),
+  );
+
+  const size = await plan.size();
+  const emitted = Buffer.byteLength(plan.headers) + Buffer.byteLength(await collect(plan.body()));
+
+  assert.equal(size, emitted);
+});
diff --git a/tests/unit/smtp-mime-regression.test.js b/tests/unit/smtp-mime-regression.test.js
new file mode 100644
index 0000000..f2a7d2f
--- /dev/null
+++ b/tests/unit/smtp-mime-regression.test.js
@@ -0,0 +1,48 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/mime-regression.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const { convertMessage } = require('../../src/smtp/message-converter.js');
+
+for (const text of ['first\r\nsecond', 'a'.repeat(150), ('x'.repeat(60) + '\n').repeat(20)]) {
+  test(`quoted-printable physical lines: ${JSON.stringify(text.slice(0, 20))}`, async () => {
+    const { raw } = await convertMessage(
+      createMessage({
+        from: 'from@example.com',
+        to: 'to@example.com',
+        subject: 'Test',
+        content: { text },
+      }),
+    );
+    const body = raw.split('\r\n\r\n')[1];
+    assert.ok(!/(?<!\r)\n/.test(body));
+    assert.ok(body.split('\r\n').every((line) => line.length <= 76));
+    const decoded = body
+      .replace(/=\r\n/g, '')
+      .replace(/=([0-9A-F]{2})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+    assert.equal(decoded, text);
+  });
+}
+
+test('reject an unfoldable inline Content-ID', async () => {
+  await assert.rejects(
+    convertMessage(
+      createMessage({
+        from: 'from@example.com',
+        to: 'to@example.com',
+        subject: 'Test',
+        content: { text: 'Test' },
+        attachments: {
+          filename: 'a',
+          contentType: 'text/plain',
+          content: new Uint8Array(),
+          inline: true,
+          contentId: 'x'.repeat(1000),
+        },
+      }),
+    ),
+    RangeError,
+  );
+});
diff --git a/tests/unit/smtp-oauth2.test.js b/tests/unit/smtp-oauth2.test.js
new file mode 100644
index 0000000..6cbd054
--- /dev/null
+++ b/tests/unit/smtp-oauth2.test.js
@@ -0,0 +1,443 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/oauth2.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const {
+  formatOauthbearer,
+  formatXoauth2,
+  OAuth2TokenManager,
+  selectOAuth2Mechanism,
+  SmtpAuthError,
+} = require('../../src/smtp/oauth2.js');
+
+// Decodes a base64 string back to its raw bytes as a Latin-1 string so that the
+// 0x01 (^A) separators are preserved for assertions.
+const decodeBase64 = (value) => {
+  const binary = atob(value);
+  return binary;
+};
+
+describe('formatXoauth2()', () => {
+  test('matches the published Google XOAUTH2 vector', () => {
+    // From https://developers.google.com/workspace/gmail/imap/xoauth2-protocol
+    const result = formatXoauth2(
+      'someuser@example.com',
+      'ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg',
+    );
+    assert.equal(
+      result,
+      'dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRm' +
+        'dDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==',
+    );
+  });
+
+  test('produces the documented control-character layout', () => {
+    const decoded = decodeBase64(formatXoauth2('u@e.com', 'tok'));
+    assert.equal(decoded, 'user=u@e.com\x01auth=Bearer tok\x01\x01');
+  });
+
+  test('encodes non-ASCII users without throwing', () => {
+    const decoded = decodeBase64(formatXoauth2('관리자@example.com', 'tok'));
+    // UTF-8 bytes of the Hangul characters must be preserved.
+    const expected = new TextEncoder().encode('user=관리자@example.com\x01auth=Bearer tok\x01\x01');
+    const actual = Uint8Array.from(decoded, (c) => c.charCodeAt(0));
+    assert.deepEqual(actual, expected);
+  });
+});
+
+describe('formatOauthbearer()', () => {
+  test('matches the RFC 7628 OAUTHBEARER vector', () => {
+    // From RFC 7628 §4.1.
+    const result = formatOauthbearer(
+      'user@example.com',
+      'vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==',
+      'server.example.com',
+      587,
+    );
+    assert.equal(
+      result,
+      'bixhPXVzZXJAZXhhbXBsZS5jb20sAWhvc3Q9c2VydmVyLmV4YW1wbGUuY29tAXBv' +
+        'cnQ9NTg3AWF1dGg9QmVhcmVyIHZGOWRmdDRxbVRjMk52YjNSbGNrQmhiSFJoZG1s' +
+        'emRHRXVZMjl0Q2c9PQEB',
+    );
+  });
+
+  test('omits host and port when not provided', () => {
+    const decoded = decodeBase64(formatOauthbearer('u@e.com', 'tok'));
+    assert.equal(decoded, 'n,a=u@e.com,\x01auth=Bearer tok\x01\x01');
+  });
+
+  test('escapes commas and equals signs in the authzid', () => {
+    const decoded = decodeBase64(formatOauthbearer('a,b=c@example.com', 'tok'));
+    assert.equal(decoded, 'n,a=a=2Cb=3Dc@example.com,\x01auth=Bearer tok\x01\x01');
+  });
+});
+
+describe('selectOAuth2Mechanism()', () => {
+  test('prefers XOAUTH2 when both are advertised', () => {
+    assert.equal(
+      selectOAuth2Mechanism(['AUTH PLAIN LOGIN XOAUTH2 OAUTHBEARER', 'HELP']),
+      'xoauth2',
+    );
+  });
+
+  test('falls back to OAUTHBEARER when XOAUTH2 is absent', () => {
+    assert.equal(selectOAuth2Mechanism(['AUTH PLAIN OAUTHBEARER']), 'oauthbearer');
+  });
+
+  test('defaults to xoauth2 when neither is advertised', () => {
+    assert.equal(selectOAuth2Mechanism(['AUTH PLAIN LOGIN']), 'xoauth2');
+    assert.equal(selectOAuth2Mechanism([]), 'xoauth2');
+  });
+
+  test('handles the AUTH= capability form', () => {
+    // The first mechanism is glued to the keyword, e.g. `AUTH=XOAUTH2 ...`.
+    assert.equal(selectOAuth2Mechanism(['AUTH=XOAUTH2 OAUTHBEARER']), 'xoauth2');
+    assert.equal(selectOAuth2Mechanism(['AUTH=OAUTHBEARER']), 'oauthbearer');
+  });
+});
+
+describe('OAuth2TokenManager', () => {
+  test('returns a static access token verbatim', async () => {
+    const auth = {
+      user: 'u@e.com',
+      accessToken: 'static-token',
+    };
+    const manager = new OAuth2TokenManager(auth);
+    assert.equal(await manager.getAccessToken(), 'static-token');
+  });
+
+  test('invokes a synchronous token provider', async () => {
+    let calls = 0;
+    const auth = {
+      user: 'u@e.com',
+      accessToken: () => {
+        calls++;
+        return 'provided';
+      },
+    };
+    const manager = new OAuth2TokenManager(auth);
+    assert.equal(await manager.getAccessToken(), 'provided');
+    await manager.getAccessToken();
+    assert.equal(calls, 2, 'provider is called for every authentication');
+  });
+
+  test('invokes an asynchronous token provider', async () => {
+    const auth = {
+      user: 'u@e.com',
+      accessToken: () => Promise.resolve('async-token'),
+    };
+    const manager = new OAuth2TokenManager(auth);
+    assert.equal(await manager.getAccessToken(), 'async-token');
+  });
+
+  test('exchanges a refresh token and caches the result', async () => {
+    let calls = 0;
+    let lastBody;
+    const fetchFn = (_input, init) => {
+      calls++;
+      lastBody = init?.body;
+      return Promise.resolve(
+        new Response(JSON.stringify({ access_token: 'fresh-token', expires_in: 3600 }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }),
+      );
+    };
+    const auth = {
+      user: 'u@e.com',
+      clientId: 'client-id',
+      clientSecret: 'client-secret',
+      refreshToken: 'refresh-token',
+      tokenEndpoint: 'https://oauth2.example.com/token',
+      scope: 'https://mail.google.com/',
+    };
+    const manager = new OAuth2TokenManager(auth, fetchFn);
+
+    assert.equal(await manager.getAccessToken(), 'fresh-token');
+    assert.equal(calls, 1);
+    assert.equal(lastBody?.get('grant_type'), 'refresh_token');
+    assert.equal(lastBody?.get('client_id'), 'client-id');
+    assert.equal(lastBody?.get('client_secret'), 'client-secret');
+    assert.equal(lastBody?.get('refresh_token'), 'refresh-token');
+    assert.equal(lastBody?.get('scope'), 'https://mail.google.com/');
+
+    // Second call within the validity window must reuse the cached token.
+    assert.equal(await manager.getAccessToken(), 'fresh-token');
+    assert.equal(calls, 1, 'cached token is reused; no second fetch');
+  });
+
+  test('calls fetchFn without binding it to the manager', async () => {
+    const receivers = [];
+    function recordingFetch() {
+      receivers.push(this);
+      return Promise.resolve(
+        new Response(JSON.stringify({ access_token: 't', expires_in: 3600 }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }),
+      );
+    }
+    const auth = {
+      user: 'u@e.com',
+      clientId: 'client-id',
+      refreshToken: 'refresh-token',
+      tokenEndpoint: 'https://oauth2.example.com/token',
+    };
+    const manager = new OAuth2TokenManager(auth, recordingFetch);
+    await manager.getAccessToken();
+
+    // The native fetch throws "Illegal invocation" if called as a method, so
+    // it must be invoked unbound, not as `this.fetchFn`. Upstream's ESM is strict
+    // and sees `undefined`; this sloppy-mode CommonJS function sees globalThis.
+    assert.ok(receivers[0] === undefined || receivers[0] === globalThis);
+    assert.notStrictEqual(receivers[0], manager);
+  });
+
+  test('refetches when the cached token is (near) expiry', async () => {
+    let calls = 0;
+    const fetchFn = () => {
+      calls++;
+      return Promise.resolve(
+        new Response(JSON.stringify({ access_token: `t${calls}`, expires_in: 0 }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }),
+      );
+    };
+    const auth = {
+      user: 'u@e.com',
+      clientId: 'client-id',
+      refreshToken: 'refresh-token',
+      tokenEndpoint: 'https://oauth2.example.com/token',
+    };
+    const manager = new OAuth2TokenManager(auth, fetchFn);
+
+    assert.equal(await manager.getAccessToken(), 't1');
+    assert.equal(await manager.getAccessToken(), 't2');
+    assert.equal(calls, 2);
+  });
+
+  test('coalesces concurrent refreshes into a single request', async () => {
+    let calls = 0;
+    const fetchFn = () => {
+      calls++;
+      return new Promise((resolve) =>
+        setTimeout(
+          () =>
+            resolve(
+              new Response(
+                JSON.stringify({
+                  access_token: 'shared-token',
+                  expires_in: 3600,
+                }),
+                {
+                  status: 200,
+                  headers: { 'content-type': 'application/json' },
+                },
+              ),
+            ),
+          10,
+        ),
+      );
+    };
+    const auth = {
+      user: 'u@e.com',
+      clientId: 'client-id',
+      refreshToken: 'refresh-token',
+      tokenEndpoint: 'https://oauth2.example.com/token',
+    };
+    const manager = new OAuth2TokenManager(auth, fetchFn);
+
+    const tokens = await Promise.all([
+      manager.getAccessToken(),
+      manager.getAccessToken(),
+      manager.getAccessToken(),
+    ]);
+    assert.deepEqual(tokens, ['shared-token', 'shared-token', 'shared-token']);
+    assert.equal(calls, 1, 'concurrent refreshes are coalesced into one request');
+  });
+
+  test('throws SmtpAuthError on a non-OK token response', async () => {
+    const fetchFn = () =>
+      Promise.resolve(
+        new Response(JSON.stringify({ error: 'invalid_grant' }), {
+          status: 400,
+          headers: { 'content-type': 'application/json' },
+        }),
+      );
+    const auth = {
+      user: 'u@e.com',
+      clientId: 'client-id',
+      refreshToken: 'refresh-token',
+      tokenEndpoint: 'https://oauth2.example.com/token',
+    };
+    const manager = new OAuth2TokenManager(auth, fetchFn);
+    await assert.rejects(
+      manager.getAccessToken(),
+      (error) => error instanceof SmtpAuthError && /invalid_grant/.test(error.message),
+    );
+  });
+
+  test('parses a string expires_in', async () => {
+    let calls = 0;
+    const fetchFn = () => {
+      calls++;
+      return Promise.resolve(
+        new Response(JSON.stringify({ access_token: `t${calls}`, expires_in: '0' }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }),
+      );
+    };
+    const auth = {
+      user: 'u@e.com',
+      clientId: 'client-id',
+      refreshToken: 'refresh-token',
+      tokenEndpoint: 'https://oauth2.example.com/token',
+    };
+    const manager = new OAuth2TokenManager(auth, fetchFn);
+
+    // "0" must parse to an immediate expiry, forcing a second fetch.
+    assert.equal(await manager.getAccessToken(), 't1');
+    assert.equal(await manager.getAccessToken(), 't2');
+    assert.equal(calls, 2);
+  });
+
+  test('falls back to the default lifetime for invalid expires_in', async () => {
+    for (const expiresIn of [-100, '100abc', '-5', 'Infinity', '1e309', null]) {
+      let calls = 0;
+      const fetchFn = () => {
+        calls++;
+        return Promise.resolve(
+          new Response(JSON.stringify({ access_token: 't', expires_in: expiresIn }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          }),
+        );
+      };
+      const auth = {
+        user: 'u@e.com',
+        clientId: 'client-id',
+        refreshToken: 'refresh-token',
+        tokenEndpoint: 'https://oauth2.example.com/token',
+      };
+      const manager = new OAuth2TokenManager(auth, fetchFn);
+
+      // An invalid value yields the default (~1h) lifetime, so the cached token
+      // is reused and there is no second fetch.
+      await manager.getAccessToken();
+      await manager.getAccessToken();
+      assert.equal(
+        calls,
+        1,
+        `expires_in=${JSON.stringify(expiresIn)} should use the default lifetime`,
+      );
+    }
+  });
+
+  test('reuses short-lived tokens within their lifetime', async () => {
+    let calls = 0;
+    const fetchFn = () => {
+      calls++;
+      return Promise.resolve(
+        new Response(JSON.stringify({ access_token: `t${calls}`, expires_in: 30 }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }),
+      );
+    };
+    const auth = {
+      user: 'u@e.com',
+      clientId: 'client-id',
+      refreshToken: 'refresh-token',
+      tokenEndpoint: 'https://oauth2.example.com/token',
+    };
+    const manager = new OAuth2TokenManager(auth, fetchFn);
+
+    // The safety margin is capped at half the lifetime, so a 30s token is
+    // cached rather than refreshed on every call.
+    assert.equal(await manager.getAccessToken(), 't1');
+    assert.equal(await manager.getAccessToken(), 't1');
+    assert.equal(calls, 1);
+  });
+
+  test('truncates an oversized error response body', async () => {
+    const fetchFn = () => Promise.resolve(new Response('E'.repeat(5000), { status: 502 }));
+    const auth = {
+      user: 'u@e.com',
+      clientId: 'client-id',
+      refreshToken: 'refresh-token',
+      tokenEndpoint: 'https://oauth2.example.com/token',
+    };
+    const manager = new OAuth2TokenManager(auth, fetchFn);
+    await assert.rejects(
+      manager.getAccessToken(),
+      (error) =>
+        error instanceof SmtpAuthError && error.message.includes('…') && error.message.length < 700,
+    );
+  });
+
+  test('rejects when the abort signal is already aborted', async () => {
+    const auth = {
+      user: 'u@e.com',
+      accessToken: 'static-token',
+    };
+    const manager = new OAuth2TokenManager(auth);
+    await assert.rejects(
+      manager.getAccessToken(AbortSignal.abort()),
+      (error) => error instanceof DOMException && error.name === 'AbortError',
+    );
+  });
+
+  test('preserves abort errors during the refresh request', async () => {
+    const controller = new AbortController();
+    const fetchFn = () => {
+      // Simulate the request being aborted mid-flight.
+      controller.abort();
+      return Promise.reject(new DOMException('The operation was aborted.', 'AbortError'));
+    };
+    const auth = {
+      user: 'u@e.com',
+      clientId: 'client-id',
+      refreshToken: 'refresh-token',
+      tokenEndpoint: 'https://oauth2.example.com/token',
+    };
+    const manager = new OAuth2TokenManager(auth, fetchFn);
+    await assert.rejects(
+      manager.getAccessToken(controller.signal),
+      (error) => error instanceof DOMException && error.name === 'AbortError',
+    );
+  });
+
+  test('rejects an insecure (non-HTTPS) token endpoint', () => {
+    assert.throws(
+      () =>
+        new OAuth2TokenManager({
+          user: 'u@e.com',
+          clientId: 'client-id',
+          refreshToken: 'refresh-token',
+          tokenEndpoint: 'http://oauth2.example.com/token',
+        }),
+      TypeError,
+    );
+  });
+
+  test('allows HTTPS and loopback HTTP token endpoints', () => {
+    for (const tokenEndpoint of [
+      'https://oauth2.example.com/token',
+      'http://localhost:8080/token',
+      'http://127.0.0.1:8080/token',
+      'http://[::1]:8080/token',
+    ]) {
+      const manager = new OAuth2TokenManager({
+        user: 'u@e.com',
+        clientId: 'client-id',
+        refreshToken: 'refresh-token',
+        tokenEndpoint,
+      });
+      assert.ok(manager instanceof OAuth2TokenManager);
+    }
+  });
+});
diff --git a/tests/unit/smtp-raw-message.integration.test.js b/tests/unit/smtp-raw-message.integration.test.js
new file mode 100644
index 0000000..014cd95
--- /dev/null
+++ b/tests/unit/smtp-raw-message.integration.test.js
@@ -0,0 +1,481 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/raw-message.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { Buffer } = require('node:buffer');
+const { createMessage } = require('../../src/core/message.js');
+const { isRawTransport } = require('../../src/core/transport.js');
+const { SmtpTransport } = require('../../src/smtp/smtp-transport.js');
+const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+const { composeMessage } = require('../../src/mime/index.js');
+const { readAttachmentContent } = require('../../src/core/attachment.js');
+const { TEST_DKIM_PRIVATE_KEY } = require('../helpers/smtp/dkim-test-keys.js');
+
+const envelope = {
+  from: 'sender@example.com',
+  to: ['recipient@example.com'],
+};
+const content = Buffer.from(
+  'Date: Tue, 1 Sep 2026 00:00:00 +0000\r\nMessage-ID: <original@example.com>\r\nBcc: hidden@example.com\r\nDKIM-Signature: existing;\r\n folded=value\r\nX-Duplicate: one\r\nX-Duplicate: two\r\nContent-Type: application/pkcs7-mime\r\n\r\n.opaque\r\n.\r\n',
+);
+const raw = { envelope, content, encoding: '7bit' };
+const setup = async (capabilities = ['SIZE 100000', '8BITMIME', 'SMTPUTF8', 'DSN']) => {
+  const server = new MockSmtpServer();
+  server.on('error', () => {});
+  server.setCapabilities(capabilities);
+  const transport = new SmtpTransport({
+    host: 'localhost',
+    port: await server.start(),
+    pool: true,
+    poolSize: 1,
+    socketTimeout: 300,
+  });
+  return {
+    server,
+    transport,
+    async close() {
+      await transport.closeAllConnections();
+      await server.stop();
+    },
+  };
+};
+
+for (const encoding of ['7bit', undefined]) {
+  test(`SMTP raw preserves MIME and reads factory ${encoding ? 'once' : 'twice'}`, async () => {
+    const context = await setup();
+    let opens = 0;
+    try {
+      assert.ok(isRawTransport(context.transport));
+      context.transport.config = {
+        ...context.transport.config,
+        dkim: {
+          signatures: [
+            {
+              signingDomain: 'example.com',
+              selector: 'x',
+              privateKey: 'must not be used',
+            },
+          ],
+        },
+      };
+      const receipt = await context.transport.sendRaw({
+        envelope,
+        encoding,
+        content: async function* () {
+          opens++;
+          if (encoding || opens === 2) {
+            assert.equal(context.server.getReceivedCommands().at(-1), 'DATA');
+          }
+          for (let i = 0; i < content.length; i++) {
+            yield content.subarray(i, i + 1);
+          }
+        },
+      });
+      assert.ok(receipt.successful, JSON.stringify(receipt));
+      assert.equal(opens, encoding ? 1 : 2);
+      const received = context.server.getReceivedMessages()[0];
+      assert.deepEqual(received.rawData, Buffer.from(content.toString().replace(/^\./gm, '..')));
+      const mail = context.server.getReceivedCommands().find((c) => c.startsWith('MAIL '));
+      assert.equal(mail.includes(`SIZE=${content.length}`), encoding === undefined);
+    } finally {
+      await context.close();
+    }
+  });
+}
+
+test('SMTP raw SIZE counts original bytes without an extra CRLF', async () => {
+  const context = await setup([`SIZE ${content.length}`]);
+  try {
+    const receipt = await context.transport.sendRaw(raw);
+    assert.ok(receipt.successful, JSON.stringify(receipt));
+    assert.ok(
+      context.server
+        .getReceivedCommands()
+        .includes(`MAIL FROM:<sender@example.com> SIZE=${content.length}`),
+    );
+  } finally {
+    await context.close();
+  }
+});
+
+for (const encoding of ['8bit', 'utf8']) {
+  test(`SMTP raw ${encoding} negotiates capabilities before opening sources`, async () => {
+    const context = await setup([]);
+    let opens = 0;
+    try {
+      const receipt = await context.transport.sendRaw({
+        ...raw,
+        encoding,
+        content: async function* () {
+          opens++;
+          yield content;
+        },
+      });
+      assert.ok(!receipt.successful);
+      assert.equal(
+        receipt.errors?.[0].code,
+        encoding === '8bit' ? 'smtp.8bitmime-unsupported' : 'smtp.smtputf8-unsupported',
+      );
+      assert.equal(opens, 0);
+      assert.ok(!context.server.getReceivedCommands().some((c) => c.startsWith('MAIL ')));
+      assert.ok((await context.transport.sendRaw(raw)).successful);
+      assert.equal(context.server.getConnectionCount(), 1);
+    } finally {
+      await context.close();
+    }
+  });
+}
+
+test('SMTP raw sends 8bit bytes unchanged without requiring SMTPUTF8', async () => {
+  const context = await setup(['8BITMIME']);
+  const binary = Buffer.concat([Buffer.from('X: y\r\n\r\n'), Buffer.from([0xff, 0x80, 13, 10])]);
+  try {
+    const receipt = await context.transport.sendRaw({
+      ...raw,
+      content: binary,
+      encoding: '8bit',
+    });
+    assert.ok(receipt.successful, JSON.stringify(receipt));
+    assert.deepEqual(context.server.getReceivedMessages()[0].rawData, binary);
+    assert.ok(
+      context.server.getReceivedCommands().includes('MAIL FROM:<sender@example.com> BODY=8BITMIME'),
+    );
+  } finally {
+    await context.close();
+  }
+});
+
+test('SMTP invalid raw DATA poisons its connection without delivering', async () => {
+  const context = await setup();
+  try {
+    const result = await context.transport.sendRaw({
+      ...raw,
+      content: Buffer.from('X: y\r\n\r\nno final newline'),
+    });
+    assert.ok(!result.successful);
+    assert.equal(result.errors?.[0].code, 'smtp.raw-message-invalid');
+    assert.equal(context.server.getReceivedMessages().length, 0);
+    assert.ok((await context.transport.sendRaw(raw)).successful);
+    assert.equal(context.server.getConnectionCount(), 2);
+  } finally {
+    await context.close();
+  }
+});
+
+test('SMTP raw envelope supports null sender and rejects option overrides', async () => {
+  const context = await setup();
+  try {
+    const receipt = await context.transport.sendRaw(
+      {
+        ...raw,
+        envelope: { ...envelope, from: null },
+      },
+      { dsn: { return: 'headers' } },
+    );
+    assert.ok(receipt.successful, JSON.stringify(receipt));
+    assert.ok(
+      context.server
+        .getReceivedCommands()
+        .some((c) => c.startsWith('MAIL FROM:<> ') && c.includes('RET=HDRS')),
+    );
+    // @ts-expect-error Raw envelopes cannot be overridden.
+    const failed = await context.transport.sendRaw(raw, { envelope });
+    assert.ok(!failed.successful);
+    assert.equal(failed.errors?.[0].code, 'smtp.envelope-invalid');
+    assert.ok(
+      (
+        await context.transport.send(
+          createMessage({
+            from: 'a@example.com',
+            to: 'b@example.com',
+            subject: 'composed',
+            content: { text: 'ok' },
+          }),
+        )
+      ).successful,
+    );
+  } finally {
+    await context.close();
+  }
+});
+
+for (const encoding of ['7bit', undefined]) {
+  test(`SMTP raw ${encoding ? 'DATA' : 'analysis'} stalls time out and close the source`, async () => {
+    const context = await setup();
+    let closed = 0;
+    try {
+      const receipt = await context.transport.sendRaw({
+        envelope,
+        encoding,
+        content: () => ({
+          [Symbol.asyncIterator]() {
+            return {
+              next: () => new Promise(() => {}),
+              return: () => {
+                closed++;
+                return Promise.resolve({
+                  done: true,
+                  value: undefined,
+                });
+              },
+            };
+          },
+        }),
+      });
+      assert.ok(!receipt.successful);
+      assert.ok(receipt.errorMessages.join().includes('timeout'));
+      assert.equal(closed, 1);
+      assert.equal(context.server.getReceivedMessages().length, 0);
+    } finally {
+      await context.close();
+    }
+  });
+
+  test(`SMTP raw ${encoding ? 'DATA' : 'analysis'} progress refreshes inactivity`, async () => {
+    const context = await setup();
+    try {
+      const receipt = await context.transport.sendRaw({
+        envelope,
+        encoding,
+        content: async function* () {
+          for (const text of ['X: y\r\n', '\r\n', 'one\r\n', 'two\r\n']) {
+            await new Promise((resolve) => setTimeout(resolve, 120));
+            yield Buffer.from(text);
+          }
+        },
+      });
+      assert.ok(receipt.successful, JSON.stringify(receipt));
+    } finally {
+      await context.close();
+    }
+  });
+}
+
+test("SMTP raw cancellation preserves the caller's reason during pending DATA", async () => {
+  const context = await setup();
+  const controller = new AbortController();
+  const reason = new TypeError('cancel raw');
+  let closed = 0;
+  try {
+    const pending = context.transport.sendRaw(
+      {
+        ...raw,
+        content: () => ({
+          [Symbol.asyncIterator]() {
+            return {
+              next() {
+                controller.abort(reason);
+                return new Promise(() => {});
+              },
+              return() {
+                closed++;
+                return Promise.resolve({ done: true, value: undefined });
+              },
+            };
+          },
+        }),
+      },
+      { signal: controller.signal },
+    );
+    await assert.rejects(pending, (error) => error === reason);
+    assert.equal(closed, 1);
+    assert.equal(context.server.getReceivedMessages().length, 0);
+  } finally {
+    await context.close();
+  }
+});
+
+test('SMTP raw analysis failure keeps a usable preflight connection', async () => {
+  const context = await setup();
+  try {
+    assert.ok(
+      !(
+        await context.transport.sendRaw({
+          ...raw,
+          encoding: undefined,
+          content: Buffer.from('bad\n'),
+        })
+      ).successful,
+    );
+    assert.ok((await context.transport.sendRaw(raw)).successful);
+    assert.equal(context.server.getConnectionCount(), 1);
+  } finally {
+    await context.close();
+  }
+});
+
+test('SMTP raw unknown source size is bounded during DATA', async () => {
+  const context = await setup(['SIZE 100']);
+  try {
+    const receipt = await context.transport.sendRaw({
+      ...raw,
+      content: async function* () {
+        yield content;
+      },
+    });
+    assert.ok(!receipt.successful);
+    assert.equal(receipt.errors?.[0].code, 'smtp.message-size-exceeded');
+    assert.equal(context.server.getReceivedMessages().length, 0);
+  } finally {
+    await context.close();
+  }
+});
+
+test('SMTP raw reports partial RCPT rejection', async () => {
+  const context = await setup(['PIPELINING']);
+  context.server.setResponses('RCPT', [
+    { code: 250, message: 'Accepted' },
+    {
+      code: 550,
+      message: 'Rejected',
+    },
+  ]);
+  try {
+    const receipt = await context.transport.sendRaw({
+      ...raw,
+      envelope: { ...envelope, to: ['a@example.com', 'b@example.com'] },
+    });
+    assert.ok(receipt.successful, JSON.stringify(receipt));
+    assert.equal(receipt.rejectedRecipients?.[0]?.recipient, 'b@example.com');
+  } finally {
+    await context.close();
+  }
+});
+
+const composedMessage = () =>
+  createMessage({
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    bcc: 'blind@example.com',
+    subject: 'Composed',
+    content: { text: '.First\r\nSecond' },
+  });
+const signing = {
+  signingDomain: 'example.com',
+  selector: 'test',
+  privateKey: TEST_DKIM_PRIVATE_KEY,
+};
+
+test('SMTP delivers composed bytes and the Bcc envelope', async () => {
+  const context = await setup();
+  try {
+    const composed = await composeMessage(composedMessage(), {
+      dkim: { signatures: [signing] },
+    });
+    const expected = await readAttachmentContent(composed.content);
+    assert.ok((await context.transport.sendRaw(composed)).successful);
+    const received = context.server.getReceivedMessages()[0];
+    assert.deepEqual(
+      Buffer.from(received.rawData.toString().replace(/^\.\./gm, '.')),
+      Buffer.from(expected),
+    );
+    assert.ok(context.server.getReceivedCommands().includes('RCPT TO:<blind@example.com>'));
+  } finally {
+    await context.close();
+  }
+});
+
+test('SMTP raw maps composed replay errors and discards interrupted DATA connections', async () => {
+  const context = await setup();
+  try {
+    let reads = 0;
+    const composed = await composeMessage(
+      {
+        ...composedMessage(),
+        attachments: [
+          {
+            filename: 'a',
+            contentId: 'a',
+            contentType: 'text/plain',
+            inline: false,
+            content: async function* () {
+              yield new Uint8Array([reads++]);
+            },
+          },
+        ],
+      },
+      { dkim: { bodyMode: 'streaming', signatures: [signing] } },
+    );
+    const receipt = await context.transport.sendRaw(composed);
+    assert.ok(!receipt.successful);
+    assert.equal(receipt.errors?.[0].code, 'smtp.raw-message-invalid');
+    assert.ok(!receipt.errors?.[0].retryable);
+    assert.ok((await context.transport.send(composedMessage())).successful);
+    assert.equal(context.server.getConnectionCount(), 2);
+  } finally {
+    await context.close();
+  }
+});
+
+for (const source of ['nested', 'signed']) {
+  test(`SMTP negotiates ${source} Unicode headers before MAIL`, async () => {
+    const context = await setup(['8BITMIME']);
+    try {
+      if (source === 'signed') {
+        context.transport.config = {
+          ...context.transport.config,
+          dkim: { signatures: [{ ...signing, signingDomain: '한글.example' }] },
+        };
+      }
+      const message =
+        source === 'nested'
+          ? {
+              ...composedMessage(),
+              attachments: [
+                {
+                  filename: 'a',
+                  contentId: '한글',
+                  contentType: 'text/plain',
+                  inline: true,
+                  content: new Uint8Array(),
+                },
+              ],
+            }
+          : composedMessage();
+      const receipt = await context.transport.send(message);
+      assert.ok(!receipt.successful);
+      assert.ok(!context.server.getReceivedCommands().some((c) => c.startsWith('MAIL ')));
+      context.transport.config = {
+        ...context.transport.config,
+        dkim: undefined,
+      };
+      assert.ok((await context.transport.send(composedMessage())).successful);
+      assert.equal(context.server.getConnectionCount(), 1);
+    } finally {
+      await context.close();
+    }
+    const supported = await setup();
+    try {
+      if (source === 'signed') {
+        supported.transport.config = {
+          ...supported.transport.config,
+          dkim: { signatures: [{ ...signing, signingDomain: '한글.example' }] },
+        };
+      }
+      const message =
+        source === 'nested'
+          ? {
+              ...composedMessage(),
+              attachments: [
+                {
+                  filename: 'a',
+                  contentId: '한글',
+                  contentType: 'text/plain',
+                  inline: true,
+                  content: new Uint8Array(),
+                },
+              ],
+            }
+          : composedMessage();
+      assert.ok((await supported.transport.send(message)).successful);
+      assert.ok(
+        supported.server
+          .getReceivedCommands()
+          .some((c) => c.startsWith('MAIL ') && c.includes('SMTPUTF8')),
+      );
+    } finally {
+      await supported.close();
+    }
+  });
+}
diff --git a/tests/unit/smtp-transport.dkim.test.js b/tests/unit/smtp-transport.dkim.test.js
new file mode 100644
index 0000000..27ce1cb
--- /dev/null
+++ b/tests/unit/smtp-transport.dkim.test.js
@@ -0,0 +1,433 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-transport.dkim.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { convertMessage } = require('../../src/smtp/message-converter.js');
+const {
+  TEST_DKIM_DOMAIN,
+  TEST_DKIM_PRIVATE_KEY,
+  TEST_DKIM_SELECTOR,
+} = require('../helpers/smtp/dkim-test-keys.js');
+
+describe('DKIM Integration Tests', () => {
+  const createTestMessage = (overrides = {}) => ({
+    sender: { name: 'John Doe', address: 'john@example.com' },
+    recipients: [{ name: 'Jane Doe', address: 'jane@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Hello, World!' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  });
+
+  const testDkimConfig = {
+    signatures: [
+      {
+        signingDomain: TEST_DKIM_DOMAIN,
+        selector: TEST_DKIM_SELECTOR,
+        privateKey: TEST_DKIM_PRIVATE_KEY,
+      },
+    ],
+  };
+
+  describe('Message Conversion with DKIM', () => {
+    test('should sign the resolved Message-ID', async () => {
+      const message = createTestMessage({ messageId: 'typed@example.com' });
+      const result = await convertMessage(message, {
+        signatures: [
+          {
+            signingDomain: TEST_DKIM_DOMAIN,
+            selector: TEST_DKIM_SELECTOR,
+            privateKey: TEST_DKIM_PRIVATE_KEY,
+            headerFields: ['from', 'to', 'subject', 'date', 'message-id'],
+          },
+        ],
+      });
+
+      const signedFields = /h=([^;]+)/.exec(result.raw);
+      assert.ok(signedFields);
+      assert.ok(signedFields[1].includes('message-id'));
+
+      // The signer reads the composed header block, so the field it covered is
+      // the one resolution produced rather than anything the message carried.
+      const messageIds = result.raw
+        .split('\r\n\r\n')[0]
+        .split('\r\n')
+        .filter((line) => line.startsWith('Message-ID:'));
+      assert.deepStrictEqual(messageIds, ['Message-ID: <typed@example.com>']);
+    });
+
+    test('should add DKIM-Signature header when DKIM is configured', async () => {
+      const message = createTestMessage();
+      const result = await convertMessage(message, testDkimConfig);
+
+      // Should have DKIM-Signature header
+      assert.ok(
+        result.raw.startsWith('DKIM-Signature:'),
+        'Message should start with DKIM-Signature header',
+      );
+
+      // Should contain required DKIM tags
+      assert.ok(result.raw.includes('v=1'), 'Should include version tag');
+      assert.ok(result.raw.includes('a=rsa-sha256'), 'Should include algorithm tag');
+      assert.ok(result.raw.includes(`d=${TEST_DKIM_DOMAIN}`), 'Should include signing domain tag');
+      assert.ok(result.raw.includes(`s=${TEST_DKIM_SELECTOR}`), 'Should include selector tag');
+      assert.ok(result.raw.includes('bh='), 'Should include body hash tag');
+      assert.ok(result.raw.includes('b='), 'Should include signature tag');
+    });
+
+    test('should include standard headers in signed header list', async () => {
+      const message = createTestMessage();
+      const result = await convertMessage(message, testDkimConfig);
+
+      // Check h= tag includes standard headers
+      const hMatch = result.raw.match(/h=([^;]+)/);
+      assert.ok(hMatch, 'Should have h= tag');
+
+      const signedHeaders = hMatch[1].toLowerCase();
+      assert.ok(signedHeaders.includes('from'), 'Should sign From header');
+      assert.ok(signedHeaders.includes('to'), 'Should sign To header');
+      assert.ok(signedHeaders.includes('subject'), 'Should sign Subject header');
+      assert.ok(signedHeaders.includes('date'), 'Should sign Date header');
+    });
+
+    test('should sign message with custom canonicalization', async () => {
+      const message = createTestMessage();
+      const config = {
+        signatures: [
+          {
+            signingDomain: TEST_DKIM_DOMAIN,
+            selector: TEST_DKIM_SELECTOR,
+            privateKey: TEST_DKIM_PRIVATE_KEY,
+            canonicalization: 'simple/simple',
+          },
+        ],
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.ok(result.raw.includes('c=simple/simple'), 'Should use specified canonicalization');
+    });
+
+    test('should sign message with custom header fields', async () => {
+      const message = createTestMessage();
+      const config = {
+        signatures: [
+          {
+            signingDomain: TEST_DKIM_DOMAIN,
+            selector: TEST_DKIM_SELECTOR,
+            privateKey: TEST_DKIM_PRIVATE_KEY,
+            headerFields: ['from', 'to', 'subject'],
+          },
+        ],
+      };
+
+      const result = await convertMessage(message, config);
+
+      const hMatch = result.raw.match(/h=([^;]+)/);
+      assert.ok(hMatch);
+      assert.strictEqual(
+        hMatch[1].toLowerCase(),
+        'from:to:subject',
+        'Should only include specified headers',
+      );
+    });
+
+    test('should preserve original message content after signing', async () => {
+      const message = createTestMessage({
+        subject: 'Original Subject',
+        content: { text: 'Original content here' },
+      });
+
+      const result = await convertMessage(message, testDkimConfig);
+
+      // Original message content should be preserved after DKIM-Signature header
+      assert.ok(result.raw.includes('Subject: Original Subject'), 'Subject should be preserved');
+      assert.ok(result.raw.includes('Original content here'), 'Content should be preserved');
+    });
+
+    test('should handle multiple DKIM signatures', async () => {
+      const message = createTestMessage();
+      const config = {
+        signatures: [
+          {
+            signingDomain: 'domain1.example.com',
+            selector: 'selector1',
+            privateKey: TEST_DKIM_PRIVATE_KEY,
+          },
+          {
+            signingDomain: 'domain2.example.com',
+            selector: 'selector2',
+            privateKey: TEST_DKIM_PRIVATE_KEY,
+          },
+        ],
+      };
+
+      const result = await convertMessage(message, config);
+
+      // Should have multiple DKIM-Signature headers
+      const dkimMatches = result.raw.match(/DKIM-Signature:/g);
+      assert.ok(dkimMatches);
+      assert.strictEqual(dkimMatches.length, 2, 'Should have two DKIM-Signature headers');
+
+      // Check both domains are present
+      assert.ok(result.raw.includes('d=domain1.example.com'), 'Should include first domain');
+      assert.ok(result.raw.includes('d=domain2.example.com'), 'Should include second domain');
+    });
+  });
+
+  describe('DKIM Signing Failure Handling', () => {
+    test('should throw error by default on signing failure', async () => {
+      const message = createTestMessage();
+      const config = {
+        signatures: [
+          {
+            signingDomain: TEST_DKIM_DOMAIN,
+            selector: TEST_DKIM_SELECTOR,
+            privateKey: 'invalid-private-key',
+          },
+        ],
+      };
+
+      await assert.rejects(
+        async () => await convertMessage(message, config),
+        /Failed to import private key/,
+        'Should throw error on invalid private key',
+      );
+    });
+
+    test("should throw error when onSigningFailure is 'throw'", async () => {
+      const message = createTestMessage();
+      const config = {
+        signatures: [
+          {
+            signingDomain: TEST_DKIM_DOMAIN,
+            selector: TEST_DKIM_SELECTOR,
+            privateKey: 'invalid-private-key',
+          },
+        ],
+        onSigningFailure: 'throw',
+      };
+
+      await assert.rejects(
+        async () => await convertMessage(message, config),
+        /Failed to import private key/,
+        "Should throw error when onSigningFailure is 'throw'",
+      );
+    });
+
+    test("should send unsigned when onSigningFailure is 'send-unsigned'", async () => {
+      const message = createTestMessage();
+      const config = {
+        signatures: [
+          {
+            signingDomain: TEST_DKIM_DOMAIN,
+            selector: TEST_DKIM_SELECTOR,
+            privateKey: 'invalid-private-key',
+          },
+        ],
+        onSigningFailure: 'send-unsigned',
+      };
+
+      // Should not throw
+      const result = await convertMessage(message, config);
+
+      // Should NOT have DKIM-Signature header (sent unsigned)
+      assert.ok(
+        !result.raw.includes('DKIM-Signature:'),
+        'Should not have DKIM-Signature when sending unsigned',
+      );
+
+      // Original message content should still be present
+      assert.ok(
+        result.raw.includes('From: John Doe <john@example.com>'),
+        'From header should be present',
+      );
+      assert.ok(result.raw.includes('Subject: Test Subject'));
+    });
+  });
+
+  describe('DKIM with Various Message Types', () => {
+    test('should sign HTML email', async () => {
+      const message = createTestMessage({
+        content: { html: '<h1>Hello</h1><p>World!</p>' },
+      });
+
+      const result = await convertMessage(message, testDkimConfig);
+
+      assert.ok(result.raw.includes('DKIM-Signature:'));
+      assert.ok(result.raw.includes('Content-Type: text/html'));
+      assert.ok(result.raw.includes('<h1>Hello</h1><p>World!</p>'));
+    });
+
+    test('should sign multipart email with HTML and text', async () => {
+      const message = createTestMessage({
+        content: {
+          text: 'Plain text version',
+          html: '<p>HTML version</p>',
+        },
+      });
+
+      const result = await convertMessage(message, testDkimConfig);
+
+      assert.ok(result.raw.includes('DKIM-Signature:'));
+      assert.ok(result.raw.includes('Content-Type: multipart/alternative'));
+      assert.ok(result.raw.includes('Plain text version'));
+      assert.ok(result.raw.includes('<p>HTML version</p>'));
+    });
+
+    test('should sign email with attachments', async () => {
+      const attachmentContent = new TextEncoder().encode('Attachment content');
+      const message = createTestMessage({
+        attachments: [
+          {
+            filename: 'test.txt',
+            content: attachmentContent,
+            contentType: 'text/plain',
+            contentId: 'test-file',
+            inline: false,
+          },
+        ],
+      });
+
+      const result = await convertMessage(message, testDkimConfig);
+
+      assert.ok(result.raw.includes('DKIM-Signature:'));
+      assert.ok(result.raw.includes('Content-Type: multipart/mixed'));
+      assert.ok(result.raw.includes('name="test.txt"'));
+    });
+
+    test('should sign email with non-ASCII content', async () => {
+      const message = createTestMessage({
+        sender: { name: '김철수', address: 'kim@example.com' },
+        subject: '한글 제목입니다',
+        content: { text: '안녕하세요! 이것은 한국어 테스트입니다.' },
+      });
+
+      const result = await convertMessage(message, testDkimConfig);
+
+      assert.ok(result.raw.includes('DKIM-Signature:'));
+      assert.ok(result.raw.includes('=?UTF-8?B?')); // Encoded subject
+    });
+
+    test('should sign high priority email', async () => {
+      const message = createTestMessage({
+        priority: 'high',
+      });
+
+      const result = await convertMessage(message, testDkimConfig);
+
+      assert.ok(result.raw.includes('DKIM-Signature:'));
+      assert.ok(result.raw.includes('X-Priority: 1'));
+      assert.ok(result.raw.includes('X-MSMail-Priority: High'));
+    });
+
+    test('should sign email with custom headers', async () => {
+      const headers = new Headers();
+      headers.set('X-Custom-Header', 'Custom Value');
+      headers.set('X-Mailer', 'Upyo Test');
+
+      const message = createTestMessage({ headers });
+      const result = await convertMessage(message, testDkimConfig);
+
+      assert.ok(result.raw.includes('DKIM-Signature:'));
+      assert.ok(result.raw.includes('x-custom-header: Custom Value'));
+      assert.ok(result.raw.includes('x-mailer: Upyo Test'));
+    });
+
+    test('should sign email with multiple recipients', async () => {
+      const message = createTestMessage({
+        recipients: [{ address: 'recipient1@example.com' }, { address: 'recipient2@example.com' }],
+        ccRecipients: [{ address: 'cc@example.com' }],
+        bccRecipients: [{ address: 'bcc@example.com' }],
+      });
+
+      const result = await convertMessage(message, testDkimConfig);
+
+      assert.ok(result.raw.includes('DKIM-Signature:'));
+      assert.deepStrictEqual(result.envelope.to, [
+        'recipient1@example.com',
+        'recipient2@example.com',
+        'cc@example.com',
+        'bcc@example.com',
+      ]);
+    });
+  });
+
+  describe('DKIM Signature Verification Structure', () => {
+    test('should produce valid DKIM-Signature header format', async () => {
+      const message = createTestMessage();
+      const result = await convertMessage(message, testDkimConfig);
+
+      // Extract DKIM-Signature header
+      const lines = result.raw.split('\r\n');
+      const dkimLine = lines[0];
+
+      assert.ok(dkimLine.startsWith('DKIM-Signature: v=1;'), 'Should start with version');
+
+      // Check all required tags are present
+      const requiredTags = ['v=', 'a=', 'c=', 'd=', 's=', 'h=', 'bh=', 'b='];
+      for (const tag of requiredTags) {
+        assert.ok(result.raw.includes(tag), `Should contain ${tag} tag`);
+      }
+    });
+
+    test('should generate valid Base64 body hash', async () => {
+      const message = createTestMessage();
+      const result = await convertMessage(message, testDkimConfig);
+
+      // Extract bh= value
+      const bhMatch = result.raw.match(/bh=([A-Za-z0-9+/]+=*)/);
+      assert.ok(bhMatch, 'Should have bh= tag with Base64 value');
+
+      // Should be valid Base64 (SHA-256 produces 32 bytes = 44 Base64 chars with padding)
+      const bhValue = bhMatch[1];
+      assert.ok(/^[A-Za-z0-9+/]+=*$/.test(bhValue), 'Body hash should be valid Base64');
+    });
+
+    test('should generate valid Base64 signature', async () => {
+      const message = createTestMessage();
+      const result = await convertMessage(message, testDkimConfig);
+
+      // Extract b= value (signature)
+      const bMatch = result.raw.match(/b=([A-Za-z0-9+/]+=*)/);
+      assert.ok(bMatch, 'Should have b= tag with Base64 value');
+
+      // Should be valid Base64 (RSA-2048 produces 256 bytes = 344 Base64 chars)
+      const bValue = bMatch[1];
+      assert.ok(/^[A-Za-z0-9+/]+=*$/.test(bValue), 'Signature should be valid Base64');
+    });
+  });
+
+  describe('Message without DKIM', () => {
+    test('should not add DKIM-Signature when no config is provided', async () => {
+      const message = createTestMessage();
+      const result = await convertMessage(message);
+
+      assert.ok(
+        !result.raw.includes('DKIM-Signature:'),
+        'Should not have DKIM-Signature without config',
+      );
+    });
+
+    test('should not add DKIM-Signature when config has empty signatures', async () => {
+      const message = createTestMessage();
+      const config = {
+        signatures: [],
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.ok(
+        !result.raw.includes('DKIM-Signature:'),
+        'Should not have DKIM-Signature with empty signatures',
+      );
+    });
+  });
+});
diff --git a/tests/unit/smtp-transport.integration.test.js b/tests/unit/smtp-transport.integration.test.js
new file mode 100644
index 0000000..589245e
--- /dev/null
+++ b/tests/unit/smtp-transport.integration.test.js
@@ -0,0 +1,1552 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-transport.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isSmtpResponseProviderDetails, SmtpTransport } = require('../../src/smtp/index.js');
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+
+describe('SmtpTransport Integration Tests', () => {
+  const setupTest = async (overrides = {}) => {
+    const server = new MockSmtpServer();
+    const serverPort = await server.start();
+
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port: serverPort,
+      secure: false,
+      connectionTimeout: 5000,
+      socketTimeout: 5000,
+      pool: false, // Disable pooling for predictable test behavior
+      ...overrides,
+    });
+
+    return { server, transport };
+  };
+
+  const teardownTest = async (server, transport) => {
+    await transport.closeAllConnections();
+    await server.stop();
+    // Give the event loop time to clean up resources
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  };
+
+  const createTestMessage = (overrides = {}) => {
+    return {
+      sender: { name: 'John Doe', address: 'john@example.com' },
+      recipients: [{ name: 'Jane Doe', address: 'jane@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+      ...overrides,
+    };
+  };
+
+  test('should reject sendMany when aborted after sending has started', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const controller = new AbortController();
+
+      const messages = async function* () {
+        yield createTestMessage();
+        yield createTestMessage();
+      };
+
+      const receipts = [];
+      await assert.rejects(
+        (async () => {
+          for await (const receipt of transport.sendMany(messages(), {
+            signal: controller.signal,
+          })) {
+            receipts.push(receipt);
+            // Cancel once the first message has been delivered.
+            controller.abort();
+          }
+        })(),
+        (error) => error instanceof DOMException && error.name === 'AbortError',
+      );
+
+      // The first message succeeded; cancellation then rejected rather than
+      // yielding a failed receipt.
+      assert.equal(receipts.length, 1);
+      assert.ok(receipts[0].successful);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should send a basic email successfully', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const message = createTestMessage();
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+      if (receipt.successful) {
+        assert.ok(receipt.messageId.length > 0);
+      }
+
+      const receivedMessages = server.getReceivedMessages();
+      assert.strictEqual(receivedMessages.length, 1);
+      assert.strictEqual(receivedMessages[0].from, 'john@example.com');
+      assert.deepStrictEqual(receivedMessages[0].to, ['jane@example.com']);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should override the SMTP envelope without changing headers', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const receipt = await transport.send(
+        createTestMessage({
+          ccRecipients: [{ address: 'copy@example.com' }],
+          bccRecipients: [{ address: 'blind@example.com' }],
+        }),
+        {
+          envelope: {
+            from: 'bounce+customer-42@example.net',
+            to: ['forward@example.net'],
+          },
+        },
+      );
+
+      assert.ok(receipt.successful);
+      const delivered = server.getReceivedMessages()[0];
+      assert.equal(delivered.from, 'bounce+customer-42@example.net');
+      assert.deepEqual(delivered.to, ['forward@example.net']);
+      assert.ok(delivered.data.includes('From: John Doe <john@example.com>'));
+      assert.ok(delivered.data.includes('To: Jane Doe <jane@example.com>'));
+      assert.ok(delivered.data.includes('Cc: copy@example.com'));
+      assert.ok(!delivered.data.includes('blind@example.com'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should serialize a null reverse-path', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const receipt = await transport.send(createTestMessage(), {
+        envelope: { from: null },
+      });
+
+      assert.ok(receipt.successful);
+      assert.ok(server.getReceivedCommands().includes('MAIL FROM:<>'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should reject an invalid envelope before connecting', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const receipt = await transport.send(createTestMessage(), {
+        envelope: { to: [] },
+      });
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.retryable, false);
+        assert.equal(receipt.errors?.[0]?.code, 'smtp.envelope-invalid');
+        assert.equal(receipt.errors?.[0]?.category, 'validation');
+      }
+      assert.equal(server.getConnectionCount(), 0);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should carry the typed identity through send and sendMany', async () => {
+    const { server, transport } = await setupTest({ pool: true });
+    try {
+      const date = new Date('2026-09-01T10:00:00Z');
+      const single = createTestMessage({
+        messageId: 'single@example.com',
+        date,
+      });
+      const receipt = await transport.send(single);
+      assert.ok(receipt.successful);
+
+      const receipts = [];
+      for await (const each of transport.sendMany([
+        createTestMessage({ messageId: 'first@example.com', date }),
+        createTestMessage({ messageId: 'second@example.com', date }),
+      ])) {
+        receipts.push(each);
+      }
+      assert.equal(receipts.length, 2);
+      assert.ok(receipts.every((each) => each.successful));
+
+      const delivered = server.getReceivedMessages().map((message) => message.data);
+      assert.equal(delivered.length, 3);
+      for (const [index, id] of ['single', 'first', 'second'].entries()) {
+        assert.ok(
+          delivered[index].includes(`Message-ID: <${id}@example.com>`),
+          `expected the ${id} identifier in message ${index}`,
+        );
+        assert.ok(delivered[index].includes('Date: Tue, 01 Sep 2026 10:00:00 +0000'));
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should reuse the same identity when a message is sent again', async () => {
+    const { server, transport } = await setupTest({ pool: true });
+    try {
+      // A retry re-sends the very same Message, so a typed identifier and date
+      // stay put where a generated one would move.
+      const message = createTestMessage({
+        messageId: 'retried@example.com',
+        date: new Date('2026-09-01T10:00:00Z'),
+      });
+      assert.ok((await transport.send(message)).successful);
+      assert.ok((await transport.send(message)).successful);
+
+      // oxlint-disable-next-line no-shadow -- upstream
+      const delivered = server.getReceivedMessages().map((message) => message.data);
+      const identity = delivered.map((data) =>
+        data
+          .split('\r\n')
+          .filter((line) => line.startsWith('Message-ID:') || line.startsWith('Date:')),
+      );
+      assert.deepEqual(identity[0], identity[1]);
+      assert.deepEqual(identity[0], [
+        'Date: Tue, 01 Sep 2026 10:00:00 +0000',
+        'Message-ID: <retried@example.com>',
+      ]);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should resolve a different envelope for each sendMany message', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const messages = [createTestMessage(), createTestMessage(), createTestMessage()];
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages, {
+        envelope: (_message, index) =>
+          index === 1
+            ? { to: [] }
+            : {
+                from: `bounce+${index}@example.net`,
+                to: [`recipient+${index}@example.net`],
+              },
+      })) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 3);
+      assert.ok(receipts[0].successful);
+      assert.ok(!receipts[1].successful);
+      if (!receipts[1].successful) {
+        assert.equal(receipts[1].errors?.[0]?.code, 'smtp.envelope-invalid');
+      }
+      assert.ok(receipts[2].successful);
+      assert.equal(server.getConnectionCount(), 1);
+      assert.deepEqual(
+        server
+          .getReceivedCommands()
+          .filter((command) => command.startsWith('MAIL FROM:') || command.startsWith('RCPT TO:')),
+        [
+          'MAIL FROM:<bounce+0@example.net>',
+          'RCPT TO:<recipient+0@example.net>',
+          'MAIL FROM:<bounce+2@example.net>',
+          'RCPT TO:<recipient+2@example.net>',
+        ],
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should continue sendMany after an envelope resolver throws', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const messages = [createTestMessage(), createTestMessage(), createTestMessage()];
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages, {
+        envelope: (_message, index) => {
+          if (index === 1) {
+            throw new TypeError('Cannot derive the SMTP envelope.');
+          }
+          return { from: `bounce+${index}@example.net` };
+        },
+      })) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 3);
+      assert.ok(receipts[0].successful);
+      assert.ok(!receipts[1].successful);
+      if (!receipts[1].successful) {
+        assert.equal(receipts[1].errors?.[0]?.code, 'smtp.envelope-invalid');
+      }
+      assert.ok(receipts[2].successful);
+      assert.equal(server.getConnectionCount(), 1);
+      assert.deepEqual(
+        server.getReceivedCommands().filter((command) => command.startsWith('MAIL FROM:')),
+        ['MAIL FROM:<bounce+0@example.net>', 'MAIL FROM:<bounce+2@example.net>'],
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should resolve envelopes for async sendMany messages', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const messages = async function* () {
+        yield createTestMessage();
+        yield createTestMessage();
+      };
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages(), {
+        envelope: (_message, index) =>
+          index === 0 ? { from: 'async-bounce+0@example.net' } : undefined,
+      })) {
+        receipts.push(receipt);
+      }
+
+      assert.ok(receipts.every((receipt) => receipt.successful));
+      assert.deepEqual(
+        server.getReceivedCommands().filter((command) => command.startsWith('MAIL FROM:')),
+        ['MAIL FROM:<async-bounce+0@example.net>', 'MAIL FROM:<john@example.com>'],
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should negotiate SMTPUTF8 from the effective envelope', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setCapabilities(['8BITMIME', 'SMTPUTF8']);
+
+      const receipt = await transport.send(createTestMessage(), {
+        envelope: { from: '반송@example.com' },
+      });
+
+      assert.ok(receipt.successful);
+      assert.ok(
+        server
+          .getReceivedCommands()
+          .includes('MAIL FROM:<반송@example.com> BODY=8BITMIME SMTPUTF8'),
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should ignore an overridden non-header Bcc address for SMTPUTF8', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const receipt = await transport.send(
+        createTestMessage({
+          bccRecipients: [{ address: '숨김@example.com' }],
+        }),
+        {
+          envelope: { to: ['forward@example.net'] },
+        },
+      );
+
+      assert.ok(receipt.successful);
+      assert.ok(server.getReceivedCommands().includes('MAIL FROM:<john@example.com>'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should retain SMTPUTF8 required by visible headers', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setCapabilities(['8BITMIME', 'SMTPUTF8']);
+
+      const receipt = await transport.send(
+        createTestMessage({
+          sender: { address: '발신@example.com' },
+        }),
+        {
+          envelope: { from: 'bounce@example.net' },
+        },
+      );
+
+      assert.ok(receipt.successful);
+      assert.ok(
+        server
+          .getReceivedCommands()
+          .includes('MAIL FROM:<bounce@example.net> BODY=8BITMIME SMTPUTF8'),
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should expose enhanced greeting failures', async () => {
+    const { server, transport } = await setupTest();
+    server.setResponse('GREETING', {
+      code: 421,
+      message: '4.3.2 Service not available',
+    });
+    try {
+      const receipt = await transport.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        const error = receipt.errors?.[0];
+        assert.equal(error?.code, 'smtp.421');
+        assert.equal(error?.category, 'service-unavailable');
+        assert.equal(error?.retryable, true);
+        assert.ok(isSmtpResponseProviderDetails(error?.providerDetails));
+        if (isSmtpResponseProviderDetails(error?.providerDetails)) {
+          assert.equal(error.providerDetails.command, 'GREETING');
+          assert.equal(error.providerDetails.response, '4.3.2 Service not available');
+          assert.deepEqual(error.providerDetails.enhancedStatusCode, {
+            code: '4.3.2',
+            class: 4,
+            subject: 3,
+            detail: 2,
+          });
+        }
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should expose enhanced EHLO failures', async () => {
+    const { server, transport } = await setupTest();
+    server.setResponse('EHLO', {
+      code: 451,
+      message: '4.4.0 Temporary DNS failure',
+    });
+    try {
+      const receipt = await transport.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        const error = receipt.errors?.[0];
+        assert.equal(error?.code, 'smtp.451');
+        assert.equal(error?.category, 'network');
+        assert.equal(error?.retryable, true);
+        assert.ok(isSmtpResponseProviderDetails(error?.providerDetails));
+        if (isSmtpResponseProviderDetails(error?.providerDetails)) {
+          assert.equal(error.providerDetails.command, 'EHLO');
+          assert.equal(error.providerDetails.response, '4.4.0 Temporary DNS failure');
+          assert.deepEqual(error.providerDetails.enhancedStatusCode, {
+            code: '4.4.0',
+            class: 4,
+            subject: 4,
+            detail: 0,
+          });
+        }
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  for (const method of ['plain', 'login']) {
+    test(`should expose enhanced ${method} authentication failures`, async () => {
+      const { server, transport } = await setupTest({
+        auth: {
+          user: 'testuser',
+          pass: 'testpass',
+          method,
+        },
+      });
+      server.setResponse('AUTH', {
+        code: 535,
+        message: '5.7.8 Bad credentials',
+      });
+      try {
+        const receipt = await transport.send(createTestMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          const error = receipt.errors?.[0];
+          assert.equal(error?.code, 'smtp.535');
+          assert.equal(error?.category, 'rejected');
+          assert.equal(error?.retryable, false);
+          assert.ok(isSmtpResponseProviderDetails(error?.providerDetails));
+          if (isSmtpResponseProviderDetails(error?.providerDetails)) {
+            assert.equal(error.providerDetails.command, `AUTH ${method.toUpperCase()}`);
+            assert.equal(error.providerDetails.response, '5.7.8 Bad credentials');
+            assert.deepEqual(error.providerDetails.enhancedStatusCode, {
+              code: '5.7.8',
+              class: 5,
+              subject: 7,
+              detail: 8,
+            });
+          }
+        }
+      } finally {
+        await teardownTest(server, transport);
+      }
+    });
+  }
+
+  test('should serialize RFC 3461 DSN parameters per recipient', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setCapabilities(['dSn', 'PIPELINING']);
+      const message = createTestMessage({
+        recipients: [{ address: 'jane+archive=2026@example.com' }],
+        ccRecipients: [{ address: 'johnny@example.com' }],
+        bccRecipients: [{ address: 'hidden@example.com' }],
+      });
+
+      const receipt = await transport.send(message, {
+        dsn: {
+          envelopeId: 'campaign+42=alpha beta',
+          return: 'headers',
+          recipients: {
+            'jane+archive=2026@example.com': {
+              notify: ['success', 'failure', 'delay'],
+              originalRecipient: 'jane+archive=2026@example.com',
+            },
+            'johnny@example.com': { notify: ['never'] },
+            'hidden@example.com': {
+              notify: ['failure'],
+              originalRecipient: 'hidden@example.com',
+            },
+          },
+        },
+      });
+
+      assert.ok(receipt.successful);
+      assert.deepEqual(
+        server
+          .getReceivedCommands()
+          .filter((command) => command.startsWith('MAIL FROM:') || command.startsWith('RCPT TO:')),
+        [
+          // oxlint-disable-next-line no-useless-concat -- upstream
+          'MAIL FROM:<john@example.com> RET=HDRS ' + 'ENVID=campaign+2B42+3Dalpha+20beta',
+          'RCPT TO:<jane+archive=2026@example.com> ' +
+            'NOTIFY=SUCCESS,FAILURE,DELAY ' +
+            'ORCPT=rfc822;jane+2Barchive+3D2026@example.com',
+          'RCPT TO:<johnny@example.com> NOTIFY=NEVER',
+          // oxlint-disable-next-line no-useless-concat -- upstream
+          'RCPT TO:<hidden@example.com> NOTIFY=FAILURE ' + 'ORCPT=rfc822;hidden@example.com',
+        ],
+      );
+      const delivered = server.getReceivedMessages()[0];
+      assert.ok(!delivered.data.includes('ENVID='));
+      assert.ok(!delivered.data.includes('NOTIFY='));
+      assert.ok(!delivered.data.includes('ORCPT='));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should validate DSN against overridden envelope recipients', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setCapabilities(['DSN']);
+
+      const receipt = await transport.send(createTestMessage(), {
+        envelope: { to: ['forward@example.net'] },
+        dsn: {
+          recipients: {
+            'forward@example.net': {
+              notify: ['failure'],
+              originalRecipient: 'forward@example.net',
+            },
+          },
+        },
+      });
+
+      assert.ok(receipt.successful);
+      assert.ok(
+        server.getReceivedCommands().includes(
+          // oxlint-disable-next-line no-useless-concat -- upstream
+          'RCPT TO:<forward@example.net> NOTIFY=FAILURE ' + 'ORCPT=rfc822;forward@example.net',
+        ),
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should reject DSN settings for replaced message recipients', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const receipt = await transport.send(createTestMessage(), {
+        envelope: { to: ['forward@example.net'] },
+        dsn: {
+          recipients: {
+            'jane@example.com': { notify: ['failure'] },
+          },
+        },
+      });
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errors?.[0]?.code, 'smtp.dsn-invalid');
+      }
+      assert.equal(server.getConnectionCount(), 0);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should fail before MAIL FROM when DSN is unavailable', async () => {
+    const { server, transport } = await setupTest({ pool: true });
+    try {
+      server.setCapabilities(['HELP']);
+
+      const unsupported = await transport.send(createTestMessage(), {
+        dsn: {
+          recipients: {
+            'jane@example.com': { notify: ['failure'] },
+          },
+        },
+      });
+      const ordinary = await transport.send(createTestMessage());
+
+      assert.ok(!unsupported.successful);
+      if (!unsupported.successful) {
+        assert.equal(unsupported.retryable, false);
+        assert.equal(unsupported.errors?.[0]?.code, 'smtp.dsn-unsupported');
+        assert.equal(unsupported.errors?.[0]?.category, 'configuration');
+      }
+      assert.ok(ordinary.successful);
+      assert.equal(server.getConnectionCount(), 1);
+      assert.deepEqual(
+        server.getReceivedCommands().filter((command) => command.startsWith('MAIL FROM:')),
+        ['MAIL FROM:<john@example.com>'],
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should reject incompatible DSN notification conditions', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const receipt = await transport.send(createTestMessage(), {
+        dsn: {
+          recipients: {
+            'jane@example.com': {
+              notify: ['never', 'failure'],
+            },
+          },
+        },
+      });
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.match(receipt.errorMessages[0], /NEVER.*by itself/);
+        assert.equal(receipt.retryable, false);
+        assert.equal(receipt.errors?.[0]?.code, 'smtp.dsn-invalid');
+        assert.equal(receipt.errors?.[0]?.category, 'validation');
+      }
+      assert.ok(!server.getReceivedCommands().some((command) => command.startsWith('MAIL FROM:')));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should reject invalid DSN xtext before connecting', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const receipt = await transport.send(createTestMessage(), {
+        dsn: { envelopeId: 'unicode-안녕' },
+      });
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.match(receipt.errorMessages[0], /printable US-ASCII/);
+        assert.equal(receipt.errors?.[0]?.code, 'smtp.dsn-invalid');
+      }
+      assert.equal(server.getConnectionCount(), 0);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should reject DSN options for a non-recipient address', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const receipt = await transport.send(createTestMessage(), {
+        dsn: {
+          recipients: {
+            'other@example.com': { notify: ['failure'] },
+          },
+        },
+      });
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.match(receipt.errorMessages[0], /not an envelope recipient/);
+        assert.equal(receipt.errors?.[0]?.code, 'smtp.dsn-invalid');
+      }
+      assert.equal(server.getConnectionCount(), 0);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should continue sendMany after invalid per-message DSN options', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setCapabilities(['DSN']);
+      const messages = [
+        createTestMessage(),
+        createTestMessage({
+          recipients: [{ address: 'other@example.com' }],
+        }),
+        createTestMessage(),
+      ];
+      const receipts = [];
+
+      for await (const receipt of transport.sendMany(messages, {
+        dsn: {
+          recipients: {
+            'jane@example.com': { notify: ['failure'] },
+          },
+        },
+      })) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 3);
+      assert.ok(receipts[0].successful);
+      assert.ok(!receipts[1].successful);
+      if (!receipts[1].successful) {
+        assert.equal(receipts[1].errors?.[0]?.code, 'smtp.dsn-invalid');
+        assert.equal(receipts[1].errors?.[0]?.category, 'validation');
+      }
+      assert.ok(receipts[2].successful);
+      assert.equal(server.getConnectionCount(), 1);
+      assert.deepEqual(
+        server.getReceivedCommands().filter((command) => command.startsWith('RCPT TO:')),
+        ['RCPT TO:<jane@example.com> NOTIFY=FAILURE', 'RCPT TO:<jane@example.com> NOTIFY=FAILURE'],
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should fail before MAIL FROM when the SIZE limit is exceeded', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setCapabilities(['SIZE 500']);
+
+      const receipt = await transport.send(
+        createTestMessage({
+          content: { text: 'x'.repeat(1000) },
+        }),
+      );
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.match(receipt.errorMessages[0], /Message size \d+ octets/);
+        assert.equal(receipt.retryable, false);
+        assert.equal(receipt.errors?.[0]?.code, 'smtp.message-size-exceeded');
+        assert.equal(receipt.errors?.[0]?.category, 'rejected');
+        const providerDetails = receipt.errors?.[0]?.providerDetails;
+        if (providerDetails == null || typeof providerDetails !== 'object') {
+          assert.fail('Expected provider details for the SIZE rejection.');
+        }
+        assert.ok('maximumSize' in providerDetails);
+        assert.equal(providerDetails.maximumSize, '500');
+        assert.ok('actualSize' in providerDetails);
+        assert.equal(typeof providerDetails.actualSize, 'number');
+      }
+      assert.ok(!server.getReceivedCommands().some((command) => command.startsWith('MAIL FROM:')));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should return a non-retryable failure when SMTPUTF8 is unavailable', async () => {
+    const { server, transport } = await setupTest({ pool: true });
+    try {
+      server.setCapabilities(['8BITMIME']);
+
+      const unsupported = await transport.send(
+        createTestMessage({
+          sender: { address: 'josé@example.com' },
+        }),
+      );
+      const accepted = await transport.send(createTestMessage());
+
+      assert.ok(!unsupported.successful);
+      if (!unsupported.successful) {
+        assert.equal(unsupported.retryable, false);
+        assert.equal(unsupported.errors?.[0]?.code, 'smtp.smtputf8-unsupported');
+        assert.equal(unsupported.errors?.[0]?.category, 'configuration');
+      }
+      assert.ok(accepted.successful);
+      assert.equal(server.getConnectionCount(), 1);
+      assert.deepEqual(
+        server.getReceivedCommands().filter((command) => command.startsWith('MAIL FROM:')),
+        ['MAIL FROM:<john@example.com>'],
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should continue sendMany after a local SIZE rejection', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setCapabilities(['SIZE 1000']);
+      const messages = [
+        createTestMessage({ content: { text: 'x'.repeat(2000) } }),
+        createTestMessage({ content: { text: 'small message' } }),
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.ok(!receipts[0].successful);
+      assert.ok(receipts[1].successful);
+      assert.equal(server.getReceivedMessages().length, 1);
+      assert.equal(
+        server.getReceivedCommands().filter((command) => command.startsWith('MAIL FROM:')).length,
+        1,
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should reuse a pooled connection after a local SIZE rejection', async () => {
+    const { server, transport } = await setupTest({ pool: true });
+    try {
+      server.setCapabilities(['SIZE 1000']);
+
+      const oversized = await transport.send(
+        createTestMessage({
+          content: { text: 'x'.repeat(2000) },
+        }),
+      );
+      const accepted = await transport.send(
+        createTestMessage({
+          content: { text: 'small message' },
+        }),
+      );
+
+      assert.ok(!oversized.successful);
+      assert.ok(accepted.successful);
+      assert.equal(server.getConnectionCount(), 1);
+      assert.equal(server.getReceivedMessages().length, 1);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should pool connections by default', async () => {
+    const { server, transport } = await setupTest({ pool: undefined });
+    try {
+      const firstReceipt = await transport.send(createTestMessage());
+      const secondReceipt = await transport.send(createTestMessage());
+
+      assert.ok(firstReceipt.successful);
+      assert.ok(secondReceipt.successful);
+      assert.equal(server.getConnectionCount(), 1);
+      assert.equal(server.getReceivedMessages().length, 2);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should require STARTTLS even when it is not advertised', async () => {
+    const { server, transport } = await setupTest({ requireTls: true });
+    server.setResponse('STARTTLS', {
+      code: 454,
+      message: '4.7.0 TLS temporarily unavailable',
+    });
+    try {
+      const receipt = await transport.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      assert.match(receipt.errorMessages.join(' '), /STARTTLS failed/);
+      if (!receipt.successful) {
+        const error = receipt.errors?.[0];
+        assert.equal(error?.code, 'smtp.454');
+        assert.equal(error?.category, 'service-unavailable');
+        assert.equal(error?.retryable, true);
+        assert.ok(isSmtpResponseProviderDetails(error?.providerDetails));
+        if (isSmtpResponseProviderDetails(error?.providerDetails)) {
+          assert.equal(error.providerDetails.command, 'STARTTLS');
+          assert.equal(error.providerDetails.response, '4.7.0 TLS temporarily unavailable');
+          assert.deepEqual(error.providerDetails.enhancedStatusCode, {
+            code: '4.7.0',
+            class: 4,
+            subject: 7,
+            detail: 0,
+          });
+        }
+      }
+      assert.equal(server.getReceivedMessages().length, 0);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should keep STARTTLS opportunistic when it is not required', async () => {
+    const { server, transport } = await setupTest({ requireTls: false });
+    server.setResponse('STARTTLS', {
+      code: 454,
+      message: 'TLS not available',
+    });
+    try {
+      const receipt = await transport.send(createTestMessage());
+
+      assert.ok(receipt.successful);
+      assert.equal(server.getReceivedMessages().length, 1);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should report rejected recipients after partial delivery', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setResponses('RCPT', [
+        { code: 250, message: 'OK' },
+        { code: 550, message: 'No such user here' },
+      ]);
+
+      const receipt = await transport.send(
+        createTestMessage({
+          recipients: [{ address: 'accepted@example.com' }, { address: 'rejected@example.com' }],
+        }),
+      );
+
+      assert.ok(receipt.successful, JSON.stringify(receipt));
+      if (receipt.successful) {
+        assert.deepStrictEqual(receipt.rejectedRecipients, [
+          {
+            recipient: 'rejected@example.com',
+            code: 550,
+            response: 'No such user here',
+            retryable: false,
+          },
+        ]);
+      }
+      assert.deepStrictEqual(server.getReceivedMessages()[0]?.to, ['accepted@example.com']);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should mark transient partial rejections as retryable', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setResponses('RCPT', [
+        { code: 250, message: 'OK' },
+        { code: 451, message: 'Try again later' },
+      ]);
+
+      const receipt = await transport.send(
+        createTestMessage({
+          recipients: [{ address: 'accepted@example.com' }, { address: 'deferred@example.com' }],
+        }),
+      );
+
+      assert.ok(receipt.successful, JSON.stringify(receipt));
+      if (receipt.successful) {
+        assert.deepStrictEqual(receipt.rejectedRecipients, [
+          {
+            recipient: 'deferred@example.com',
+            code: 451,
+            response: 'Try again later',
+            retryable: true,
+          },
+        ]);
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should retry interrupted recipient pipelines', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setCapabilities(['PIPELINING']);
+      server.setResponses('RCPT', [
+        { code: 250, message: 'OK' },
+        {
+          code: 550,
+          message: 'No such user here',
+          closeConnection: true,
+        },
+        { code: 250, message: 'OK' },
+      ]);
+
+      const receipt = await transport.send(
+        createTestMessage({
+          recipients: [
+            { address: 'accepted@example.com' },
+            { address: 'rejected@example.com' },
+            { address: 'unanswered@example.com' },
+          ],
+        }),
+      );
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.errors?.[0]?.category, 'network');
+        assert.equal(receipt.errors?.[0]?.code, 'network');
+        assert.match(receipt.errorMessages[0], /550 No such user here/);
+      }
+      assert.ok(!server.getReceivedCommands().some((command) => command === 'DATA'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should preserve retryability when every recipient is rejected', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setResponses('RCPT', [
+        { code: 550, message: 'No such user here' },
+        { code: 451, message: 'Try again later' },
+      ]);
+
+      const receipt = await transport.send(
+        createTestMessage({
+          recipients: [{ address: 'invalid@example.com' }, { address: 'deferred@example.com' }],
+        }),
+      );
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.strictEqual(receipt.retryable, true);
+        assert.ok(receipt.errorMessages[0].includes('550 No such user here'));
+        assert.ok(receipt.errorMessages[0].includes('451 Try again later'));
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should send email with HTML content', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const message = createTestMessage({
+        content: { html: '<h1>Hello, World!</h1>' },
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+
+      const receivedMessages = server.getReceivedMessages();
+      assert.strictEqual(receivedMessages.length, 1);
+      assert.ok(receivedMessages[0].data.includes('Content-Type: text/html'));
+      assert.ok(receivedMessages[0].data.includes('<h1>Hello, World!</h1>'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should send email with multiple recipients', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const message = createTestMessage({
+        recipients: [{ address: 'recipient1@example.com' }, { address: 'recipient2@example.com' }],
+        ccRecipients: [{ address: 'cc@example.com' }],
+        bccRecipients: [{ address: 'bcc@example.com' }],
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+
+      const receivedMessages = server.getReceivedMessages();
+      assert.strictEqual(receivedMessages.length, 1);
+      assert.deepStrictEqual(receivedMessages[0].to, [
+        'recipient1@example.com',
+        'recipient2@example.com',
+        'cc@example.com',
+        'bcc@example.com',
+      ]);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should send email with attachments', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const message = createTestMessage({
+        attachments: [
+          {
+            filename: 'test.txt',
+            contentType: 'text/plain',
+            content: new Uint8Array([72, 101, 108, 108, 111]), // "Hello"
+            contentId: 'attachment1',
+            inline: false,
+          },
+        ],
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+
+      const receivedMessages = server.getReceivedMessages();
+      assert.strictEqual(receivedMessages.length, 1);
+      assert.ok(receivedMessages[0].data.includes('Content-Type: multipart/mixed'));
+      assert.ok(receivedMessages[0].data.includes('filename="test.txt"'));
+      assert.ok(receivedMessages[0].data.includes('Content-Transfer-Encoding: base64'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should send multiple emails with sendMany', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const messages = [
+        createTestMessage({
+          subject: 'First email',
+          content: { text: 'First email content' },
+        }),
+        createTestMessage({
+          subject: 'Second email',
+          content: { text: 'Second email content' },
+        }),
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.strictEqual(receipts.length, 2);
+      assert.ok(receipts.every((r) => r.successful));
+
+      const receivedMessages = server.getReceivedMessages();
+      assert.strictEqual(receivedMessages.length, 2);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should continue sendMany after partial delivery', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setResponses('RCPT', [
+        { code: 250, message: 'OK' },
+        { code: 550, message: 'No such user here' },
+      ]);
+
+      const messages = [
+        createTestMessage({
+          recipients: [{ address: 'accepted@example.com' }, { address: 'rejected@example.com' }],
+        }),
+        createTestMessage({
+          recipients: [{ address: 'next@example.com' }],
+        }),
+      ];
+      const receipts = [];
+
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.strictEqual(receipts.length, 2);
+      assert.ok(receipts[0].successful);
+      if (receipts[0].successful) {
+        assert.strictEqual(receipts[0].rejectedRecipients.length, 1);
+      }
+      assert.ok(receipts[1].successful);
+      assert.deepStrictEqual(
+        server.getReceivedMessages().map((message) => message.to),
+        [['accepted@example.com'], ['next@example.com']],
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should handle custom headers', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const headers = new Headers();
+      headers.set('X-Custom-Header', 'Custom Value');
+      headers.set('X-Mailer', 'Test Mailer');
+
+      const message = createTestMessage({ headers });
+
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+
+      const receivedMessages = server.getReceivedMessages();
+      const receivedMessage = receivedMessages[0];
+
+      assert.ok(receivedMessage.data.includes('x-custom-header: Custom Value'));
+      assert.ok(receivedMessage.data.includes('x-mailer: Test Mailer'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should handle server errors gracefully', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setResponse('MAIL', { code: 550, message: 'Sender rejected' });
+
+      const message = createTestMessage();
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, false);
+      if (!receipt.successful) {
+        assert.ok(receipt.errorMessages.length > 0);
+        assert.ok(receipt.errorMessages[0].includes('MAIL FROM failed'));
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should mark transient recipient failures as retryable', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setResponse('RCPT', {
+        code: 451,
+        message: 'Requested action aborted: local error in processing',
+      });
+
+      const receipt = await transport.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.provider, 'smtp');
+        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.errors?.[0]?.code, 'smtp.451');
+        assert.equal(receipt.errors?.[0]?.category, 'service-unavailable');
+        assert.equal(receipt.errors?.[0]?.retryable, true);
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should expose enhanced address status codes', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setResponse('RCPT', {
+        code: 550,
+        message: '5.1.1 User unknown',
+      });
+
+      const receipt = await transport.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errors?.[0]?.category, 'validation');
+        assert.equal(receipt.errors?.[0]?.retryable, false);
+        assert.deepStrictEqual(receipt.errors?.[0]?.providerDetails, {
+          command: 'RCPT TO',
+          response: '5.1.1 User unknown',
+          rejectedRecipients: [
+            {
+              recipient: 'jane@example.com',
+              code: 550,
+              response: '5.1.1 User unknown',
+              retryable: false,
+              enhancedStatusCode: {
+                code: '5.1.1',
+                class: 5,
+                subject: 1,
+                detail: 1,
+              },
+            },
+          ],
+          enhancedStatusCode: {
+            code: '5.1.1',
+            class: 5,
+            subject: 1,
+            detail: 1,
+          },
+        });
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should expose enhanced transient policy status codes', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setResponse('RCPT', {
+        code: 451,
+        message: '4.7.1 Try again later',
+      });
+
+      const receipt = await transport.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errors?.[0]?.category, 'service-unavailable');
+        assert.equal(receipt.errors?.[0]?.retryable, true);
+        const details = receipt.errors?.[0]?.providerDetails;
+        assert.ok(isSmtpResponseProviderDetails(details));
+        assert.deepStrictEqual(details.enhancedStatusCode, {
+          code: '4.7.1',
+          class: 4,
+          subject: 7,
+          detail: 1,
+        });
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should expose enhanced permanent policy status codes', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      server.setResponse('RCPT', {
+        code: 550,
+        message: '5.7.1 Message rejected',
+      });
+
+      const receipt = await transport.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errors?.[0]?.category, 'rejected');
+        assert.equal(receipt.errors?.[0]?.retryable, false);
+        const details = receipt.errors?.[0]?.providerDetails;
+        assert.ok(details != null && typeof details === 'object');
+        assert.ok('enhancedStatusCode' in details);
+        assert.deepStrictEqual(details.enhancedStatusCode, {
+          code: '5.7.1',
+          class: 5,
+          subject: 7,
+          detail: 1,
+        });
+      }
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  for (const [code, message, category, retryable] of [
+    [451, '4.4.1 No answer from host', 'network', true],
+    [550, '5.6.1 Media not supported', 'validation', false],
+  ]) {
+    test(`should classify ${message} failures`, async () => {
+      const { server, transport } = await setupTest();
+      try {
+        server.setResponse('RCPT', { code, message });
+
+        const receipt = await transport.send(createTestMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.equal(receipt.errors?.[0]?.category, category);
+          assert.equal(receipt.errors?.[0]?.retryable, retryable);
+        }
+      } finally {
+        await teardownTest(server, transport);
+      }
+    });
+  }
+
+  for (const [name, message] of [
+    ['traditional reply', 'User unknown'],
+    ['leading zero', '5.01.1 User unknown'],
+    ['missing separator', '5.1.1User unknown'],
+    ['tab separator', '5.1.1\tUser unknown'],
+    ['incomplete code', '5.1 User unknown'],
+    ['overlong detail', '5.1.1000 User unknown'],
+    ['inconsistent class', '4.1.1 User unknown'],
+  ]) {
+    test(`should ignore enhanced status in ${name}`, async () => {
+      const { server, transport } = await setupTest();
+      try {
+        server.setResponse('RCPT', { code: 550, message });
+
+        const receipt = await transport.send(createTestMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.equal(receipt.errors?.[0]?.category, 'rejected');
+          const details = receipt.errors?.[0]?.providerDetails;
+          assert.ok(details != null && typeof details === 'object');
+          assert.ok(!('enhancedStatusCode' in details));
+        }
+      } finally {
+        await teardownTest(server, transport);
+      }
+    });
+  }
+
+  test('should handle non-ASCII characters in headers and content', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const message = createTestMessage({
+        subject: '테스트 제목 (Korean Subject)',
+        content: { text: '안녕하세요! Hello World! 🌍' },
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+
+      const receivedMessages = server.getReceivedMessages();
+      const receivedMessage = receivedMessages[0];
+
+      // Subject should be RFC 2047 encoded
+      assert.ok(receivedMessage.data.includes('Subject: =?UTF-8?B?'));
+
+      // Content should be quoted-printable encoded
+      assert.ok(receivedMessage.data.includes('Content-Transfer-Encoding: quoted-printable'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should handle mixed HTML and text content', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const message = createTestMessage({
+        content: {
+          text: 'Hello, World! (Plain text version)',
+          html: '<h1>Hello, World!</h1><p>HTML version</p>',
+        },
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+
+      const receivedMessages = server.getReceivedMessages();
+      const receivedMessage = receivedMessages[0];
+
+      // Should create multipart/alternative structure
+      assert.ok(receivedMessage.data.includes('Content-Type: multipart/alternative'));
+      assert.ok(receivedMessage.data.includes('Content-Type: text/plain'));
+      assert.ok(receivedMessage.data.includes('Content-Type: text/html'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should handle multiple attachment types', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const message = createTestMessage({
+        attachments: [
+          {
+            filename: 'document.pdf',
+            contentType: 'application/pdf',
+            content: new Uint8Array([37, 80, 68, 70]), // PDF header
+            contentId: 'doc1',
+            inline: false,
+          },
+          {
+            filename: 'image.png',
+            contentType: 'image/png',
+            content: new Uint8Array([137, 80, 78, 71]), // PNG header
+            contentId: 'img1',
+            inline: true,
+          },
+        ],
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+
+      const receivedMessages = server.getReceivedMessages();
+      const receivedMessage = receivedMessages[0];
+
+      assert.ok(receivedMessage.data.includes('Content-Type: multipart/mixed'));
+      assert.ok(receivedMessage.data.includes('filename="document.pdf"'));
+      assert.ok(receivedMessage.data.includes('filename="image.png"'));
+      assert.ok(receivedMessage.data.includes('Content-Disposition: attachment'));
+      assert.ok(receivedMessage.data.includes('Content-Disposition: inline'));
+      assert.ok(receivedMessage.data.includes('Content-ID: <img1>'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should handle priority levels correctly', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      // Test high priority
+      const highPriorityMessage = createTestMessage({
+        priority: 'high',
+        subject: 'High Priority Message',
+      });
+
+      await transport.send(highPriorityMessage);
+
+      // Test low priority
+      const lowPriorityMessage = createTestMessage({
+        priority: 'low',
+        subject: 'Low Priority Message',
+      });
+
+      await transport.send(lowPriorityMessage);
+
+      const receivedMessages = server.getReceivedMessages();
+      assert.strictEqual(receivedMessages.length, 2);
+
+      const highPriorityReceived = receivedMessages[0];
+      const lowPriorityReceived = receivedMessages[1];
+
+      // High priority should have priority headers
+      assert.ok(highPriorityReceived.data.includes('X-Priority: 1'));
+      assert.ok(highPriorityReceived.data.includes('X-MSMail-Priority: High'));
+
+      // Low priority should have priority headers
+      assert.ok(lowPriorityReceived.data.includes('X-Priority: 5'));
+      assert.ok(lowPriorityReceived.data.includes('X-MSMail-Priority: Low'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('should handle reply-to addresses', async () => {
+    const { server, transport } = await setupTest();
+    try {
+      const message = createTestMessage({
+        replyRecipients: [
+          { name: 'Support', address: 'support@example.com' },
+          { name: 'Sales', address: 'sales@example.com' },
+        ],
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.strictEqual(receipt.successful, true);
+
+      const receivedMessages = server.getReceivedMessages();
+      const receivedMessage = receivedMessages[receivedMessages.length - 1];
+
+      assert.ok(
+        receivedMessage.data.includes(
+          'Reply-To: Support <support@example.com>, Sales <sales@example.com>',
+        ),
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+});
diff --git a/tests/unit/smtp-transport.oauth2.integration.test.js b/tests/unit/smtp-transport.oauth2.integration.test.js
new file mode 100644
index 0000000..812834f
--- /dev/null
+++ b/tests/unit/smtp-transport.oauth2.integration.test.js
@@ -0,0 +1,140 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-transport.oauth2.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { isSmtpResponseProviderDetails } = require('../../src/smtp/smtp-receipt.js');
+const { SmtpTransport } = require('../../src/smtp/smtp-transport.js');
+const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+const { createTestMessage } = require('../helpers/smtp/test-config.js');
+
+describe('SmtpTransport OAuth 2.0 integration', () => {
+  const setup = async (auth, overrides = {}) => {
+    const server = new MockSmtpServer();
+    await server.start();
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port: server.getPort(),
+      secure: false,
+      connectionTimeout: 5000,
+      socketTimeout: 5000,
+      auth,
+      ...overrides,
+    });
+    return { server, transport };
+  };
+
+  test('sends a message authenticated with a static XOAUTH2 token', async () => {
+    const { server, transport } = await setup({
+      user: 'user@example.com',
+      accessToken: 'the-access-token',
+    });
+    try {
+      const receipt = await transport.send(createTestMessage());
+      assert.ok(receipt.successful);
+      assert.equal(server.getReceivedMessages().length, 1);
+      assert.ok(server.getLastAuthCommand()?.startsWith('AUTH XOAUTH2 '));
+    } finally {
+      await transport.closeAllConnections();
+      await server.stop();
+    }
+  });
+
+  test('sends a message authenticated with OAUTHBEARER', async () => {
+    const { server, transport } = await setup({
+      user: 'user@example.com',
+      accessToken: 'the-access-token',
+      method: 'oauthbearer',
+    });
+    try {
+      const receipt = await transport.send(createTestMessage());
+      assert.ok(receipt.successful);
+      assert.ok(server.getLastAuthCommand()?.startsWith('AUTH OAUTHBEARER '));
+    } finally {
+      await transport.closeAllConnections();
+      await server.stop();
+    }
+  });
+
+  test('shares one refreshed access token across connections', async () => {
+    const originalFetch = globalThis.fetch;
+    let fetchCalls = 0;
+    globalThis.fetch = (_input, _init) => {
+      fetchCalls++;
+      return Promise.resolve(
+        new Response(JSON.stringify({ access_token: 'refreshed', expires_in: 3600 }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        }),
+      );
+    };
+
+    let server;
+    let transport;
+    try {
+      // Pooling disabled so each send uses a fresh connection that
+      // authenticates independently; the shared token manager must still
+      // refresh only once.
+      ({ server, transport } = await setup(
+        {
+          user: 'user@example.com',
+          clientId: 'client-id',
+          clientSecret: 'client-secret',
+          refreshToken: 'refresh-token',
+          tokenEndpoint: 'https://oauth2.example.com/token',
+        },
+        { pool: false },
+      ));
+
+      const first = await transport.send(createTestMessage());
+      const second = await transport.send(createTestMessage());
+      assert.ok(first.successful);
+      assert.ok(second.successful);
+      assert.equal(
+        fetchCalls,
+        1,
+        'the refresh token is exchanged once and cached across connections',
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+      await transport?.closeAllConnections();
+      await server?.stop();
+    }
+  });
+
+  test('reports a failed receipt when OAuth authentication is rejected', async () => {
+    // Authentication happens while establishing the connection; like other SMTP
+    // setup failures, a rejected token yields a failed receipt rather than
+    // throwing.
+    const { server, transport } = await setup({
+      user: 'user@example.com',
+      accessToken: 'bad-token',
+    });
+    server.setResponse('AUTH', { code: 535, message: '5.7.8 Bad credentials' });
+    try {
+      const receipt = await transport.send(createTestMessage());
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.ok(receipt.errorMessages.some((m) => /XOAUTH2/.test(m)));
+        const error = receipt.errors?.[0];
+        assert.equal(error?.code, 'smtp.535');
+        assert.equal(error?.category, 'rejected');
+        assert.equal(error?.retryable, false);
+        assert.ok(isSmtpResponseProviderDetails(error?.providerDetails));
+        if (isSmtpResponseProviderDetails(error?.providerDetails)) {
+          assert.equal(error.providerDetails.command, 'AUTH XOAUTH2');
+          assert.equal(error.providerDetails.response, '5.7.8 Bad credentials');
+          assert.deepEqual(error.providerDetails.enhancedStatusCode, {
+            code: '5.7.8',
+            class: 5,
+            subject: 7,
+            detail: 8,
+          });
+        }
+      }
+    } finally {
+      await transport.closeAllConnections();
+      await server.stop();
+    }
+  });
+});
diff --git a/tests/unit/smtp-transport.pool.integration.test.js b/tests/unit/smtp-transport.pool.integration.test.js
new file mode 100644
index 0000000..e60d8e7
--- /dev/null
+++ b/tests/unit/smtp-transport.pool.integration.test.js
@@ -0,0 +1,451 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-transport.pool.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { SmtpTransport } = require('../../src/smtp/index.js');
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+
+describe('SmtpTransport connection limit', () => {
+  const createTestMessage = (overrides = {}) => {
+    return {
+      sender: { name: 'John Doe', address: 'john@example.com' },
+      recipients: [{ name: 'Jane Doe', address: 'jane@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+      ...overrides,
+    };
+  };
+
+  const setupTest = async (options) => {
+    const server = new MockSmtpServer();
+    const serverPort = await server.start();
+
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port: serverPort,
+      secure: false,
+      connectionTimeout: 5000,
+      socketTimeout: 5000,
+      pool: options.pool ?? true,
+      poolSize: options.poolSize,
+    });
+
+    return { server, transport };
+  };
+
+  const teardownTest = async (server, transport) => {
+    await transport.closeAllConnections();
+    await server.stop();
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  };
+
+  test('concurrent sends never exceed poolSize connections', async () => {
+    const { server, transport } = await setupTest({ poolSize: 3 });
+
+    try {
+      const receipts = await Promise.all(
+        Array.from({ length: 12 }, () => transport.send(createTestMessage())),
+      );
+
+      for (const receipt of receipts) {
+        assert.ok(
+          receipt.successful,
+          `Expected every send to succeed, got: ${
+            receipt.successful ? '' : receipt.errorMessages.join(', ')
+          }`,
+        );
+      }
+      assert.ok(
+        server.getPeakConcurrentConnections() <= 3,
+        `Expected at most 3 simultaneous connections, saw ${server.getPeakConcurrentConnections()}`,
+      );
+      assert.strictEqual(server.getReceivedMessages().length, 12);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('concurrent sendMany calls never exceed poolSize connections', async () => {
+    const { server, transport } = await setupTest({ poolSize: 2 });
+
+    try {
+      await Promise.all(
+        Array.from({ length: 6 }, async () => {
+          const messages = [createTestMessage(), createTestMessage()];
+          for await (const receipt of transport.sendMany(messages)) {
+            assert.ok(receipt.successful);
+          }
+        }),
+      );
+
+      assert.ok(
+        server.getPeakConcurrentConnections() <= 2,
+        `Expected at most 2 simultaneous connections, saw ${server.getPeakConcurrentConnections()}`,
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('overlapping returns never leave more idle connections than poolSize', async () => {
+    const { server, transport } = await setupTest({ poolSize: 3 });
+    // A slow RSET keeps several returns in flight at once, which is the window
+    // where a plain length check lets every return past the limit.
+    server.setResponseDelay('RSET', 40);
+
+    try {
+      await Promise.all(Array.from({ length: 9 }, () => transport.send(createTestMessage())));
+
+      assert.ok(
+        server.getPeakConcurrentConnections() <= 3,
+        `Expected at most 3 simultaneous connections, saw ${server.getPeakConcurrentConnections()}`,
+      );
+      assert.ok(
+        server.getActiveConnectionCount() <= 3,
+        `Expected at most 3 retained connections, saw ${server.getActiveConnectionCount()}`,
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('the limit applies even when pooling is disabled', async () => {
+    const { server, transport } = await setupTest({
+      pool: false,
+      poolSize: 2,
+    });
+
+    try {
+      await Promise.all(Array.from({ length: 8 }, () => transport.send(createTestMessage())));
+
+      assert.ok(
+        server.getPeakConcurrentConnections() <= 2,
+        `Expected at most 2 simultaneous connections, saw ${server.getPeakConcurrentConnections()}`,
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('aborting while waiting for capacity rejects without sending', async () => {
+    const { server, transport } = await setupTest({ poolSize: 1 });
+    // Hold the only connection inside DATA long enough for the second send to
+    // queue behind it.
+    server.setResponseDelay('DATA_END', 300);
+
+    try {
+      const first = transport.send(createTestMessage({ subject: 'first' }));
+
+      const controller = new AbortController();
+      const waiting = transport.send(createTestMessage({ subject: 'waiting' }), {
+        signal: controller.signal,
+      });
+      const rejection = assert.rejects(
+        () => waiting,
+        (error) => error.name === 'AbortError',
+      );
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      controller.abort();
+      await rejection;
+
+      const firstReceipt = await first;
+      assert.ok(firstReceipt.successful);
+
+      const subjects = server
+        .getReceivedMessages()
+        .map((message) => /Subject: (.*)/.exec(message.data)?.[1]?.trim());
+      assert.ok(!subjects.includes('waiting'));
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('aborting a waiting send does not leak capacity', async () => {
+    const { server, transport } = await setupTest({ poolSize: 1 });
+    server.setResponseDelay('DATA_END', 200);
+
+    try {
+      const first = transport.send(createTestMessage());
+
+      const controller = new AbortController();
+      const waiting = transport.send(createTestMessage(), {
+        signal: controller.signal,
+      });
+      const rejection = assert.rejects(() => waiting);
+      // Queued behind the send that gets aborted, so it can only proceed if the
+      // aborted one leaves the queue and passes its wake-up along.
+      const queued = transport.send(createTestMessage());
+
+      await new Promise((resolve) => setTimeout(resolve, 20));
+      controller.abort();
+      await rejection;
+
+      assert.ok((await first).successful);
+      assert.ok((await queued).successful);
+
+      // The aborted send must have given its place back, so this one proceeds.
+      server.setResponseDelay('DATA_END', 0);
+      const later = await transport.send(createTestMessage());
+      assert.ok(later.successful);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('a failed connection setup gives its slot back', async () => {
+    const { server, transport } = await setupTest({ poolSize: 1 });
+    server.setResponse('EHLO', { code: 550, message: 'Not today' });
+
+    try {
+      const failed = await transport.send(createTestMessage());
+      assert.ok(!failed.successful);
+
+      // The only slot was reserved before the handshake, so a leak here would
+      // make every later send wait forever.
+      server.setResponse('EHLO', {
+        code: 250,
+        message: 'Hello, pleased to meet you',
+      });
+      const later = await transport.send(createTestMessage());
+      assert.ok(later.successful);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('abandoning sendMany early releases the connection', async () => {
+    const { server, transport } = await setupTest({ poolSize: 1 });
+
+    try {
+      const messages = [createTestMessage(), createTestMessage(), createTestMessage()];
+      for await (const receipt of transport.sendMany(messages)) {
+        assert.ok(receipt.successful);
+        break;
+      }
+
+      // The abandoned iteration must not keep the only connection slot.
+      const later = await transport.send(createTestMessage());
+      assert.ok(later.successful);
+      assert.ok(server.getPeakConcurrentConnections() <= 1);
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  for (const pool of [false, true]) {
+    for (const asyncInput of [false, true]) {
+      for (const stopEarly of [false, true]) {
+        test(`sendMany cleanup: pool=${pool}, async=${asyncInput}, break=${stopEarly}`, async () => {
+          const { server, transport } = await setupTest({
+            pool,
+            poolSize: 1,
+          });
+          const messages = [createTestMessage(), createTestMessage()];
+          // Exercise both iteration branches without an external SMTP service.
+          const source = async function* () {
+            yield* messages;
+          };
+
+          try {
+            let receipts = 0;
+            for await (const receipt of transport.sendMany(asyncInput ? source() : messages)) {
+              assert.ok(receipt.successful);
+              receipts++;
+              if (stopEarly) break;
+            }
+            assert.strictEqual(receipts, stopEarly ? 1 : 2);
+            assert.strictEqual(server.getReceivedMessages().length, receipts);
+            assert.strictEqual(
+              server.getReceivedCommands().filter((command) => command === 'RSET').length,
+              pool ? 1 : 0,
+            );
+
+            await transport.closeAllConnections();
+            // QUIT is flushed without waiting for the server's reply.
+            for (
+              let attempt = 0;
+              attempt < 50 && !server.getReceivedCommands().includes('QUIT');
+              attempt++
+            ) {
+              await new Promise((resolve) => setTimeout(resolve, 10));
+            }
+            assert.strictEqual(
+              server.getReceivedCommands().filter((command) => command === 'QUIT').length,
+              1,
+              'The batch connection must be closed after iteration and cleanup.',
+            );
+          } finally {
+            await teardownTest(server, transport);
+          }
+        });
+      }
+    }
+  }
+
+  test('closing the pool while a send runs stays within poolSize', async () => {
+    const { server, transport } = await setupTest({ poolSize: 1 });
+
+    try {
+      // Populate the pool so that closeAllConnections() has a connection to
+      // shut down.
+      assert.ok((await transport.send(createTestMessage())).successful);
+
+      // A shutdown that hands its slot back before the socket is gone would let
+      // this send open a second connection alongside the closing one.
+      const closing = transport.closeAllConnections();
+      const sending = transport.send(createTestMessage());
+      await closing;
+      assert.ok((await sending).successful);
+
+      assert.ok(
+        server.getPeakConcurrentConnections() <= 1,
+        `Expected at most 1 simultaneous connection, saw ${server.getPeakConcurrentConnections()}`,
+      );
+    } finally {
+      await teardownTest(server, transport);
+    }
+  });
+
+  for (const command of ['DATA', 'RSET']) {
+    for (const pool of command === 'RSET' ? [true] : [true, false]) {
+      test(`shutdown drains sends during ${command}, pool=${pool}`, async () => {
+        const { server, transport } = await setupTest({ pool, poolSize: 1 });
+        server.setResponseDelay(command === 'DATA' ? 'DATA_END' : command, 100);
+        const sending = transport.send(createTestMessage());
+        try {
+          while (!server.getReceivedCommands().includes(command)) {
+            await new Promise((resolve) => setTimeout(resolve, 1));
+          }
+          const queued = transport.send(createTestMessage());
+          let closed = false;
+          // oxlint-disable-next-line promise/always-return -- upstream
+          const closing = transport.closeAllConnections().then(() => {
+            closed = true;
+          });
+          const disposing = transport[Symbol.asyncDispose]();
+          await new Promise((resolve) => setTimeout(resolve, 10));
+          assert.ok(!closed, 'Shutdown must wait for admitted sends.');
+          assert.ok((await sending).successful);
+          assert.ok((await queued).successful);
+          await Promise.all([closing, disposing]);
+          // QUIT is flushed without waiting for the server to process it.
+          for (let i = 0; i < 50 && server.getActiveConnectionCount() > 0; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+          }
+          assert.strictEqual(server.getActiveConnectionCount(), 0);
+          assert.ok((await transport.send(createTestMessage())).successful);
+        } finally {
+          await sending;
+          await teardownTest(server, transport);
+        }
+      });
+    }
+  }
+
+  for (const failSetup of [false, true]) {
+    test(`shutdown includes connection setup, failure=${failSetup}`, async () => {
+      const { server, transport } = await setupTest({ poolSize: 1 });
+      if (failSetup) {
+        server.setResponse('EHLO', { code: 550, message: 'Not today' });
+      }
+      try {
+        const sending = transport.send(createTestMessage());
+        await transport.closeAllConnections();
+        assert.strictEqual((await sending).successful, !failSetup);
+        for (let i = 0; i < 50 && server.getActiveConnectionCount() > 0; i++) {
+          await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+        assert.strictEqual(server.getActiveConnectionCount(), 0);
+      } finally {
+        await teardownTest(server, transport);
+      }
+    });
+  }
+
+  test('new sends wait for shutdown and can cancel that wait', async () => {
+    const { server, transport } = await setupTest({ poolSize: 1 });
+    const batch = transport.sendMany([createTestMessage()])[Symbol.asyncIterator]();
+    try {
+      assert.ok((await batch.next()).value?.successful);
+      const closing = transport.closeAllConnections();
+      const controller = new AbortController();
+      const cancelled = transport.send(createTestMessage(), {
+        signal: controller.signal,
+      });
+      const rejection = assert.rejects(cancelled, { name: 'AbortError' });
+      let sent = false;
+      const later = transport.send(createTestMessage()).then((receipt) => {
+        sent = true;
+        return receipt;
+      });
+      controller.abort();
+      await rejection;
+      assert.ok(!sent);
+      await batch.return?.();
+      await closing;
+      assert.ok((await later).successful);
+      assert.strictEqual(server.getReceivedMessages().length, 2);
+    } finally {
+      await batch.return?.();
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('shutdown waits for a paused batch to be returned', async () => {
+    const { server, transport } = await setupTest({ poolSize: 1 });
+    const batch = transport.sendMany([createTestMessage(), createTestMessage()])[
+      // oxlint-disable-next-line no-unexpected-multiline -- upstream
+      Symbol.asyncIterator
+    ]();
+    try {
+      assert.ok((await batch.next()).value?.successful);
+      let closed = false;
+      // oxlint-disable-next-line promise/always-return -- upstream
+      const closing = transport.closeAllConnections().then(() => {
+        closed = true;
+      });
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      assert.ok(!closed);
+      await batch.return?.();
+      await closing;
+      assert.strictEqual(server.getReceivedMessages().length, 1);
+    } finally {
+      await batch.return?.();
+      await teardownTest(server, transport);
+    }
+  });
+
+  test('rejects a poolSize that no connection could satisfy', () => {
+    for (const poolSize of [0, -1, 2.5, Number.NaN]) {
+      assert.throws(
+        () =>
+          new SmtpTransport({
+            host: 'localhost',
+            port: 1025,
+            secure: false,
+            poolSize,
+          }),
+        RangeError,
+        `Expected poolSize ${poolSize} to be rejected`,
+      );
+    }
+  });
+
+  test('accepts an unbounded poolSize', () => {
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port: 1025,
+      secure: false,
+      poolSize: Number.POSITIVE_INFINITY,
+    });
+    assert.strictEqual(transport.poolSize, Number.POSITIVE_INFINITY);
+  });
+});
diff --git a/tests/unit/smtp-transport.test.js b/tests/unit/smtp-transport.test.js
new file mode 100644
index 0000000..bb3ec1b
--- /dev/null
+++ b/tests/unit/smtp-transport.test.js
@@ -0,0 +1,553 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/smtp-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { SmtpTransport } = require('../../src/smtp/index.js');
+const assert = require('node:assert/strict');
+const { createServer } = require('node:net');
+const { before, describe, test } = require('node:test');
+
+// A port nothing listens on, bound and released: a send fails fast with
+// ECONNREFUSED instead of reaching what runs on a fixed port (upstream used
+// 1025, Mailpit's, and 9999).
+const closedPort = () =>
+  new Promise((resolve, reject) => {
+    const server = createServer();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+
+describe('SmtpTransport', () => {
+  before(async () => {
+    mockConfig.port = await closedPort();
+  });
+
+  const mockConfig = {
+    host: '127.0.0.1',
+    port: 0,
+    secure: false,
+    auth: {
+      user: 'test',
+      pass: 'test',
+    },
+  };
+
+  test('should create SmtpTransport instance', () => {
+    const transport = new SmtpTransport(mockConfig);
+    assert.strictEqual(transport instanceof SmtpTransport, true);
+  });
+
+  test('should handle message conversion', async () => {
+    const transport = new SmtpTransport(mockConfig);
+
+    const message = {
+      sender: { name: 'Test Sender', address: 'sender@example.com' },
+      recipients: [
+        {
+          name: 'Test Recipient',
+          address: 'recipient@example.com',
+        },
+      ],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test message content' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    // send() returns a receipt (success or failure) without throwing, even when
+    // no SMTP server is listening, so assert the receipt shape either way.
+    const receipt = await transport.send(message);
+    if (receipt.successful) {
+      assert.ok(receipt.messageId.length > 0);
+    } else {
+      assert.ok(receipt.errorMessages.length > 0);
+    }
+  });
+
+  test('should handle sendMany method', async () => {
+    const transport = new SmtpTransport(mockConfig);
+
+    const messages = [
+      {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient1@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject 1',
+        content: { text: 'Test message 1' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      },
+      {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient2@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject 2',
+        content: { text: 'Test message 2' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      },
+    ];
+
+    const receipts = [];
+    try {
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+      assert.strictEqual(receipts.length, 2);
+    } catch (error) {
+      // Expected to fail without a real SMTP server
+      assert.strictEqual(error instanceof Error, true);
+    }
+  });
+
+  test('should cleanup connections properly', async () => {
+    const transport = new SmtpTransport(mockConfig);
+
+    try {
+      await transport.closeAllConnections();
+      assert.strictEqual(true, true); // Should complete without error
+    } catch (error) {
+      assert.strictEqual(error instanceof Error, true);
+    }
+  });
+
+  test('should respect AbortSignal in send method', async () => {
+    const transport = new SmtpTransport(mockConfig);
+    const controller = new AbortController();
+
+    // Abort immediately
+    controller.abort();
+
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test message' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    try {
+      await transport.send(message, { signal: controller.signal });
+      assert.fail('Expected AbortError to be thrown');
+    } catch (error) {
+      // Should throw DOMException with name 'AbortError'
+      assert.ok(error instanceof DOMException);
+      assert.strictEqual(error.name, 'AbortError');
+    }
+  });
+
+  test('should respect AbortSignal in sendMany method', async () => {
+    const transport = new SmtpTransport(mockConfig);
+    const controller = new AbortController();
+
+    const messages = [
+      {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test message' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      },
+    ];
+
+    // Abort immediately
+    controller.abort();
+
+    try {
+      // oxlint-disable-next-line no-unused-vars -- upstream
+      for await (const _ of transport.sendMany(messages, { signal: controller.signal })) {
+        // Should not reach here
+      }
+      assert.fail('Expected AbortError to be thrown');
+    } catch (error) {
+      // Should throw DOMException with name 'AbortError'
+      assert.ok(error instanceof DOMException);
+      assert.strictEqual(error.name, 'AbortError');
+    }
+  });
+
+  test('should implement AsyncDisposable interface', async () => {
+    const transport = new SmtpTransport(mockConfig);
+
+    // Test that Symbol.asyncDispose method exists
+    assert.strictEqual(typeof transport[Symbol.asyncDispose], 'function');
+
+    // Test that we can call the dispose method directly
+    await transport[Symbol.asyncDispose]();
+
+    // Should complete without error
+    assert.strictEqual(true, true);
+  });
+
+  test('should work with using statement pattern', async () => {
+    // This test verifies the pattern works even if the environment
+    // doesn't fully support using statements yet
+
+    const testUsingPattern = async () => {
+      const transport = new SmtpTransport(mockConfig);
+
+      try {
+        // Simulate some work
+        assert.strictEqual(transport instanceof SmtpTransport, true);
+      } finally {
+        // Simulate what the using statement would do
+        await transport[Symbol.asyncDispose]();
+      }
+    };
+
+    await testUsingPattern();
+    assert.strictEqual(true, true); // Should complete without error
+  });
+
+  describe('Error Boundary Testing', () => {
+    test('should handle connection timeout gracefully', async () => {
+      const timeoutConfig = {
+        ...mockConfig,
+        host: '192.0.2.1', // TEST-NET-1 address (RFC 5737) - should timeout
+        port: 25,
+        connectionTimeout: 100, // Very short timeout
+      };
+
+      const transport = new SmtpTransport(timeoutConfig);
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Timeout Test',
+        content: { text: 'This should timeout' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      // Connection setup failures are reported as a failed receipt.
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.ok(
+          receipt.errorMessages.some(
+            (m) =>
+              m.includes('timeout') ||
+              m.includes('connect') ||
+              m.includes('ECONNREFUSED') ||
+              m.includes('EHOSTUNREACH'),
+          ),
+        );
+      }
+    });
+
+    test('should handle invalid host gracefully', async () => {
+      const invalidHostConfig = {
+        ...mockConfig,
+        host: 'invalid-host-that-does-not-exist.example',
+        port: 25,
+      };
+
+      const transport = new SmtpTransport(invalidHostConfig);
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Invalid Host Test',
+        content: { text: 'This should fail with DNS error' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      // Connection setup failures are reported as a failed receipt.
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.ok(
+          receipt.errorMessages.some(
+            (m) =>
+              m.includes('ENOTFOUND') ||
+              m.includes('getaddrinfo') ||
+              m.includes('connect') ||
+              m.includes('host'),
+          ),
+        );
+      }
+    });
+
+    test('should handle connection refused error', async () => {
+      const refusedConfig = {
+        ...mockConfig,
+        host: '127.0.0.1',
+        port: mockConfig.port,
+      };
+
+      const transport = new SmtpTransport(refusedConfig);
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Connection Refused Test',
+        content: { text: 'This should fail with connection refused' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      // Connection setup failures are reported as a failed receipt.
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.ok(
+          receipt.errorMessages.some(
+            (m) => m.includes('ECONNREFUSED') || m.includes('connect') || m.includes('refused'),
+          ),
+        );
+        assert.equal(receipt.provider, 'smtp');
+        assert.equal(receipt.attempts, 1);
+        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.errors?.[0]?.category, 'network');
+      }
+    });
+
+    test('should handle multiple rapid abort signals', async () => {
+      const transport = new SmtpTransport(mockConfig);
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Multiple Abort Test',
+        content: { text: 'Test message' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      // Test multiple rapid aborts don't cause issues
+      const promises = [];
+      for (let i = 0; i < 5; i++) {
+        const controller = new AbortController();
+        controller.abort();
+
+        const promise = transport
+          .send(message, { signal: controller.signal })
+          // oxlint-disable-next-line promise/always-return -- upstream
+          .then(() => {
+            assert.fail('Expected AbortError');
+          })
+          .catch((error) => {
+            assert.ok(error instanceof DOMException);
+            assert.strictEqual(error.name, 'AbortError');
+          });
+
+        promises.push(promise);
+      }
+
+      await Promise.all(promises);
+    });
+
+    test('should handle malformed message data gracefully', async () => {
+      const transport = new SmtpTransport(mockConfig);
+
+      // Test with extremely long subject
+      const longSubjectMessage = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'A'.repeat(2000), // Very long subject line
+        content: { text: 'Test message' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      try {
+        await transport.send(longSubjectMessage);
+        // This might succeed depending on server limits, which is fine
+      } catch (error) {
+        assert.ok(error instanceof Error);
+        // If it fails, should be a proper error
+      }
+
+      // Test with empty recipients (should fail at validation level)
+      const noRecipientsMessage = {
+        sender: { address: 'sender@example.com' },
+        recipients: [],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'No Recipients Test',
+        content: { text: 'Test message' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      // Sending with no recipients (or no reachable server) yields a failed
+      // receipt rather than throwing.
+      const receipt = await transport.send(noRecipientsMessage);
+      assert.ok(!receipt.successful);
+    });
+
+    test('should handle connection errors during sendMany', async () => {
+      const badConfig = {
+        ...mockConfig,
+        host: '192.0.2.1', // Non-routable address
+        port: 25,
+        connectionTimeout: 50,
+      };
+
+      const transport = new SmtpTransport(badConfig);
+      const messages = Array.from({ length: 3 }, (_, i) => ({
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: `recipient${i}@example.com` }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: `Test Message ${i}`,
+        content: { text: `Test content ${i}` },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      }));
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      // Connection setup failure yields a failed receipt for every message.
+      assert.strictEqual(receipts.length, 3);
+      receipts.forEach((receipt) => {
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.ok(receipt.errorMessages.length > 0);
+        }
+      });
+    });
+
+    test('should handle resource cleanup after errors', async () => {
+      const transport = new SmtpTransport({
+        ...mockConfig,
+        host: '192.0.2.1', // Non-routable address
+        connectionTimeout: 50,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Resource Cleanup Test',
+        content: { text: 'Test message' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      // Try to send and expect failure
+      try {
+        await transport.send(message);
+      } catch (error) {
+        // Expected to fail
+        assert.ok(error instanceof Error);
+      }
+
+      // Should be able to clean up resources without issues
+      try {
+        await transport.closeAllConnections();
+        await transport[Symbol.asyncDispose]();
+      } catch (error) {
+        // Cleanup should not throw additional errors
+        console.warn(
+          'Cleanup error (might be expected):',
+          error instanceof Error ? error.message : String(error),
+        );
+      }
+
+      // Test should complete without hanging
+      assert.ok(true);
+    });
+
+    test('should handle concurrent connection attempts with errors', async () => {
+      const transport = new SmtpTransport({
+        ...mockConfig,
+        host: '192.0.2.1', // Non-routable address
+        connectionTimeout: 100,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Concurrent Error Test',
+        content: { text: 'Test message' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      // Try multiple concurrent sends that should all fail
+      const promises = Array.from({ length: 5 }, () => transport.send(message));
+
+      const results = await Promise.all(promises);
+
+      // All should have resulted in failed receipts
+      assert.strictEqual(results.length, 5);
+      results.forEach((result) => {
+        assert.ok(!result.successful);
+        if (!result.successful) {
+          assert.ok(result.errorMessages.length > 0);
+        }
+      });
+    });
+  });
+});
diff --git a/tests/unit/smtp-verify-tls.integration.test.js b/tests/unit/smtp-verify-tls.integration.test.js
new file mode 100644
index 0000000..30502c1
--- /dev/null
+++ b/tests/unit/smtp-verify-tls.integration.test.js
@@ -0,0 +1,158 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/verify-tls.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { readFileSync } = require('node:fs');
+const path = require('node:path');
+const { createServer } = require('node:net');
+const { createSecureContext, createServer: createTlsServer, TLSSocket } = require('node:tls');
+const { SmtpTransport } = require('../../src/smtp/index.js');
+
+const credentials = {
+  key: readFileSync(path.join(__dirname, '../fixtures/smtp/server-key.pem')),
+  cert: readFileSync(path.join(__dirname, '../fixtures/smtp/server-cert.pem')),
+};
+
+const setup = async (implicit, stall = '') => {
+  const sockets = new Set();
+  const commands = [];
+  let resolveReached;
+  const reachedPromise = new Promise((resolve) => {
+    resolveReached = resolve;
+  });
+  const reached = { promise: reachedPromise, resolve: resolveReached };
+  const handle = (socket, upgraded = false) => {
+    sockets.add(socket);
+    socket.on('error', () => {});
+    socket.on('close', () => sockets.delete(socket));
+    if (stall === 'implicit') {
+      socket.once('data', () => reached.resolve());
+      return;
+    }
+    if (!upgraded) {
+      if (stall === 'greeting') {
+        reached.resolve();
+        return;
+      }
+      socket.write('220 ready\r\n');
+    }
+    let buffer = '';
+    const onData = (bytes) => {
+      buffer += Buffer.from(bytes).toString();
+      let end;
+      while ((end = buffer.indexOf('\r\n')) >= 0) {
+        const command = buffer.slice(0, end);
+        buffer = buffer.slice(end + 2);
+        commands.push(command);
+        if (command.startsWith('EHLO')) {
+          socket.write(
+            implicit || upgraded
+              ? '250-ready\r\n250 AUTH PLAIN\r\n'
+              : '250-ready\r\n250 STARTTLS\r\n',
+          );
+        } else if (command === 'STARTTLS') {
+          socket.off('data', onData);
+          socket.write('220 upgrade\r\n');
+          if (stall === 'STARTTLS') {
+            socket.once('data', () => reached.resolve());
+            return;
+          }
+          handle(
+            new TLSSocket(socket, {
+              isServer: true,
+              secureContext: createSecureContext(credentials),
+            }),
+            true,
+          );
+          return;
+        } else if (command.startsWith('AUTH')) {
+          if (stall === 'AUTH') {
+            reached.resolve();
+            return;
+          }
+          socket.write('235 authenticated\r\n');
+        } else if (command === 'QUIT') socket.end('221 bye\r\n');
+        else socket.write('500 unexpected command\r\n');
+      }
+    };
+    socket.on('data', onData);
+  };
+  const server =
+    implicit && stall !== 'implicit' ? createTlsServer(credentials, handle) : createServer(handle);
+  server.on('tlsClientError', () => {});
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address();
+  assert.ok(address && typeof address !== 'string');
+  const transport = new SmtpTransport({
+    host: '127.0.0.1',
+    port: address.port,
+    secure: implicit,
+    requireTls: !implicit,
+    tls: { rejectUnauthorized: false },
+    auth: { user: 'u', pass: 'p' },
+    connectionTimeout: 150,
+    socketTimeout: 150,
+  });
+  return {
+    transport,
+    commands,
+    reached,
+    sockets,
+    async close() {
+      await transport.closeAllConnections();
+      for (const socket of sockets) socket.destroy();
+      await new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+};
+
+for (const implicit of [false, true]) {
+  test(`verify negotiates real ${implicit ? 'implicit TLS' : 'STARTTLS'} and rejects untrusted certificates`, async () => {
+    const f = await setup(implicit);
+    try {
+      await f.transport.verify();
+      assert.equal(f.commands.filter((c) => c.startsWith('EHLO')).length, implicit ? 1 : 2);
+      assert.ok(f.commands.some((c) => c.startsWith('AUTH PLAIN')));
+      assert.ok(f.commands.every((c) => /^(EHLO|STARTTLS|AUTH|QUIT)\b/.test(c)));
+      f.transport.config = {
+        ...f.transport.config,
+        tls: { rejectUnauthorized: true },
+      };
+      await assert.rejects(f.transport.verify());
+    } finally {
+      await f.close();
+    }
+  });
+}
+
+for (const stage of ['greeting', 'implicit', 'STARTTLS', 'AUTH']) {
+  for (const cancel of [false, true]) {
+    test(`verify ${stage} ${cancel ? 'cancellation' : 'timeout'} releases its connection`, async () => {
+      const f = await setup(stage === 'implicit', stage);
+      const controller = new AbortController();
+      const reason = new TypeError('Canceled.');
+      try {
+        if (cancel) {
+          f.transport.config = {
+            ...f.transport.config,
+            connectionTimeout: 5000,
+            socketTimeout: 5000,
+          };
+        }
+        const pending = f.transport.verify({ signal: controller.signal });
+        const checked = assert.rejects(pending, (e) =>
+          cancel ? e === reason : e instanceof Error,
+        );
+        await f.reached.promise;
+        if (cancel) controller.abort(reason);
+        await checked;
+        await f.transport.closeAllConnections();
+        assert.ok(f.commands.every((c) => !/^(MAIL|RCPT|DATA|BDAT)\b/.test(c)));
+      } finally {
+        controller.abort(reason);
+        await f.close();
+      }
+    });
+  }
+}
diff --git a/tests/unit/smtp-verify.integration.test.js b/tests/unit/smtp-verify.integration.test.js
new file mode 100644
index 0000000..7cdaafc
--- /dev/null
+++ b/tests/unit/smtp-verify.integration.test.js
@@ -0,0 +1,333 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/verify.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const { isVerifiableTransport } = require('../../src/core/transport.js');
+const {
+  SmtpAuthResponseError,
+  SmtpResponseError,
+  SmtpTransport,
+} = require('../../src/smtp/index.js');
+const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+
+const deferred = () => {
+  let resolve;
+  let reject;
+  // oxlint-disable-next-line promise/param-names -- upstream
+  const promise = new Promise((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+};
+
+const message = () =>
+  createMessage({
+    from: 'a@example.com',
+    to: 'b@example.com',
+    subject: 'Test',
+    content: { text: 'Test' },
+  });
+
+for (const auth of [
+  undefined,
+  { user: 'u', pass: 'p' },
+  {
+    user: 'u',
+    accessToken: 'token',
+  },
+]) {
+  test(`verify performs fresh setup without delivery, auth=${auth == null ? 'none' : 'pass' in auth ? 'password' : 'oauth'}`, async () => {
+    const server = new MockSmtpServer();
+    const port = await server.start();
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port,
+      auth,
+      poolSize: 1,
+    });
+    try {
+      assert.ok(isVerifiableTransport(transport));
+      assert.equal(await transport.verify(), undefined);
+      await transport.verify();
+      assert.equal(server.getConnectionCount(), 2);
+      assert.equal(server.getReceivedMessages().length, 0);
+      assert.ok(server.getReceivedCommands().every((c) => /^(EHLO|HELO|AUTH|QUIT)\b/.test(c)));
+      if (auth) {
+        server.setResponse('AUTH', {
+          code: 535,
+          message: 'Invalid credentials',
+        });
+        await assert.rejects(transport.verify(), SmtpAuthResponseError);
+      }
+    } finally {
+      await transport.closeAllConnections();
+      await server.stop();
+    }
+  });
+}
+
+test('verification rejects greeting/EHLO/TLS errors and releases capacity', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  const transport = new SmtpTransport({ host: 'localhost', port, poolSize: 1 });
+  try {
+    server.setResponse('GREETING', { code: 554, message: 'Unavailable' });
+    await assert.rejects(
+      transport.verify(),
+      (e) => e instanceof SmtpResponseError && e.command === 'GREETING',
+    );
+    server.setResponse('GREETING', { code: 220, message: 'Ready' });
+    server.setResponse('EHLO', { code: 500, message: 'Unsupported' });
+    await transport.verify();
+    assert.ok(server.getReceivedCommands().some((c) => c.startsWith('HELO ')));
+    server.setResponse('HELO', { code: 550, message: 'Rejected' });
+    await assert.rejects(transport.verify(), SmtpResponseError);
+    server.setResponse('EHLO', { code: 250, message: 'Ready' });
+    transport.config = { ...transport.config, requireTls: true };
+    server.setResponse('STARTTLS', { code: 454, message: 'Unavailable' });
+    await assert.rejects(
+      transport.verify(),
+      (e) => e instanceof SmtpResponseError && e.command === 'STARTTLS',
+    );
+    transport.config = { ...transport.config, requireTls: false };
+    await transport.verify();
+  } finally {
+    await transport.closeAllConnections();
+    await server.stop();
+  }
+});
+
+test('fresh verification keeps its slot while a token callback is pending', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  const entered = deferred();
+  const token = deferred();
+  let calls = 0;
+  const transport = new SmtpTransport({
+    host: 'localhost',
+    port,
+    poolSize: 1,
+    auth: {
+      user: 'u',
+      accessToken: () => {
+        if (++calls === 2) {
+          entered.resolve();
+          return token.promise;
+        }
+        return 'token';
+      },
+    },
+  });
+  try {
+    assert.ok((await transport.send(message())).successful);
+    const verification = transport.verify();
+    await entered.promise;
+    const controller = new AbortController();
+    const queued = transport.verify({ signal: controller.signal });
+    controller.abort('queued cancellation');
+    await assert.rejects(queued, (e) => e === 'queued cancellation');
+    const send = transport.send(message());
+    assert.equal(server.getConnectionCount(), 2);
+    assert.equal(calls, 2);
+    token.resolve('token');
+    await verification;
+    assert.ok((await send).successful);
+    assert.equal(calls, 3);
+  } finally {
+    token.resolve('token');
+    await transport.closeAllConnections();
+    await server.stop();
+  }
+});
+
+test('verification cancellation releases a slot held by an uncooperative token provider', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  const entered = deferred();
+  const token = deferred();
+  let calls = 0;
+  const transport = new SmtpTransport({
+    host: 'localhost',
+    port,
+    poolSize: 1,
+    auth: {
+      user: 'u',
+      accessToken: () => {
+        if (++calls === 1) {
+          entered.resolve();
+          return token.promise;
+        }
+        return 'token';
+      },
+    },
+  });
+  try {
+    const controller = new AbortController();
+    const pending = transport.verify({ signal: controller.signal });
+    await entered.promise;
+    controller.abort('stop');
+    await assert.rejects(pending, (e) => e === 'stop');
+    token.reject(new TypeError('Late failure.'));
+    await transport.verify();
+    const aborted = new AbortController();
+    aborted.abort(null);
+    await assert.rejects(transport.verify({ signal: aborted.signal }), (e) => e === null);
+    assert.equal(server.getConnectionCount(), 2);
+  } finally {
+    token.resolve('token');
+    await transport.closeAllConnections();
+    await server.stop();
+  }
+});
+
+for (const warm of [false, true]) {
+  test(`cancel during ${warm ? 'eviction' : 'final'} QUIT releases exactly one slot`, async () => {
+    const { SmtpConnection } = require('../../src/smtp/smtp-connection.js');
+    // oxlint-disable-next-line no-shadow -- upstream
+    const { SmtpTransport } = require('../../src/smtp/smtp-transport.js');
+    const server = new MockSmtpServer();
+    const port = await server.start();
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port,
+      poolSize: 1,
+    });
+    const entered = deferred();
+    const controller = new AbortController();
+    const originalQuit = SmtpConnection.prototype.quit;
+    try {
+      if (warm) assert.ok((await transport.send(message())).successful);
+      SmtpConnection.prototype.quit = async function (signal) {
+        const socket = this.socket;
+        assert.ok(socket);
+        const write = socket.write;
+        socket.write = () => {
+          entered.resolve();
+          return true;
+        };
+        try {
+          await originalQuit.call(this, signal);
+        } finally {
+          socket.write = write;
+        }
+      };
+      const pending = transport.verify({ signal: controller.signal });
+      const checked = assert.rejects(pending, (e) => e === 'stop cleanup');
+      await entered.promise;
+      controller.abort('stop cleanup');
+      await checked;
+      SmtpConnection.prototype.quit = originalQuit;
+      await transport.verify();
+      assert.ok((await transport.send(message())).successful);
+    } finally {
+      controller.abort('stop cleanup');
+      SmtpConnection.prototype.quit = originalQuit;
+      await transport.closeAllConnections();
+      await server.stop();
+    }
+  });
+}
+
+test('shutdown drains admitted verification and newly arriving verification can cancel', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  const entered = deferred();
+  const token = deferred();
+  const transport = new SmtpTransport({
+    host: 'localhost',
+    port,
+    poolSize: 1,
+    auth: {
+      user: 'u',
+      accessToken: () => {
+        entered.resolve();
+        return token.promise;
+      },
+    },
+  });
+  try {
+    const pending = transport.verify();
+    await entered.promise;
+    const closing = transport.closeAllConnections();
+    const controller = new AbortController();
+    const waiting = transport.verify({ signal: controller.signal });
+    controller.abort('shutdown wait');
+    await assert.rejects(waiting, (e) => e === 'shutdown wait');
+    token.resolve('token');
+    await pending;
+    await closing;
+    await transport.verify();
+  } finally {
+    token.resolve('token');
+    await transport.closeAllConnections();
+    await server.stop();
+  }
+});
+
+test('failed connection establishment does not leak the verification slot', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  await server.stop();
+  const transport = new SmtpTransport({
+    host: 'localhost',
+    port,
+    poolSize: 1,
+    connectionTimeout: 500,
+  });
+  try {
+    await assert.rejects(transport.verify());
+    await assert.rejects(transport.verify());
+  } finally {
+    await transport.closeAllConnections();
+  }
+});
+
+test('cancelled verification does not cancel a shared OAuth2 refresh needed by a send', async () => {
+  const originalFetch = globalThis.fetch;
+  const entered = deferred();
+  const refreshed = deferred();
+  let refreshes = 0;
+  globalThis.fetch = () => {
+    refreshes++;
+    entered.resolve();
+    return refreshed.promise;
+  };
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  const transport = new SmtpTransport({
+    host: 'localhost',
+    port,
+    poolSize: 2,
+    auth: {
+      user: 'u',
+      clientId: 'client',
+      refreshToken: 'refresh',
+      tokenEndpoint: 'https://oauth.example.com/token',
+    },
+  });
+  const controller = new AbortController();
+  try {
+    const verification = transport.verify({ signal: controller.signal });
+    const checked = assert.rejects(verification, (e) => e === 'cancel verifier');
+    await entered.promise;
+    const send = transport.send(message());
+    controller.abort('cancel verifier');
+    await checked;
+    refreshed.resolve(
+      new Response(JSON.stringify({ access_token: 'token', expires_in: 3600 }), { status: 200 }),
+    );
+    assert.ok((await send).successful);
+    assert.equal(refreshes, 1);
+  } finally {
+    controller.abort('cancel verifier');
+    refreshed.resolve(
+      new Response(JSON.stringify({ access_token: 'token', expires_in: 3600 }), { status: 200 }),
+    );
+    globalThis.fetch = originalFetch;
+    await transport.closeAllConnections();
+    await server.stop();
+  }
+});
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
new file mode 100644
index 0000000..34aea8a
--- /dev/null
+++ b/tests/unit/smtp.test.js
@@ -0,0 +1,188 @@
+// Paths of the ported SMTP transport (src/smtp/) that upstream's suites leave
+// out or reach only through Mailpit: broken connections, rejected AUTH LOGIN
+// steps, a rejected DATA, and the guards of the DATA writer.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { EventEmitter } = require('node:events');
+const { createServer } = require('node:net');
+const { createMessage } = require('../../index.js');
+const { SmtpTransport } = require('../../src/smtp/index.js');
+const { prepareOnSocket, writeMessageData } = require('../../src/smtp/data-stream.js');
+const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+
+const message = () =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+
+// A raw TCP server driven line by line, for replies MockSmtpServer cannot give.
+const scripted = async (onLine, onConnection = (socket) => socket.write('220 ready\r\n')) => {
+  const server = createServer((socket) => {
+    socket.on('error', () => {});
+    onConnection(socket);
+    let buffer = '';
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString('latin1');
+      let end;
+      while ((end = buffer.indexOf('\r\n')) >= 0) {
+        const line = buffer.slice(0, end);
+        buffer = buffer.slice(end + 2);
+        onLine(line, socket);
+      }
+    });
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  return { server, port: server.address().port };
+};
+const stop = (server) => new Promise((resolve) => server.close(() => resolve()));
+
+const failureOf = async (transport) => {
+  const receipt = await transport.send(message());
+  await transport.closeAllConnections();
+  assert.strictEqual(receipt.successful, false);
+  return receipt.errorMessages.join(' | ');
+};
+
+test('SMTP: a server that closes before its greeting fails the send', async () => {
+  const { server, port } = await scripted(
+    () => {},
+    (socket) => socket.destroy(),
+  );
+  try {
+    const transport = new SmtpTransport({ host: '127.0.0.1', port, pool: false });
+    assert.match(await failureOf(transport), /closed before greeting|ECONNRESET|socket/i);
+  } finally {
+    await stop(server);
+  }
+});
+
+test('SMTP: a server that closes during STARTTLS fails the send', async () => {
+  const { server, port } = await scripted((line, socket) => {
+    if (line.startsWith('EHLO')) socket.write('250-localhost\r\n250 STARTTLS\r\n');
+    else if (line === 'STARTTLS') socket.end('220 go ahead\r\n');
+  });
+  try {
+    const transport = new SmtpTransport({ host: '127.0.0.1', port, pool: false });
+    assert.match(await failureOf(transport), /STARTTLS|TLS|socket|disconnected/i);
+  } finally {
+    await stop(server);
+  }
+});
+
+test('SMTP: AUTH LOGIN rejected at the method or at the user name', async () => {
+  for (const [step, expected] of [
+    [0, /AUTH LOGIN failed: Not here/],
+    [1, /Username authentication failed: No such user/],
+  ]) {
+    let sent = 0;
+    const { server, port } = await scripted((line, socket) => {
+      if (line.startsWith('EHLO')) socket.write('250-localhost\r\n250 AUTH LOGIN\r\n');
+      else if (line === 'AUTH LOGIN' || sent > 0) {
+        socket.write(
+          sent++ === step
+            ? `535 ${step === 0 ? 'Not here' : 'No such user'}\r\n`
+            : '334 VXNlcm5hbWU6\r\n',
+        );
+      } else if (line === 'QUIT') socket.end('221 bye\r\n');
+    });
+    try {
+      const transport = new SmtpTransport({
+        host: '127.0.0.1',
+        port,
+        pool: false,
+        auth: { user: 'alex', pass: 'secret', method: 'login' },
+      });
+      assert.match(await failureOf(transport), expected);
+    } finally {
+      await stop(server);
+    }
+  }
+});
+
+test('SMTP: an unsupported AUTH method fails the send', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  server.setCapabilities(['AUTH PLAIN LOGIN CRAM-MD5']);
+  try {
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port,
+      pool: false,
+      auth: { user: 'alex', pass: 'secret', method: 'cram-md5' },
+    });
+    assert.match(await failureOf(transport), /Unsupported authentication method: cram-md5/);
+  } finally {
+    await server.stop();
+  }
+});
+
+test('SMTP: a rejection after DATA fails the send', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  server.setResponse('DATA_END', { code: 554, message: 'Content rejected' });
+  try {
+    const transport = new SmtpTransport({ host: 'localhost', port, pool: false });
+    assert.match(await failureOf(transport), /Content rejected/);
+  } finally {
+    await server.stop();
+  }
+});
+
+const fakeSocket = (state = {}) =>
+  Object.assign(new EventEmitter(), { destroyed: false, writable: true, destroy() {} }, state);
+
+test('SMTP: message preparation fails on a socket that is already closed', async () => {
+  const socket = fakeSocket({ destroyed: true, writable: false });
+  await assert.rejects(
+    prepareOnSocket(socket, 1000, () => new Promise(() => {})),
+    { name: 'TypeError', message: 'SMTP connection closed during message preparation.' },
+  );
+});
+
+test('SMTP: the DATA writer refuses a reply over 64 KiB', async () => {
+  const socket = fakeSocket({
+    write(chunk, callback) {
+      if (chunk.toString() === '.\r\n') {
+        queueMicrotask(() => socket.emit('data', Buffer.alloc(70000, 0x61)));
+      }
+      callback?.();
+      return true;
+    },
+  });
+  const source = async function* () {
+    yield Buffer.from('Subject: x\r\n\r\nbody\r\n');
+  };
+  await assert.rejects(
+    writeMessageData(socket, source, 1000, () => {}),
+    {
+      name: 'RangeError',
+      message: 'SMTP DATA reply exceeds 64 KiB.',
+    },
+  );
+});
+
+test('SMTP: a reply during message preparation fails it', async () => {
+  const socket = fakeSocket();
+  const preparing = prepareOnSocket(socket, 1000, () => new Promise(() => {}));
+  socket.emit('data', Buffer.from('421 closing\r\n'));
+  await assert.rejects(preparing, {
+    name: 'TypeError',
+    message: 'Unexpected SMTP reply during message preparation.',
+  });
+});
+
+test('SMTP: a connection reset in the middle of the envelope fails the send', async () => {
+  const { server, port } = await scripted((line, socket) => {
+    if (line.startsWith('EHLO')) socket.write('250-localhost\r\n250 PIPELINING\r\n');
+    else if (line.startsWith('MAIL FROM')) socket.resetAndDestroy();
+  });
+  try {
+    const transport = new SmtpTransport({ host: '127.0.0.1', port, pool: false });
+    assert.match(await failureOf(transport), /ECONNRESET|closed|socket/i);
+  } finally {
+    await stop(server);
+  }
+});

From e7a1e7f6da4646dc587189e915ee1fb7fcd85849 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:04:58 +0300
Subject: [PATCH 006/158] feat(ses): port the Amazon SES transport from upyo
 0.7.0

./ses exports SesTransport: SES v2 SendEmail over fetch with a SigV4
signature on WebCrypto, static or session credentials, configuration sets
and default tags, retries with exponential backoff for 5xx and network
errors, a request timeout, and sendMany in concurrent batches. Its types
are SesConfig and SesAuthentication.

Upstream's unit suites are ported; the e2e suite (real credentials) goes to
tests/e2e. Its test of a runtime without AbortSignal.any is not ported:
Node 22 always has it, and the core keeps no fallback. tests/unit/ses.test.js
covers what upstream reached only end to end: session credentials, HTTP and
network failures, timeouts, an abort between retries and attachment
defaults. The dead convertMessagesToBulk of upstream is excluded from the
coverage, as listed in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                    |   2 +-
 package.json                                |   4 +
 src/ses/config.js                           |  43 ++
 src/ses/http-client.js                      | 328 +++++++++++++++
 src/ses/index.d.ts                          | 260 ++++++++++++
 src/ses/index.js                            |   6 +
 src/ses/message-converter.js                | 241 +++++++++++
 src/ses/ses-transport.js                    | 234 +++++++++++
 tests/e2e/ses-transport.e2e.test.js         | 278 +++++++++++++
 tests/helpers/ses/test-config.js            |  33 ++
 tests/types/ses.test-d.ts                   |  28 ++
 tests/unit/ses-attachment-content.test.js   |  48 +++
 tests/unit/ses-config.test.js               |  99 +++++
 tests/unit/ses-message-converter.test.js    | 312 ++++++++++++++
 tests/unit/ses-transport-concurrent.test.js | 196 +++++++++
 tests/unit/ses-transport.test.js            | 431 ++++++++++++++++++++
 tests/unit/ses.test.js                      | 144 +++++++
 17 files changed, 2686 insertions(+), 1 deletion(-)
 create mode 100644 src/ses/config.js
 create mode 100644 src/ses/http-client.js
 create mode 100644 src/ses/index.d.ts
 create mode 100644 src/ses/index.js
 create mode 100644 src/ses/message-converter.js
 create mode 100644 src/ses/ses-transport.js
 create mode 100644 tests/e2e/ses-transport.e2e.test.js
 create mode 100644 tests/helpers/ses/test-config.js
 create mode 100644 tests/types/ses.test-d.ts
 create mode 100644 tests/unit/ses-attachment-content.test.js
 create mode 100644 tests/unit/ses-config.test.js
 create mode 100644 tests/unit/ses-message-converter.test.js
 create mode 100644 tests/unit/ses-transport-concurrent.test.js
 create mode 100644 tests/unit/ses-transport.test.js
 create mode 100644 tests/unit/ses.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5227ee8..1175788 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 764804a..a6e7d61 100644
--- a/package.json
+++ b/package.json
@@ -32,6 +32,10 @@
       "types": "./src/smtp/index.d.ts",
       "default": "./src/smtp/index.js"
     },
+    "./ses": {
+      "types": "./src/ses/index.d.ts",
+      "default": "./src/ses/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
diff --git a/src/ses/config.js b/src/ses/config.js
new file mode 100644
index 0000000..482a664
--- /dev/null
+++ b/src/ses/config.js
@@ -0,0 +1,43 @@
+// Ported from upyo v0.7.0 (packages/ses/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved SES configuration with default values applied.
+ *
+ * This function takes a partial SES configuration and fills in default values
+ * for all optional fields, ensuring the transport has all necessary configuration.
+ *
+ * @example
+ * ```typescript
+ * const config = createSesConfig({
+ *   authentication: {
+ *     type: "credentials",
+ *     accessKeyId: "AKIA...",
+ *     secretAccessKey: "wJal..",
+ *   },
+ *   region: "eu-west-1",
+ * });
+ *
+ * // config.timeout is now 30000 (default)
+ * // config.retries is now 3 (default)
+ * // config.batchSize is now 50 (default)
+ * ```
+ *
+ * @param config The SES configuration object.
+ * @returns A resolved configuration with all defaults applied.
+ */
+const createSesConfig = (config) => {
+  return {
+    authentication: config.authentication,
+    region: config.region ?? 'us-east-1',
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    validateSsl: config.validateSsl ?? true,
+    headers: config.headers ?? {},
+    configurationSetName: config.configurationSetName,
+    defaultTags: config.defaultTags ?? {},
+    batchSize: config.batchSize ?? 50,
+  };
+};
+
+module.exports = { createSesConfig };
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
new file mode 100644
index 0000000..c3b0fb6
--- /dev/null
+++ b/src/ses/http-client.js
@@ -0,0 +1,328 @@
+// Ported from upyo v0.7.0 (packages/ses/src/http-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { parseRetryAfter } = require('../core/receipt.js');
+
+class SesHttpClient {
+  config;
+
+  constructor(config) {
+    this.config = config;
+  }
+
+  sendMessage(messageData, signal) {
+    const region = this.config.region;
+    const url = `https://email.${region}.amazonaws.com/v2/email/outbound-emails`;
+
+    return this.makeRequest(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(messageData),
+      signal,
+    });
+  }
+
+  /**
+   * Makes an HTTP request to the SES API with retry logic.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the parsed response.
+   * @throws {DOMException} If the caller aborts the request.
+   * @throws {SesApiError} If SES returns a client error or all retry attempts
+   *                       are exhausted.
+   */
+  async makeRequest(url, options) {
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      try {
+        const response = await this.fetchWithAuth(url, options);
+        const text = await response.text();
+
+        if (response.status === 200) {
+          return {
+            statusCode: response.status,
+            body: text,
+            headers: this.headersToRecord(response.headers),
+          };
+        }
+
+        let errorData;
+        try {
+          errorData = JSON.parse(text);
+        } catch {
+          errorData = { message: text || `HTTP ${response.status}` };
+        }
+
+        throw new SesApiError(
+          errorData.message || `HTTP ${response.status}`,
+          response.status,
+          errorData.errors,
+          parseRetryAfter(response.headers.get('Retry-After')),
+          attempt + 1,
+        );
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (options.signal?.aborted) {
+          throw createAbortError(options.signal);
+        }
+
+        if (isAbortError(error)) {
+          throw error;
+        }
+
+        if (
+          error instanceof SesApiError &&
+          error.statusCode &&
+          error.statusCode >= 400 &&
+          error.statusCode < 500
+        ) {
+          throw error;
+        }
+
+        if (attempt === this.config.retries) {
+          if (lastError instanceof SesApiError) {
+            throw lastError;
+          }
+          throw new SesApiError(lastError.message, undefined, undefined, undefined, attempt + 1);
+        }
+
+        const delay = Math.pow(2, attempt) * 1000;
+        await sleep(delay, options.signal);
+      }
+    }
+
+    throw lastError || new Error('Request failed after all retries');
+  }
+
+  /**
+   * Makes a signed fetch request to the SES API.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the fetch response.
+   * @throws {Error} If the configured request timeout is reached.
+   * @throws {DOMException} If the caller aborts the request.
+   */
+  async fetchWithAuth(url, options) {
+    const credentials = await this.getCredentials();
+    const headers = new Headers(options.headers);
+
+    const signedHeaders = await this.signRequest(
+      url,
+      {
+        ...options,
+        headers,
+      },
+      credentials,
+    );
+
+    for (const [key, value] of Object.entries(this.config.headers)) {
+      signedHeaders.set(key, value);
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    const combinedSignal = combineSignals(controller.signal, options.signal);
+
+    try {
+      return await globalThis.fetch(url, {
+        ...options,
+        headers: this.headersToRecord(signedHeaders),
+        signal: combinedSignal.signal,
+      });
+    } catch (error) {
+      if (isAbortError(error) && controller.signal.aborted && !options.signal?.aborted) {
+        // oxlint-disable-next-line preserve-caught-error -- upstream
+        throw new Error(`SES API request timed out after ${this.config.timeout} ms.`);
+      }
+      throw error;
+    } finally {
+      combinedSignal.cleanup();
+      clearTimeout(timeoutId);
+    }
+  }
+
+  async getCredentials() {
+    const auth = this.config.authentication;
+
+    switch (auth.type) {
+      case 'credentials':
+        return {
+          accessKeyId: auth.accessKeyId,
+          secretAccessKey: auth.secretAccessKey,
+        };
+
+      case 'session':
+        return {
+          accessKeyId: auth.accessKeyId,
+          secretAccessKey: auth.secretAccessKey,
+          sessionToken: auth.sessionToken,
+        };
+
+      default:
+        throw new Error(`Unsupported authentication type: ${auth.type}`);
+    }
+  }
+
+  async signRequest(url, options, credentials) {
+    const parsedUrl = new URL(url);
+    const method = options.method || 'GET';
+    const headers = new Headers(options.headers);
+
+    const host = parsedUrl.host;
+    const path = parsedUrl.pathname + parsedUrl.search;
+    const service = 'ses';
+    const region = this.config.region;
+
+    const now = new Date();
+    const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, '');
+    const dateStamp = amzDate.substring(0, 8);
+
+    headers.set('Host', host);
+    headers.set('X-Amz-Date', amzDate);
+
+    if (credentials.sessionToken) {
+      headers.set('X-Amz-Security-Token', credentials.sessionToken);
+    }
+
+    const signedHeaders =
+      'host;x-amz-date' + (credentials.sessionToken ? ';x-amz-security-token' : '');
+    const canonicalHeaders =
+      `host:${host}\nx-amz-date:${amzDate}\n` +
+      (credentials.sessionToken ? `x-amz-security-token:${credentials.sessionToken}\n` : '');
+
+    const payloadHash = await this.sha256(options.body || '');
+    const canonicalRequest = `${method}\n${path}\n\n${canonicalHeaders}\n${signedHeaders}\n${payloadHash}`;
+
+    const algorithm = 'AWS4-HMAC-SHA256';
+    const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
+    const stringToSign = `${algorithm}\n${amzDate}\n${credentialScope}\n${await this.sha256(
+      canonicalRequest,
+    )}`;
+
+    const signingKey = await this.getSignatureKey(
+      credentials.secretAccessKey,
+      dateStamp,
+      region,
+      service,
+    );
+    const signature = await this.hmacSha256(signingKey, stringToSign);
+
+    const authorizationHeader = `${algorithm} Credential=${credentials.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    headers.set('Authorization', authorizationHeader);
+
+    return headers;
+  }
+
+  async sha256(data) {
+    const encoder = new TextEncoder();
+    const dataBuffer = encoder.encode(data);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', dataBuffer);
+    return Array.from(new Uint8Array(hashBuffer))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  async hmacSha256(key, data) {
+    const encoder = new TextEncoder();
+    const dataBuffer = encoder.encode(data);
+    const cryptoKey = await crypto.subtle.importKey(
+      'raw',
+      key,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign'],
+    );
+    const signature = await crypto.subtle.sign('HMAC', cryptoKey, dataBuffer);
+    return Array.from(new Uint8Array(signature))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  async getSignatureKey(key, dateStamp, regionName, serviceName) {
+    const encoder = new TextEncoder();
+
+    let keyBuffer = new Uint8Array(encoder.encode('AWS4' + key)).buffer;
+    keyBuffer = await this.hmacSha256Buffer(keyBuffer, dateStamp);
+    keyBuffer = await this.hmacSha256Buffer(keyBuffer, regionName);
+    keyBuffer = await this.hmacSha256Buffer(keyBuffer, serviceName);
+    keyBuffer = await this.hmacSha256Buffer(keyBuffer, 'aws4_request');
+
+    return keyBuffer;
+  }
+
+  async hmacSha256Buffer(key, data) {
+    const encoder = new TextEncoder();
+    const dataBuffer = encoder.encode(data);
+    const cryptoKey = await crypto.subtle.importKey(
+      'raw',
+      key,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign'],
+    );
+    return await crypto.subtle.sign('HMAC', cryptoKey, dataBuffer);
+  }
+
+  headersToRecord(headers) {
+    const record = {};
+    for (const [key, value] of headers.entries()) {
+      record[key] = value;
+    }
+    return record;
+  }
+}
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const sleep = (milliseconds, signal) => {
+  if (signal?.aborted) {
+    return Promise.reject(createAbortError(signal));
+  }
+
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener('abort', abort);
+      reject(createAbortError(signal));
+    };
+
+    const timeoutId = setTimeout(() => {
+      signal?.removeEventListener('abort', abort);
+      resolve();
+    }, milliseconds);
+
+    signal?.addEventListener('abort', abort, { once: true });
+  });
+};
+
+const createAbortError = (signal) => {
+  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+};
+
+class SesApiError extends Error {
+  statusCode;
+  errors;
+  retryAfterMilliseconds;
+  attempts;
+
+  constructor(message, statusCode, errors, retryAfterMilliseconds, attempts) {
+    super(message);
+    this.name = 'SesApiError';
+    this.statusCode = statusCode;
+    this.errors = errors;
+    this.retryAfterMilliseconds = retryAfterMilliseconds;
+    this.attempts = attempts;
+  }
+}
+
+module.exports = { SesHttpClient, SesApiError };
diff --git a/src/ses/index.d.ts b/src/ses/index.d.ts
new file mode 100644
index 0000000..e71fc7a
--- /dev/null
+++ b/src/ses/index.d.ts
@@ -0,0 +1,260 @@
+// Types ported from upyo v0.7.0 (packages/ses/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Authentication configuration for AWS SES.
+ *
+ * This is a discriminated union type that supports two authentication methods:
+ *
+ * - `credentials`: Basic access key and secret key authentication
+ * - `session`: Temporary credentials with session token
+ *
+ * **Note**: IAM role assumption (`assumeRole`) is not currently supported.
+ * If you need to use IAM roles, perform the AssumeRole operation externally
+ * (e.g., using AWS CLI or SDK) and use the resulting temporary credentials
+ * with the `session` authentication type.
+ *
+ * @example
+ * ```typescript
+ * // Basic credentials
+ * const auth: SesAuthentication = {
+ *   type: "credentials",
+ *   accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ * };
+ *
+ * // Session credentials (from external AssumeRole)
+ * const sessionAuth: SesAuthentication = {
+ *   type: "session",
+ *   accessKeyId: "ASIAXYZ...",
+ *   secretAccessKey: "abc123...",
+ *   sessionToken: "FwoGZXIvYXdzE...",
+ * };
+ * ```
+ */
+export type SesAuthentication =
+  | {
+      /** Authentication type identifier. */
+      readonly type: 'credentials';
+      /** AWS access key ID. */
+      readonly accessKeyId: string;
+      /** AWS secret access key. */
+      readonly secretAccessKey: string;
+    }
+  | {
+      /** Authentication type identifier. */
+      readonly type: 'session';
+      /** AWS access key ID for temporary credentials. */
+      readonly accessKeyId: string;
+      /** AWS secret access key for temporary credentials. */
+      readonly secretAccessKey: string;
+      /** AWS session token for temporary credentials. */
+      readonly sessionToken: string;
+    };
+/**
+ * Configuration options for the Amazon SES transport.
+ *
+ * @example
+ * ```typescript
+ * const config: SesConfig = {
+ *   authentication: {
+ *     type: "credentials",
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ *   region: "us-east-1",
+ *   timeout: 30000,
+ *   retries: 3,
+ *   batchSize: 25,
+ *   defaultTags: {
+ *     environment: "production",
+ *     service: "notifications",
+ *   },
+ * };
+ * ```
+ */
+export interface SesConfig {
+  /** AWS authentication configuration. */
+  readonly authentication: SesAuthentication;
+  /**
+   * AWS region.
+   * @default "us-east-1"
+   */
+  readonly region?: string;
+  /**
+   * Request timeout in milliseconds.
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts on failure.
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Whether to validate SSL certificates.
+   * @default true
+   */
+  readonly validateSsl?: boolean;
+  /** Additional HTTP headers to include in requests. */
+  readonly headers?: Record<string, string>;
+  /** SES configuration set name for tracking and reputation management. */
+  readonly configurationSetName?: string;
+  /** Default tags to apply to all sent emails. */
+  readonly defaultTags?: Record<string, string>;
+  /**
+   *  Maximum number of messages to send concurrently in sendMany().
+   * @default 50
+   */
+  readonly batchSize?: number;
+}
+/**
+ * Resolved SES configuration with all optional fields filled with default values.
+ *
+ * This type is returned by `createSesConfig()` and used internally by `SesTransport`.
+ * It ensures all required fields have values, making the transport implementation simpler.
+ */
+type ResolvedSesConfig = Required<
+  Omit<SesConfig, 'configurationSetName' | 'defaultTags' | 'batchSize'>
+> & {
+  /** SES configuration set name (optional) */
+  readonly configurationSetName?: string;
+  /** Default tags to apply to all emails (always defined, may be empty) */
+  readonly defaultTags: Record<string, string>;
+  /** Maximum concurrent messages in batch operations */
+  readonly batchSize: number;
+};
+/**
+ * Creates a resolved SES configuration with default values applied.
+ *
+ * This function takes a partial SES configuration and fills in default values
+ * for all optional fields, ensuring the transport has all necessary configuration.
+ *
+ * @example
+ * ```typescript
+ * const config = createSesConfig({
+ *   authentication: {
+ *     type: "credentials",
+ *     accessKeyId: "AKIA...",
+ *     secretAccessKey: "wJal..",
+ *   },
+ *   region: "eu-west-1",
+ * });
+ *
+ * // config.timeout is now 30000 (default)
+ * // config.retries is now 3 (default)
+ * // config.batchSize is now 50 (default)
+ * ```
+ *
+ * @param config The SES configuration object.
+ * @returns A resolved configuration with all defaults applied.
+ */
+
+/**
+ * Amazon SES email transport implementation.
+ *
+ * This transport sends emails through the AWS Simple Email Service (SES) using
+ * the v2 API.  It supports AWS Signature v4 authentication, configurable
+ * retries, and concurrent batch sending.
+ *
+ * @example
+ * ```typescript
+ * import { SesTransport } from "@alexify/mailer/ses";
+ * import { createMessage } from "@alexify/mailer";
+ *
+ * const transport = new SesTransport({
+ *   authentication: {
+ *     type: "credentials",
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ *   region: "us-east-1",
+ * });
+ *
+ * const message = createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from SES",
+ *   content: { text: "This is a test message" },
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log("Email sent with ID:", receipt.messageId);
+ * }
+ * ```
+ */
+export declare class SesTransport implements Transport<'ses'> {
+  readonly id = 'ses';
+  /** Resolved configuration with defaults applied */
+  config: ResolvedSesConfig;
+  /**
+   * Creates a new SES transport instance.
+   *
+   * @param config SES configuration options.
+   */
+  constructor(config: SesConfig);
+  /**
+   * Sends a single email message through Amazon SES.
+   *
+   * This method converts the message to SES format, sends it via the SES v2 API,
+   * and returns a receipt indicating success or failure.
+   *
+   * @example
+   * ```typescript
+   * const message = createMessage({
+   *   from: "sender@example.com",
+   *   to: "recipient@example.com",
+   *   subject: "Hello",
+   *   content: { text: "Hello, world!" },
+   *   attachments: [{
+   *     filename: "document.pdf",
+   *     content: Promise.resolve(pdfBytes),
+   *     contentType: "application/pdf",
+   *   }],
+   * });
+   *
+   * const receipt = await transport.send(message);
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options (e.g., abort signal).
+   * @returns A promise that resolves to a receipt with the result.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'ses'>>;
+  /**
+   * Sends multiple email messages concurrently through Amazon SES.
+   *
+   * This method processes messages in batches (configurable via `batchSize`)
+   * and sends each batch concurrently to improve performance. It yields
+   * receipts as they become available, allowing for streaming processing of
+   * results.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   createMessage({ from: "sender@example.com", to: "user1@example.com", subject: "Hello 1", content: { text: "Message 1" } }),
+   *   createMessage({ from: "sender@example.com", to: "user2@example.com", subject: "Hello 2", content: { text: "Message 2" } }),
+   *   createMessage({ from: "sender@example.com", to: "user3@example.com", subject: "Hello 3", content: { text: "Message 3" } }),
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log("Sent:", receipt.messageId);
+   *   } else {
+   *     console.error("Failed:", receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options (e.g., abort signal).
+   * @returns Individual receipts for each message as they complete.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'ses'>>;
+}
diff --git a/src/ses/index.js b/src/ses/index.js
new file mode 100644
index 0000000..19baaef
--- /dev/null
+++ b/src/ses/index.js
@@ -0,0 +1,6 @@
+// Ported from upyo v0.7.0 (packages/ses/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { SesTransport } = require('./ses-transport.js');
+
+module.exports = { SesTransport };
diff --git a/src/ses/message-converter.js b/src/ses/message-converter.js
new file mode 100644
index 0000000..e34daf6
--- /dev/null
+++ b/src/ses/message-converter.js
@@ -0,0 +1,241 @@
+// Ported from upyo v0.7.0 (packages/ses/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { readAttachmentContent } = require('../core/attachment.js');
+const { createCalendarAttachment } = require('../core/calendar.js');
+
+const convertMessage = async (message, config, signal) => {
+  const destination = {};
+
+  if (message.recipients.length > 0) {
+    destination.ToAddresses = message.recipients.map(formatAddress);
+  }
+
+  if (message.ccRecipients.length > 0) {
+    destination.CcAddresses = message.ccRecipients.map(formatAddress);
+  }
+
+  if (message.bccRecipients.length > 0) {
+    destination.BccAddresses = message.bccRecipients.map(formatAddress);
+  }
+
+  const sesMessage = {
+    Destination: destination,
+    Content: {},
+    FromEmailAddress: formatAddress(message.sender),
+  };
+
+  if (message.replyRecipients.length > 0) {
+    sesMessage.ReplyToAddresses = message.replyRecipients.map(formatAddress);
+  }
+
+  if (config.configurationSetName) {
+    sesMessage.ConfigurationSetName = config.configurationSetName;
+  }
+
+  sesMessage.Content.Simple = await createSimpleContent(message, signal);
+
+  const tags = [];
+
+  if (message.tags.length > 0) {
+    for (const tag of message.tags) {
+      tags.push({ Name: 'category', Value: tag });
+    }
+  }
+
+  if (message.priority !== 'normal') {
+    tags.push({ Name: 'priority', Value: message.priority });
+  }
+
+  for (const [name, value] of Object.entries(config.defaultTags)) {
+    tags.push({ Name: name, Value: value });
+  }
+
+  if (tags.length > 0) {
+    sesMessage.Tags = tags;
+  }
+
+  return sesMessage;
+};
+
+const createSimpleContent = async (message, signal) => {
+  const content = {
+    Subject: {
+      Data: message.subject,
+      Charset: 'UTF-8',
+    },
+    Body: {},
+  };
+
+  if ('html' in message.content) {
+    content.Body.Html = {
+      Data: message.content.html,
+      Charset: 'UTF-8',
+    };
+
+    if (message.content.text) {
+      content.Body.Text = {
+        Data: message.content.text,
+        Charset: 'UTF-8',
+      };
+    }
+  } else {
+    content.Body.Text = {
+      Data: message.content.text,
+      Charset: 'UTF-8',
+    };
+  }
+
+  // A transport that cannot compose a `text/calendar` alternative carries the
+  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
+  // own files so that a client looking for the first calendar part finds it.
+  const attachments =
+    message.calendar == null
+      ? message.attachments
+      : [createCalendarAttachment(message.calendar), ...message.attachments];
+
+  if (attachments.length > 0) {
+    const cancellation = new AbortController();
+    const combined = combineSignals(cancellation.signal, signal);
+    try {
+      content.Attachments = await Promise.all(
+        attachments.map(async (attachment) => {
+          const contentBytes = await readAttachmentContent(attachment.content, combined.signal);
+          const parts = [];
+          for (let offset = 0; offset < contentBytes.length; offset += 8192) {
+            parts.push(String.fromCharCode(...contentBytes.subarray(offset, offset + 8192)));
+          }
+          const base64Content = btoa(parts.join(''));
+
+          const converted = {
+            FileName: attachment.filename,
+            ContentType: attachment.contentType || 'application/octet-stream',
+            ContentDisposition: attachment.inline ? 'INLINE' : 'ATTACHMENT',
+            ContentTransferEncoding: 'BASE64',
+            RawContent: base64Content,
+          };
+          // An empty content ID is how Upyo spells "this part has none", so it
+          // is left out rather than sent as an empty header value.
+          if (attachment.contentId !== '') {
+            converted.ContentId = attachment.contentId;
+          }
+          return converted;
+        }),
+      );
+    } finally {
+      cancellation.abort();
+      combined.cleanup();
+    }
+  }
+
+  return content;
+};
+
+const formatAddress = (address) => {
+  if (address.name) {
+    return `"${address.name}" <${address.address}>`;
+  }
+  return address.address;
+};
+
+// Dead upstream: nothing calls it (CLAUDE.md, known upstream bugs).
+/* c8 ignore start */
+const convertMessagesToBulk = async (messages, config, signal) => {
+  if (messages.length === 0) {
+    throw new Error('Cannot convert empty message array to bulk email');
+  }
+
+  const firstMessage = messages[0];
+  const defaultContent = await createSimpleContent(firstMessage, signal);
+
+  const defaultTags = [];
+  for (const [name, value] of Object.entries(config.defaultTags)) {
+    defaultTags.push({ Name: name, Value: value });
+  }
+
+  const bulkMessage = {
+    FromEmailAddress: formatAddress(firstMessage.sender),
+    DefaultContent: { Simple: defaultContent },
+    DefaultEmailTags: defaultTags.length > 0 ? defaultTags : undefined,
+    BulkEmailEntries: [],
+  };
+
+  if (firstMessage.replyRecipients.length > 0) {
+    bulkMessage.ReplyToAddresses = firstMessage.replyRecipients.map(formatAddress);
+  }
+
+  if (config.configurationSetName) {
+    bulkMessage.ConfigurationSetName = config.configurationSetName;
+  }
+
+  for (const message of messages) {
+    const destination = {};
+
+    if (message.recipients.length > 0) {
+      destination.ToAddresses = message.recipients.map(formatAddress);
+    }
+    if (message.ccRecipients.length > 0) {
+      destination.CcAddresses = message.ccRecipients.map(formatAddress);
+    }
+    if (message.bccRecipients.length > 0) {
+      destination.BccAddresses = message.bccRecipients.map(formatAddress);
+    }
+
+    const entry = {
+      Destination: destination,
+    };
+
+    const isContentDifferent =
+      message.subject !== firstMessage.subject ||
+      JSON.stringify(message.content) !== JSON.stringify(firstMessage.content) ||
+      JSON.stringify(message.calendar) !== JSON.stringify(firstMessage.calendar) ||
+      message.attachments.length !== firstMessage.attachments.length ||
+      (message.attachments.length > 0 &&
+        JSON.stringify(
+          message.attachments.map((a) => ({
+            filename: a.filename,
+            contentType: a.contentType,
+            contentId: a.contentId,
+            inline: a.inline,
+          })),
+        ) !==
+          JSON.stringify(
+            firstMessage.attachments.map((a) => ({
+              filename: a.filename,
+              contentType: a.contentType,
+              contentId: a.contentId,
+              inline: a.inline,
+            })),
+          ));
+
+    if (isContentDifferent) {
+      const messageContent = await createSimpleContent(message, signal);
+      entry.ReplacementEmailContent = { Simple: messageContent };
+    }
+
+    const messageTags = [];
+
+    if (message.tags.length > 0) {
+      for (const tag of message.tags) {
+        messageTags.push({ Name: 'category', Value: tag });
+      }
+    }
+
+    if (message.priority !== 'normal') {
+      messageTags.push({ Name: 'priority', Value: message.priority });
+    }
+
+    if (messageTags.length > 0) {
+      entry.ReplacementTags = messageTags;
+    }
+
+    bulkMessage.BulkEmailEntries.push(entry);
+  }
+
+  return bulkMessage;
+};
+
+/* c8 ignore stop */
+
+module.exports = { convertMessage, convertMessagesToBulk };
diff --git a/src/ses/ses-transport.js b/src/ses/ses-transport.js
new file mode 100644
index 0000000..7435cb3
--- /dev/null
+++ b/src/ses/ses-transport.js
@@ -0,0 +1,234 @@
+// Ported from upyo v0.7.0 (packages/ses/src/ses-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createSesConfig } = require('./config.js');
+const { SesApiError, SesHttpClient } = require('./http-client.js');
+const { convertMessage } = require('./message-converter.js');
+
+/**
+ * Amazon SES email transport implementation.
+ *
+ * This transport sends emails through the AWS Simple Email Service (SES) using
+ * the v2 API.  It supports AWS Signature v4 authentication, configurable
+ * retries, and concurrent batch sending.
+ *
+ * @example
+ * ```typescript
+ * import { SesTransport } from "@alexify/mailer/ses";
+ * import { createMessage } from "@alexify/mailer";
+ *
+ * const transport = new SesTransport({
+ *   authentication: {
+ *     type: "credentials",
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ *   region: "us-east-1",
+ * });
+ *
+ * const message = createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from SES",
+ *   content: { text: "This is a test message" },
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log("Email sent with ID:", receipt.messageId);
+ * }
+ * ```
+ */
+class SesTransport {
+  id = 'ses';
+
+  /** Resolved configuration with defaults applied */
+  config;
+
+  /** HTTP client for SES API requests */
+  httpClient;
+
+  /**
+   * Creates a new SES transport instance.
+   *
+   * @param config SES configuration options.
+   */
+  constructor(config) {
+    this.config = createSesConfig(config);
+    this.httpClient = new SesHttpClient(this.config);
+  }
+
+  /**
+   * Sends a single email message through Amazon SES.
+   *
+   * This method converts the message to SES format, sends it via the SES v2 API,
+   * and returns a receipt indicating success or failure.
+   *
+   * @example
+   * ```typescript
+   * const message = createMessage({
+   *   from: "sender@example.com",
+   *   to: "recipient@example.com",
+   *   subject: "Hello",
+   *   content: { text: "Hello, world!" },
+   *   attachments: [{
+   *     filename: "document.pdf",
+   *     content: Promise.resolve(pdfBytes),
+   *     contentType: "application/pdf",
+   *   }],
+   * });
+   *
+   * const receipt = await transport.send(message);
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options (e.g., abort signal).
+   * @returns A promise that resolves to a receipt with the result.
+   */
+  async send(message, options) {
+    options?.signal?.throwIfAborted();
+
+    try {
+      const sesMessage = await convertMessage(message, this.config, options?.signal);
+
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendMessage(sesMessage, options?.signal);
+
+      const messageId = this.extractMessageId(response);
+
+      return {
+        successful: true,
+        messageId,
+        provider: 'ses',
+      };
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) {
+        throw error;
+      }
+
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      return createSesFailure(errorMessage, error);
+    }
+  }
+
+  /**
+   * Sends multiple email messages concurrently through Amazon SES.
+   *
+   * This method processes messages in batches (configurable via `batchSize`)
+   * and sends each batch concurrently to improve performance. It yields
+   * receipts as they become available, allowing for streaming processing of
+   * results.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   createMessage({ from: "sender@example.com", to: "user1@example.com", subject: "Hello 1", content: { text: "Message 1" } }),
+   *   createMessage({ from: "sender@example.com", to: "user2@example.com", subject: "Hello 2", content: { text: "Message 2" } }),
+   *   createMessage({ from: "sender@example.com", to: "user3@example.com", subject: "Hello 3", content: { text: "Message 3" } }),
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log("Sent:", receipt.messageId);
+   *   } else {
+   *     console.error("Failed:", receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options (e.g., abort signal).
+   * @returns Individual receipts for each message as they complete.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    const isAsyncIterable = Symbol.asyncIterator in messages;
+    const messageArray = [];
+
+    if (isAsyncIterable) {
+      for await (const message of messages) {
+        messageArray.push(message);
+      }
+    } else {
+      for (const message of messages) {
+        messageArray.push(message);
+      }
+    }
+
+    const batchSize = this.config.batchSize;
+
+    for (let i = 0; i < messageArray.length; i += batchSize) {
+      options?.signal?.throwIfAborted();
+
+      const batch = messageArray.slice(i, i + batchSize);
+
+      const receipts = await this.sendConcurrent(batch, options);
+      for (const receipt of receipts) {
+        yield receipt;
+      }
+    }
+  }
+
+  async sendConcurrent(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    const sendPromises = messages.map((message) => this.send(message, options));
+
+    return await Promise.all(sendPromises);
+  }
+
+  extractMessageId(response) {
+    if (response.body) {
+      try {
+        const parsed = JSON.parse(response.body);
+        if (parsed.MessageId) {
+          return parsed.MessageId;
+        }
+      } catch {
+        // Ignore JSON parsing errors
+      }
+    }
+
+    const messageIdHeader =
+      response.headers?.['x-amzn-requestid'] || response.headers?.['X-Amzn-RequestId'];
+
+    if (messageIdHeader) {
+      return messageIdHeader;
+    }
+
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 8);
+
+    return `ses-${timestamp}-${random}`;
+  }
+}
+
+const createSesFailure = (message, error) => {
+  if (error instanceof SesApiError) {
+    return createFailedReceipt(message, {
+      provider: 'ses',
+      statusCode: error.statusCode,
+      retryAfterMilliseconds: error.retryAfterMilliseconds,
+      providerDetails: error.errors,
+      attempts: error.attempts,
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'ses',
+  });
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+module.exports = { SesTransport };
diff --git a/tests/e2e/ses-transport.e2e.test.js b/tests/e2e/ses-transport.e2e.test.js
new file mode 100644
index 0000000..d5051ee
--- /dev/null
+++ b/tests/e2e/ses-transport.e2e.test.js
@@ -0,0 +1,278 @@
+// Ported from upyo v0.7.0 (packages/ses/src/ses-transport.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const { SesTransport } = require('../../src/ses/index.js');
+const assert = require('node:assert/strict');
+const process = require('node:process');
+const { test } = require('node:test');
+
+const shouldRunE2ETests =
+  process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY && process.env.SES_FROM_EMAIL;
+
+test('SesTransport E2E: send simple message', { skip: !shouldRunE2ETests }, async () => {
+  if (!shouldRunE2ETests) return;
+
+  const transport = new SesTransport({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    },
+    region: process.env.AWS_REGION || 'us-east-1',
+    retries: 1,
+  });
+
+  const message = createMessage({
+    from: process.env.SES_FROM_EMAIL,
+    to: process.env.SES_TO_EMAIL || process.env.SES_FROM_EMAIL,
+    subject: 'Upyo SES E2E Test - Simple Message',
+    content: { text: 'This is a test message from the Upyo SES transport.' },
+    tags: ['e2e-test', 'simple'],
+  });
+
+  const receipt = await transport.send(message);
+
+  assert.ok(
+    receipt.successful,
+    `Send failed: ${receipt.successful ? '' : receipt.errorMessages.join(', ')}`,
+  );
+  if (receipt.successful) {
+    assert.ok(receipt.messageId.length > 0, 'Message ID should not be empty');
+    console.log(`✓ Message sent successfully with ID: ${receipt.messageId}`);
+  }
+});
+
+test('SesTransport E2E: send HTML message', { skip: !shouldRunE2ETests }, async () => {
+  if (!shouldRunE2ETests) return;
+
+  const transport = new SesTransport({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    },
+    region: process.env.AWS_REGION || 'us-east-1',
+    retries: 1,
+  });
+
+  const message = createMessage({
+    from: process.env.SES_FROM_EMAIL,
+    to: process.env.SES_TO_EMAIL || process.env.SES_FROM_EMAIL,
+    subject: 'Upyo SES E2E Test - HTML Message',
+    content: {
+      html: '<h1>HTML Test</h1><p>This is an <strong>HTML</strong> test message.</p>',
+      text: 'HTML Test\n\nThis is an HTML test message.',
+    },
+    tags: ['e2e-test', 'html'],
+    priority: 'high',
+  });
+
+  const receipt = await transport.send(message);
+
+  assert.ok(
+    receipt.successful,
+    `Send failed: ${receipt.successful ? '' : receipt.errorMessages.join(', ')}`,
+  );
+  if (receipt.successful) {
+    assert.ok(receipt.messageId.length > 0, 'Message ID should not be empty');
+    console.log(`✓ HTML message sent successfully with ID: ${receipt.messageId}`);
+  }
+});
+
+test('SesTransport E2E: send multiple messages', { skip: !shouldRunE2ETests }, async () => {
+  if (!shouldRunE2ETests) return;
+
+  const transport = new SesTransport({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    },
+    region: process.env.AWS_REGION || 'us-east-1',
+    retries: 1,
+  });
+
+  const messages = [
+    createMessage({
+      from: process.env.SES_FROM_EMAIL,
+      to: process.env.SES_TO_EMAIL || process.env.SES_FROM_EMAIL,
+      subject: 'Upyo SES E2E Test - Batch Message 1',
+      content: { text: 'This is batch message 1.' },
+      tags: ['e2e-test', 'batch'],
+    }),
+    createMessage({
+      from: process.env.SES_FROM_EMAIL,
+      to: process.env.SES_TO_EMAIL || process.env.SES_FROM_EMAIL,
+      subject: 'Upyo SES E2E Test - Batch Message 2',
+      content: { text: 'This is batch message 2.' },
+      tags: ['e2e-test', 'batch'],
+    }),
+  ];
+
+  const receipts = [];
+  for await (const receipt of transport.sendMany(messages)) {
+    receipts.push(receipt);
+  }
+
+  assert.equal(receipts.length, 2, 'Should have 2 receipts');
+
+  for (const [index, receipt] of receipts.entries()) {
+    assert.ok(
+      receipt.successful,
+      `Message ${index + 1} failed: ${receipt.successful ? '' : receipt.errorMessages.join(', ')}`,
+    );
+    if (receipt.successful) {
+      assert.ok(receipt.messageId.length > 0, `Message ${index + 1} ID should not be empty`);
+      console.log(`✓ Batch message ${index + 1} sent successfully with ID: ${receipt.messageId}`);
+    }
+  }
+});
+
+test('SesTransport E2E: handle invalid recipient', { skip: !shouldRunE2ETests }, async () => {
+  if (!shouldRunE2ETests) return;
+
+  const transport = new SesTransport({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    },
+    region: process.env.AWS_REGION || 'us-east-1',
+    retries: 1,
+  });
+
+  const message = createMessage({
+    from: process.env.SES_FROM_EMAIL,
+    to: 'invalid@nonexistent-domain-that-should-fail.invalid',
+    subject: 'Upyo SES E2E Test - Invalid Recipient',
+    content: { text: 'This should fail due to invalid recipient.' },
+    tags: ['e2e-test', 'error'],
+  });
+
+  const receipt = await transport.send(message);
+
+  assert.ok(!receipt.successful, 'Send should have failed for invalid email');
+  if (!receipt.successful) {
+    assert.ok(receipt.errorMessages.length > 0, 'Should have error messages');
+    console.log(`✓ Invalid recipient correctly failed: ${receipt.errorMessages.join(', ')}`);
+  }
+});
+
+test('SesTransport E2E: send message with attachment', { skip: !shouldRunE2ETests }, async () => {
+  if (!shouldRunE2ETests) return;
+
+  const transport = new SesTransport({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    },
+    region: process.env.AWS_REGION || 'us-east-1',
+    retries: 1,
+  });
+
+  // Create a simple text attachment
+  const attachmentContent = new TextEncoder().encode(
+    'This is a test attachment file.\nIt contains some sample text content.\n',
+  );
+
+  const attachment = {
+    inline: false,
+    filename: 'test-attachment.txt',
+    content: Promise.resolve(attachmentContent),
+    contentType: 'text/plain',
+    contentId: 'test-attachment-id',
+  };
+
+  const message = createMessage({
+    from: process.env.SES_FROM_EMAIL,
+    to: process.env.SES_TO_EMAIL || process.env.SES_FROM_EMAIL,
+    subject: 'Upyo SES E2E Test - Message with Attachment',
+    content: {
+      html: `
+          <h1>Attachment Test</h1>
+          <p>This email contains a test attachment.</p>
+          <p>The attachment is a simple text file that should be delivered along with this message.</p>
+        `,
+      text: 'Attachment Test\n\nThis email contains a test attachment.\n\nThe attachment is a simple text file that should be delivered along with this message.',
+    },
+    attachments: [attachment],
+    tags: ['e2e-test', 'attachment'],
+    priority: 'normal',
+  });
+
+  const receipt = await transport.send(message);
+
+  assert.ok(
+    receipt.successful,
+    `Send failed: ${receipt.successful ? '' : receipt.errorMessages.join(', ')}`,
+  );
+  if (receipt.successful) {
+    assert.ok(receipt.messageId.length > 0, 'Message ID should not be empty');
+    console.log(`✓ Message with attachment sent successfully with ID: ${receipt.messageId}`);
+  }
+});
+
+test(
+  'SesTransport E2E: send bulk messages (concurrent)',
+  { skip: !shouldRunE2ETests },
+  async () => {
+    if (!shouldRunE2ETests) return;
+
+    const transport = new SesTransport({
+      authentication: {
+        type: 'credentials',
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+      },
+      region: process.env.AWS_REGION || 'us-east-1',
+      retries: 1,
+      batchSize: 3, // Small batch for testing
+    });
+
+    const messages = [
+      createMessage({
+        from: process.env.SES_FROM_EMAIL,
+        to: process.env.SES_TO_EMAIL || process.env.SES_FROM_EMAIL,
+        subject: 'Upyo SES E2E Test - Bulk Message 1',
+        content: { text: 'This is bulk test message 1.' },
+        tags: ['e2e-test', 'bulk'],
+      }),
+      createMessage({
+        from: process.env.SES_FROM_EMAIL,
+        to: process.env.SES_TO_EMAIL || process.env.SES_FROM_EMAIL,
+        subject: 'Upyo SES E2E Test - Bulk Message 2',
+        content: { text: 'This is bulk test message 2.' },
+        tags: ['e2e-test', 'bulk'],
+      }),
+      createMessage({
+        from: process.env.SES_FROM_EMAIL,
+        to: process.env.SES_TO_EMAIL || process.env.SES_FROM_EMAIL,
+        subject: 'Upyo SES E2E Test - Bulk Message 3',
+        content: { text: 'This is bulk test message 3.' },
+        tags: ['e2e-test', 'bulk'],
+      }),
+    ];
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 3, 'Should have 3 receipts');
+
+    for (const [index, receipt] of receipts.entries()) {
+      assert.ok(
+        receipt.successful,
+        `Bulk message ${index + 1} failed: ${
+          receipt.successful ? '' : receipt.errorMessages.join(', ')
+        }`,
+      );
+      if (receipt.successful) {
+        assert.ok(receipt.messageId.length > 0, `Bulk message ${index + 1} ID should not be empty`);
+        console.log(`✓ Bulk message ${index + 1} sent successfully with ID: ${receipt.messageId}`);
+      }
+    }
+  },
+);
diff --git a/tests/helpers/ses/test-config.js b/tests/helpers/ses/test-config.js
new file mode 100644
index 0000000..dcd22ee
--- /dev/null
+++ b/tests/helpers/ses/test-config.js
@@ -0,0 +1,33 @@
+// Ported from upyo v0.7.0 (packages/ses/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const createTestSesConfig = (overrides = {}) => {
+  return {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+      secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+    },
+    region: 'us-east-1',
+    timeout: 30000,
+    retries: 0,
+    ...overrides,
+  };
+};
+
+const createTestSessionConfig = (overrides = {}) => {
+  return {
+    authentication: {
+      type: 'session',
+      accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+      secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+      sessionToken: 'example-session-token',
+    },
+    region: 'us-east-1',
+    timeout: 30000,
+    retries: 0,
+    ...overrides,
+  };
+};
+
+module.exports = { createTestSesConfig, createTestSessionConfig };
diff --git a/tests/types/ses.test-d.ts b/tests/types/ses.test-d.ts
new file mode 100644
index 0000000..0f8f756
--- /dev/null
+++ b/tests/types/ses.test-d.ts
@@ -0,0 +1,28 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import { SesTransport, type SesAuthentication, type SesConfig } from '../../src/ses/index.js';
+
+const authentication: SesAuthentication = {
+  type: 'credentials',
+  accessKeyId: 'AKID',
+  secretAccessKey: 'secret',
+};
+const transport = new SesTransport({ authentication, region: 'eu-west-1', retries: 2 });
+expectAssignable<Transport<'ses'>>(transport);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'ses'>>>(transport.send(message));
+expectType<AsyncIterable<Receipt<'ses'>>>(transport.sendMany([message]));
+
+expectAssignable<SesConfig>({
+  authentication: { type: 'session', accessKeyId: 'A', secretAccessKey: 'S', sessionToken: 'T' },
+  configurationSetName: 'transactional',
+  defaultTags: { app: 'billing' },
+});
+expectError(new SesTransport({ region: 'eu-west-1' }));
+expectError<SesAuthentication>({ type: 'session', accessKeyId: 'A', secretAccessKey: 'S' });
diff --git a/tests/unit/ses-attachment-content.test.js b/tests/unit/ses-attachment-content.test.js
new file mode 100644
index 0000000..6dbb2df
--- /dev/null
+++ b/tests/unit/ses-attachment-content.test.js
@@ -0,0 +1,48 @@
+// Ported from upyo v0.7.0 (packages/ses/src/attachment-content.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const { createSesConfig } = require('../../src/ses/config.js');
+const { convertMessage } = require('../../src/ses/message-converter.js');
+
+test('collects large replayable attachments without argument overflow', async () => {
+  const bytes = new Uint8Array(256 * 1024).fill(123);
+  const config = createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test',
+      secretAccessKey: 'test',
+    },
+  });
+  for (const content of [
+    new Blob([bytes]),
+    async function* () {
+      yield bytes;
+    },
+  ]) {
+    const result = await convertMessage(
+      createMessage({
+        from: 'from@example.com',
+        to: 'to@example.com',
+        subject: 'Test',
+        content: { text: 'Test' },
+        attachments: {
+          inline: false,
+          filename: 'large.bin',
+          content,
+          contentId: 'large',
+          contentType: 'application/octet-stream',
+        },
+      }),
+      config,
+    );
+    const encoded = result.Content.Simple?.Attachments?.[0].RawContent;
+    assert.ok(encoded);
+    assert.deepEqual(
+      Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0)),
+      bytes,
+    );
+  }
+});
diff --git a/tests/unit/ses-config.test.js b/tests/unit/ses-config.test.js
new file mode 100644
index 0000000..5662f82
--- /dev/null
+++ b/tests/unit/ses-config.test.js
@@ -0,0 +1,99 @@
+// Ported from upyo v0.7.0 (packages/ses/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { test } = require('node:test');
+const { strict: assert } = require('node:assert');
+const { createSesConfig } = require('../../src/ses/config.js');
+
+test('createSesConfig applies default values', () => {
+  const config = {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  };
+
+  const resolved = createSesConfig(config);
+
+  assert.equal(resolved.region, 'us-east-1');
+  assert.equal(resolved.timeout, 30000);
+  assert.equal(resolved.retries, 3);
+  assert.equal(resolved.validateSsl, true);
+  assert.deepEqual(resolved.headers, {});
+  assert.deepEqual(resolved.defaultTags, {});
+  assert.equal(resolved.configurationSetName, undefined);
+});
+
+test('createSesConfig preserves provided values', () => {
+  const config = {
+    authentication: {
+      type: 'session',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+      sessionToken: 'test-token',
+    },
+    region: 'eu-west-1',
+    timeout: 15000,
+    retries: 5,
+    validateSsl: false,
+    headers: { 'X-Custom': 'value' },
+    configurationSetName: 'test-config-set',
+    defaultTags: { environment: 'test' },
+  };
+
+  const resolved = createSesConfig(config);
+
+  assert.deepEqual(resolved.authentication, config.authentication);
+  assert.equal(resolved.region, 'eu-west-1');
+  assert.equal(resolved.timeout, 15000);
+  assert.equal(resolved.retries, 5);
+  assert.equal(resolved.validateSsl, false);
+  assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
+  assert.equal(resolved.configurationSetName, 'test-config-set');
+  assert.deepEqual(resolved.defaultTags, { environment: 'test' });
+});
+
+test('createSesConfig handles credentials authentication', () => {
+  const config = {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+      secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+    },
+  };
+
+  const resolved = createSesConfig(config);
+
+  assert.equal(resolved.authentication.type, 'credentials');
+  if (resolved.authentication.type === 'credentials') {
+    assert.equal(resolved.authentication.accessKeyId, 'AKIAIOSFODNN7EXAMPLE');
+    assert.equal(
+      resolved.authentication.secretAccessKey,
+      'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+    );
+  }
+});
+
+test('createSesConfig handles session authentication', () => {
+  const config = {
+    authentication: {
+      type: 'session',
+      accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+      secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+      sessionToken: 'example-session-token',
+    },
+  };
+
+  const resolved = createSesConfig(config);
+
+  assert.equal(resolved.authentication.type, 'session');
+  if (resolved.authentication.type === 'session') {
+    assert.equal(resolved.authentication.accessKeyId, 'AKIAIOSFODNN7EXAMPLE');
+    assert.equal(
+      resolved.authentication.secretAccessKey,
+      'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+    );
+    assert.equal(resolved.authentication.sessionToken, 'example-session-token');
+  }
+});
diff --git a/tests/unit/ses-message-converter.test.js b/tests/unit/ses-message-converter.test.js
new file mode 100644
index 0000000..af956c5
--- /dev/null
+++ b/tests/unit/ses-message-converter.test.js
@@ -0,0 +1,312 @@
+// Ported from upyo v0.7.0 (packages/ses/src/message-converter.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const { convertMessage } = require('../../src/ses/message-converter.js');
+const { createSesConfig } = require('../../src/ses/config.js');
+
+test('convertMessage handles simple text message', async () => {
+  const config = createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  });
+
+  const message = createMessage({
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Test Subject',
+    content: { text: 'Hello World!' },
+  });
+
+  const sesMessage = await convertMessage(message, config);
+
+  assert.equal(sesMessage.FromEmailAddress, 'sender@example.com');
+  assert.deepEqual(sesMessage.Destination.ToAddresses, ['recipient@example.com']);
+  assert.equal(sesMessage.Content.Simple?.Subject.Data, 'Test Subject');
+  assert.equal(sesMessage.Content.Simple?.Body.Text?.Data, 'Hello World!');
+  assert.equal(sesMessage.Content.Simple?.Body.Html, undefined);
+});
+
+test('convertMessage handles HTML message with text fallback', async () => {
+  const config = createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  });
+
+  const message = createMessage({
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'HTML Test',
+    content: {
+      html: '<h1>Hello World!</h1>',
+      text: 'Hello World!',
+    },
+  });
+
+  const sesMessage = await convertMessage(message, config);
+
+  assert.equal(sesMessage.Content.Simple?.Body.Html?.Data, '<h1>Hello World!</h1>');
+  assert.equal(sesMessage.Content.Simple?.Body.Text?.Data, 'Hello World!');
+});
+
+test('convertMessage handles multiple recipients', async () => {
+  const config = createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  });
+
+  const message = createMessage({
+    from: 'sender@example.com',
+    to: ['recipient1@example.com', 'recipient2@example.com'],
+    cc: 'cc@example.com',
+    bcc: ['bcc1@example.com', 'bcc2@example.com'],
+    subject: 'Multiple Recipients',
+    content: { text: 'Hello Everyone!' },
+  });
+
+  const sesMessage = await convertMessage(message, config);
+
+  assert.deepEqual(sesMessage.Destination.ToAddresses, [
+    'recipient1@example.com',
+    'recipient2@example.com',
+  ]);
+  assert.deepEqual(sesMessage.Destination.CcAddresses, ['cc@example.com']);
+  assert.deepEqual(sesMessage.Destination.BccAddresses, ['bcc1@example.com', 'bcc2@example.com']);
+});
+
+test('convertMessage handles reply-to addresses', async () => {
+  const config = createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  });
+
+  const message = createMessage({
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    replyTo: ['reply1@example.com', 'reply2@example.com'],
+    subject: 'Reply-To Test',
+    content: { text: 'Hello!' },
+  });
+
+  const sesMessage = await convertMessage(message, config);
+
+  assert.deepEqual(sesMessage.ReplyToAddresses, ['reply1@example.com', 'reply2@example.com']);
+});
+
+test('convertMessage handles tags and priority', async () => {
+  const config = createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+    defaultTags: { environment: 'test' },
+  });
+
+  const message = createMessage({
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Tagged Message',
+    content: { text: 'Hello!' },
+    tags: ['newsletter', 'marketing'],
+    priority: 'high',
+  });
+
+  const sesMessage = await convertMessage(message, config);
+
+  const tags = sesMessage.Tags || [];
+
+  assert.ok(tags.some((tag) => tag.Name === 'category' && tag.Value === 'newsletter'));
+  assert.ok(tags.some((tag) => tag.Name === 'category' && tag.Value === 'marketing'));
+  assert.ok(tags.some((tag) => tag.Name === 'priority' && tag.Value === 'high'));
+  assert.ok(tags.some((tag) => tag.Name === 'environment' && tag.Value === 'test'));
+});
+
+test('convertMessage handles configuration set', async () => {
+  const config = createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+    configurationSetName: 'test-config-set',
+  });
+
+  const message = createMessage({
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Config Set Test',
+    content: { text: 'Hello!' },
+  });
+
+  const sesMessage = await convertMessage(message, config);
+
+  assert.equal(sesMessage.ConfigurationSetName, 'test-config-set');
+});
+
+test('convertMessage handles named addresses', async () => {
+  const config = createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  });
+
+  const message = createMessage({
+    from: { address: 'sender@example.com', name: 'John Sender' },
+    to: { address: 'recipient@example.com', name: 'Jane Recipient' },
+    subject: 'Named Addresses',
+    content: { text: 'Hello!' },
+  });
+
+  const sesMessage = await convertMessage(message, config);
+
+  assert.equal(sesMessage.FromEmailAddress, '"John Sender" <sender@example.com>');
+  assert.deepEqual(sesMessage.Destination.ToAddresses, [
+    '"Jane Recipient" <recipient@example.com>',
+  ]);
+});
+
+test('convertMessage handles attachments', async () => {
+  const config = createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  });
+
+  const attachment = {
+    inline: false,
+    filename: 'test.txt',
+    content: Promise.resolve(new Uint8Array([72, 101, 108, 108, 111])), // "Hello"
+    contentType: 'text/plain',
+    contentId: 'test-content-id',
+  };
+
+  const message = createMessage({
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Test with Attachment',
+    content: { text: 'Message with attachment' },
+    attachments: [attachment],
+  });
+
+  const sesMessage = await convertMessage(message, config);
+
+  assert.ok(sesMessage.Content.Simple?.Attachments);
+  assert.equal(sesMessage.Content.Simple.Attachments.length, 1);
+
+  const sesAttachment = sesMessage.Content.Simple.Attachments[0];
+  assert.equal(sesAttachment.FileName, 'test.txt');
+  assert.equal(sesAttachment.ContentType, 'text/plain');
+  assert.equal(sesAttachment.ContentDisposition, 'ATTACHMENT');
+  assert.equal(sesAttachment.ContentId, 'test-content-id');
+  assert.equal(sesAttachment.ContentTransferEncoding, 'BASE64');
+  assert.equal(sesAttachment.RawContent, btoa('Hello'));
+});
+
+const CALENDAR_ICS =
+  [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'SUMMARY:Lunch',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+const CALENDAR_BASE64 = btoa(CALENDAR_ICS);
+
+const AGENDA_ATTACHMENT = {
+  inline: false,
+  filename: 'agenda.txt',
+  content: new TextEncoder().encode('agenda'),
+  contentType: 'text/plain',
+  contentId: '',
+};
+
+const calendarTestConfig = () => {
+  return createSesConfig({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  });
+};
+
+test('convertMessage carries the calendar as an invite.ics attachment', async () => {
+  const config = calendarTestConfig();
+  const message = createMessage({
+    from: 'organizer@example.com',
+    to: 'attendee@example.net',
+    subject: 'Lunch',
+    content: { text: 'Lunch on Wednesday.' },
+    calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+  });
+
+  const sesMessage = await convertMessage(message, config);
+  const attachments = sesMessage.Content.Simple?.Attachments;
+
+  assert.equal(attachments?.length, 1);
+  assert.equal(attachments?.[0].FileName, 'invite.ics');
+  assert.equal(attachments?.[0].ContentType, 'text/calendar; charset=utf-8; method=REQUEST');
+  assert.equal(attachments?.[0].ContentDisposition, 'ATTACHMENT');
+  assert.equal(attachments?.[0].RawContent, CALENDAR_BASE64);
+  // SES rejects an empty content ID, and this part has none.
+  assert.ok(!('ContentId' in (attachments?.[0] ?? {})));
+});
+
+test('convertMessage places the invitation ahead of the other attachments', async () => {
+  const config = calendarTestConfig();
+  const message = createMessage({
+    from: 'organizer@example.com',
+    to: 'attendee@example.net',
+    subject: 'Lunch',
+    content: { text: 'Lunch on Wednesday.' },
+    calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+    attachments: [AGENDA_ATTACHMENT],
+  });
+
+  const sesMessage = await convertMessage(message, config);
+
+  assert.deepEqual(
+    sesMessage.Content.Simple?.Attachments?.map((a) => a.FileName),
+    ['invite.ics', 'agenda.txt'],
+  );
+});
+
+test('convertMessage rejects calendar content that never passed createMessage()', async () => {
+  const config = calendarTestConfig();
+  const message = {
+    ...createMessage({
+      from: 'organizer@example.com',
+      to: 'attendee@example.net',
+      subject: 'Lunch',
+      content: { text: 'Lunch.' },
+    }),
+    calendar: { method: 'REQUEST', content: 'not a calendar' },
+  };
+
+  await assert.rejects(() => convertMessage(message, config), {
+    name: 'TypeError',
+  });
+});
diff --git a/tests/unit/ses-transport-concurrent.test.js b/tests/unit/ses-transport-concurrent.test.js
new file mode 100644
index 0000000..f539ce6
--- /dev/null
+++ b/tests/unit/ses-transport-concurrent.test.js
@@ -0,0 +1,196 @@
+// Ported from upyo v0.7.0 (packages/ses/src/ses-transport-concurrent.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const { SesTransport } = require('../../src/ses/index.js');
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+
+test('SesTransport sendMany handles concurrent sending', async () => {
+  const originalFetch = globalThis.fetch;
+  let fetchCallCount = 0;
+
+  try {
+    globalThis.fetch = () => {
+      fetchCallCount++;
+      return Promise.resolve(
+        new Response(JSON.stringify({ MessageId: `test-id-${fetchCallCount}` }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+      );
+    };
+
+    const transport = new SesTransport({
+      authentication: {
+        type: 'credentials',
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+      },
+      region: 'us-east-1',
+      batchSize: 2,
+    });
+
+    const messages = [
+      createMessage({
+        from: 'sender@example.com',
+        to: 'recipient1@example.com',
+        subject: 'Test Subject 1',
+        content: { text: 'Hello World 1!' },
+      }),
+      createMessage({
+        from: 'sender@example.com',
+        to: 'recipient2@example.com',
+        subject: 'Test Subject 2',
+        content: { text: 'Hello World 2!' },
+      }),
+    ];
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 2);
+    assert.equal(fetchCallCount, 2);
+
+    for (const receipt of receipts) {
+      assert.ok(receipt.successful);
+      if (receipt.successful) {
+        assert.ok(receipt.messageId.startsWith('test-id-'));
+      }
+    }
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('SesTransport sendMany respects batchSize', async () => {
+  const originalFetch = globalThis.fetch;
+  const fetchCalls = [];
+
+  try {
+    globalThis.fetch = () => {
+      fetchCalls.push(Date.now());
+      return Promise.resolve(
+        new Response(JSON.stringify({ MessageId: `test-id-${fetchCalls.length}` }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+      );
+    };
+
+    const transport = new SesTransport({
+      authentication: {
+        type: 'credentials',
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+      },
+      region: 'us-east-1',
+      batchSize: 2,
+    });
+
+    const messages = Array(5)
+      .fill(null)
+      .map((_, i) =>
+        createMessage({
+          from: 'sender@example.com',
+          to: `recipient${i}@example.com`,
+          subject: `Test Subject ${i}`,
+          content: { text: `Hello World ${i}!` },
+        }),
+      );
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 5);
+    assert.equal(fetchCalls.length, 5);
+
+    // Check that first 2 calls happened roughly at the same time (concurrent)
+    // and next 2 calls happened roughly at the same time
+    // and last call happened separately
+    const timeDiff1 = Math.abs(fetchCalls[1] - fetchCalls[0]);
+    const timeDiff2 = Math.abs(fetchCalls[3] - fetchCalls[2]);
+
+    // Concurrent calls should happen within 50ms of each other
+    assert.ok(
+      timeDiff1 < 50,
+      `First batch calls should be concurrent, but diff was ${timeDiff1}ms`,
+    );
+    assert.ok(
+      timeDiff2 < 50,
+      `Second batch calls should be concurrent, but diff was ${timeDiff2}ms`,
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('SesTransport sendMany handles errors in concurrent sending', async () => {
+  const originalFetch = globalThis.fetch;
+  let fetchCallCount = 0;
+
+  try {
+    globalThis.fetch = () => {
+      fetchCallCount++;
+      if (fetchCallCount === 2) {
+        return Promise.reject(new Error('Network error'));
+      }
+      return Promise.resolve(
+        new Response(JSON.stringify({ MessageId: `test-id-${fetchCallCount}` }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+      );
+    };
+
+    const transport = new SesTransport({
+      authentication: {
+        type: 'credentials',
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+      },
+      region: 'us-east-1',
+      batchSize: 2,
+      retries: 0, // Disable retries for predictable test behavior
+    });
+
+    const messages = [
+      createMessage({
+        from: 'sender@example.com',
+        to: 'recipient1@example.com',
+        subject: 'Test Subject 1',
+        content: { text: 'Hello World 1!' },
+      }),
+      createMessage({
+        from: 'sender@example.com',
+        to: 'recipient2@example.com',
+        subject: 'Test Subject 2',
+        content: { text: 'Hello World 2!' },
+      }),
+    ];
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 2);
+    assert.equal(fetchCallCount, 2);
+
+    const successfulReceipts = receipts.filter((receipt) => receipt.successful);
+    const failedReceipts = receipts.filter((receipt) => !receipt.successful);
+
+    assert.equal(successfulReceipts.length, 1);
+    assert.equal(failedReceipts.length, 1);
+
+    const [failedReceipt] = failedReceipts;
+    assert.ok(!failedReceipt.successful);
+    assert.ok(failedReceipt.errorMessages.includes('Network error'));
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
diff --git a/tests/unit/ses-transport.test.js b/tests/unit/ses-transport.test.js
new file mode 100644
index 0000000..15da37f
--- /dev/null
+++ b/tests/unit/ses-transport.test.js
@@ -0,0 +1,431 @@
+// Ported from upyo v0.7.0 (packages/ses/src/ses-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const { SesTransport } = require('../../src/ses/index.js');
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+
+test('SesTransport constructor creates instance with valid config', () => {
+  const config = {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  };
+
+  const transport = new SesTransport(config);
+
+  assert.ok(transport instanceof SesTransport);
+  assert.equal(transport.config.region, 'us-east-1');
+  assert.equal(transport.config.authentication.type, 'credentials');
+});
+
+test('SesTransport handles AbortSignal cancellation', async () => {
+  const config = {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  };
+
+  const transport = new SesTransport(config);
+  const controller = new AbortController();
+  controller.abort();
+
+  const message = createMessage({
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Test Subject',
+    content: { text: 'Hello World!' },
+  });
+
+  try {
+    await transport.send(message, { signal: controller.signal });
+    assert.fail('Should have thrown AbortError');
+  } catch (error) {
+    assert.ok(error instanceof Error);
+    assert.ok(error.name === 'AbortError' || error.message.includes('abort'));
+  }
+});
+
+test('SesTransport rejects caller aborts during fetch', async () => {
+  const originalFetch = globalThis.fetch;
+  const controller = new AbortController();
+
+  try {
+    globalThis.fetch = (_url, options) =>
+      new Promise((_resolve, reject) => {
+        options?.signal?.addEventListener(
+          'abort',
+          () => {
+            reject(new DOMException('The operation was aborted.', 'AbortError'));
+          },
+          { once: true },
+        );
+        setTimeout(() => controller.abort(), 0);
+      });
+
+    const transport = new SesTransport({
+      authentication: {
+        type: 'credentials',
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+      },
+      retries: 0,
+    });
+
+    const message = createMessage({
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test Subject',
+      content: { text: 'Hello World!' },
+    });
+
+    await assert.rejects(
+      () => transport.send(message, { signal: controller.signal }),
+      (error) => error instanceof Error && error.name === 'AbortError',
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('SesTransport preserves custom caller abort reasons during fetch', async () => {
+  const originalFetch = globalThis.fetch;
+  const controller = new AbortController();
+  const reason = new Error('Stop fetching.');
+
+  try {
+    globalThis.fetch = (_url, options) =>
+      new Promise((_resolve, reject) => {
+        options?.signal?.addEventListener(
+          'abort',
+          () => {
+            reject(options.signal?.reason);
+          },
+          { once: true },
+        );
+        setTimeout(() => controller.abort(reason), 0);
+      });
+
+    const transport = new SesTransport({
+      authentication: {
+        type: 'credentials',
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+      },
+      retries: 0,
+    });
+
+    const message = createMessage({
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test Subject',
+      content: { text: 'Hello World!' },
+    });
+
+    await assert.rejects(
+      () => transport.send(message, { signal: controller.signal }),
+      (error) => error === reason,
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('SesTransport rejects caller aborts during retry backoff', async () => {
+  const originalFetch = globalThis.fetch;
+  const controller = new AbortController();
+  const reason = new Error('Stop retrying.');
+  let attempts = 0;
+
+  try {
+    globalThis.fetch = async () => {
+      attempts++;
+      setTimeout(() => controller.abort(reason), 0);
+      return new Response('Server Error', { status: 500 });
+    };
+
+    const transport = new SesTransport({
+      authentication: {
+        type: 'credentials',
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+      },
+      retries: 1,
+    });
+
+    const message = createMessage({
+      from: 'sender@example.com',
+      to: 'recipient@example.com',
+      subject: 'Test Subject',
+      content: { text: 'Hello World!' },
+    });
+
+    const startedAt = Date.now();
+    await assert.rejects(
+      () => transport.send(message, { signal: controller.signal }),
+      (error) => error === reason,
+    );
+
+    assert.equal(attempts, 1);
+    assert.ok(Date.now() - startedAt < 500);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+// Upstream's "SesTransport falls back when AbortSignal.any is unavailable" is not
+// ported: Node 22 always has AbortSignal.any, and src/core/abort-signal.js keeps
+// no fallback for runtimes without it.
+
+test('SesTransport sendMany handles async iterables', async () => {
+  const config = {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  };
+
+  const transport = new SesTransport(config);
+
+  const messageGenerator = async function* () {
+    for (let i = 0; i < 3; i++) {
+      yield createMessage({
+        from: 'sender@example.com',
+        to: `recipient${i}@example.com`,
+        subject: `Message ${i}`,
+        content: { text: `Hello ${i}!` },
+      });
+    }
+  };
+
+  const controller = new AbortController();
+  controller.abort();
+
+  const receipts = [];
+
+  try {
+    for await (const receipt of transport.sendMany(messageGenerator(), {
+      signal: controller.signal,
+    })) {
+      receipts.push(receipt);
+    }
+    assert.fail('Should have thrown AbortError');
+  } catch (error) {
+    assert.ok(error instanceof Error);
+    assert.ok(error.name === 'AbortError' || error.message.includes('abort'));
+    assert.equal(receipts.length, 0);
+  }
+});
+
+test('SesTransport sendMany handles sync iterables', async () => {
+  const config = {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  };
+
+  const transport = new SesTransport(config);
+
+  const messages = [
+    createMessage({
+      from: 'sender@example.com',
+      to: 'recipient1@example.com',
+      subject: 'Message 1',
+      content: { text: 'Hello 1!' },
+    }),
+    createMessage({
+      from: 'sender@example.com',
+      to: 'recipient2@example.com',
+      subject: 'Message 2',
+      content: { text: 'Hello 2!' },
+    }),
+  ];
+
+  const controller = new AbortController();
+  controller.abort();
+
+  const receipts = [];
+
+  try {
+    for await (const receipt of transport.sendMany(messages, {
+      signal: controller.signal,
+    })) {
+      receipts.push(receipt);
+    }
+    assert.fail('Should have thrown AbortError');
+  } catch (error) {
+    assert.ok(error instanceof Error);
+    assert.ok(error.name === 'AbortError' || error.message.includes('abort'));
+    assert.equal(receipts.length, 0);
+  }
+});
+
+test('SesTransport extractMessageId handles JSON response', () => {
+  const config = {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  };
+
+  const transport = new SesTransport(config);
+
+  const extractMessageId = transport.extractMessageId.bind(transport);
+
+  const response = {
+    statusCode: 200,
+    body: '{"MessageId":"test-message-id-123"}',
+    headers: {},
+  };
+
+  const messageId = extractMessageId(response);
+  assert.equal(messageId, 'test-message-id-123');
+});
+
+test('SesTransport extractMessageId handles header fallback', () => {
+  const config = {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  };
+
+  const transport = new SesTransport(config);
+
+  const extractMessageId = transport.extractMessageId.bind(transport);
+
+  const response = {
+    statusCode: 200,
+    body: '',
+    headers: { 'x-amzn-requestid': 'header-request-id-456' },
+  };
+
+  const messageId = extractMessageId(response);
+  assert.equal(messageId, 'header-request-id-456');
+});
+
+test('SesTransport extractMessageId generates synthetic ID', () => {
+  const config = {
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'test-key',
+      secretAccessKey: 'test-secret',
+    },
+  };
+
+  const transport = new SesTransport(config);
+
+  const extractMessageId = transport.extractMessageId.bind(transport);
+
+  const response = {
+    statusCode: 200,
+    body: '',
+    headers: {},
+  };
+
+  const messageId = extractMessageId(response);
+  assert.ok(messageId.startsWith('ses-'));
+  assert.ok(messageId.length > 10);
+});
+
+test('SesTransport returns structured API failures', async () => {
+  const originalFetch = globalThis.fetch;
+  try {
+    globalThis.fetch = () =>
+      Promise.resolve(
+        new Response(JSON.stringify({ message: 'Too Many Requests' }), {
+          status: 429,
+          headers: { 'Retry-After': '60' },
+        }),
+      );
+
+    const transport = new SesTransport({
+      authentication: {
+        type: 'credentials',
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+      },
+      retries: 0,
+    });
+
+    const receipt = await transport.send(
+      createMessage({
+        from: 'sender@example.com',
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: { text: 'Hello World!' },
+      }),
+    );
+
+    assert.ok(!receipt.successful);
+    if (!receipt.successful) {
+      assert.equal(receipt.provider, 'ses');
+      assert.ok(receipt.retryable);
+      assert.equal(receipt.attempts, 1);
+      assert.equal(receipt.errors?.[0]?.category, 'rate-limit');
+      assert.equal(receipt.errors?.[0]?.statusCode, 429);
+      assert.equal(receipt.errors?.[0]?.retryAfterMilliseconds, 60_000);
+    }
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('SesTransport preserves provider error details', async () => {
+  const originalFetch = globalThis.fetch;
+  const providerErrors = [
+    {
+      message: 'Email address is not verified',
+      field: 'Destination.ToAddresses.member.1',
+      code: 'MessageRejected',
+    },
+  ];
+
+  try {
+    globalThis.fetch = () =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            message: 'Email address is not verified',
+            errors: providerErrors,
+          }),
+          { status: 400 },
+        ),
+      );
+
+    const transport = new SesTransport({
+      authentication: {
+        type: 'credentials',
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+      },
+      retries: 0,
+    });
+
+    const receipt = await transport.send(
+      createMessage({
+        from: 'sender@example.com',
+        to: 'recipient@example.com',
+        subject: 'Test Subject',
+        content: { text: 'Hello World!' },
+      }),
+    );
+
+    assert.ok(!receipt.successful);
+    if (!receipt.successful) {
+      assert.deepEqual(receipt.errors?.[0]?.providerDetails, providerErrors);
+    }
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
diff --git a/tests/unit/ses.test.js b/tests/unit/ses.test.js
new file mode 100644
index 0000000..3d853a8
--- /dev/null
+++ b/tests/unit/ses.test.js
@@ -0,0 +1,144 @@
+// Paths of the ported SES transport (src/ses/) that upstream reaches only
+// through its e2e suite: session credentials, HTTP and network failures,
+// timeouts, aborts and attachment defaults, all against a stubbed fetch.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { SesTransport } = require('../../src/ses/index.js');
+
+const message = (extra = {}) =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+    ...extra,
+  });
+const authentication = { type: 'credentials', accessKeyId: 'AKID', secretAccessKey: 'secret' };
+
+const withFetch = async (t, handler) => {
+  t.mock.method(globalThis, 'fetch', handler);
+};
+
+test('SES: session credentials and custom headers are signed', async (t) => {
+  let request;
+  await withFetch(t, async (url, init) => {
+    request = new Headers(init.headers);
+    return new Response('{"MessageId":"m1"}', { status: 200 });
+  });
+  const transport = new SesTransport({
+    authentication: { type: 'session', accessKeyId: 'A', secretAccessKey: 'S', sessionToken: 'T' },
+    headers: { 'X-Custom': 'yes' },
+    retries: 0,
+  });
+  assert.deepStrictEqual(await transport.send(message()), {
+    successful: true,
+    messageId: 'm1',
+    provider: 'ses',
+  });
+  assert.strictEqual(request.get('x-amz-security-token'), 'T');
+  assert.strictEqual(request.get('x-custom'), 'yes');
+  assert.match(request.get('authorization'), /SignedHeaders=host;x-amz-date;x-amz-security-token/);
+});
+
+test('SES: an unknown authentication type fails the send', async () => {
+  const transport = new SesTransport({ authentication: { type: 'role' }, retries: 0 });
+  const receipt = await transport.send(message());
+  assert.strictEqual(receipt.successful, false);
+  assert.deepStrictEqual(receipt.errorMessages, ['Unsupported authentication type: role']);
+});
+
+test('SES: HTTP and network failures become failed receipts', async (t) => {
+  const cases = [
+    [() => new Response('Internal oops', { status: 500 }), 'Internal oops', 'server-error'],
+    [() => new Response('', { status: 500 }), 'HTTP 500', 'server-error'],
+    [
+      () => {
+        throw new TypeError('fetch failed');
+      },
+      'fetch failed',
+      'network',
+    ],
+  ];
+  for (const [respond, expected, category] of cases) {
+    t.mock.restoreAll();
+    await withFetch(t, async () => respond());
+    const receipt = await new SesTransport({ authentication, retries: 0 }).send(message());
+    assert.deepStrictEqual(receipt.errorMessages, [expected]);
+    assert.strictEqual(receipt.errors[0].category, category);
+  }
+});
+
+test('SES: a request over the timeout fails, and an abort between retries rejects', async (t) => {
+  await withFetch(
+    t,
+    (url, init) =>
+      new Promise((resolve, reject) => {
+        init.signal.addEventListener('abort', () => reject(init.signal.reason));
+      }),
+  );
+  const slow = await new SesTransport({ authentication, retries: 0, timeout: 20 }).send(message());
+  assert.deepStrictEqual(slow.errorMessages, ['SES API request timed out after 20 ms.']);
+
+  t.mock.restoreAll();
+  await withFetch(t, async () => new Response('', { status: 500 }));
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), 30);
+  await assert.rejects(
+    new SesTransport({ authentication, retries: 1 }).send(message(), {
+      signal: controller.signal,
+    }),
+    { name: 'AbortError' },
+  );
+});
+
+test('SES: a 200 without JSON gets a generated message id', async (t) => {
+  await withFetch(t, async () => new Response('not json', { status: 200 }));
+  const receipt = await new SesTransport({ authentication, retries: 0 }).send(message());
+  assert.strictEqual(receipt.successful, true);
+  assert.match(receipt.messageId, /^ses-\d+-\w+$/);
+});
+
+test('SES: an inline attachment without a type is sent as INLINE octet-stream', async (t) => {
+  let body;
+  await withFetch(t, async (url, init) => {
+    body = JSON.parse(init.body);
+    return new Response('{"MessageId":"m"}');
+  });
+  const attachments = [
+    {
+      inline: true,
+      filename: 'a.png',
+      content: new Uint8Array([1]),
+      contentType: '',
+      contentId: 'logo',
+    },
+  ];
+  await new SesTransport({ authentication, retries: 0 }).send(message({ attachments }));
+  assert.deepStrictEqual(body.Content.Simple.Attachments, [
+    {
+      FileName: 'a.png',
+      ContentType: 'application/octet-stream',
+      ContentDisposition: 'INLINE',
+      ContentTransferEncoding: 'BASE64',
+      RawContent: 'AQ==',
+      ContentId: 'logo',
+    },
+  ]);
+});
+
+test('SES: sendMany reads an async iterable', async (t) => {
+  let calls = 0;
+  await withFetch(t, async () => new Response(`{"MessageId":"m${++calls}"}`));
+  const messages = async function* () {
+    yield message();
+    yield message();
+  };
+  const receipts = [];
+  for await (const receipt of new SesTransport({ authentication, retries: 0 }).sendMany(
+    messages(),
+  )) {
+    receipts.push(receipt.messageId);
+  }
+  assert.deepStrictEqual(receipts.sort(), ['m1', 'm2']);
+});

From 0d83f7a3457c41f1cfbcef1e67cb36e3d28c4e73 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:08:19 +0300
Subject: [PATCH 007/158] feat(resend): port the Resend transport from upyo
 0.7.0

./resend exports ResendTransport: the Resend REST API over fetch, with
attachments, tags, threading and custom headers, an idempotency key per
message, retries and a request timeout, and sendMany through the batch API
(in chunks of 100) when no message has attachments, tags or a calendar
part. ResendApiError stays a type only, as upstream exports it.

Upstream's unit suites are ported, the e2e suite goes to tests/e2e, and its
two tests of a runtime without AbortSignal.any are left out (Node 22 always
has it). tests/unit/resend.test.js covers what upstream reached only end to
end: a 200 that is not JSON, the timeout, chunked and failed batches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                    |   2 +-
 package.json                                |   4 +
 src/resend/config.js                        |  26 +
 src/resend/http-client.js                   | 248 +++++++
 src/resend/index.d.ts                       | 281 +++++++
 src/resend/index.js                         |  35 +
 src/resend/message-converter.js             | 289 ++++++++
 src/resend/resend-transport.js              | 344 +++++++++
 tests/e2e/resend-transport.e2e.test.js      | 464 ++++++++++++
 tests/helpers/resend/test-config.js         |  39 +
 tests/types/resend.test-d.ts                |  26 +
 tests/unit/resend-config.test.js            |  60 ++
 tests/unit/resend-message-converter.test.js | 549 ++++++++++++++
 tests/unit/resend-transport.test.js         | 779 ++++++++++++++++++++
 tests/unit/resend.test.js                   |  82 +++
 15 files changed, 3227 insertions(+), 1 deletion(-)
 create mode 100644 src/resend/config.js
 create mode 100644 src/resend/http-client.js
 create mode 100644 src/resend/index.d.ts
 create mode 100644 src/resend/index.js
 create mode 100644 src/resend/message-converter.js
 create mode 100644 src/resend/resend-transport.js
 create mode 100644 tests/e2e/resend-transport.e2e.test.js
 create mode 100644 tests/helpers/resend/test-config.js
 create mode 100644 tests/types/resend.test-d.ts
 create mode 100644 tests/unit/resend-config.test.js
 create mode 100644 tests/unit/resend-message-converter.test.js
 create mode 100644 tests/unit/resend-transport.test.js
 create mode 100644 tests/unit/resend.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1175788..131521d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index a6e7d61..2beb038 100644
--- a/package.json
+++ b/package.json
@@ -36,6 +36,10 @@
       "types": "./src/ses/index.d.ts",
       "default": "./src/ses/index.js"
     },
+    "./resend": {
+      "types": "./src/resend/index.d.ts",
+      "default": "./src/resend/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
diff --git a/src/resend/config.js b/src/resend/config.js
new file mode 100644
index 0000000..02d7853
--- /dev/null
+++ b/src/resend/config.js
@@ -0,0 +1,26 @@
+// Ported from upyo v0.7.0 (packages/resend/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved Resend configuration by applying default values to optional fields.
+ *
+ * This function takes a partial Resend configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the Resend transport.
+ *
+ * @param config - The Resend configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ * @internal
+ */
+const createResendConfig = (config) => {
+  return {
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl ?? 'https://api.resend.com',
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    validateSsl: config.validateSsl ?? true,
+    headers: config.headers ?? {},
+  };
+};
+
+module.exports = { createResendConfig };
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
new file mode 100644
index 0000000..b8d65fc
--- /dev/null
+++ b/src/resend/http-client.js
@@ -0,0 +1,248 @@
+// Ported from upyo v0.7.0 (packages/resend/src/http-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { parseRetryAfter } = require('../core/receipt.js');
+
+/**
+ * Error thrown when a Resend API request fails.
+ */
+class ResendApiError extends Error {
+  /**
+   * HTTP status code returned by Resend, if the request reached the API.
+   */
+  statusCode;
+
+  /**
+   * Retry delay from Resend's `Retry-After` response header.
+   */
+  retryAfterMilliseconds;
+
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  attempts;
+
+  /**
+   * Creates a Resend API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code returned by Resend.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(message, statusCode, retryAfterMilliseconds, attempts) {
+    super(message);
+    this.name = 'ResendApiError';
+    this.statusCode = statusCode;
+    this.retryAfterMilliseconds = retryAfterMilliseconds;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * HTTP client wrapper for Resend API requests.
+ *
+ * This class handles authentication, request formatting, error handling,
+ * and retry logic for Resend API calls.
+ */
+class ResendHttpClient {
+  config;
+
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Sends a single message via Resend API.
+   *
+   * @param messageData The JSON data to send to Resend.
+   * @param signal Optional AbortSignal for cancellation.
+   * @param idempotencyKey Optional idempotency key for request deduplication.
+   * @returns Promise that resolves to the Resend response.
+   */
+  sendMessage(messageData, signal, idempotencyKey) {
+    const url = `${this.config.baseUrl}/emails`;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+
+    if (idempotencyKey) {
+      headers['Idempotency-Key'] = idempotencyKey;
+    }
+
+    return this.makeRequest(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(messageData),
+      signal,
+    });
+  }
+
+  /**
+   * Sends multiple messages via Resend batch API.
+   *
+   * @param messagesData Array of message data objects to send.
+   * @param signal Optional AbortSignal for cancellation.
+   * @param idempotencyKey Optional idempotency key for request deduplication.
+   * @returns Promise that resolves to the Resend batch response.
+   */
+  sendBatch(messagesData, signal, idempotencyKey) {
+    const url = `${this.config.baseUrl}/emails/batch`;
+    const headers = {
+      'Content-Type': 'application/json',
+    };
+
+    if (idempotencyKey) {
+      headers['Idempotency-Key'] = idempotencyKey;
+    }
+
+    return this.makeRequest(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(messagesData),
+      signal,
+    });
+  }
+
+  /**
+   * Makes an HTTP request to Resend API with retry logic.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the parsed response.
+   */
+  async makeRequest(url, options) {
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      try {
+        const response = await this.fetchWithAuth(url, options);
+        const text = await response.text();
+
+        if (!response.ok) {
+          let errorMessage;
+          try {
+            const errorBody = JSON.parse(text);
+            errorMessage = errorBody.message;
+          } catch {
+            // Ignore if JSON parsing fails, as the body may be non-JSON
+          }
+
+          const parsedErrorMessage = errorMessage === '' ? undefined : errorMessage;
+          const responseMessage = truncateErrorBody(text);
+          const fallbackMessage = responseMessage === '' ? undefined : responseMessage;
+
+          throw new ResendApiError(
+            parsedErrorMessage ?? fallbackMessage ?? `HTTP ${response.status}`,
+            response.status,
+            parseRetryAfter(response.headers.get('Retry-After')),
+            attempt + 1,
+          );
+        }
+
+        try {
+          return JSON.parse(text);
+        } catch (parseError) {
+          // oxlint-disable-next-line preserve-caught-error -- upstream
+          throw new Error(
+            `Invalid JSON response from Resend API: ${
+              parseError instanceof Error ? parseError.message : String(parseError)
+            }`,
+          );
+        }
+      } catch (error) {
+        if (isCallerAbort(error, options.signal)) {
+          throw error;
+        }
+
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        // Don't retry on client errors (4xx) or AbortError
+        if (
+          error instanceof ResendApiError &&
+          error.statusCode !== undefined &&
+          error.statusCode >= 400 &&
+          error.statusCode < 500
+        ) {
+          throw error;
+        }
+
+        if (error instanceof Error && error.name === 'AbortError') {
+          throw error;
+        }
+
+        // If this is the last attempt, throw the error
+        if (attempt === this.config.retries) {
+          if (lastError instanceof ResendApiError) {
+            throw lastError;
+          }
+          throw new ResendApiError(lastError.message, undefined, undefined, attempt + 1);
+        }
+
+        // Wait before retrying with exponential backoff
+        const backoffMs = Math.min(1000 * Math.pow(2, attempt), 10000);
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      }
+    }
+
+    throw lastError || new Error('Request failed after all retry attempts');
+  }
+
+  /**
+   * Makes a fetch request with authentication headers.
+   *
+   * @param url The URL to fetch.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the Response.
+   */
+  async fetchWithAuth(url, options) {
+    const headers = new Headers(options.headers);
+
+    // Add authentication
+    headers.set('Authorization', `Bearer ${this.config.apiKey}`);
+
+    // Add custom headers from config
+    for (const [key, value] of Object.entries(this.config.headers)) {
+      headers.set(key, value);
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    const combinedSignal = combineSignals(controller.signal, options.signal);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers,
+        signal: combinedSignal.signal,
+      });
+
+      return response;
+    } catch (error) {
+      if (isAbortError(error) && controller.signal.aborted && !options.signal?.aborted) {
+        // oxlint-disable-next-line preserve-caught-error -- upstream
+        throw new Error(`Resend API request timed out after ${this.config.timeout} ms.`);
+      }
+      throw error;
+    } finally {
+      combinedSignal.cleanup();
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+const truncateErrorBody = (text) => {
+  return text.length > 500 ? `${text.slice(0, 500)}...` : text;
+};
+
+module.exports = { ResendApiError, ResendHttpClient };
diff --git a/src/resend/index.d.ts b/src/resend/index.d.ts
new file mode 100644
index 0000000..f02c65b
--- /dev/null
+++ b/src/resend/index.d.ts
@@ -0,0 +1,281 @@
+// Types ported from upyo v0.7.0 (packages/resend/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Configuration interface for Resend transport connection settings.
+ *
+ * This interface defines all available options for configuring a Resend
+ * API connection including authentication and HTTP options.
+ *
+ * @example
+ * ```typescript
+ * const config: ResendConfig = {
+ *   apiKey: 'your-api-key',
+ *   timeout: 30000,
+ *   retries: 3
+ * };
+ * ```
+ */
+export interface ResendConfig {
+  /**
+   * Your Resend API key.
+   *
+   * You can find your API key in the Resend dashboard at https://resend.com/api-keys.
+   * It should start with 're_' for API keys.
+   */
+  readonly apiKey: string;
+  /**
+   * Base URL for the Resend API.
+   *
+   * @default "https://api.resend.com"
+   */
+  readonly baseUrl?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   *
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Whether to validate SSL certificates.
+   *
+   * @default true
+   */
+  readonly validateSsl?: boolean;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+}
+/**
+ * Resolved Resend configuration with all optional fields filled with default values.
+ *
+ * This type represents the final configuration after applying defaults,
+ * used internally by the Resend transport implementation.
+ */
+export type ResolvedResendConfig = Required<ResendConfig>;
+/**
+ * Creates a resolved Resend configuration by applying default values to optional fields.
+ *
+ * This function takes a partial Resend configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the Resend transport.
+ *
+ * @param config - The Resend configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ * @internal
+ */
+
+/**
+ * Resend transport implementation for sending emails via Resend API.
+ *
+ * This transport provides efficient email delivery using Resend's HTTP API,
+ * with support for authentication, retry logic, batch sending capabilities,
+ * and idempotency for reliable delivery.
+ *
+ * @example
+ * ```typescript
+ * import { ResendTransport } from '@alexify/mailer/resend';
+ *
+ * const transport = new ResendTransport({
+ *   apiKey: 'your-resend-api-key',
+ *   timeout: 30000,
+ *   retries: 3
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
+ * ```
+ */
+export declare class ResendTransport implements Transport<'resend'> {
+  readonly id = 'resend';
+  /**
+   * The resolved Resend configuration used by this transport.
+   */
+  config: ResolvedResendConfig;
+  /**
+   * Creates a new Resend transport instance.
+   *
+   * @param config Resend configuration including API key and options.
+   */
+  constructor(config: ResendConfig);
+  /**
+   * Sends a single email message via Resend API.
+   *
+   * This method converts the message to Resend format, makes an HTTP request
+   * to the Resend API with automatic idempotency key generation, and returns
+   * a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent with ID:', receipt.messageId);
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'resend'>>;
+  /**
+   * Sends multiple email messages efficiently via Resend API.
+   *
+   * This method intelligently chooses between single requests and batch API
+   * based on message count and features used. For optimal performance:
+   * - Uses batch API for ≤100 messages without attachments or tags
+   * - Falls back to individual requests for messages with unsupported features
+   * - Chunks large batches (>100) into multiple batch requests
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'resend'>>;
+}
+
+/**
+ * Response from Resend API for sending a single message.
+ */
+export interface ResendResponse {
+  /**
+   * The message ID returned by Resend.
+   */
+  id: string;
+}
+/**
+ * Response from Resend API for sending batch messages.
+ */
+export interface ResendBatchResponse {
+  /**
+   * Array of message objects with IDs.
+   */
+  data: Array<{
+    id: string;
+  }>;
+}
+/**
+ * Error response from Resend API.
+ */
+export interface ResendError {
+  /**
+   * Error message from Resend.
+   */
+  message: string;
+  /**
+   * Error name/type.
+   */
+  name?: string;
+}
+/**
+ * Error thrown when a Resend API request fails.
+ */
+// A type only, as upstream exports it: the class is not exported at runtime.
+declare class ResendApiError extends Error {
+  /**
+   * HTTP status code returned by Resend, if the request reached the API.
+   */
+  readonly statusCode?: number;
+  /**
+   * Retry delay from Resend's `Retry-After` response header.
+   */
+  readonly retryAfterMilliseconds?: number;
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * Creates a Resend API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code returned by Resend.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(
+    message: string,
+    statusCode?: number,
+    retryAfterMilliseconds?: number,
+    attempts?: number,
+  );
+}
+/**
+ * HTTP client wrapper for Resend API requests.
+ *
+ * This class handles authentication, request formatting, error handling,
+ * and retry logic for Resend API calls.
+ */
+
+export type { ResendApiError };
diff --git a/src/resend/index.js b/src/resend/index.js
new file mode 100644
index 0000000..2f02234
--- /dev/null
+++ b/src/resend/index.js
@@ -0,0 +1,35 @@
+// Ported from upyo v0.7.0 (packages/resend/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * @fileoverview Resend transport for Upyo email library.
+ *
+ * This module provides a transport implementation for sending emails through
+ * Resend's HTTP API. It supports single messages, batch sending, attachments,
+ * and all standard email features with automatic retry logic and idempotency.
+ *
+ * @example
+ * ```typescript
+ * import { ResendTransport } from '@alexify/mailer/resend';
+ *
+ * const transport = new ResendTransport({
+ *   apiKey: 'your-resend-api-key'
+ * });
+ *
+ * // Send a single message
+ * const receipt = await transport.send({
+ *   sender: { address: 'hello@example.com' },
+ *   recipients: [{ address: 'user@example.com' }],
+ *   subject: 'Welcome!',
+ *   content: { html: '<h1>Hello!</h1>' }
+ * });
+ *
+ * if (receipt.successful) {
+ *   console.log('Message sent:', receipt.messageId);
+ * }
+ * ```
+ */
+
+const { ResendTransport } = require('./resend-transport.js');
+
+module.exports = { ResendTransport };
diff --git a/src/resend/message-converter.js b/src/resend/message-converter.js
new file mode 100644
index 0000000..cd64332
--- /dev/null
+++ b/src/resend/message-converter.js
@@ -0,0 +1,289 @@
+// Ported from upyo v0.7.0 (packages/resend/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createCalendarAttachment } = require('../core/calendar.js');
+const { combineSignals } = require('../core/abort-signal.js');
+const { readAttachmentContent } = require('../core/attachment.js');
+const { resolveThreadingHeaders } = require('../core/message-id.js');
+
+/**
+ * Converts a Upyo Message to Resend API JSON format.
+ *
+ * This function transforms the standardized Upyo message format into
+ * the specific format expected by the Resend API.
+ *
+ * @param message - The Upyo message to convert
+ * @param config - The resolved Resend configuration
+ * @param options - Optional conversion options
+ * @returns JSON object ready for Resend API submission
+ * @throws {TypeError} If the message carries an invalid message identifier.
+ *
+ * @example
+ * ```typescript
+ * const emailData = await convertMessage(message, config);
+ * const response = await fetch(url, {
+ *   method: 'POST',
+ *   body: JSON.stringify(emailData),
+ *   headers: { 'Content-Type': 'application/json' }
+ * });
+ * ```
+ */
+const convertMessage = async (message, _config, options = {}) => {
+  // A transport that cannot compose a `text/calendar` alternative carries the
+  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
+  // own files so that a client looking for the first calendar part finds it.
+  const attachments =
+    message.calendar == null
+      ? message.attachments
+      : [createCalendarAttachment(message.calendar), ...message.attachments];
+
+  const emailData = {
+    from: formatAddress(message.sender),
+    to:
+      message.recipients.length === 1
+        ? formatAddress(message.recipients[0])
+        : message.recipients.map(formatAddress),
+    subject: message.subject,
+  };
+
+  // CC recipients
+  if (message.ccRecipients.length > 0) {
+    emailData.cc = message.ccRecipients.map(formatAddress);
+  }
+
+  // BCC recipients
+  if (message.bccRecipients.length > 0) {
+    emailData.bcc = message.bccRecipients.map(formatAddress);
+  }
+
+  // Reply-to
+  if (message.replyRecipients.length > 0) {
+    // Resend supports only one reply-to address, so we take the first one
+    emailData.reply_to = formatAddress(message.replyRecipients[0]);
+  }
+
+  // Content
+  if ('html' in message.content) {
+    emailData.html = message.content.html;
+    if (message.content.text) {
+      emailData.text = message.content.text;
+    }
+  } else {
+    emailData.text = message.content.text;
+  }
+
+  // Attachments
+  if (attachments.length > 0) {
+    const cancellation = new AbortController();
+    const combined = combineSignals(cancellation.signal, options.signal);
+    try {
+      emailData.attachments = await Promise.all(
+        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
+      );
+    } finally {
+      cancellation.abort();
+      combined.cleanup();
+    }
+  }
+
+  // Tags - Resend uses different format than Upyo
+  if (message.tags.length > 0) {
+    emailData.tags = message.tags.map((tag, index) => ({
+      name: `tag${index + 1}`, // Resend requires name-value pairs
+      value: tag,
+    }));
+  }
+
+  // Custom headers
+  const headers = {};
+
+  // Priority
+  if (message.priority !== 'normal') {
+    const priorityMap = {
+      high: '1',
+      normal: '3',
+      low: '5',
+    };
+    headers['X-Priority'] = priorityMap[message.priority];
+  }
+
+  // Custom headers from message
+  // Reply threading comes from the typed fields when the message defines them,
+  // and from a custom header otherwise.  A field the message owns but left
+  // empty writes nothing, which is how a caller drops an inherited header.
+  const threading = resolveThreadingHeaders(message);
+  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+
+  for (const [key, value] of message.headers.entries()) {
+    // Skip standard headers that are handled separately
+    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
+      headers[key] = value;
+    }
+  }
+  for (const [name, value] of threading) {
+    if (value != null) headers[name] = value;
+  }
+
+  if (Object.keys(headers).length > 0) {
+    emailData.headers = headers;
+  }
+
+  // Scheduled sending
+  if (options.scheduledAt) {
+    emailData.scheduled_at = options.scheduledAt.toISOString();
+  }
+
+  return emailData;
+};
+
+/**
+ * Converts multiple Upyo Messages to Resend batch API format.
+ *
+ * This function handles the batch conversion with proper validation
+ * for Resend's batch API limitations.
+ *
+ * @param messages - Array of Upyo messages to convert
+ * @param config - The resolved Resend configuration
+ * @returns Array of JSON objects ready for Resend batch API
+ * @throws {TypeError} If a message carries an invalid message identifier.
+ */
+const convertMessagesBatch = async (messages, _config) => {
+  // Resend batch API limitations
+  if (messages.length > 100) {
+    throw new Error('Resend batch API supports maximum 100 emails per request');
+  }
+
+  // Check for unsupported features in batch mode.  A calendar is checked here
+  // too: it becomes an attachment during conversion, so reading
+  // `message.attachments` alone would let one through the batch API that
+  // forbids attachments.
+  for (const message of messages) {
+    if (message.attachments.length > 0 || message.calendar != null) {
+      throw new Error('Attachments are not supported in Resend batch API');
+    }
+    if (message.tags.length > 0) {
+      throw new Error('Tags are not supported in Resend batch API');
+    }
+  }
+
+  const batchData = await Promise.all(messages.map((message) => convertMessage(message, _config)));
+
+  return batchData;
+};
+
+/**
+ * Formats an Address object into a string suitable for Resend API.
+ *
+ * @param address - The address to format
+ * @returns Formatted address string
+ */
+const formatAddress = (address) => {
+  if (address.name) {
+    // If the name contains special characters, quote it
+    const name =
+      address.name.includes('"') ||
+      address.name.includes(',') ||
+      address.name.includes('<') ||
+      address.name.includes('>')
+        ? `"${address.name.replace(/"/g, '\\"')}"`
+        : address.name;
+    return `${name} <${address.address}>`;
+  }
+  return address.address;
+};
+
+/**
+ * Converts a Upyo Attachment to Resend attachment format.
+ *
+ * @param attachment - The Upyo attachment to convert
+ * @returns Resend attachment object
+ */
+const convertAttachment = async (attachment, signal) => {
+  const content = await readAttachmentContent(attachment.content, signal);
+  const resendAttachment = {
+    filename: attachment.filename,
+    content: await uint8ArrayToBase64(content),
+  };
+
+  if (attachment.contentType) {
+    resendAttachment.content_type = attachment.contentType;
+  }
+
+  return resendAttachment;
+};
+
+/**
+ * Converts a Uint8Array to base64 string using pure JavaScript implementation.
+ * This avoids deprecated APIs like btoa() and Node.js-specific Buffer.
+ *
+ * @param bytes - The Uint8Array to convert
+ * @returns Base64 encoded string
+ */
+const uint8ArrayToBase64 = (bytes) => {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let result = '';
+  let i = 0;
+
+  while (i < bytes.length) {
+    const a = bytes[i++];
+    const b = i < bytes.length ? bytes[i++] : 0;
+    const c = i < bytes.length ? bytes[i++] : 0;
+
+    const bitmap = (a << 16) | (b << 8) | c;
+
+    result +=
+      chars.charAt((bitmap >> 18) & 63) +
+      chars.charAt((bitmap >> 12) & 63) +
+      chars.charAt((bitmap >> 6) & 63) +
+      chars.charAt(bitmap & 63);
+  }
+
+  // Add padding
+  const remainder = bytes.length % 3;
+  if (remainder !== 0) {
+    const padding = 3 - remainder;
+    result = result.slice(0, -padding) + '='.repeat(padding);
+  }
+
+  return result;
+};
+
+/**
+ * Checks if a header is a standard email header that should not be prefixed.
+ *
+ * @param headerName - The header name to check
+ * @returns True if the header is a standard header
+ */
+const isStandardHeader = (headerName) => {
+  const standardHeaders = new Set([
+    'from',
+    'to',
+    'cc',
+    'bcc',
+    'reply-to',
+    'subject',
+    'content-type',
+    'content-transfer-encoding',
+    'mime-version',
+    'date',
+    'message-id',
+  ]);
+
+  return standardHeaders.has(headerName.toLowerCase());
+};
+
+/**
+ * Generates a random idempotency key for request deduplication.
+ *
+ * @returns A unique string suitable for use as an idempotency key
+ */
+const generateIdempotencyKey = () => {
+  // Generate a UUID-like string
+  const timestamp = Date.now().toString(36);
+  const random1 = Math.random().toString(36).substring(2, 15);
+  const random2 = Math.random().toString(36).substring(2, 15);
+
+  return `${timestamp}-${random1}${random2}`;
+};
+
+module.exports = { convertMessage, convertMessagesBatch, generateIdempotencyKey };
diff --git a/src/resend/resend-transport.js b/src/resend/resend-transport.js
new file mode 100644
index 0000000..1d6cae8
--- /dev/null
+++ b/src/resend/resend-transport.js
@@ -0,0 +1,344 @@
+// Ported from upyo v0.7.0 (packages/resend/src/resend-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createResendConfig } = require('./config.js');
+const { ResendApiError, ResendHttpClient } = require('./http-client.js');
+const {
+  convertMessage,
+  convertMessagesBatch,
+  generateIdempotencyKey,
+} = require('./message-converter.js');
+
+/**
+ * Resend transport implementation for sending emails via Resend API.
+ *
+ * This transport provides efficient email delivery using Resend's HTTP API,
+ * with support for authentication, retry logic, batch sending capabilities,
+ * and idempotency for reliable delivery.
+ *
+ * @example
+ * ```typescript
+ * import { ResendTransport } from '@alexify/mailer/resend';
+ *
+ * const transport = new ResendTransport({
+ *   apiKey: 'your-resend-api-key',
+ *   timeout: 30000,
+ *   retries: 3
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
+ * ```
+ */
+class ResendTransport {
+  id = 'resend';
+
+  /**
+   * The resolved Resend configuration used by this transport.
+   */
+  config;
+
+  httpClient;
+
+  /**
+   * Creates a new Resend transport instance.
+   *
+   * @param config Resend configuration including API key and options.
+   */
+  constructor(config) {
+    this.config = createResendConfig(config);
+    this.httpClient = new ResendHttpClient(this.config);
+  }
+
+  /**
+   * Sends a single email message via Resend API.
+   *
+   * This method converts the message to Resend format, makes an HTTP request
+   * to the Resend API with automatic idempotency key generation, and returns
+   * a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent with ID:', receipt.messageId);
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  async send(message, options) {
+    try {
+      options?.signal?.throwIfAborted();
+
+      // Use provided idempotency key or generate one for reliable delivery
+      const idempotencyKey = message.idempotencyKey ?? generateIdempotencyKey();
+
+      const emailData = await convertMessage(message, this.config, {
+        signal: options?.signal,
+      });
+
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendMessage(
+        emailData,
+        options?.signal,
+        idempotencyKey,
+      );
+
+      return {
+        successful: true,
+        messageId: response.id,
+        provider: 'resend',
+      };
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) {
+        throw error;
+      }
+
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      return createResendFailure(errorMessage, error);
+    }
+  }
+
+  /**
+   * Sends multiple email messages efficiently via Resend API.
+   *
+   * This method intelligently chooses between single requests and batch API
+   * based on message count and features used. For optimal performance:
+   * - Uses batch API for ≤100 messages without attachments or tags
+   * - Falls back to individual requests for messages with unsupported features
+   * - Chunks large batches (>100) into multiple batch requests
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    const isAsyncIterable = Symbol.asyncIterator in messages;
+
+    // Convert to array for batch processing optimization
+    const messageArray = [];
+
+    if (isAsyncIterable) {
+      for await (const message of messages) {
+        options?.signal?.throwIfAborted();
+        messageArray.push(message);
+      }
+    } else {
+      for (const message of messages) {
+        options?.signal?.throwIfAborted();
+        messageArray.push(message);
+      }
+    }
+
+    // Optimize sending strategy based on message characteristics
+    yield* this.sendManyOptimized(messageArray, options);
+  }
+
+  /**
+   * Optimized batch sending that chooses the best strategy based on message features.
+   *
+   * @param messages Array of messages to send
+   * @param options Transport options
+   * @returns Async iterable of receipts
+   */
+  async *sendManyOptimized(messages, options) {
+    if (messages.length === 0) {
+      return;
+    }
+
+    // Check if messages are suitable for batch API
+    const canUseBatch = this.canUseBatchApi(messages);
+
+    if (canUseBatch && messages.length <= 100) {
+      // Use batch API for optimal performance
+      yield* this.sendBatch(messages, options);
+    } else if (canUseBatch && messages.length > 100) {
+      // Chunk large batches into multiple batch requests
+      const chunks = this.chunkArray(messages, 100);
+      for (const chunk of chunks) {
+        options?.signal?.throwIfAborted();
+        yield* this.sendBatch(chunk, options);
+      }
+    } else {
+      // Fall back to individual requests for messages with unsupported features
+      for (const message of messages) {
+        options?.signal?.throwIfAborted();
+        yield await this.send(message, options);
+      }
+    }
+  }
+
+  /**
+   * Sends a batch of messages using Resend's batch API.
+   *
+   * @param messages Array of messages (≤100)
+   * @param options Transport options
+   * @returns Async iterable of receipts
+   */
+  async *sendBatch(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    try {
+      // Use first message's idempotency key or generate one for reliable delivery
+      const idempotencyKey = messages[0]?.idempotencyKey ?? generateIdempotencyKey();
+
+      const batchData = await convertMessagesBatch(messages, this.config);
+
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendBatch(batchData, options?.signal, idempotencyKey);
+
+      // Yield receipt for each message
+      for (const result of response.data) {
+        yield {
+          successful: true,
+          messageId: result.id,
+          provider: 'resend',
+        };
+      }
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) {
+        throw error;
+      }
+
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      // If batch fails, yield error receipt for each message
+      for (let i = 0; i < messages.length; i++) {
+        yield createResendFailure(errorMessage, error);
+      }
+    }
+  }
+
+  /**
+   * Checks if messages can use Resend's batch API.
+   *
+   * Batch API limitations:
+   * - No attachments, and so no calendar
+   * - No tags
+   * - No scheduled sending
+   *
+   * @param messages Array of messages to check
+   * @returns True if all messages are suitable for batch API
+   */
+  canUseBatchApi(messages) {
+    return messages.every(
+      (message) =>
+        message.attachments.length === 0 &&
+        message.tags.length === 0 &&
+        // A calendar becomes an attachment during conversion, which the batch
+        // API forbids, and `sendBatch()` fails a whole chunk on one conversion
+        // error.  Sending these individually keeps the failure — or the success
+        // — confined to the message it belongs to.
+        message.calendar == null,
+    );
+  }
+
+  /**
+   * Splits an array into chunks of specified size.
+   *
+   * @param array Array to chunk
+   * @param size Chunk size
+   * @returns Array of chunks
+   */
+  chunkArray(array, size) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+      chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+  }
+}
+
+const createResendFailure = (message, error) => {
+  if (error instanceof ResendApiError) {
+    return createFailedReceipt(message, {
+      provider: 'resend',
+      statusCode: error.statusCode,
+      retryAfterMilliseconds: error.retryAfterMilliseconds,
+      attempts: error.attempts,
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'resend',
+  });
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+module.exports = { ResendTransport };
diff --git a/tests/e2e/resend-transport.e2e.test.js b/tests/e2e/resend-transport.e2e.test.js
new file mode 100644
index 0000000..ccdc728
--- /dev/null
+++ b/tests/e2e/resend-transport.e2e.test.js
@@ -0,0 +1,464 @@
+// Ported from upyo v0.7.0 (packages/resend/src/resend-transport.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../../src/core/receipt.js');
+const { isEmailAddress } = require('../../src/core/address.js');
+const { ResendTransport } = require('../../src/resend/resend-transport.js');
+const { createTestConfig } = require('../helpers/resend/test-config.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+
+// Check if API key is available for E2E tests
+const hasApiKey = () => {
+  try {
+    createTestConfig();
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// Shared test setup outside of describe blocks to avoid parallel execution issues
+let transport;
+let testConfig;
+
+// Check if API key is available and set up transport
+const setupTransport = () => {
+  try {
+    testConfig = createTestConfig();
+    transport = new ResendTransport(testConfig);
+    return true;
+  } catch (_error) {
+    console.warn('Skipping E2E tests: Missing Resend API configuration');
+    return false;
+  }
+};
+
+// Helper function to get test recipient email
+const getTestRecipient = () => {
+  if (testConfig.recipientEmail) {
+    if (!isEmailAddress(testConfig.recipientEmail)) {
+      throw new Error(`Invalid recipient email address: ${testConfig.recipientEmail}`);
+    }
+    console.log(`📧 Using custom recipient: ${testConfig.recipientEmail}`);
+    return testConfig.recipientEmail;
+  }
+
+  // For unverified accounts, we must use the account owner's email
+  console.log('📧 Using account owner email for testing: sweep-squishy-clad@duck.com');
+  return 'sweep-squishy-clad@duck.com';
+};
+
+// Helper function to get test sender email
+const getTestSender = () => {
+  if (testConfig.verifiedDomain) {
+    const senderEmail = `test@${testConfig.verifiedDomain}`;
+    console.log(`📤 Using verified domain sender: ${senderEmail}`);
+    return senderEmail;
+  }
+
+  // Use Resend's test domain for unverified accounts
+  console.log('📤 Using Resend test domain: onboarding@resend.dev');
+  return 'onboarding@resend.dev';
+};
+
+// Check if we have a verified domain for full E2E testing
+const hasVerifiedDomain = () => {
+  return !!testConfig?.verifiedDomain;
+};
+
+// Helper function to add delay between API calls to respect rate limits
+const waitForRateLimit = async () => {
+  // Resend allows 2 requests per second, so wait at least 1000ms between calls to be safe
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+};
+
+describe(
+  'ResendTransport E2E Test 1',
+  {
+    skip: !hasApiKey() || !setupTransport() || !hasVerifiedDomain(),
+  },
+  () => {
+    it('should send and deliver email successfully', async () => {
+      await waitForRateLimit();
+      const recipientEmail = getTestRecipient();
+
+      const message = {
+        sender: {
+          address: getTestSender(),
+          name: 'Upyo Test',
+        },
+        recipients: [
+          {
+            address: recipientEmail,
+            name: 'Test Recipient',
+          },
+        ],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Email from Upyo Resend Transport',
+        content: {
+          html: '<h1>Hello from Upyo!</h1><p>This is a test email sent using the Resend transport.</p>',
+          text: 'Hello from Upyo!\n\nThis is a test email sent using the Resend transport.',
+        },
+        attachments: [],
+        priority: 'normal',
+        tags: ['test', 'upyo'],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      if (acceptDailyQuotaLimit(receipt, 'Simple email')) return;
+
+      if (!receipt.successful) {
+        console.log('❌ First test failed with errors:', receipt.errorMessages);
+      }
+
+      assert.equal(receipt.successful, true);
+      if (receipt.successful) {
+        assert.ok(receipt.messageId);
+        assert.ok(receipt.messageId.length > 0);
+        console.log(`✅ Message sent successfully with ID: ${receipt.messageId}`);
+      }
+
+      // Additional wait after API call
+      await waitForRateLimit();
+    });
+  },
+);
+
+describe(
+  'ResendTransport E2E Test 2',
+  {
+    skip: !hasApiKey() || !setupTransport() || !hasVerifiedDomain(),
+  },
+  () => {
+    it('should send HTML email with text alternative', async () => {
+      await waitForRateLimit();
+      const recipientEmail = getTestRecipient();
+
+      const message = {
+        sender: { address: getTestSender() },
+        recipients: [{ address: recipientEmail }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'HTML Email Test',
+        content: {
+          html: `
+          <html>
+            <body>
+              <h1 style="color: #333;">Welcome to Upyo!</h1>
+              <p>This is an <strong>HTML email</strong> with formatting.</p>
+              <ul>
+                <li>Feature 1</li>
+                <li>Feature 2</li>
+                <li>Feature 3</li>
+              </ul>
+            </body>
+          </html>
+        `,
+          text: 'Welcome to Upyo!\n\nThis is an HTML email with formatting.\n\n- Feature 1\n- Feature 2\n- Feature 3',
+        },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      if (acceptDailyQuotaLimit(receipt, 'HTML email')) return;
+
+      assert.equal(receipt.successful, true);
+      if (receipt.successful) {
+        console.log(`✅ HTML email sent with ID: ${receipt.messageId}`);
+      }
+    });
+  },
+);
+
+describe(
+  'ResendTransport E2E Test 3',
+  {
+    skip: !hasApiKey() || !setupTransport() || !hasVerifiedDomain(),
+  },
+  () => {
+    it('should send high priority email', async () => {
+      await waitForRateLimit();
+      const recipientEmail = getTestRecipient();
+
+      const message = {
+        sender: { address: getTestSender() },
+        recipients: [{ address: recipientEmail }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: '🚨 High Priority Email',
+        content: {
+          text: 'This is a high priority email sent via Upyo Resend transport.',
+        },
+        attachments: [],
+        priority: 'high',
+        tags: ['urgent'],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      if (acceptDailyQuotaLimit(receipt, 'High priority email')) return;
+
+      assert.equal(receipt.successful, true);
+      if (receipt.successful) {
+        console.log(`✅ High priority email sent with ID: ${receipt.messageId}`);
+      }
+    });
+  },
+);
+
+describe(
+  'ResendTransport E2E Test 4',
+  {
+    skip: !hasApiKey() || !setupTransport() || !hasVerifiedDomain(),
+  },
+  () => {
+    it('should send email with attachments', async () => {
+      await waitForRateLimit();
+      const recipientEmail = getTestRecipient();
+
+      // Create a simple text attachment
+      const textContent = 'This is a test attachment from Upyo Resend transport.';
+      const textBuffer = new TextEncoder().encode(textContent);
+
+      const message = {
+        sender: { address: getTestSender() },
+        recipients: [{ address: recipientEmail }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Email with Attachment',
+        content: {
+          text: 'This email contains an attachment. Please check!',
+        },
+        attachments: [
+          {
+            filename: 'test-document.txt',
+            content: textBuffer,
+            contentType: 'text/plain',
+            inline: false,
+            contentId: '',
+          },
+        ],
+        priority: 'normal',
+        tags: ['attachment-test'],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      if (acceptDailyQuotaLimit(receipt, 'Attachment email')) return;
+
+      assert.equal(receipt.successful, true);
+      if (receipt.successful) {
+        console.log(`✅ Email with attachment sent with ID: ${receipt.messageId}`);
+      }
+    });
+  },
+);
+
+describe(
+  'ResendTransport E2E Test 5',
+  {
+    skip: !hasApiKey() || !setupTransport() || !hasVerifiedDomain(),
+  },
+  () => {
+    it('should send multiple emails sequentially', async () => {
+      await waitForRateLimit();
+      const recipientEmail = getTestRecipient();
+
+      const messages = [
+        {
+          sender: { address: getTestSender() },
+          recipients: [{ address: recipientEmail }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Batch Test Email 1',
+          content: { text: 'This is the first email in the batch.' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+        {
+          sender: { address: getTestSender() },
+          recipients: [{ address: recipientEmail }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Batch Test Email 2',
+          content: { text: 'This is the second email in the batch.' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+        {
+          sender: { address: getTestSender() },
+          recipients: [{ address: recipientEmail }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Batch Test Email 3',
+          content: { text: 'This is the third email in the batch.' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 3);
+      const dailyQuotaFailures = assertBatchReceipts(receipts);
+
+      for (let i = 0; i < receipts.length; i++) {
+        const receipt = receipts[i];
+        if (receipt.successful) {
+          console.log(`✅ Batch email ${i + 1} sent with ID: ${receipt.messageId}`);
+        }
+      }
+
+      if (dailyQuotaFailures > 0) {
+        console.log('Batch email test limited by Resend daily quota.');
+      }
+    });
+  },
+);
+
+describe(
+  'ResendTransport E2E Test 6',
+  {
+    skip: !hasApiKey() || !setupTransport(),
+  },
+  () => {
+    it('should handle invalid sender address gracefully', async () => {
+      const message = {
+        sender: { address: 'invalid@invalid-domain-that-does-not-exist.com' },
+        recipients: [{ address: 'delivered@resend.dev' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Invalid Sender Test',
+        content: { text: 'This should fail due to invalid sender.' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, false);
+      if (!receipt.successful) {
+        assert.ok(receipt.errorMessages.length > 0);
+        console.log(`✅ Invalid sender correctly rejected: ${receipt.errorMessages[0]}`);
+      }
+    });
+  },
+);
+
+describe(
+  'ResendTransport E2E Test 7',
+  {
+    skip: !hasApiKey() || !setupTransport(),
+  },
+  () => {
+    it('should handle malformed recipient address gracefully', async () => {
+      const message = {
+        sender: { address: getTestSender() },
+        recipients: [{ address: 'invalid@invalid' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Invalid Recipient Test',
+        content: { text: 'This should fail due to malformed recipient.' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, false);
+      if (!receipt.successful) {
+        assert.ok(receipt.errorMessages.length > 0);
+        console.log(`✅ Invalid recipient correctly rejected: ${receipt.errorMessages[0]}`);
+      }
+    });
+  },
+);
+
+describe('ResendTransport E2E quota helpers', () => {
+  it('only accepts daily sending quota failures', () => {
+    const dailyQuota = createFailedReceipt('You have reached your daily email sending quota.', {
+      provider: 'resend',
+      statusCode: 429,
+    });
+    const rateLimit = createFailedReceipt('Too many requests.', {
+      provider: 'resend',
+      statusCode: 429,
+    });
+    const authFailure = createFailedReceipt('Invalid API key.', {
+      provider: 'resend',
+      statusCode: 401,
+    });
+    const successfulReceipt = {
+      successful: true,
+      messageId: 'sent',
+    };
+
+    assert.ok(isDailyQuotaLimitReceipt(dailyQuota));
+    assert.ok(!isDailyQuotaLimitReceipt(rateLimit));
+    assert.ok(!isDailyQuotaLimitReceipt(authFailure));
+    assert.equal(assertBatchReceipts([dailyQuota, dailyQuota]), 2);
+    assert.throws(() => assertBatchReceipts([dailyQuota, rateLimit]));
+    assert.equal(assertBatchReceipts([successfulReceipt]), 0);
+    assert.equal(assertBatchReceipts([successfulReceipt, dailyQuota]), 1);
+  });
+});
+
+function acceptDailyQuotaLimit(receipt, label) {
+  if (!isDailyQuotaLimitReceipt(receipt)) return false;
+  console.log(`${label} test skipped due to Resend daily quota.`);
+  return true;
+}
+
+function assertBatchReceipts(receipts) {
+  let dailyQuotaFailures = 0;
+  for (const receipt of receipts) {
+    if (isDailyQuotaLimitReceipt(receipt)) {
+      dailyQuotaFailures++;
+      continue;
+    }
+    assert.ok(receipt.successful);
+  }
+  return dailyQuotaFailures;
+}
+
+function isDailyQuotaLimitReceipt(receipt) {
+  return (
+    !receipt.successful &&
+    receipt.errors?.some((error) => error.statusCode === 429) === true &&
+    receipt.errorMessages.some((message) =>
+      message.toLowerCase().includes('daily email sending quota'),
+    )
+  );
+}
diff --git a/tests/helpers/resend/test-config.js b/tests/helpers/resend/test-config.js
new file mode 100644
index 0000000..e3d1612
--- /dev/null
+++ b/tests/helpers/resend/test-config.js
@@ -0,0 +1,39 @@
+// Ported from upyo v0.7.0 (packages/resend/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const process = require('node:process');
+
+/**
+ * Creates a test configuration for Resend transport from environment variables.
+ *
+ * This function reads the Resend API key from environment variables and
+ * creates a configuration suitable for testing purposes.
+ *
+ * @returns Test configuration for Resend transport
+ * @throws Error if required environment variables are not set
+ */
+const createTestConfig = () => {
+  const apiKey = process.env.RESEND_API_KEY;
+
+  if (!apiKey) {
+    throw new Error(
+      'RESEND_API_KEY environment variable is required for E2E tests. ' +
+        'Please set it to your Resend API key.',
+    );
+  }
+
+  const baseUrl = process.env.RESEND_BASE_URL;
+  const recipientEmail = process.env.RESEND_TO;
+  const verifiedDomain = process.env.RESEND_VERIFIED_DOMAIN;
+
+  return {
+    apiKey,
+    ...(baseUrl && { baseUrl }),
+    ...(recipientEmail && { recipientEmail }),
+    ...(verifiedDomain && { verifiedDomain }),
+    timeout: 30000,
+    retries: 3,
+  };
+};
+
+module.exports = { createTestConfig };
diff --git a/tests/types/resend.test-d.ts b/tests/types/resend.test-d.ts
new file mode 100644
index 0000000..82d4537
--- /dev/null
+++ b/tests/types/resend.test-d.ts
@@ -0,0 +1,26 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import {
+  ResendTransport,
+  type ResendApiError,
+  type ResendConfig,
+  type ResolvedResendConfig,
+} from '../../src/resend/index.js';
+
+const transport = new ResendTransport({ apiKey: 're_123', timeout: 10_000, retries: 1 });
+expectAssignable<Transport<'resend'>>(transport);
+expectType<ResolvedResendConfig>(transport.config);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { html: '<p>Hi</p>' },
+});
+expectType<Promise<Receipt<'resend'>>>(transport.send(message));
+expectType<AsyncIterable<Receipt<'resend'>>>(transport.sendMany([message]));
+
+expectAssignable<ResendConfig>({ apiKey: 're_123', baseUrl: 'https://api.resend.com' });
+declare const error: ResendApiError;
+expectType<number | undefined>(error.statusCode);
+expectError(new ResendTransport({}));
diff --git a/tests/unit/resend-config.test.js b/tests/unit/resend-config.test.js
new file mode 100644
index 0000000..11f9f13
--- /dev/null
+++ b/tests/unit/resend-config.test.js
@@ -0,0 +1,60 @@
+// Ported from upyo v0.7.0 (packages/resend/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createResendConfig } = require('../../src/resend/config.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+
+describe('createResendConfig', () => {
+  it('should apply default values to optional fields', () => {
+    const config = {
+      apiKey: 'test-api-key',
+    };
+
+    const resolved = createResendConfig(config);
+
+    assert.equal(resolved.apiKey, 'test-api-key');
+    assert.equal(resolved.baseUrl, 'https://api.resend.com');
+    assert.equal(resolved.timeout, 30000);
+    assert.equal(resolved.retries, 3);
+    assert.equal(resolved.validateSsl, true);
+    assert.deepEqual(resolved.headers, {});
+  });
+
+  it('should preserve provided optional values', () => {
+    const config = {
+      apiKey: 'test-api-key',
+      baseUrl: 'https://custom.resend.com',
+      timeout: 60000,
+      retries: 5,
+      validateSsl: false,
+      headers: { 'X-Custom': 'value' },
+    };
+
+    const resolved = createResendConfig(config);
+
+    assert.equal(resolved.apiKey, 'test-api-key');
+    assert.equal(resolved.baseUrl, 'https://custom.resend.com');
+    assert.equal(resolved.timeout, 60000);
+    assert.equal(resolved.retries, 5);
+    assert.equal(resolved.validateSsl, false);
+    assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
+  });
+
+  it('should handle mixed partial configuration', () => {
+    const config = {
+      apiKey: 'test-api-key',
+      timeout: 45000,
+      headers: { 'User-Agent': 'test-agent' },
+    };
+
+    const resolved = createResendConfig(config);
+
+    assert.equal(resolved.apiKey, 'test-api-key');
+    assert.equal(resolved.baseUrl, 'https://api.resend.com'); // default
+    assert.equal(resolved.timeout, 45000); // provided
+    assert.equal(resolved.retries, 3); // default
+    assert.equal(resolved.validateSsl, true); // default
+    assert.deepEqual(resolved.headers, { 'User-Agent': 'test-agent' }); // provided
+  });
+});
diff --git a/tests/unit/resend-message-converter.test.js b/tests/unit/resend-message-converter.test.js
new file mode 100644
index 0000000..3f26916
--- /dev/null
+++ b/tests/unit/resend-message-converter.test.js
@@ -0,0 +1,549 @@
+// Ported from upyo v0.7.0 (packages/resend/src/message-converter.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const { Buffer } = require('node:buffer');
+const {
+  convertMessage,
+  convertMessagesBatch,
+  generateIdempotencyKey,
+} = require('../../src/resend/message-converter.js');
+const { createResendConfig } = require('../../src/resend/config.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+
+describe('Message Converter', () => {
+  const config = createResendConfig({ apiKey: 'test-key' });
+
+  describe('convertMessage', () => {
+    for (const length of [0, 1, 2, 3, 4, 5, 6, 256, 257, 258]) {
+      it(`preserves attachment bytes at length ${length}`, async () => {
+        const bytes = Uint8Array.from({ length }, (_, i) => i % 256);
+        const sources = [
+          bytes,
+          Promise.resolve(bytes),
+          new Blob([bytes]),
+          async function* () {
+            yield bytes.subarray(0, 1);
+            yield bytes.subarray(1);
+          },
+        ];
+        for (const content of sources) {
+          const message = createMessage({
+            from: 'sender@example.com',
+            to: 'recipient@example.com',
+            subject: 'Attachment padding',
+            content: { text: 'Test' },
+            attachments: [
+              {
+                filename: 'data.bin',
+                content,
+                contentType: 'application/octet-stream',
+                inline: false,
+                contentId: '',
+              },
+            ],
+          });
+          const result = await convertMessage(message, config);
+          assert.equal(result.attachments?.[0].content, Buffer.from(bytes).toString('base64'));
+        }
+      });
+    }
+
+    it('should convert basic message correctly', async () => {
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.equal(result.from, 'sender@example.com');
+      assert.equal(result.to, 'recipient@example.com');
+      assert.equal(result.subject, 'Test Subject');
+      assert.equal(result.text, 'Test content');
+      assert.equal(result.html, undefined);
+    });
+
+    it('should handle multiple recipients as array', async () => {
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient1@example.com' }, { address: 'recipient2@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.deepEqual(result.to, ['recipient1@example.com', 'recipient2@example.com']);
+    });
+
+    it('should format addresses with names correctly', async () => {
+      const message = {
+        sender: { address: 'sender@example.com', name: 'John Doe' },
+        recipients: [{ address: 'recipient@example.com', name: 'Jane Smith' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.equal(result.from, 'John Doe <sender@example.com>');
+      assert.equal(result.to, 'Jane Smith <recipient@example.com>');
+    });
+
+    it('should handle HTML content with text alternative', async () => {
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: {
+          html: '<h1>Hello</h1>',
+          text: 'Hello',
+        },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.equal(result.html, '<h1>Hello</h1>');
+      assert.equal(result.text, 'Hello');
+    });
+
+    it('should handle CC and BCC recipients', async () => {
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [{ address: 'cc@example.com' }],
+        bccRecipients: [{ address: 'bcc@example.com' }],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.deepEqual(result.cc, ['cc@example.com']);
+      assert.deepEqual(result.bcc, ['bcc@example.com']);
+    });
+
+    it('should handle reply-to address', async () => {
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [{ address: 'reply@example.com' }],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.equal(result.reply_to, 'reply@example.com');
+    });
+
+    it('should convert tags to Resend format', async () => {
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: ['newsletter', 'marketing'],
+        headers: new Headers(),
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.deepEqual(result.tags, [
+        { name: 'tag1', value: 'newsletter' },
+        { name: 'tag2', value: 'marketing' },
+      ]);
+    });
+
+    it('should handle priority headers', async () => {
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'high',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.equal(result.headers?.['X-Priority'], '1');
+    });
+
+    it('should handle custom headers', async () => {
+      const headers = new Headers();
+      headers.set('X-Custom-Header', 'custom-value');
+      headers.set('X-Another', 'another-value');
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers,
+      };
+
+      const result = await convertMessage(message, config);
+
+      assert.equal(result.headers?.['x-custom-header'], 'custom-value');
+      assert.equal(result.headers?.['x-another'], 'another-value');
+    });
+
+    it('should handle scheduled sending', async () => {
+      const scheduledDate = new Date('2024-12-01T10:00:00Z');
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const result = await convertMessage(message, config, {
+        scheduledAt: scheduledDate,
+      });
+
+      assert.equal(result.scheduled_at, '2024-12-01T10:00:00.000Z');
+    });
+  });
+
+  describe('convertMessagesBatch', () => {
+    it('should convert multiple messages for batch API', async () => {
+      const messages = [
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient1@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 1',
+          content: { text: 'Test content 1' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient2@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 2',
+          content: { text: 'Test content 2' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+      ];
+
+      const result = await convertMessagesBatch(messages, config);
+
+      assert.equal(result.length, 2);
+      assert.equal(result[0].subject, 'Test Subject 1');
+      assert.equal(result[1].subject, 'Test Subject 2');
+    });
+
+    it('should reject batch with more than 100 messages', async () => {
+      const messages = Array(101)
+        .fill(null)
+        .map((_, i) => ({
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: `recipient${i}@example.com` }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: `Test Subject ${i}`,
+          content: { text: `Test content ${i}` },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        }));
+
+      await assert.rejects(() => convertMessagesBatch(messages, config), {
+        message: 'Resend batch API supports maximum 100 emails per request',
+      });
+    });
+
+    it('should reject batch with attachments', async () => {
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [
+          {
+            filename: 'test.txt',
+            content: new Uint8Array(10),
+            contentType: 'text/plain',
+            inline: false,
+            contentId: '',
+          },
+        ],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      await assert.rejects(() => convertMessagesBatch([message], config), {
+        message: 'Attachments are not supported in Resend batch API',
+      });
+    });
+
+    it('should reject batch with tags', async () => {
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: ['newsletter'],
+        headers: new Headers(),
+      };
+
+      await assert.rejects(() => convertMessagesBatch([message], config), {
+        message: 'Tags are not supported in Resend batch API',
+      });
+    });
+  });
+
+  describe('generateIdempotencyKey', () => {
+    it('should generate unique keys', () => {
+      const key1 = generateIdempotencyKey();
+      const key2 = generateIdempotencyKey();
+
+      assert.notEqual(key1, key2);
+      assert.ok(key1.length > 10);
+      assert.ok(key2.length > 10);
+    });
+
+    it('should generate keys with expected format', () => {
+      const key = generateIdempotencyKey();
+
+      // Should contain timestamp and random parts separated by hyphens
+      const parts = key.split('-');
+      assert.ok(parts.length >= 2);
+      assert.ok(parts.every((part) => part.length > 0));
+    });
+  });
+});
+
+const threadingConfig = createResendConfig({ apiKey: 'test-key' });
+
+const headerOf = (headers, name) =>
+  Object.entries(headers)
+    .filter(([key]) => key.toLowerCase() === name.toLowerCase())
+    .map(([, value]) => value);
+
+describe('convertMessage() reply threading', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Re: Your request',
+    content: { text: 'Thanks for getting in touch.' },
+  };
+
+  it('writes the typed threading fields', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: '122@example.com',
+      references: ['120@example.com', '121@example.com'],
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<122@example.com>']);
+    assert.deepEqual(headerOf(result, 'References'), ['<120@example.com> <121@example.com>']);
+  });
+
+  it('prefers a typed field over a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: ['typed@example.com'],
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<typed@example.com>']);
+  });
+
+  it('lets an empty list suppress a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: [],
+      references: [],
+      headers: {
+        'In-Reply-To': '<custom@example.com>',
+        References: '<custom@example.com>',
+      },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), []);
+    assert.deepEqual(headerOf(result, 'References'), []);
+  });
+
+  it('lets a custom header through when the field is unset', async () => {
+    const message = createMessage({
+      ...base,
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<custom@example.com>']);
+  });
+});
+
+const CALENDAR_ICS =
+  [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'SUMMARY:Lunch',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+const CALENDAR_BASE64 = btoa(CALENDAR_ICS);
+
+const AGENDA_ATTACHMENT = {
+  inline: false,
+  filename: 'agenda.txt',
+  content: new TextEncoder().encode('agenda'),
+  contentType: 'text/plain',
+  contentId: '',
+};
+
+describe('convertMessage() calendar', () => {
+  const calendarConfig = createResendConfig({ apiKey: 'test-key' });
+
+  const invitation = (attachments = []) =>
+    createMessage({
+      from: 'organizer@example.com',
+      to: 'attendee@example.net',
+      subject: 'Lunch',
+      content: { text: 'Lunch on Wednesday.' },
+      calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+      attachments,
+    });
+
+  it('should carry the calendar as an invite.ics attachment', async () => {
+    const result = await convertMessage(invitation(), calendarConfig);
+
+    assert.equal(result.attachments?.length, 1);
+    assert.equal(result.attachments?.[0].filename, 'invite.ics');
+    assert.equal(
+      result.attachments?.[0].content_type,
+      'text/calendar; charset=utf-8; method=REQUEST',
+    );
+    assert.equal(result.attachments?.[0].content, CALENDAR_BASE64);
+  });
+
+  it('should place the invitation ahead of the other attachments', async () => {
+    const result = await convertMessage(invitation([AGENDA_ATTACHMENT]), calendarConfig);
+
+    assert.deepEqual(
+      result.attachments?.map((attachment) => attachment.filename),
+      ['invite.ics', 'agenda.txt'],
+    );
+  });
+
+  it('should refuse a calendar message in the batch API', async () => {
+    // The calendar becomes an attachment during conversion, which the batch
+    // API forbids, so reading `message.attachments` alone would miss it.
+    await assert.rejects(() => convertMessagesBatch([invitation()], calendarConfig), {
+      message: /Attachments are not supported/,
+    });
+  });
+
+  it('should reject calendar content that never passed createMessage()', async () => {
+    const message = {
+      ...createMessage({
+        from: 'organizer@example.com',
+        to: 'attendee@example.net',
+        subject: 'Lunch',
+        content: { text: 'Lunch.' },
+      }),
+      calendar: { method: 'REQUEST', content: 'not a calendar' },
+    };
+
+    await assert.rejects(() => convertMessage(message, calendarConfig), {
+      name: 'TypeError',
+    });
+  });
+});
diff --git a/tests/unit/resend-transport.test.js b/tests/unit/resend-transport.test.js
new file mode 100644
index 0000000..ca45665
--- /dev/null
+++ b/tests/unit/resend-transport.test.js
@@ -0,0 +1,779 @@
+// Ported from upyo v0.7.0 (packages/resend/src/resend-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createResendConfig } = require('../../src/resend/config.js');
+const { ResendHttpClient } = require('../../src/resend/http-client.js');
+const { ResendTransport } = require('../../src/resend/resend-transport.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+
+// Note: Tests are split into separate describe blocks instead of one unified block
+// because Deno runs tests within the same describe block concurrently, which causes
+// globalThis.fetch mocking to interfere between tests. Node.js runs tests sequentially
+// so it doesn't have this issue. By separating each test into its own describe block,
+// we ensure that fetch mocking is isolated between tests in both environments.
+
+let fetchMockChain = Promise.resolve();
+
+const withMockedFetch = async (fetchMock, callback) => {
+  const previous = fetchMockChain;
+  let release = () => {};
+  fetchMockChain = new Promise((resolve) => {
+    release = resolve;
+  });
+  await previous;
+
+  const originalFetch = globalThis.fetch;
+  try {
+    globalThis.fetch = fetchMock;
+    return await callback();
+  } finally {
+    globalThis.fetch = originalFetch;
+    release();
+  }
+};
+
+const createTestMessage = () => {
+  return {
+    sender: { address: 'sender@example.com' },
+    recipients: [{ address: 'recipient@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test content' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+  };
+};
+
+describe('ResendTransport - Send Message', () => {
+  it('should send a message successfully', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock successful response
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            id: 'test-message-id',
+          }),
+          {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new ResendTransport({
+        apiKey: 'test-key',
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, true);
+      if (receipt.successful) {
+        assert.equal(receipt.messageId, 'test-message-id');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('ResendTransport - API Errors', () => {
+  it('should handle API errors', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify({
+              message: 'Invalid API key',
+            }),
+            {
+              status: 401,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          ),
+        ),
+      async () => {
+        const transport = new ResendTransport({
+          apiKey: 'invalid-key',
+        });
+
+        const message = {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject',
+          content: { text: 'Test content' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        };
+
+        const receipt = await transport.send(message);
+
+        assert.equal(receipt.successful, false);
+        if (!receipt.successful) {
+          assert.ok(receipt.errorMessages.length > 0);
+          assert.ok(receipt.errorMessages[0].includes('Invalid API key'));
+          assert.equal(receipt.provider, 'resend');
+          assert.equal(receipt.retryable, false);
+          assert.equal(receipt.attempts, 1);
+          assert.equal(receipt.errors?.[0]?.category, 'auth');
+          assert.equal(receipt.errors?.[0]?.statusCode, 401);
+        }
+      },
+    );
+  });
+
+  it('should truncate non-JSON error response bodies', async () => {
+    const longBody = 'x'.repeat(600);
+    await withMockedFetch(
+      () => Promise.resolve(new Response(longBody, { status: 500 })),
+      async () => {
+        const transport = new ResendTransport({
+          apiKey: 'test-key',
+          retries: 0,
+        });
+
+        const message = {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject',
+          content: { text: 'Test content' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        };
+
+        const receipt = await transport.send(message);
+
+        assert.ok(!receipt.successful);
+        assert.equal(receipt.errorMessages[0], `${'x'.repeat(500)}...`);
+      },
+    );
+  });
+
+  it('should expose rate limit retry metadata', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify({
+              message: 'Rate limit exceeded',
+            }),
+            {
+              status: 429,
+              headers: { 'Retry-After': '20' },
+            },
+          ),
+        ),
+      async () => {
+        const transport = new ResendTransport({
+          apiKey: 'test-key',
+          retries: 0,
+        });
+
+        const message = {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject',
+          content: { text: 'Test content' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        };
+
+        const receipt = await transport.send(message);
+
+        assert.equal(receipt.successful, false);
+        if (!receipt.successful) {
+          assert.equal(receipt.provider, 'resend');
+          assert.equal(receipt.retryable, true);
+          assert.equal(receipt.errors?.[0]?.category, 'rate-limit');
+          assert.equal(receipt.errors?.[0]?.retryAfterMilliseconds, 20_000);
+        }
+      },
+    );
+  });
+});
+
+describe('ResendHttpClient - Abort Signal', () => {
+  it('should pass an already aborted signal to fetch', async () => {
+    await withMockedFetch(
+      (_url, init) => {
+        assert.ok(init?.signal instanceof AbortSignal);
+        assert.ok(init.signal.aborted);
+        return Promise.reject(new DOMException('The operation was aborted.', 'AbortError'));
+      },
+      async () => {
+        const client = new ResendHttpClient(createResendConfig({ apiKey: 'test-key', retries: 0 }));
+        const controller = new AbortController();
+        controller.abort();
+
+        await assert.rejects(() => client.sendMessage({}, controller.signal), {
+          name: 'AbortError',
+        });
+      },
+    );
+  });
+
+  // Upstream's "falls back when AbortSignal.any is unavailable" is not ported: Node 22 always
+  // has AbortSignal.any, and the core keeps no fallback without it.
+
+  // Upstream's "preserves abort reasons without AbortSignal.any" is not ported: Node 22 always
+  // has AbortSignal.any, and the core keeps no fallback without it.
+});
+
+describe('ResendTransport - Network Errors', () => {
+  it('should handle network errors', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock network error
+      globalThis.fetch = async () => {
+        throw new Error('Network error');
+      };
+
+      const transport = new ResendTransport({
+        apiKey: 'test-key',
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, false);
+      if (!receipt.successful) {
+        assert.ok(receipt.errorMessages.length > 0);
+        assert.ok(receipt.errorMessages[0].includes('Network error'));
+        assert.equal(receipt.provider, 'resend');
+        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.attempts, 4);
+        assert.equal(receipt.errors?.[0]?.category, 'network');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('ResendTransport - Abort Signal', () => {
+  it('should handle abort signal', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock slow response
+      globalThis.fetch = async () => {
+        return new Promise((resolve) => {
+          setTimeout(() => {
+            resolve(new Response(JSON.stringify({ id: 'test-id' }), { status: 200 }));
+          }, 1000);
+        });
+      };
+
+      const transport = new ResendTransport({
+        apiKey: 'test-key',
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const controller = new AbortController();
+      controller.abort();
+
+      try {
+        await transport.send(message, { signal: controller.signal });
+        assert.fail('Should have thrown AbortError');
+      } catch (error) {
+        assert.ok(error instanceof Error);
+        assert.equal(error.name, 'AbortError');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('should preserve custom abort reasons in send', async () => {
+    const abortReason = new Error('Stop resend send.');
+    const controller = new AbortController();
+    controller.abort(abortReason);
+    const transport = new ResendTransport({
+      apiKey: 'test-key',
+    });
+
+    await assert.rejects(
+      () => transport.send(createTestMessage(), { signal: controller.signal }),
+      (error) => error === abortReason,
+    );
+  });
+});
+
+describe('ResendTransport - Batch Sending Small', () => {
+  it('should send small batch using batch API', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock batch API response
+      globalThis.fetch = async (url) => {
+        // Check that batch endpoint is called
+        if (typeof url === 'string' && url.includes('/emails/batch')) {
+          return new Response(
+            JSON.stringify({
+              data: [{ id: 'message-1' }, { id: 'message-2' }],
+            }),
+            {
+              status: 200,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          );
+        }
+
+        throw new Error('Unexpected URL called');
+      };
+
+      const transport = new ResendTransport({
+        apiKey: 'test-key',
+      });
+
+      const messages = [
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient1@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 1',
+          content: { text: 'Test content 1' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient2@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 2',
+          content: { text: 'Test content 2' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.equal(receipts[0].successful, true);
+      assert.equal(receipts[1].successful, true);
+
+      if (receipts[0].successful && receipts[1].successful) {
+        assert.equal(receipts[0].messageId, 'message-1');
+        assert.equal(receipts[1].messageId, 'message-2');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('ResendTransport - Individual Sending', () => {
+  it('should fall back to individual requests for messages with attachments', async () => {
+    const originalFetch = globalThis.fetch;
+    let callCount = 0;
+
+    try {
+      // Mock individual API responses
+      globalThis.fetch = async (url) => {
+        callCount++;
+        // Should call individual endpoint, not batch
+        if (typeof url === 'string' && url.includes('/emails') && !url.includes('/batch')) {
+          return new Response(JSON.stringify({ id: `message-${callCount}` }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          });
+        }
+
+        throw new Error('Unexpected URL called');
+      };
+
+      const transport = new ResendTransport({
+        apiKey: 'test-key',
+      });
+
+      const messages = [
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient1@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 1',
+          content: { text: 'Test content 1' },
+          attachments: [
+            {
+              filename: 'test.txt',
+              content: new Uint8Array(10),
+              contentType: 'text/plain',
+              inline: false,
+              contentId: '',
+            },
+          ],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient2@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 2',
+          content: { text: 'Test content 2' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.equal(callCount, 2); // Should make 2 individual calls
+      assert.equal(receipts[0].successful, true);
+      assert.equal(receipts[1].successful, true);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('ResendTransport - Empty Batch', () => {
+  it('should handle empty message array', async () => {
+    const transport = new ResendTransport({
+      apiKey: 'test-key',
+    });
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany([])) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 0);
+  });
+});
+
+describe('ResendTransport - Config Validation', () => {
+  it('should create transport with minimal config', () => {
+    const transport = new ResendTransport({
+      apiKey: 'test-key',
+    });
+
+    assert.equal(transport.config.apiKey, 'test-key');
+    assert.equal(transport.config.baseUrl, 'https://api.resend.com');
+    assert.equal(transport.config.timeout, 30000);
+    assert.equal(transport.config.retries, 3);
+  });
+
+  it('should create transport with custom config', () => {
+    const transport = new ResendTransport({
+      apiKey: 'test-key',
+      baseUrl: 'https://custom.resend.com',
+      timeout: 60000,
+      retries: 5,
+    });
+
+    assert.equal(transport.config.apiKey, 'test-key');
+    assert.equal(transport.config.baseUrl, 'https://custom.resend.com');
+    assert.equal(transport.config.timeout, 60000);
+    assert.equal(transport.config.retries, 5);
+  });
+});
+
+// Note: Idempotency key tests are split into separate describe blocks
+// because Deno runs tests within the same describe block concurrently,
+// which causes globalThis.fetch mocking to interfere between tests.
+
+describe('ResendTransport - Idempotency Key Provided', () => {
+  it('should use provided idempotency key in HTTP header', async () => {
+    const originalFetch = globalThis.fetch;
+    const captured = { headers: null };
+
+    try {
+      // Mock fetch to capture headers
+      globalThis.fetch = (_url, init) => {
+        captured.headers = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(JSON.stringify({ id: 'test-message-id' }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      };
+
+      const transport = new ResendTransport({ apiKey: 'test-key' });
+
+      const testKey = `test-key-${Date.now()}`;
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+        idempotencyKey: testKey,
+      };
+
+      await transport.send(message);
+
+      assert.ok(captured.headers !== null);
+      assert.equal(captured.headers.get('Idempotency-Key'), testKey);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('ResendTransport - Idempotency Key Auto-generated', () => {
+  it('should generate idempotency key when not provided', async () => {
+    const originalFetch = globalThis.fetch;
+    const captured = { headers: null };
+
+    try {
+      globalThis.fetch = (_url, init) => {
+        captured.headers = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(JSON.stringify({ id: 'test-message-id' }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      };
+
+      const transport = new ResendTransport({ apiKey: 'test-key' });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      await transport.send(message);
+
+      assert.ok(captured.headers !== null);
+      const idempotencyKey = captured.headers.get('Idempotency-Key');
+      assert.ok(idempotencyKey, 'Idempotency-Key header should be present');
+      assert.ok(idempotencyKey.length > 10, 'Auto-generated key should have reasonable length');
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('ResendTransport - Idempotency Key Retry', () => {
+  it('should allow retry with same idempotency key', async () => {
+    const originalFetch = globalThis.fetch;
+    const capturedKeys = [];
+
+    try {
+      let callCount = 0;
+      globalThis.fetch = (_url, init) => {
+        const headers = new Headers(init?.headers);
+        const key = headers.get('Idempotency-Key');
+        if (key) capturedKeys.push(key);
+
+        callCount++;
+        if (callCount === 1) {
+          // First call fails
+          return Promise.resolve(
+            new Response(JSON.stringify({ message: 'Server error' }), {
+              status: 500,
+              headers: { 'Content-Type': 'application/json' },
+            }),
+          );
+        }
+        // Second call succeeds
+        return Promise.resolve(
+          new Response(JSON.stringify({ id: 'test-message-id' }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      };
+
+      const transport = new ResendTransport({ apiKey: 'test-key', retries: 0 });
+
+      const idempotencyKey = `retry-key-${Date.now()}`;
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+        idempotencyKey,
+      };
+
+      // First attempt fails
+      const receipt1 = await transport.send(message);
+      assert.equal(receipt1.successful, false);
+
+      // Retry with same message (same idempotency key)
+      const receipt2 = await transport.send(message);
+      assert.equal(receipt2.successful, true);
+
+      // Both calls should use the same key
+      assert.equal(capturedKeys.length, 2);
+      assert.equal(capturedKeys[0], idempotencyKey);
+      assert.equal(capturedKeys[1], idempotencyKey);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('ResendTransport - Idempotency Key Batch', () => {
+  it('should use provided idempotency key in batch API', async () => {
+    const originalFetch = globalThis.fetch;
+    const captured = { headers: null };
+
+    try {
+      globalThis.fetch = (url, init) => {
+        if (typeof url === 'string' && url.includes('/emails/batch')) {
+          captured.headers = new Headers(init?.headers);
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                data: [{ id: 'message-1' }, { id: 'message-2' }],
+              }),
+              { status: 200, headers: { 'Content-Type': 'application/json' } },
+            ),
+          );
+        }
+        return Promise.reject(new Error('Unexpected URL called'));
+      };
+
+      const transport = new ResendTransport({ apiKey: 'test-key' });
+
+      const batchKey = `batch-key-${Date.now()}`;
+      const messages = [
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient1@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 1',
+          content: { text: 'Test content 1' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+          idempotencyKey: batchKey, // First message's key is used for batch
+        },
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient2@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 2',
+          content: { text: 'Test content 2' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.ok(captured.headers !== null);
+      assert.equal(captured.headers.get('Idempotency-Key'), batchKey);
+      assert.equal(receipts.length, 2);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
diff --git a/tests/unit/resend.test.js b/tests/unit/resend.test.js
new file mode 100644
index 0000000..09dc16e
--- /dev/null
+++ b/tests/unit/resend.test.js
@@ -0,0 +1,82 @@
+// Paths of the ported Resend transport (src/resend/) that upstream reaches
+// only through its e2e suite, against a stubbed fetch.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { ResendTransport } = require('../../src/resend/index.js');
+
+const message = (index = 0) =>
+  createMessage({
+    from: 'Alex "the Sender" <alex@example.com>',
+    to: `bob${index}@example.com`,
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+const json = (body, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+
+test('Resend: custom headers are sent and a quoted name is escaped', async (t) => {
+  let request;
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    request = { headers: new Headers(init.headers), body: JSON.parse(init.body) };
+    return json({ id: 'r1' });
+  });
+  const transport = new ResendTransport({ apiKey: 'key', headers: { 'X-Custom': 'yes' } });
+  const receipt = await transport.send(message());
+  assert.strictEqual(receipt.messageId, 'r1');
+  assert.strictEqual(request.headers.get('x-custom'), 'yes');
+  assert.strictEqual(request.body.from, '"Alex \\"the Sender\\"" <alex@example.com>');
+});
+
+test('Resend: a 200 that is not JSON, and a request over the timeout, fail', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => new Response('<html>', { status: 200 }));
+  const broken = await new ResendTransport({ apiKey: 'key', retries: 0 }).send(message());
+  assert.strictEqual(broken.successful, false);
+  assert.match(broken.errorMessages[0], /^Invalid JSON response from Resend API: /);
+
+  t.mock.restoreAll();
+  t.mock.method(
+    globalThis,
+    'fetch',
+    (url, init) =>
+      new Promise((resolve, reject) => {
+        init.signal.addEventListener('abort', () => reject(init.signal.reason));
+      }),
+  );
+  const slow = await new ResendTransport({ apiKey: 'key', retries: 0, timeout: 20 }).send(
+    message(),
+  );
+  assert.deepStrictEqual(slow.errorMessages, ['Resend API request timed out after 20 ms.']);
+});
+
+test('Resend: more than 100 messages go out in batches of 100', async (t) => {
+  const batches = [];
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    const body = JSON.parse(init.body);
+    batches.push(body.length);
+    return json({ data: body.map((_, index) => ({ id: `b${batches.length}-${index}` })) });
+  });
+  const messages = async function* () {
+    for (let index = 0; index < 150; index++) yield message(index);
+  };
+  const receipts = [];
+  for await (const receipt of new ResendTransport({ apiKey: 'key' }).sendMany(messages())) {
+    receipts.push(receipt);
+  }
+  assert.deepStrictEqual(batches, [100, 50]);
+  assert.strictEqual(receipts.length, 150);
+  assert.ok(receipts.every((receipt) => receipt.successful));
+});
+
+test('Resend: a failed batch fails each of its messages', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => json({ message: 'Bad batch' }, 422));
+  const receipts = [];
+  const transport = new ResendTransport({ apiKey: 'key', retries: 0 });
+  for await (const receipt of transport.sendMany([message(1), message(2)])) {
+    receipts.push(receipt);
+  }
+  assert.deepStrictEqual(
+    receipts.map((receipt) => receipt.errorMessages),
+    [['Bad batch'], ['Bad batch']],
+  );
+});

From 0909657b86d64e9d412412677ae4d7f1b6a51d3b Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:10:46 +0300
Subject: [PATCH 008/158] feat(sendgrid): port the SendGrid transport from upyo
 0.7.0

./sendgrid exports SendGridTransport and SendGridApiError: the v3 Mail Send
API over fetch, with attachments, categories, priority headers, click and
open tracking settings, retries and a request timeout; a 202 is a success,
identified by X-Message-Id or a generated id.

Upstream's unit suites are ported, the e2e suite goes to tests/e2e, and its
test of a runtime without AbortSignal.any is left out. Upstream checked even
a successful send only end to end; tests/unit/sendgrid.test.js covers it,
sendMany, error bodies, retries, the timeout and an abort between retries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   2 +-
 package.json                                  |   4 +
 src/sendgrid/config.js                        |  30 ++
 src/sendgrid/http-client.js                   | 258 ++++++++++
 src/sendgrid/index.d.ts                       | 274 +++++++++++
 src/sendgrid/index.js                         |   8 +
 src/sendgrid/message-converter.js             | 267 +++++++++++
 src/sendgrid/sendgrid-transport.js            | 237 ++++++++++
 tests/e2e/sendgrid-transport.e2e.test.js      | 196 ++++++++
 tests/helpers/sendgrid/test-config.js         |  67 +++
 tests/types/sendgrid.test-d.ts                |  23 +
 .../unit/sendgrid-attachment-content.test.js  |  84 ++++
 tests/unit/sendgrid-config.test.js            |  69 +++
 tests/unit/sendgrid-message-converter.test.js | 446 ++++++++++++++++++
 tests/unit/sendgrid-transport.test.js         | 295 ++++++++++++
 tests/unit/sendgrid.test.js                   |  96 ++++
 16 files changed, 2355 insertions(+), 1 deletion(-)
 create mode 100644 src/sendgrid/config.js
 create mode 100644 src/sendgrid/http-client.js
 create mode 100644 src/sendgrid/index.d.ts
 create mode 100644 src/sendgrid/index.js
 create mode 100644 src/sendgrid/message-converter.js
 create mode 100644 src/sendgrid/sendgrid-transport.js
 create mode 100644 tests/e2e/sendgrid-transport.e2e.test.js
 create mode 100644 tests/helpers/sendgrid/test-config.js
 create mode 100644 tests/types/sendgrid.test-d.ts
 create mode 100644 tests/unit/sendgrid-attachment-content.test.js
 create mode 100644 tests/unit/sendgrid-config.test.js
 create mode 100644 tests/unit/sendgrid-message-converter.test.js
 create mode 100644 tests/unit/sendgrid-transport.test.js
 create mode 100644 tests/unit/sendgrid.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 131521d..2c45056 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 2beb038..469770f 100644
--- a/package.json
+++ b/package.json
@@ -40,6 +40,10 @@
       "types": "./src/resend/index.d.ts",
       "default": "./src/resend/index.js"
     },
+    "./sendgrid": {
+      "types": "./src/sendgrid/index.d.ts",
+      "default": "./src/sendgrid/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
diff --git a/src/sendgrid/config.js b/src/sendgrid/config.js
new file mode 100644
index 0000000..b0107bf
--- /dev/null
+++ b/src/sendgrid/config.js
@@ -0,0 +1,30 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved SendGrid configuration by applying default values to optional fields.
+ *
+ * This function takes a partial SendGrid configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the SendGrid transport.
+ *
+ * @param config - The SendGrid configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ * @internal
+ */
+const createSendGridConfig = (config) => {
+  return {
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl ?? 'https://api.sendgrid.com/v3',
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    validateSsl: config.validateSsl ?? true,
+    headers: config.headers ?? {},
+    clickTracking: config.clickTracking ?? true,
+    openTracking: config.openTracking ?? true,
+    subscriptionTracking: config.subscriptionTracking ?? false,
+    googleAnalytics: config.googleAnalytics ?? false,
+  };
+};
+
+module.exports = { createSendGridConfig };
diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
new file mode 100644
index 0000000..51fb0d1
--- /dev/null
+++ b/src/sendgrid/http-client.js
@@ -0,0 +1,258 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/http-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { parseRetryAfter } = require('../core/receipt.js');
+
+/**
+ * HTTP client wrapper for SendGrid API requests.
+ *
+ * This class handles authentication, request formatting, error handling,
+ * and retry logic for SendGrid API calls.
+ */
+class SendGridHttpClient {
+  config;
+
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Sends a message via SendGrid API.
+   *
+   * @param messageData The JSON data to send to SendGrid.
+   * @param signal Optional AbortSignal for cancellation.
+   * @returns Promise that resolves to the SendGrid response.
+   */
+  sendMessage(messageData, signal) {
+    const url = `${this.config.baseUrl}/mail/send`;
+
+    return this.makeRequest(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(messageData),
+      signal,
+    });
+  }
+
+  /**
+   * Makes an HTTP request to SendGrid API with retry logic.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the parsed response.
+   * @throws {DOMException} If the caller aborts the request.
+   * @throws {SendGridApiError} If SendGrid returns a client error or all retry
+   *                            attempts are exhausted.
+   */
+  async makeRequest(url, options) {
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      try {
+        const response = await this.fetchWithAuth(url, options);
+
+        // Get response text
+        const text = await response.text();
+
+        // SendGrid returns 202 for successful sends
+        if (response.status === 202) {
+          return {
+            statusCode: response.status,
+            body: text,
+            headers: this.headersToRecord(response.headers),
+          };
+        }
+
+        // Handle errors
+        let errorData;
+        try {
+          errorData = JSON.parse(text);
+        } catch {
+          errorData = { message: text || `HTTP ${response.status}` };
+        }
+
+        throw new SendGridApiError(
+          errorData.message || `HTTP ${response.status}`,
+          response.status,
+          errorData.errors,
+          parseRetryAfter(response.headers.get('Retry-After')),
+          attempt + 1,
+        );
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        // Don't retry caller cancellation.
+        if (isCallerAbort(error, options.signal)) {
+          throw error;
+        }
+
+        // Don't retry on client errors (4xx) or if it's the last attempt
+        if (
+          error instanceof SendGridApiError &&
+          error.statusCode &&
+          error.statusCode >= 400 &&
+          error.statusCode < 500
+        ) {
+          throw error;
+        }
+
+        if (attempt === this.config.retries) {
+          if (lastError instanceof SendGridApiError) {
+            throw lastError;
+          }
+          throw new SendGridApiError(
+            lastError.message,
+            undefined,
+            undefined,
+            undefined,
+            attempt + 1,
+          );
+        }
+
+        // Wait before retrying (exponential backoff)
+        const delay = Math.pow(2, attempt) * 1000;
+        await sleep(delay, options.signal);
+      }
+    }
+
+    throw lastError || new Error('Request failed after all retries');
+  }
+
+  /**
+   * Makes a fetch request with SendGrid authentication.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the fetch response.
+   * @throws {Error} If the configured request timeout is reached.
+   * @throws {DOMException} If the caller aborts the request.
+   */
+  async fetchWithAuth(url, options) {
+    const headers = new Headers(options.headers);
+
+    // Add authentication header
+    headers.set('Authorization', `Bearer ${this.config.apiKey}`);
+
+    // Add custom headers from config
+    for (const [key, value] of Object.entries(this.config.headers)) {
+      headers.set(key, value);
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    const combinedSignal = combineSignals(controller.signal, options.signal);
+
+    try {
+      return await globalThis.fetch(url, {
+        ...options,
+        headers,
+        signal: combinedSignal.signal,
+      });
+    } catch (error) {
+      if (isAbortError(error) && controller.signal.aborted && !options.signal?.aborted) {
+        // oxlint-disable-next-line preserve-caught-error -- upstream
+        throw new Error(`SendGrid API request timed out after ${this.config.timeout} ms.`);
+      }
+      throw error;
+    } finally {
+      combinedSignal.cleanup();
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * Converts Headers object to a plain Record.
+   *
+   * @param headers The Headers object to convert.
+   * @returns A plain object with header key-value pairs.
+   */
+  headersToRecord(headers) {
+    const record = {};
+    for (const [key, value] of headers.entries()) {
+      record[key] = value;
+    }
+    return record;
+  }
+}
+
+/**
+ * Error thrown when a SendGrid API request fails.
+ */
+class SendGridApiError extends Error {
+  /**
+   * HTTP status code returned by SendGrid, if the request reached the API.
+   */
+  statusCode;
+
+  /**
+   * Provider-supplied SendGrid error details.
+   */
+  errors;
+
+  /**
+   * Retry delay from SendGrid's `Retry-After` response header.
+   */
+  retryAfterMilliseconds;
+
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  attempts;
+
+  /**
+   * Creates a SendGrid API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code returned by SendGrid.
+   * @param errors Provider-supplied SendGrid error details.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(message, statusCode, errors, retryAfterMilliseconds, attempts) {
+    super(message);
+    this.name = 'SendGridApiError';
+    this.statusCode = statusCode;
+    this.errors = errors;
+    this.retryAfterMilliseconds = retryAfterMilliseconds;
+    this.attempts = attempts;
+  }
+}
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+const sleep = (milliseconds, signal) => {
+  if (signal?.aborted) {
+    return Promise.reject(createAbortError(signal));
+  }
+
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener('abort', abort);
+      reject(createAbortError(signal));
+    };
+
+    const timeoutId = setTimeout(() => {
+      signal?.removeEventListener('abort', abort);
+      resolve();
+    }, milliseconds);
+
+    signal?.addEventListener('abort', abort, { once: true });
+  });
+};
+
+const createAbortError = (signal) => {
+  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+};
+
+module.exports = { SendGridHttpClient, SendGridApiError };
diff --git a/src/sendgrid/index.d.ts b/src/sendgrid/index.d.ts
new file mode 100644
index 0000000..f1e5e44
--- /dev/null
+++ b/src/sendgrid/index.d.ts
@@ -0,0 +1,274 @@
+// Types ported from upyo v0.7.0 (packages/sendgrid/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Configuration interface for SendGrid transport connection settings.
+ *
+ * This interface defines all available options for configuring a SendGrid
+ * API connection including authentication, HTTP options, and tracking settings.
+ *
+ * @example
+ * ```typescript
+ * const config: SendGridConfig = {
+ *   apiKey: 'your-api-key',
+ *   timeout: 30000,
+ *   retries: 3,
+ *   tracking: true
+ * };
+ * ```
+ */
+export interface SendGridConfig {
+  /**
+   * Your SendGrid API key.
+   *
+   * You can find your API key in the SendGrid Control Panel under Settings > API Keys.
+   * It should start with 'SG.' for v3 API keys.
+   */
+  readonly apiKey: string;
+  /**
+   * Base URL for the SendGrid API.
+   *
+   * @default "https://api.sendgrid.com/v3"
+   */
+  readonly baseUrl?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   *
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Whether to validate SSL certificates.
+   *
+   * @default true
+   */
+  readonly validateSsl?: boolean;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Whether to enable click tracking for sent messages.
+   *
+   * @default true
+   */
+  readonly clickTracking?: boolean;
+  /**
+   * Whether to enable open tracking for sent messages.
+   *
+   * @default true
+   */
+  readonly openTracking?: boolean;
+  /**
+   * Whether to enable subscription tracking for sent messages.
+   *
+   * @default false
+   */
+  readonly subscriptionTracking?: boolean;
+  /**
+   * Whether to enable Google Analytics tracking for sent messages.
+   *
+   * @default false
+   */
+  readonly googleAnalytics?: boolean;
+}
+/**
+ * Resolved SendGrid configuration with all optional fields filled with default values.
+ *
+ * This type represents the final configuration after applying defaults,
+ * used internally by the SendGrid transport implementation.
+ */
+type ResolvedSendGridConfig = Required<SendGridConfig>;
+/**
+ * Creates a resolved SendGrid configuration by applying default values to optional fields.
+ *
+ * This function takes a partial SendGrid configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the SendGrid transport.
+ *
+ * @param config - The SendGrid configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ * @internal
+ */
+
+/**
+ * SendGrid transport implementation for sending emails via SendGrid API.
+ *
+ * This transport provides efficient email delivery using SendGrid's v3 HTTP API,
+ * with support for authentication, retry logic, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { SendGridTransport } from '@alexify/mailer/sendgrid';
+ *
+ * const transport = new SendGridTransport({
+ *   apiKey: 'your-sendgrid-api-key',
+ *   clickTracking: true,
+ *   openTracking: true
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
+ * ```
+ */
+export declare class SendGridTransport implements Transport<'sendgrid'> {
+  readonly id = 'sendgrid';
+  /**
+   * The resolved SendGrid configuration used by this transport.
+   */
+  config: ResolvedSendGridConfig;
+  /**
+   * Creates a new SendGrid transport instance.
+   *
+   * @param config SendGrid configuration including API key and options.
+   */
+  constructor(config: SendGridConfig);
+  /**
+   * Sends a single email message via SendGrid API.
+   *
+   * This method converts the message to SendGrid format, makes an HTTP request
+   * to the SendGrid API, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent successfully');
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'sendgrid'>>;
+  /**
+   * Sends multiple email messages efficiently via SendGrid API.
+   *
+   * This method sends each message individually but provides a streamlined
+   * interface for processing multiple messages. Each message is sent as a
+   * separate API request to SendGrid.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'sendgrid'>>;
+}
+
+/**
+ * Error thrown when a SendGrid API request fails.
+ */
+export declare class SendGridApiError extends Error {
+  /**
+   * HTTP status code returned by SendGrid, if the request reached the API.
+   */
+  readonly statusCode?: number;
+  /**
+   * Provider-supplied SendGrid error details.
+   */
+  readonly errors?: {
+    readonly message: string;
+    readonly field?: string;
+    readonly help?: string;
+  }[];
+  /**
+   * Retry delay from SendGrid's `Retry-After` response header.
+   */
+  readonly retryAfterMilliseconds?: number;
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * Creates a SendGrid API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code returned by SendGrid.
+   * @param errors Provider-supplied SendGrid error details.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(
+    message: string,
+    statusCode?: number,
+    errors?: Array<{
+      message: string;
+      field?: string;
+      help?: string;
+    }>,
+    retryAfterMilliseconds?: number,
+    attempts?: number,
+  );
+}
diff --git a/src/sendgrid/index.js b/src/sendgrid/index.js
new file mode 100644
index 0000000..458a502
--- /dev/null
+++ b/src/sendgrid/index.js
@@ -0,0 +1,8 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { SendGridTransport } = require('./sendgrid-transport.js');
+
+const { SendGridApiError } = require('./http-client.js');
+
+module.exports = { SendGridTransport, SendGridApiError };
diff --git a/src/sendgrid/message-converter.js b/src/sendgrid/message-converter.js
new file mode 100644
index 0000000..30da53c
--- /dev/null
+++ b/src/sendgrid/message-converter.js
@@ -0,0 +1,267 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createCalendarAttachment } = require('../core/calendar.js');
+const { combineSignals } = require('../core/abort-signal.js');
+const { readAttachmentContent } = require('../core/attachment.js');
+const { resolveThreadingHeaders } = require('../core/message-id.js');
+
+/**
+ * Converts a Upyo Message to SendGrid API JSON format.
+ *
+ * This function transforms the standardized Upyo message format into
+ * the specific format expected by the SendGrid API.
+ *
+ * @param message - The Upyo message to convert
+ * @param config - The resolved SendGrid configuration
+ * @returns Promise that resolves to a SendGrid mail object
+ * @throws {TypeError} If the message carries an invalid message identifier.
+ *
+ * @example
+ * ```typescript
+ * const mailData = await convertMessage(message, config);
+ * const response = await httpClient.sendMessage(mailData);
+ * ```
+ */
+const convertMessage = async (message, config, signal) => {
+  // A transport that cannot compose a `text/calendar` alternative carries the
+  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
+  // own files so that a client looking for the first calendar part finds it.
+  const attachments =
+    message.calendar == null
+      ? message.attachments
+      : [createCalendarAttachment(message.calendar), ...message.attachments];
+
+  const sendGridMail = {
+    personalizations: [],
+    from: formatAddress(message.sender),
+  };
+
+  // Create personalization object
+  const personalization = {
+    to: message.recipients.map(formatAddress),
+    subject: message.subject,
+  };
+
+  // Add CC recipients if any
+  if (message.ccRecipients.length > 0) {
+    personalization.cc = message.ccRecipients.map(formatAddress);
+  }
+
+  // Add BCC recipients if any
+  if (message.bccRecipients.length > 0) {
+    personalization.bcc = message.bccRecipients.map(formatAddress);
+  }
+
+  sendGridMail.personalizations.push(personalization);
+
+  // Reply-to handling
+  if (message.replyRecipients.length > 0) {
+    if (message.replyRecipients.length === 1) {
+      sendGridMail.reply_to = formatAddress(message.replyRecipients[0]);
+    } else {
+      sendGridMail.reply_to_list = message.replyRecipients.map(formatAddress);
+    }
+  }
+
+  // Content
+  const content = [];
+
+  if ('html' in message.content) {
+    if (message.content.text) {
+      content.push({
+        type: 'text/plain',
+        value: message.content.text,
+      });
+    }
+    content.push({
+      type: 'text/html',
+      value: message.content.html,
+    });
+  } else {
+    content.push({
+      type: 'text/plain',
+      value: message.content.text,
+    });
+  }
+
+  sendGridMail.content = content;
+
+  // Priority handling (using custom headers)
+  if (message.priority !== 'normal') {
+    const headers = {};
+
+    switch (message.priority) {
+      case 'high':
+        headers['X-Priority'] = '1';
+        headers['X-MSMail-Priority'] = 'High';
+        headers['Importance'] = 'High';
+        break;
+      case 'low':
+        headers['X-Priority'] = '5';
+        headers['X-MSMail-Priority'] = 'Low';
+        headers['Importance'] = 'Low';
+        break;
+    }
+
+    sendGridMail.headers = { ...sendGridMail.headers, ...headers };
+  }
+
+  // Tags (categories in SendGrid)
+  if (message.tags.length > 0) {
+    sendGridMail.categories = [...message.tags];
+  }
+
+  // Custom headers
+  const customHeaders = {};
+  // Reply threading comes from the typed fields when the message defines them,
+  // and from a custom header otherwise.  A field the message owns but left
+  // empty writes nothing, which is how a caller drops an inherited header.
+  const threading = resolveThreadingHeaders(message);
+  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+
+  for (const [key, value] of message.headers.entries()) {
+    // Skip standard headers that are handled separately
+    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
+      customHeaders[key] = value;
+    }
+  }
+  for (const [name, value] of threading) {
+    if (value != null) customHeaders[name] = value;
+  }
+
+  if (Object.keys(customHeaders).length > 0) {
+    sendGridMail.headers = { ...sendGridMail.headers, ...customHeaders };
+  }
+
+  // Attachments
+  if (attachments.length > 0) {
+    const cancellation = new AbortController();
+    const combined = combineSignals(cancellation.signal, signal);
+    try {
+      sendGridMail.attachments = await Promise.all(
+        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
+      );
+    } finally {
+      cancellation.abort();
+      combined.cleanup();
+    }
+  }
+
+  // Tracking settings
+  const trackingSettings = {};
+
+  if (config.clickTracking !== undefined) {
+    trackingSettings.click_tracking = {
+      enable: config.clickTracking,
+      enable_text: config.clickTracking,
+    };
+  }
+
+  if (config.openTracking !== undefined) {
+    trackingSettings.open_tracking = {
+      enable: config.openTracking,
+    };
+  }
+
+  if (config.subscriptionTracking !== undefined) {
+    trackingSettings.subscription_tracking = {
+      enable: config.subscriptionTracking,
+    };
+  }
+
+  if (config.googleAnalytics !== undefined) {
+    trackingSettings.ganalytics = {
+      enable: config.googleAnalytics,
+    };
+  }
+
+  if (Object.keys(trackingSettings).length > 0) {
+    sendGridMail.tracking_settings = trackingSettings;
+  }
+
+  return sendGridMail;
+};
+
+/**
+ * Formats an address for SendGrid API.
+ *
+ * @param address - The address to format
+ * @returns Formatted address object
+ */
+const formatAddress = (address) => {
+  const result = {
+    email: address.address,
+  };
+
+  if (address.name) {
+    result.name = address.name;
+  }
+
+  return result;
+};
+
+/**
+ * Converts a Upyo attachment to SendGrid format.
+ *
+ * @param attachment - The attachment to convert
+ * @returns Promise that resolves to a SendGrid attachment object
+ */
+const convertAttachment = async (attachment, signal) => {
+  // Get the content as Uint8Array then convert to base64
+  const contentBytes = await readAttachmentContent(attachment.content, signal);
+
+  // Convert to base64
+  const parts = [];
+  for (let offset = 0; offset < contentBytes.length; offset += 8192) {
+    parts.push(String.fromCharCode(...contentBytes.subarray(offset, offset + 8192)));
+  }
+  const base64Content = btoa(parts.join(''));
+
+  const sendGridAttachment = {
+    content: base64Content,
+    filename: attachment.filename,
+  };
+
+  if (attachment.contentType) {
+    sendGridAttachment.type = attachment.contentType;
+  }
+
+  if (attachment.inline && attachment.contentId) {
+    sendGridAttachment.disposition = 'inline';
+    sendGridAttachment.content_id = attachment.contentId;
+  } else {
+    sendGridAttachment.disposition = 'attachment';
+  }
+
+  return sendGridAttachment;
+};
+
+/**
+ * Checks if a header is a standard email header that should not be added as custom header.
+ *
+ * @param headerName - The header name to check
+ * @returns True if it's a standard header
+ */
+const isStandardHeader = (headerName) => {
+  const standardHeaders = [
+    'from',
+    'to',
+    'cc',
+    'bcc',
+    'reply-to',
+    'subject',
+    'date',
+    'message-id',
+    'content-type',
+    'content-transfer-encoding',
+    'mime-version',
+    'x-priority',
+    'x-msmail-priority',
+    'importance',
+  ];
+
+  return standardHeaders.includes(headerName.toLowerCase());
+};
+
+module.exports = { convertMessage };
diff --git a/src/sendgrid/sendgrid-transport.js b/src/sendgrid/sendgrid-transport.js
new file mode 100644
index 0000000..9a4c46f
--- /dev/null
+++ b/src/sendgrid/sendgrid-transport.js
@@ -0,0 +1,237 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/sendgrid-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createSendGridConfig } = require('./config.js');
+const { SendGridApiError, SendGridHttpClient } = require('./http-client.js');
+const { convertMessage } = require('./message-converter.js');
+
+/**
+ * SendGrid transport implementation for sending emails via SendGrid API.
+ *
+ * This transport provides efficient email delivery using SendGrid's v3 HTTP API,
+ * with support for authentication, retry logic, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { SendGridTransport } from '@alexify/mailer/sendgrid';
+ *
+ * const transport = new SendGridTransport({
+ *   apiKey: 'your-sendgrid-api-key',
+ *   clickTracking: true,
+ *   openTracking: true
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
+ * ```
+ */
+class SendGridTransport {
+  id = 'sendgrid';
+
+  /**
+   * The resolved SendGrid configuration used by this transport.
+   */
+  config;
+
+  httpClient;
+
+  /**
+   * Creates a new SendGrid transport instance.
+   *
+   * @param config SendGrid configuration including API key and options.
+   */
+  constructor(config) {
+    this.config = createSendGridConfig(config);
+    this.httpClient = new SendGridHttpClient(this.config);
+  }
+
+  /**
+   * Sends a single email message via SendGrid API.
+   *
+   * This method converts the message to SendGrid format, makes an HTTP request
+   * to the SendGrid API, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent successfully');
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  async send(message, options) {
+    options?.signal?.throwIfAborted();
+
+    try {
+      const mailData = await convertMessage(message, this.config, options?.signal);
+
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendMessage(mailData, options?.signal);
+
+      // SendGrid returns 202 for successful sends, but doesn't provide a message ID
+      // in the response body. We'll generate a synthetic ID based on the response.
+      const messageId = this.extractMessageId(response);
+
+      return {
+        successful: true,
+        messageId,
+        provider: 'sendgrid',
+      };
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) {
+        throw error;
+      }
+
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      return createSendGridFailure(errorMessage, error);
+    }
+  }
+
+  /**
+   * Sends multiple email messages efficiently via SendGrid API.
+   *
+   * This method sends each message individually but provides a streamlined
+   * interface for processing multiple messages. Each message is sent as a
+   * separate API request to SendGrid.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    const isAsyncIterable = Symbol.asyncIterator in messages;
+
+    if (isAsyncIterable) {
+      for await (const message of messages) {
+        options?.signal?.throwIfAborted();
+        yield await this.send(message, options);
+      }
+    } else {
+      for (const message of messages) {
+        options?.signal?.throwIfAborted();
+        yield await this.send(message, options);
+      }
+    }
+  }
+
+  /**
+   * Extracts or generates a message ID from the SendGrid response.
+   *
+   * SendGrid doesn't return a message ID in the response body for successful sends,
+   * so we generate a synthetic ID based on timestamp and some response data.
+   *
+   * @param response The SendGrid API response.
+   * @returns A message ID string.
+   */
+  extractMessageId(response) {
+    // Check if there's an X-Message-Id header (SendGrid sometimes provides this)
+    const messageIdHeader =
+      response.headers?.['x-message-id'] || response.headers?.['X-Message-Id'];
+
+    if (messageIdHeader) {
+      return messageIdHeader;
+    }
+
+    // Generate a synthetic message ID based on timestamp
+    // This follows a similar pattern to what SendGrid might use
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 8);
+
+    return `sendgrid-${timestamp}-${random}`;
+  }
+}
+
+const createSendGridFailure = (message, error) => {
+  if (error instanceof SendGridApiError) {
+    return createFailedReceipt(message, {
+      provider: 'sendgrid',
+      statusCode: error.statusCode,
+      retryAfterMilliseconds: error.retryAfterMilliseconds,
+      providerDetails: error.errors,
+      attempts: error.attempts,
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'sendgrid',
+  });
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+module.exports = { SendGridTransport };
diff --git a/tests/e2e/sendgrid-transport.e2e.test.js b/tests/e2e/sendgrid-transport.e2e.test.js
new file mode 100644
index 0000000..ff30756
--- /dev/null
+++ b/tests/e2e/sendgrid-transport.e2e.test.js
@@ -0,0 +1,196 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/sendgrid-transport.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { SendGridTransport } = require('../../src/sendgrid/index.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const {
+  createTestMessage,
+  getTestConfig,
+  isE2eTestingEnabled,
+} = require('../helpers/sendgrid/test-config.js');
+
+// Only run E2E tests if environment is configured
+const describeE2E = isE2eTestingEnabled() ? describe : describe.skip;
+
+describeE2E('SendGridTransport E2E', () => {
+  let transport;
+
+  it('should initialize transport with test config', () => {
+    const config = getTestConfig();
+    transport = new SendGridTransport(config.sendgrid);
+    assert.ok(transport);
+  });
+
+  it('should send a simple text email', async () => {
+    const message = createTestMessage({
+      subject: '[E2E] Simple text email',
+      content: { text: 'This is a test email sent via SendGrid API' },
+    });
+
+    const receipt = await transport.send(message);
+
+    assert.equal(receipt.successful, true, 'Send should be successful');
+    if (receipt.successful) {
+      assert.ok(receipt.messageId, 'Should have a message ID');
+    }
+
+    if (receipt.successful) {
+      console.log(`Sent email with ID: ${receipt.messageId}`);
+    }
+  });
+
+  it('should send an HTML email', async () => {
+    const message = createTestMessage({
+      subject: '[E2E] HTML email',
+      content: {
+        text: 'This is the plain text version.',
+        html: '<h1>HTML Email</h1><p>This is a <strong>test email</strong> sent via SendGrid API.</p>',
+      },
+    });
+
+    const receipt = await transport.send(message);
+
+    assert.equal(receipt.successful, true, 'Send should be successful');
+    if (receipt.successful) {
+      assert.ok(receipt.messageId, 'Should have a message ID');
+    }
+
+    if (receipt.successful) {
+      console.log(`Sent HTML email with ID: ${receipt.messageId}`);
+    }
+  });
+
+  it('should send an email with attachments', async () => {
+    const textContent = new TextEncoder().encode('Hello from attachment!');
+
+    const message = createTestMessage({
+      subject: '[E2E] Email with attachment',
+      content: { text: 'This email has an attachment.' },
+      attachments: [
+        {
+          filename: 'test.txt',
+          contentType: 'text/plain',
+          content: Promise.resolve(textContent),
+          inline: false,
+          contentId: '',
+        },
+      ],
+    });
+
+    const receipt = await transport.send(message);
+
+    assert.equal(receipt.successful, true, 'Send should be successful');
+    if (receipt.successful) {
+      assert.ok(receipt.messageId, 'Should have a message ID');
+    }
+
+    if (receipt.successful) {
+      console.log(`Sent email with attachment, ID: ${receipt.messageId}`);
+    }
+  });
+
+  it('should send an email with high priority', async () => {
+    const message = createTestMessage({
+      subject: '[E2E] High priority email',
+      content: { text: 'This is a high priority email.' },
+      priority: 'high',
+    });
+
+    const receipt = await transport.send(message);
+
+    assert.equal(receipt.successful, true, 'Send should be successful');
+    if (receipt.successful) {
+      assert.ok(receipt.messageId, 'Should have a message ID');
+    }
+
+    if (receipt.successful) {
+      console.log(`Sent high priority email with ID: ${receipt.messageId}`);
+    }
+  });
+
+  it('should send an email with custom headers and tags', async () => {
+    const headers = new Headers();
+    headers.set('X-Test-Campaign', 'sendgrid-e2e');
+    headers.set('X-Test-ID', `test-${Date.now()}`);
+
+    const message = createTestMessage({
+      subject: '[E2E] Email with custom headers and tags',
+      content: { text: 'This email has custom headers and tags.' },
+      headers,
+      tags: ['e2e-test', 'custom-headers', 'sendgrid'],
+    });
+
+    const receipt = await transport.send(message);
+
+    assert.equal(receipt.successful, true, 'Send should be successful');
+    if (receipt.successful) {
+      assert.ok(receipt.messageId, 'Should have a message ID');
+    }
+
+    if (receipt.successful) {
+      console.log(`Sent email with custom headers/tags, ID: ${receipt.messageId}`);
+    }
+  });
+
+  it('should send multiple emails via sendMany', async () => {
+    const messages = [
+      createTestMessage({
+        subject: '[E2E] Batch email 1',
+        content: { text: 'This is the first email in the batch.' },
+      }),
+      createTestMessage({
+        subject: '[E2E] Batch email 2',
+        content: { text: 'This is the second email in the batch.' },
+      }),
+      createTestMessage({
+        subject: '[E2E] Batch email 3',
+        content: { text: 'This is the third email in the batch.' },
+      }),
+    ];
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 3);
+
+    for (let i = 0; i < receipts.length; i++) {
+      const receipt = receipts[i];
+      assert.equal(receipt.successful, true, `Batch email ${i + 1} should be successful`);
+
+      if (receipt.successful) {
+        assert.ok(receipt.messageId, `Batch email ${i + 1} should have a message ID`);
+
+        console.log(`Sent batch email ${i + 1} with ID: ${receipt.messageId}`);
+      }
+    }
+  });
+
+  it('should handle send timeout with AbortSignal', async () => {
+    const message = createTestMessage({
+      subject: '[E2E] Timeout test',
+      content: { text: 'This test should timeout.' },
+    });
+
+    const controller = new AbortController();
+
+    // Abort immediately to test signal handling
+    setTimeout(() => controller.abort(), 1);
+
+    try {
+      await transport.send(message, { signal: controller.signal });
+      assert.fail('Should have been aborted');
+    } catch (error) {
+      assert.ok(error instanceof Error);
+      // The error could be AbortError or a general error depending on timing
+      assert.ok(
+        error.name === 'AbortError' ||
+          error.message.includes('aborted') ||
+          error.message.includes('abort'),
+        `Expected abort-related error, got: ${error.message}`,
+      );
+    }
+  });
+});
diff --git a/tests/helpers/sendgrid/test-config.js b/tests/helpers/sendgrid/test-config.js
new file mode 100644
index 0000000..f64fe24
--- /dev/null
+++ b/tests/helpers/sendgrid/test-config.js
@@ -0,0 +1,67 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isEmailAddress } = require('../../../src/core/address.js');
+const process = require('node:process');
+
+const getTestConfig = () => {
+  if (!isE2eTestingEnabled()) {
+    throw new Error(
+      'E2E testing is not enabled. Set SENDGRID_API_KEY, SENDGRID_FROM, and SENDGRID_TO environment variables.',
+    );
+  }
+
+  return {
+    sendgrid: {
+      apiKey: process.env.SENDGRID_API_KEY,
+    },
+    testEmails: {
+      from: process.env.SENDGRID_FROM,
+      to: process.env.SENDGRID_TO,
+    },
+  };
+};
+
+function isE2eTestingEnabled() {
+  return !!(process.env.SENDGRID_API_KEY && process.env.SENDGRID_FROM && process.env.SENDGRID_TO);
+}
+
+const createTestMessage = (options = {}) => {
+  const config = getTestConfig();
+  const timestamp = Date.now();
+  const randomId = Math.random().toString(36).substr(2, 9);
+
+  const senderEmail = options.senderEmail ?? config.testEmails.from;
+  const recipientEmail = options.recipientEmail ?? config.testEmails.to;
+
+  if (!isEmailAddress(senderEmail)) {
+    throw new Error(`Invalid sender email address: ${senderEmail}`);
+  }
+  if (!isEmailAddress(recipientEmail)) {
+    throw new Error(`Invalid recipient email address: ${recipientEmail}`);
+  }
+
+  return {
+    sender: {
+      name: options.senderName ?? 'SendGrid E2E Test Sender',
+      address: senderEmail,
+    },
+    recipients: options.recipients ?? [
+      {
+        name: 'E2E Test Recipient',
+        address: recipientEmail,
+      },
+    ],
+    ccRecipients: options.ccRecipients ?? [],
+    bccRecipients: options.bccRecipients ?? [],
+    replyRecipients: options.replyRecipients ?? [],
+    subject: options.subject ?? `[SendGrid E2E Test] ${timestamp}`,
+    content: options.content ?? { text: `Test message content ${randomId}` },
+    attachments: options.attachments ?? [],
+    priority: options.priority ?? 'normal',
+    tags: options.tags ?? ['e2e-test'],
+    headers: options.headers ?? new Headers(),
+  };
+};
+
+module.exports = { getTestConfig, isE2eTestingEnabled, createTestMessage };
diff --git a/tests/types/sendgrid.test-d.ts b/tests/types/sendgrid.test-d.ts
new file mode 100644
index 0000000..afcfd78
--- /dev/null
+++ b/tests/types/sendgrid.test-d.ts
@@ -0,0 +1,23 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import {
+  SendGridApiError,
+  SendGridTransport,
+  type SendGridConfig,
+} from '../../src/sendgrid/index.js';
+
+const transport = new SendGridTransport({ apiKey: 'SG.key', clickTracking: false });
+expectAssignable<Transport<'sendgrid'>>(transport);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'sendgrid'>>>(transport.send(message));
+expectType<AsyncIterable<Receipt<'sendgrid'>>>(transport.sendMany([message]));
+
+expectAssignable<SendGridConfig>({ apiKey: 'SG.key', timeout: 5000, retries: 2 });
+expectAssignable<Error>(new SendGridApiError('Bad request', 400));
+expectError(new SendGridTransport({ retries: 1 }));
diff --git a/tests/unit/sendgrid-attachment-content.test.js b/tests/unit/sendgrid-attachment-content.test.js
new file mode 100644
index 0000000..453cffe
--- /dev/null
+++ b/tests/unit/sendgrid-attachment-content.test.js
@@ -0,0 +1,84 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/attachment-content.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createMessage } = require('../../src/core/message.js');
+const { createSendGridConfig } = require('../../src/sendgrid/config.js');
+const { convertMessage } = require('../../src/sendgrid/message-converter.js');
+
+test('closes sibling sources when one attachment conversion fails', async () => {
+  let siblingSignal;
+  const failure = new TypeError('Read failed.');
+  const attachment = {
+    filename: 'a',
+    contentId: 'a',
+    inline: false,
+    contentType: 'application/octet-stream',
+  };
+  const mail = createMessage({
+    from: 'from@example.com',
+    to: 'to@example.com',
+    subject: 'Test',
+    content: { text: 'Test' },
+    attachments: [
+      {
+        ...attachment,
+        content: async function* () {
+          yield new Uint8Array([1]);
+          throw failure;
+        },
+      },
+      {
+        ...attachment,
+        content: (signal) => {
+          siblingSignal = signal;
+          return {
+            [Symbol.asyncIterator]() {
+              return { next: () => new Promise(() => {}) };
+            },
+          };
+        },
+      },
+    ],
+  });
+  await assert.rejects(
+    convertMessage(mail, createSendGridConfig({ apiKey: 'SG.test' })),
+    (error) => error === failure,
+  );
+  assert.ok(siblingSignal?.aborted);
+});
+
+test('collects large replayable attachments without argument overflow', async () => {
+  const bytes = new Uint8Array(256 * 1024).fill(123);
+  const config = createSendGridConfig({ apiKey: 'SG.test' });
+  for (const content of [
+    new Blob([bytes]),
+    async function* () {
+      yield bytes;
+    },
+  ]) {
+    const result = await convertMessage(
+      createMessage({
+        from: 'from@example.com',
+        to: 'to@example.com',
+        subject: 'Test',
+        content: { text: 'Test' },
+        attachments: {
+          inline: false,
+          filename: 'large.bin',
+          content,
+          contentId: 'large',
+          contentType: 'application/octet-stream',
+        },
+      }),
+      config,
+    );
+    const encoded = result.attachments?.[0].content;
+    assert.ok(encoded);
+    assert.deepEqual(
+      Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0)),
+      bytes,
+    );
+  }
+});
diff --git a/tests/unit/sendgrid-config.test.js b/tests/unit/sendgrid-config.test.js
new file mode 100644
index 0000000..1b871d5
--- /dev/null
+++ b/tests/unit/sendgrid-config.test.js
@@ -0,0 +1,69 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { strict: assert } = require('node:assert');
+const { describe, it } = require('node:test');
+const { createSendGridConfig } = require('../../src/sendgrid/config.js');
+
+describe('SendGridConfig', () => {
+  it('should create a config with default values', () => {
+    const config = {
+      apiKey: 'SG.test-key',
+    };
+
+    const resolved = createSendGridConfig(config);
+
+    assert.equal(resolved.apiKey, 'SG.test-key');
+    assert.equal(resolved.baseUrl, 'https://api.sendgrid.com/v3');
+    assert.equal(resolved.timeout, 30000);
+    assert.equal(resolved.retries, 3);
+    assert.equal(resolved.validateSsl, true);
+    assert.deepEqual(resolved.headers, {});
+    assert.equal(resolved.clickTracking, true);
+    assert.equal(resolved.openTracking, true);
+    assert.equal(resolved.subscriptionTracking, false);
+    assert.equal(resolved.googleAnalytics, false);
+  });
+
+  it('should create a config with custom values', () => {
+    const config = {
+      apiKey: 'SG.test-key',
+      baseUrl: 'https://custom.sendgrid.com/v3',
+      timeout: 15000,
+      retries: 5,
+      validateSsl: false,
+      headers: { 'X-Custom': 'value' },
+      clickTracking: false,
+      openTracking: false,
+      subscriptionTracking: true,
+      googleAnalytics: true,
+    };
+
+    const resolved = createSendGridConfig(config);
+
+    assert.equal(resolved.apiKey, 'SG.test-key');
+    assert.equal(resolved.baseUrl, 'https://custom.sendgrid.com/v3');
+    assert.equal(resolved.timeout, 15000);
+    assert.equal(resolved.retries, 5);
+    assert.equal(resolved.validateSsl, false);
+    assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
+    assert.equal(resolved.clickTracking, false);
+    assert.equal(resolved.openTracking, false);
+    assert.equal(resolved.subscriptionTracking, true);
+    assert.equal(resolved.googleAnalytics, true);
+  });
+
+  it('should preserve original config immutability', () => {
+    const config = {
+      apiKey: 'SG.test-key',
+    };
+
+    const resolved = createSendGridConfig(config);
+
+    // Modify resolved config
+    resolved.timeout = 60000;
+
+    // Original config should remain unchanged
+    assert.equal(config.timeout, undefined);
+  });
+});
diff --git a/tests/unit/sendgrid-message-converter.test.js b/tests/unit/sendgrid-message-converter.test.js
new file mode 100644
index 0000000..973f82d
--- /dev/null
+++ b/tests/unit/sendgrid-message-converter.test.js
@@ -0,0 +1,446 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/message-converter.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const { SendGridTransport } = require('../../src/sendgrid/index.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { convertMessage } = require('../../src/sendgrid/message-converter.js');
+
+describe('convertMessage', () => {
+  const transport = new SendGridTransport({
+    apiKey: 'SG.test-key',
+  });
+  const config = transport.config;
+
+  it('should convert a basic text message', async () => {
+    const message = {
+      sender: { address: 'from@example.com', name: 'Sender Name' },
+      recipients: [{ address: 'to@example.com', name: 'Recipient Name' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.from.email, 'from@example.com');
+    assert.equal(result.from.name, 'Sender Name');
+    assert.equal(result.personalizations[0].to[0].email, 'to@example.com');
+    assert.equal(result.personalizations[0].to[0].name, 'Recipient Name');
+    assert.equal(result.personalizations[0].subject, 'Test Subject');
+    assert.equal(result.content[0].type, 'text/plain');
+    assert.equal(result.content[0].value, 'Hello, World!');
+  });
+
+  it('should convert a message with HTML content', async () => {
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: {
+        text: 'Hello, World!',
+        html: '<h1>Hello, World!</h1>',
+      },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.content.length, 2);
+    assert.equal(result.content[0].type, 'text/plain');
+    assert.equal(result.content[0].value, 'Hello, World!');
+    assert.equal(result.content[1].type, 'text/html');
+    assert.equal(result.content[1].value, '<h1>Hello, World!</h1>');
+  });
+
+  it('should handle CC and BCC recipients', async () => {
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [{ address: 'cc@example.com' }],
+      bccRecipients: [{ address: 'bcc@example.com' }],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.personalizations[0].cc[0].email, 'cc@example.com');
+    assert.equal(result.personalizations[0].bcc[0].email, 'bcc@example.com');
+  });
+
+  it('should handle reply-to recipients', async () => {
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [{ address: 'reply@example.com' }],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.reply_to.email, 'reply@example.com');
+  });
+
+  it('should handle multiple reply-to recipients', async () => {
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [{ address: 'reply1@example.com' }, { address: 'reply2@example.com' }],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.reply_to_list.length, 2);
+    assert.equal(result.reply_to_list[0].email, 'reply1@example.com');
+    assert.equal(result.reply_to_list[1].email, 'reply2@example.com');
+  });
+
+  it('should handle priority settings', async () => {
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'high',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.headers['X-Priority'], '1');
+    assert.equal(result.headers['X-MSMail-Priority'], 'High');
+    assert.equal(result.headers['Importance'], 'High');
+  });
+
+  it('should handle tags as categories', async () => {
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'normal',
+      tags: ['newsletter', 'marketing'],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.deepEqual(result.categories, ['newsletter', 'marketing']);
+  });
+
+  it('should handle custom headers', async () => {
+    const headers = new Headers();
+    headers.set('X-Custom-Header', 'custom-value');
+    headers.set('X-Campaign-ID', 'campaign-123');
+
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers,
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.headers['x-custom-header'], 'custom-value');
+    assert.equal(result.headers['x-campaign-id'], 'campaign-123');
+  });
+
+  it('should handle tracking settings', async () => {
+    const transportWithTracking = new SendGridTransport({
+      apiKey: 'SG.test-key',
+      clickTracking: false,
+      openTracking: true,
+      subscriptionTracking: true,
+      googleAnalytics: true,
+    });
+    const configWithTracking = transportWithTracking.config;
+
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, configWithTracking);
+
+    assert.equal(result.tracking_settings.click_tracking.enable, false);
+    assert.equal(result.tracking_settings.open_tracking.enable, true);
+    assert.equal(result.tracking_settings.subscription_tracking.enable, true);
+    assert.equal(result.tracking_settings.ganalytics.enable, true);
+  });
+
+  it('should handle attachments', async () => {
+    const textContent = new TextEncoder().encode('Hello, attachment!');
+
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [
+        {
+          filename: 'test.txt',
+          contentType: 'text/plain',
+          content: Promise.resolve(textContent),
+          inline: false,
+          contentId: '',
+        },
+      ],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.attachments.length, 1);
+    assert.equal(result.attachments[0].filename, 'test.txt');
+    assert.equal(result.attachments[0].type, 'text/plain');
+    assert.equal(result.attachments[0].disposition, 'attachment');
+    // Base64 encoded "Hello, attachment!"
+    assert.equal(result.attachments[0].content, btoa('Hello, attachment!'));
+  });
+
+  it('should handle inline attachments', async () => {
+    const textContent = new TextEncoder().encode('Inline content');
+
+    const message = {
+      sender: { address: 'from@example.com' },
+      recipients: [{ address: 'to@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Hello, World!' },
+      attachments: [
+        {
+          filename: 'inline.txt',
+          contentType: 'text/plain',
+          content: Promise.resolve(textContent),
+          inline: true,
+          contentId: 'inline-123',
+        },
+      ],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.attachments.length, 1);
+    assert.equal(result.attachments[0].disposition, 'inline');
+    assert.equal(result.attachments[0].content_id, 'inline-123');
+  });
+});
+
+const threadingConfig = new SendGridTransport({ apiKey: 'SG.test-key' }).config;
+
+const headerOf = (headers, name) =>
+  Object.entries(headers)
+    .filter(([key]) => key.toLowerCase() === name.toLowerCase())
+    .map(([, value]) => value);
+
+describe('convertMessage() reply threading', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Re: Your request',
+    content: { text: 'Thanks for getting in touch.' },
+  };
+
+  it('writes the typed threading fields', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: '122@example.com',
+      references: ['120@example.com', '121@example.com'],
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<122@example.com>']);
+    assert.deepEqual(headerOf(result, 'References'), ['<120@example.com> <121@example.com>']);
+  });
+
+  it('prefers a typed field over a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: ['typed@example.com'],
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<typed@example.com>']);
+  });
+
+  it('lets an empty list suppress a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: [],
+      references: [],
+      headers: {
+        'In-Reply-To': '<custom@example.com>',
+        References: '<custom@example.com>',
+      },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), []);
+    assert.deepEqual(headerOf(result, 'References'), []);
+  });
+
+  it('lets a custom header through when the field is unset', async () => {
+    const message = createMessage({
+      ...base,
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<custom@example.com>']);
+  });
+});
+
+const CALENDAR_ICS =
+  [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'SUMMARY:Lunch',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+/** The invitation content as the providers below carry it: Base64. */
+const CALENDAR_BASE64 = btoa(CALENDAR_ICS);
+
+describe('convertMessage() calendar', () => {
+  const transport = new SendGridTransport({ apiKey: 'SG.test-key' });
+  const config = transport.config;
+
+  const invitation = (extra = {}) =>
+    createMessage({
+      from: 'organizer@example.com',
+      to: 'attendee@example.net',
+      subject: 'Lunch',
+      content: { text: 'Lunch on Wednesday.' },
+      calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+      ...extra,
+    });
+
+  it('should carry the calendar as an invite.ics attachment', async () => {
+    const mail = await convertMessage(invitation(), config);
+
+    assert.equal(mail.attachments?.length, 1);
+    assert.equal(mail.attachments?.[0].filename, 'invite.ics');
+    assert.equal(mail.attachments?.[0].type, 'text/calendar; charset=utf-8; method=REQUEST');
+    assert.equal(mail.attachments?.[0].content, CALENDAR_BASE64);
+    // An empty content ID keeps the part an ordinary attachment.
+    assert.equal(mail.attachments?.[0].disposition, 'attachment');
+  });
+
+  it('should place the invitation ahead of the other attachments', async () => {
+    const mail = await convertMessage(
+      invitation({
+        attachments: [
+          {
+            inline: false,
+            filename: 'agenda.txt',
+            content: new TextEncoder().encode('agenda'),
+            contentType: 'text/plain',
+            contentId: '',
+          },
+        ],
+      }),
+      config,
+    );
+
+    assert.deepEqual(
+      mail.attachments?.map((attachment) => attachment.filename),
+      ['invite.ics', 'agenda.txt'],
+    );
+  });
+
+  it('should reject calendar content that never passed createMessage()', async () => {
+    const message = {
+      sender: { address: 'organizer@example.com' },
+      recipients: [{ address: 'attendee@example.net' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Lunch',
+      content: { text: 'Lunch.' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+      calendar: { method: 'REQUEST', content: 'not a calendar' },
+    };
+
+    await assert.rejects(() => convertMessage(message, config), {
+      name: 'TypeError',
+    });
+  });
+});
diff --git a/tests/unit/sendgrid-transport.test.js b/tests/unit/sendgrid-transport.test.js
new file mode 100644
index 0000000..541204e
--- /dev/null
+++ b/tests/unit/sendgrid-transport.test.js
@@ -0,0 +1,295 @@
+// Ported from upyo v0.7.0 (packages/sendgrid/src/sendgrid-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { SendGridTransport } = require('../../src/sendgrid/index.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+
+let fetchMockChain = Promise.resolve();
+
+const withMockedFetch = async (fetchMock, callback) => {
+  const previous = fetchMockChain;
+  let release = () => {};
+  fetchMockChain = new Promise((resolve) => {
+    release = resolve;
+  });
+  await previous;
+
+  const originalFetch = globalThis.fetch;
+  try {
+    globalThis.fetch = fetchMock;
+    return await callback();
+  } finally {
+    globalThis.fetch = originalFetch;
+    release();
+  }
+};
+
+describe('SendGridTransport', { concurrency: false }, () => {
+  const basicMessage = {
+    sender: { address: 'from@example.com' },
+    recipients: [{ address: 'to@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test content' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+  };
+
+  it('should create a transport instance', () => {
+    const transport = new SendGridTransport({
+      apiKey: 'SG.test-key',
+    });
+    assert.ok(transport);
+    assert.equal(transport.config.apiKey, 'SG.test-key');
+    assert.equal(transport.config.baseUrl, 'https://api.sendgrid.com/v3');
+    assert.equal(transport.config.timeout, 30000);
+    assert.equal(transport.config.retries, 3);
+  });
+
+  it('should create config with custom values', () => {
+    const transport = new SendGridTransport({
+      apiKey: 'SG.custom-key',
+      baseUrl: 'https://custom.sendgrid.com/v3',
+      timeout: 5000,
+      retries: 1,
+      clickTracking: false,
+      openTracking: false,
+    });
+
+    assert.equal(transport.config.apiKey, 'SG.custom-key');
+    assert.equal(transport.config.baseUrl, 'https://custom.sendgrid.com/v3');
+    assert.equal(transport.config.timeout, 5000);
+    assert.equal(transport.config.retries, 1);
+    assert.equal(transport.config.clickTracking, false);
+    assert.equal(transport.config.openTracking, false);
+  });
+
+  it('should handle abort signal', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const transport = new SendGridTransport({
+      apiKey: 'SG.test-key',
+    });
+
+    try {
+      await transport.send(basicMessage, { signal: controller.signal });
+      assert.fail('Should have thrown AbortError');
+    } catch (error) {
+      assert.ok(error instanceof Error);
+      assert.ok(error.name === 'AbortError' || error.message.includes('aborted'));
+    }
+  });
+
+  it('should reject caller aborts during fetch', async () => {
+    const controller = new AbortController();
+
+    await withMockedFetch(
+      (_url, options) =>
+        new Promise((_resolve, reject) => {
+          if (options?.signal == null) {
+            reject(new TypeError('Expected fetch to receive an AbortSignal.'));
+            return;
+          }
+
+          options.signal.addEventListener(
+            'abort',
+            () => {
+              reject(new DOMException('The operation was aborted.', 'AbortError'));
+            },
+            { once: true },
+          );
+          setTimeout(() => controller.abort(), 0);
+        }),
+      async () => {
+        const transport = new SendGridTransport({
+          apiKey: 'SG.test-key',
+          retries: 0,
+        });
+
+        await assert.rejects(
+          () => transport.send(basicMessage, { signal: controller.signal }),
+          (error) => error instanceof Error && error.name === 'AbortError',
+        );
+      },
+    );
+  });
+
+  it('should reject custom caller abort reasons during final fetch', async () => {
+    const controller = new AbortController();
+    const reason = 'custom abort reason';
+
+    await withMockedFetch(
+      (_url, options) =>
+        new Promise((_resolve, reject) => {
+          if (options?.signal == null) {
+            reject(new TypeError('Expected fetch to receive an AbortSignal.'));
+            return;
+          }
+
+          options.signal.addEventListener(
+            'abort',
+            () => {
+              reject(options.signal?.reason);
+            },
+            { once: true },
+          );
+          setTimeout(() => controller.abort(reason), 0);
+        }),
+      async () => {
+        const transport = new SendGridTransport({
+          apiKey: 'SG.test-key',
+          retries: 0,
+        });
+
+        await assert.rejects(
+          () => transport.send(basicMessage, { signal: controller.signal }),
+          (error) => error === reason,
+        );
+      },
+    );
+  });
+
+  it('should validate message structure in sendMany', async () => {
+    const transport = new SendGridTransport({
+      apiKey: 'SG.test-key',
+    });
+
+    const messages = [basicMessage, basicMessage];
+
+    // sendMany는 AsyncIterable을 반환해야 함
+    const iterator = transport.sendMany(messages);
+    assert.ok(Symbol.asyncIterator in iterator);
+
+    // AbortController로 즉시 중단하여 실제 네트워크 요청 방지
+    const controller = new AbortController();
+    controller.abort();
+
+    try {
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages, {
+        signal: controller.signal,
+      })) {
+        receipts.push(receipt);
+      }
+      assert.fail('Should have thrown AbortError');
+    } catch (error) {
+      assert.ok(error instanceof Error);
+      assert.ok(error.name === 'AbortError' || error.message.includes('aborted'));
+    }
+  });
+
+  it('should expose structured API error metadata', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify({
+              message: 'Too Many Requests',
+              errors: [
+                {
+                  message: 'Rate limit exceeded',
+                  field: 'personalizations.0.to',
+                  help: 'https://sendgrid.com/docs/',
+                },
+              ],
+            }),
+            {
+              status: 429,
+              headers: { 'Retry-After': '30' },
+            },
+          ),
+        ),
+      async () => {
+        const transport = new SendGridTransport({
+          apiKey: 'SG.test-key',
+          retries: 0,
+        });
+
+        const receipt = await transport.send(basicMessage);
+
+        assert.equal(receipt.successful, false);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, ['Too Many Requests']);
+          assert.equal(receipt.provider, 'sendgrid');
+          assert.equal(receipt.retryable, true);
+          assert.equal(receipt.attempts, 1);
+          assert.equal(receipt.errors?.[0]?.category, 'rate-limit');
+          assert.equal(receipt.errors?.[0]?.code, 'http.429');
+          assert.equal(receipt.errors?.[0]?.statusCode, 429);
+          assert.equal(receipt.errors?.[0]?.retryAfterMilliseconds, 30_000);
+          assert.deepEqual(receipt.errors?.[0]?.providerDetails, [
+            {
+              message: 'Rate limit exceeded',
+              field: 'personalizations.0.to',
+              help: 'https://sendgrid.com/docs/',
+            },
+          ]);
+        }
+      },
+    );
+  });
+
+  it('should expose structured network error metadata', async () => {
+    await withMockedFetch(
+      () => {
+        throw new TypeError('fetch failed');
+      },
+      async () => {
+        const transport = new SendGridTransport({
+          apiKey: 'SG.test-key',
+          retries: 0,
+        });
+
+        const receipt = await transport.send(basicMessage);
+
+        assert.equal(receipt.successful, false);
+        if (!receipt.successful) {
+          assert.equal(receipt.provider, 'sendgrid');
+          assert.equal(receipt.retryable, true);
+          assert.equal(receipt.errors?.[0]?.category, 'network');
+        }
+      },
+    );
+  });
+
+  it('should reject caller aborts during retry backoff', async () => {
+    const controller = new AbortController();
+    const reason = new Error('Stop retrying.');
+    let attempts = 0;
+
+    await withMockedFetch(
+      () => {
+        attempts++;
+        setTimeout(() => controller.abort(reason), 0);
+        return Promise.resolve(new Response('Server Error', { status: 500 }));
+      },
+      async () => {
+        const transport = new SendGridTransport({
+          apiKey: 'SG.test-key',
+          retries: 1,
+        });
+
+        const startedAt = Date.now();
+        await assert.rejects(
+          () => transport.send(basicMessage, { signal: controller.signal }),
+          (error) => error === reason,
+        );
+
+        assert.equal(attempts, 1);
+        assert.ok(Date.now() - startedAt < 500);
+      },
+    );
+  });
+
+  // Upstream's "falls back when AbortSignal.any is unavailable" is not ported: Node 22 always
+  // has AbortSignal.any, and the core keeps no fallback without it.
+
+  // 네트워크 테스트는 E2E 테스트 파일에서 환경 변수와 함께 실행
+  // src/sendgrid-transport.e2e.test.ts에서 실제 SendGrid API 연동 테스트 수행
+});
diff --git a/tests/unit/sendgrid.test.js b/tests/unit/sendgrid.test.js
new file mode 100644
index 0000000..6440f5d
--- /dev/null
+++ b/tests/unit/sendgrid.test.js
@@ -0,0 +1,96 @@
+// Paths of the ported SendGrid transport (src/sendgrid/) that upstream reaches
+// only through its e2e suite, against a stubbed fetch.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { SendGridTransport } = require('../../src/sendgrid/index.js');
+
+const message = (extra = {}) =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+    ...extra,
+  });
+const accepted = (headers = {}) => new Response('', { status: 202, headers });
+const hang = (url, init) =>
+  new Promise((resolve, reject) => {
+    init.signal.addEventListener('abort', () => reject(init.signal.reason));
+  });
+
+test('SendGrid: a 202 is a success, with the X-Message-Id or a generated id', async (t) => {
+  let request;
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    request = { headers: new Headers(init.headers), body: JSON.parse(init.body) };
+    return accepted({ 'X-Message-Id': 'sg-1' });
+  });
+  const transport = new SendGridTransport({ apiKey: 'key', headers: { 'X-Custom': 'yes' } });
+  assert.deepStrictEqual(await transport.send(message({ priority: 'low' })), {
+    successful: true,
+    messageId: 'sg-1',
+    provider: 'sendgrid',
+  });
+  assert.strictEqual(request.headers.get('x-custom'), 'yes');
+  assert.deepStrictEqual(
+    {
+      priority: request.body.headers['X-Priority'],
+      importance: request.body.headers.Importance,
+    },
+    { priority: '5', importance: 'Low' },
+  );
+
+  t.mock.restoreAll();
+  t.mock.method(globalThis, 'fetch', async () => accepted());
+  const generated = await transport.send(message());
+  assert.match(generated.messageId, /^sendgrid-\d+-\w+$/);
+});
+
+test('SendGrid: sendMany sends arrays and async iterables one by one', async (t) => {
+  let calls = 0;
+  t.mock.method(globalThis, 'fetch', async () => accepted({ 'X-Message-Id': `m${++calls}` }));
+  const transport = new SendGridTransport({ apiKey: 'key' });
+  const ids = [];
+  for await (const receipt of transport.sendMany([message(), message()])) {
+    ids.push(receipt.messageId);
+  }
+  const iterable = async function* () {
+    yield message();
+  };
+  for await (const receipt of transport.sendMany(iterable())) ids.push(receipt.messageId);
+  assert.deepStrictEqual(ids, ['m1', 'm2', 'm3']);
+});
+
+test('SendGrid: error bodies, retries, timeouts and aborts', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => new Response('Oops', { status: 400 }));
+  const transport = new SendGridTransport({ apiKey: 'key', retries: 0 });
+  assert.deepStrictEqual((await transport.send(message())).errorMessages, ['Oops']);
+
+  t.mock.restoreAll();
+  let calls = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    calls++;
+    return new Response('', { status: 503 });
+  });
+  const retried = await new SendGridTransport({ apiKey: 'key', retries: 1 }).send(message());
+  assert.strictEqual(calls, 2);
+  assert.deepStrictEqual(retried.errorMessages, ['HTTP 503']);
+
+  t.mock.restoreAll();
+  t.mock.method(globalThis, 'fetch', hang);
+  const slow = await new SendGridTransport({ apiKey: 'key', retries: 0, timeout: 20 }).send(
+    message(),
+  );
+  assert.deepStrictEqual(slow.errorMessages, ['SendGrid API request timed out after 20 ms.']);
+
+  t.mock.restoreAll();
+  t.mock.method(globalThis, 'fetch', async () => new Response('', { status: 503 }));
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), 30);
+  await assert.rejects(
+    new SendGridTransport({ apiKey: 'key', retries: 1 }).send(message(), {
+      signal: controller.signal,
+    }),
+    { name: 'AbortError' },
+  );
+});

From d1a3bb5bf8ae219a21c5af145ef07bddf7eb6fb5 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:12:28 +0300
Subject: [PATCH 009/158] feat(mailgun): port the Mailgun transport from upyo
 0.7.0

./mailgun exports MailgunTransport and MailgunApiError: the Messages API
over fetch with multipart form data, US and EU regions, attachments and
inline parts, tags, tracking options, retries and a request timeout.

Upstream's unit suites are ported and the e2e suite goes to tests/e2e.
tests/unit/mailgun.test.js covers an unknown region, custom headers, a 2xx
without JSON and sendMany over an async iterable. The inline bug of
upstream (sent under the filename, not the content id) is kept and listed
in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   2 +-
 package.json                                  |   4 +
 src/mailgun/config.js                         |  51 +
 src/mailgun/http-client.js                    | 239 +++++
 src/mailgun/index.d.ts                        | 269 +++++
 src/mailgun/index.js                          |   8 +
 src/mailgun/mailgun-transport.js              | 206 ++++
 src/mailgun/message-converter.js              | 190 ++++
 tests/e2e/mailgun-transport.e2e.test.js       | 380 +++++++
 .../helpers/mailgun/mailgun-delivery-utils.js | 147 +++
 tests/helpers/mailgun/test-config.js          |  74 ++
 tests/types/mailgun.test-d.ts                 |  20 +
 tests/unit/mailgun-config.test.js             |  72 ++
 tests/unit/mailgun-message-converter.test.js  | 456 +++++++++
 tests/unit/mailgun-transport.test.js          | 929 ++++++++++++++++++
 tests/unit/mailgun.test.js                    |  54 +
 16 files changed, 3100 insertions(+), 1 deletion(-)
 create mode 100644 src/mailgun/config.js
 create mode 100644 src/mailgun/http-client.js
 create mode 100644 src/mailgun/index.d.ts
 create mode 100644 src/mailgun/index.js
 create mode 100644 src/mailgun/mailgun-transport.js
 create mode 100644 src/mailgun/message-converter.js
 create mode 100644 tests/e2e/mailgun-transport.e2e.test.js
 create mode 100644 tests/helpers/mailgun/mailgun-delivery-utils.js
 create mode 100644 tests/helpers/mailgun/test-config.js
 create mode 100644 tests/types/mailgun.test-d.ts
 create mode 100644 tests/unit/mailgun-config.test.js
 create mode 100644 tests/unit/mailgun-message-converter.test.js
 create mode 100644 tests/unit/mailgun-transport.test.js
 create mode 100644 tests/unit/mailgun.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2c45056..b7d4cc3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 469770f..492afe2 100644
--- a/package.json
+++ b/package.json
@@ -44,6 +44,10 @@
       "types": "./src/sendgrid/index.d.ts",
       "default": "./src/sendgrid/index.js"
     },
+    "./mailgun": {
+      "types": "./src/mailgun/index.d.ts",
+      "default": "./src/mailgun/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
diff --git a/src/mailgun/config.js b/src/mailgun/config.js
new file mode 100644
index 0000000..312d9ea
--- /dev/null
+++ b/src/mailgun/config.js
@@ -0,0 +1,51 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved Mailgun configuration by applying default values to optional fields.
+ *
+ * This function takes a partial Mailgun configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the Mailgun transport.
+ *
+ * @param config - The Mailgun configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ * @internal
+ */
+const createMailgunConfig = (config) => {
+  const region = config.region ?? 'us';
+  const baseUrl = config.baseUrl ?? getDefaultBaseUrl(region);
+
+  return {
+    apiKey: config.apiKey,
+    domain: config.domain,
+    region,
+    baseUrl,
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    validateSsl: config.validateSsl ?? true,
+    headers: config.headers ?? {},
+    tracking: config.tracking ?? true,
+    clickTracking: config.clickTracking ?? true,
+    openTracking: config.openTracking ?? true,
+  };
+};
+
+/**
+ * Gets the default base URL for a given Mailgun region.
+ *
+ * @param region - The Mailgun region
+ * @returns The default base URL for the region
+ */
+const getDefaultBaseUrl = (region) => {
+  switch (region) {
+    case 'us':
+      return 'https://api.mailgun.net/v3';
+    case 'eu':
+      return 'https://api.eu.mailgun.net/v3';
+    default:
+      throw new Error(`Unsupported region: ${region}`);
+  }
+};
+
+module.exports = { createMailgunConfig };
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
new file mode 100644
index 0000000..b9b5d59
--- /dev/null
+++ b/src/mailgun/http-client.js
@@ -0,0 +1,239 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/http-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { parseRetryAfter } = require('../core/receipt.js');
+
+/**
+ * HTTP client wrapper for Mailgun API requests.
+ *
+ * This class handles authentication, request formatting, error handling,
+ * and retry logic for Mailgun API calls.
+ */
+class MailgunHttpClient {
+  config;
+
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Sends a message via Mailgun API.
+   *
+   * @param formData The form data to send to Mailgun.
+   * @param signal Optional AbortSignal for cancellation.
+   * @returns Promise that resolves to the Mailgun response.
+   */
+  sendMessage(formData, signal) {
+    const url = `${this.config.baseUrl}/${this.config.domain}/messages`;
+
+    return this.makeRequest(url, {
+      method: 'POST',
+      body: formData,
+      signal,
+    });
+  }
+
+  /**
+   * Makes an HTTP request to Mailgun API with retry logic.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the parsed response.
+   * @throws {MailgunApiError} If Mailgun returns an error response or all
+   *                           retry attempts are exhausted.
+   */
+  async makeRequest(url, options) {
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      try {
+        const response = await this.fetchWithAuth(url, options);
+        const text = await response.text();
+
+        if (!response.ok) {
+          let errorMessage;
+          try {
+            // Try to parse the error message from the JSON body
+            errorMessage = JSON.parse(text)?.message;
+          } catch {
+            // Ignore if JSON parsing fails, as the body may be non-JSON
+          }
+
+          // Fallback logic for creating a meaningful error message.
+          // 1. Use the parsed `errorMessage` if available.
+          // 2. Otherwise, use the raw `text` response.
+          // 3. If the raw `text` is also empty, fall back to the HTTP status.
+          // Using `||` is intentional here to treat empty strings as falsy
+          // and ensure a non-empty error message for the tests.
+          throw new MailgunApiError(
+            errorMessage || truncateErrorBody(text) || `HTTP ${response.status}`,
+            response.status,
+            parseRetryAfter(response.headers.get('Retry-After')),
+            attempt + 1,
+          );
+        }
+
+        try {
+          return JSON.parse(text);
+        } catch (jsonError) {
+          // This handles cases where the request was successful (e.g., 2xx status)
+          // but the response body is not valid JSON.
+          // oxlint-disable-next-line preserve-caught-error -- upstream
+          throw new Error(
+            `Successfully received response but failed to parse JSON: ${jsonError.message}`,
+          );
+        }
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (options.signal?.aborted) {
+          throw createAbortError(options.signal);
+        }
+
+        // Don't retry caller cancellation.
+        if (isAbortError(error)) {
+          throw error;
+        }
+
+        // Don't retry on client errors (4xx) or if it's the last attempt
+        if (
+          error instanceof MailgunApiError &&
+          error.statusCode &&
+          error.statusCode >= 400 &&
+          error.statusCode < 500
+        ) {
+          throw error;
+        }
+
+        if (attempt === this.config.retries) {
+          if (lastError instanceof MailgunApiError) {
+            throw lastError;
+          }
+          throw new MailgunApiError(lastError.message, undefined, undefined, attempt + 1);
+        }
+
+        // Wait before retrying (exponential backoff)
+        const delay = Math.pow(2, attempt) * 1000;
+        await sleep(delay, options.signal);
+      }
+    }
+
+    throw lastError || new Error('Request failed after all retries');
+  }
+
+  /**
+   * Makes a fetch request with Mailgun authentication.
+   *
+   * @param url The URL to make the request to.
+   * @param options Fetch options.
+   * @returns Promise that resolves to the fetch response.
+   * @throws {Error} If the configured request timeout is reached.
+   * @throws {DOMException} If the caller aborts the request.
+   */
+  async fetchWithAuth(url, options) {
+    const headers = new Headers(options.headers);
+
+    // Add authentication header
+    const auth = btoa(`api:${this.config.apiKey}`);
+    headers.set('Authorization', `Basic ${auth}`);
+
+    // Add custom headers from config
+    for (const [key, value] of Object.entries(this.config.headers)) {
+      headers.set(key, value);
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    const combinedSignal = combineSignals(controller.signal, options.signal);
+
+    try {
+      return await globalThis.fetch(url, {
+        ...options,
+        headers,
+        signal: combinedSignal.signal,
+      });
+    } catch (error) {
+      if (isAbortError(error) && controller.signal.aborted && !options.signal?.aborted) {
+        // oxlint-disable-next-line preserve-caught-error -- upstream
+        throw new Error(`Mailgun API request timed out after ${this.config.timeout} ms.`);
+      }
+      throw error;
+    } finally {
+      combinedSignal.cleanup();
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+/**
+ * Error thrown when a Mailgun API request fails.
+ */
+class MailgunApiError extends Error {
+  /**
+   * HTTP status code returned by Mailgun, if the request reached the API.
+   */
+  statusCode;
+
+  /**
+   * Retry delay from Mailgun's `Retry-After` response header.
+   */
+  retryAfterMilliseconds;
+
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  attempts;
+
+  /**
+   * Creates a Mailgun API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code returned by Mailgun.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(message, statusCode, retryAfterMilliseconds, attempts) {
+    super(message);
+    this.name = 'MailgunApiError';
+    this.statusCode = statusCode;
+    this.retryAfterMilliseconds = retryAfterMilliseconds;
+    this.attempts = attempts;
+  }
+}
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const sleep = (milliseconds, signal) => {
+  if (signal?.aborted) {
+    return Promise.reject(createAbortError(signal));
+  }
+
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener('abort', abort);
+      reject(createAbortError(signal));
+    };
+
+    const timeoutId = setTimeout(() => {
+      signal?.removeEventListener('abort', abort);
+      resolve();
+    }, milliseconds);
+
+    signal?.addEventListener('abort', abort, { once: true });
+  });
+};
+
+const createAbortError = (signal) => {
+  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+};
+
+const truncateErrorBody = (text) => {
+  return text.length > 500 ? `${text.slice(0, 500)}...` : text;
+};
+
+module.exports = { MailgunHttpClient, MailgunApiError };
diff --git a/src/mailgun/index.d.ts b/src/mailgun/index.d.ts
new file mode 100644
index 0000000..b876619
--- /dev/null
+++ b/src/mailgun/index.d.ts
@@ -0,0 +1,269 @@
+// Types ported from upyo v0.7.0 (packages/mailgun/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Configuration interface for Mailgun transport connection settings.
+ *
+ * This interface defines all available options for configuring a Mailgun
+ * API connection including authentication, server region, and HTTP options.
+ *
+ * @example
+ * ```typescript
+ * const config: MailgunConfig = {
+ *   apiKey: 'your-api-key',
+ *   domain: 'your-domain.com',
+ *   region: 'us', // or 'eu'
+ *   timeout: 30000,
+ *   retries: 3
+ * };
+ * ```
+ */
+export interface MailgunConfig {
+  /**
+   * Your Mailgun API key.
+   *
+   * You can find your API key in the Mailgun Control Panel.
+   * It should start with 'key-' for private API keys.
+   */
+  readonly apiKey: string;
+  /**
+   * Your Mailgun domain.
+   *
+   * This is the domain you verified with Mailgun to send emails from.
+   */
+  readonly domain: string;
+  /**
+   * Mailgun region where your domain is hosted.
+   *
+   * @default "us"
+   */
+  readonly region?: 'us' | 'eu';
+  /**
+   * Base URL for the Mailgun API.
+   *
+   * If not provided, will be automatically determined based on the region.
+   * - US region: https://api.mailgun.net/v3
+   * - EU region: https://api.eu.mailgun.net/v3
+   */
+  readonly baseUrl?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   *
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Whether to validate SSL certificates.
+   *
+   * @default true
+   */
+  readonly validateSsl?: boolean;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Whether to enable tracking for sent messages.
+   *
+   * @default true
+   */
+  readonly tracking?: boolean;
+  /**
+   * Whether to enable click tracking for sent messages.
+   *
+   * @default true
+   */
+  readonly clickTracking?: boolean;
+  /**
+   * Whether to enable open tracking for sent messages.
+   *
+   * @default true
+   */
+  readonly openTracking?: boolean;
+}
+/**
+ * Resolved Mailgun configuration with all optional fields filled with default values.
+ *
+ * This type represents the final configuration after applying defaults,
+ * used internally by the Mailgun transport implementation.
+ */
+type ResolvedMailgunConfig = Required<MailgunConfig>;
+/**
+ * Creates a resolved Mailgun configuration by applying default values to optional fields.
+ *
+ * This function takes a partial Mailgun configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the Mailgun transport.
+ *
+ * @param config - The Mailgun configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ * @internal
+ */
+
+/**
+ * Mailgun transport implementation for sending emails via Mailgun API.
+ *
+ * This transport provides efficient email delivery using Mailgun's HTTP API,
+ * with support for authentication, retry logic, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { MailgunTransport } from '@alexify/mailer/mailgun';
+ *
+ * const transport = new MailgunTransport({
+ *   apiKey: 'your-api-key',
+ *   domain: 'your-domain.com',
+ *   region: 'us' // or 'eu'
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
+ * ```
+ */
+export declare class MailgunTransport implements Transport<'mailgun'> {
+  readonly id = 'mailgun';
+  /**
+   * The resolved Mailgun configuration used by this transport.
+   */
+  config: ResolvedMailgunConfig;
+  /**
+   * Creates a new Mailgun transport instance.
+   *
+   * @param config Mailgun configuration including API key, domain, and options.
+   */
+  constructor(config: MailgunConfig);
+  /**
+   * Sends a single email message via Mailgun API.
+   *
+   * This method converts the message to Mailgun format, makes an HTTP request
+   * to the Mailgun API, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent with ID:', receipt.messageId);
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'mailgun'>>;
+  /**
+   * Sends multiple email messages efficiently via Mailgun API.
+   *
+   * This method sends each message individually but provides a streamlined
+   * interface for processing multiple messages. Each message is sent as a
+   * separate API request to Mailgun.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'mailgun'>>;
+}
+
+/**
+ * Error thrown when a Mailgun API request fails.
+ */
+export declare class MailgunApiError extends Error {
+  /**
+   * HTTP status code returned by Mailgun, if the request reached the API.
+   */
+  statusCode?: number;
+  /**
+   * Retry delay from Mailgun's `Retry-After` response header.
+   */
+  retryAfterMilliseconds?: number;
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  attempts?: number;
+  /**
+   * Creates a Mailgun API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code returned by Mailgun.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(
+    message: string,
+    statusCode?: number,
+    retryAfterMilliseconds?: number,
+    attempts?: number,
+  );
+}
diff --git a/src/mailgun/index.js b/src/mailgun/index.js
new file mode 100644
index 0000000..1825fd6
--- /dev/null
+++ b/src/mailgun/index.js
@@ -0,0 +1,8 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { MailgunTransport } = require('./mailgun-transport.js');
+
+const { MailgunApiError } = require('./http-client.js');
+
+module.exports = { MailgunTransport, MailgunApiError };
diff --git a/src/mailgun/mailgun-transport.js b/src/mailgun/mailgun-transport.js
new file mode 100644
index 0000000..ac4f999
--- /dev/null
+++ b/src/mailgun/mailgun-transport.js
@@ -0,0 +1,206 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/mailgun-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createMailgunConfig } = require('./config.js');
+const { MailgunApiError, MailgunHttpClient } = require('./http-client.js');
+const { convertMessage } = require('./message-converter.js');
+
+/**
+ * Mailgun transport implementation for sending emails via Mailgun API.
+ *
+ * This transport provides efficient email delivery using Mailgun's HTTP API,
+ * with support for authentication, retry logic, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { MailgunTransport } from '@alexify/mailer/mailgun';
+ *
+ * const transport = new MailgunTransport({
+ *   apiKey: 'your-api-key',
+ *   domain: 'your-domain.com',
+ *   region: 'us' // or 'eu'
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
+ * ```
+ */
+class MailgunTransport {
+  id = 'mailgun';
+
+  /**
+   * The resolved Mailgun configuration used by this transport.
+   */
+  config;
+
+  httpClient;
+
+  /**
+   * Creates a new Mailgun transport instance.
+   *
+   * @param config Mailgun configuration including API key, domain, and options.
+   */
+  constructor(config) {
+    this.config = createMailgunConfig(config);
+    this.httpClient = new MailgunHttpClient(this.config);
+  }
+
+  /**
+   * Sends a single email message via Mailgun API.
+   *
+   * This method converts the message to Mailgun format, makes an HTTP request
+   * to the Mailgun API, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent with ID:', receipt.messageId);
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  async send(message, options) {
+    options?.signal?.throwIfAborted();
+
+    try {
+      const formData = await convertMessage(message, this.config, options?.signal);
+
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendMessage(formData, options?.signal);
+
+      return {
+        successful: true,
+        messageId: response.id,
+        provider: 'mailgun',
+      };
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) {
+        throw error;
+      }
+
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      return createMailgunFailure(errorMessage, error);
+    }
+  }
+
+  /**
+   * Sends multiple email messages efficiently via Mailgun API.
+   *
+   * This method sends each message individually but provides a streamlined
+   * interface for processing multiple messages. Each message is sent as a
+   * separate API request to Mailgun.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    const isAsyncIterable = Symbol.asyncIterator in messages;
+
+    if (isAsyncIterable) {
+      for await (const message of messages) {
+        options?.signal?.throwIfAborted();
+        yield await this.send(message, options);
+      }
+    } else {
+      for (const message of messages) {
+        options?.signal?.throwIfAborted();
+        yield await this.send(message, options);
+      }
+    }
+  }
+}
+
+const createMailgunFailure = (message, error) => {
+  if (error instanceof MailgunApiError) {
+    return createFailedReceipt(message, {
+      provider: 'mailgun',
+      statusCode: error.statusCode,
+      retryAfterMilliseconds: error.retryAfterMilliseconds,
+      attempts: error.attempts,
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'mailgun',
+  });
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+module.exports = { MailgunTransport };
diff --git a/src/mailgun/message-converter.js b/src/mailgun/message-converter.js
new file mode 100644
index 0000000..cd9faf6
--- /dev/null
+++ b/src/mailgun/message-converter.js
@@ -0,0 +1,190 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createCalendarAttachment } = require('../core/calendar.js');
+const { readAttachmentContent } = require('../core/attachment.js');
+const { resolveThreadingHeaders } = require('../core/message-id.js');
+
+/**
+ * Converts a Upyo Message to Mailgun API FormData format.
+ *
+ * This function transforms the standardized Upyo message format into
+ * the specific format expected by the Mailgun API.
+ *
+ * @param message - The Upyo message to convert
+ * @param config - The resolved Mailgun configuration
+ * @returns FormData object ready for Mailgun API submission
+ * @throws {TypeError} If the message carries an invalid message identifier.
+ *
+ * @example
+ * ```typescript
+ * const formData = await convertMessage(message, config);
+ * const response = await fetch(url, { method: 'POST', body: formData });
+ * ```
+ */
+const convertMessage = async (message, config, signal) => {
+  const formData = new FormData();
+  // A transport that cannot compose a `text/calendar` alternative carries the
+  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
+  // own files so that a client looking for the first calendar part finds it.
+  const attachments =
+    message.calendar == null
+      ? message.attachments
+      : [createCalendarAttachment(message.calendar), ...message.attachments];
+
+  // Required fields
+  formData.append('from', formatAddress(message.sender));
+
+  // Recipients
+  for (const recipient of message.recipients) {
+    formData.append('to', formatAddress(recipient));
+  }
+
+  // CC recipients
+  for (const ccRecipient of message.ccRecipients) {
+    formData.append('cc', formatAddress(ccRecipient));
+  }
+
+  // BCC recipients
+  for (const bccRecipient of message.bccRecipients) {
+    formData.append('bcc', formatAddress(bccRecipient));
+  }
+
+  // Reply-to
+  if (message.replyRecipients.length > 0) {
+    const replyTo = message.replyRecipients.map(formatAddress).join(', ');
+    formData.append('h:Reply-To', replyTo);
+  }
+
+  // Subject
+  formData.append('subject', message.subject);
+
+  // Content
+  if ('html' in message.content) {
+    formData.append('html', message.content.html);
+    if (message.content.text) {
+      formData.append('text', message.content.text);
+    }
+  } else {
+    formData.append('text', message.content.text);
+  }
+
+  // Priority
+  if (message.priority !== 'normal') {
+    const priorityMap = {
+      high: '1',
+      normal: '3',
+      low: '5',
+    };
+    formData.append('h:X-Priority', priorityMap[message.priority]);
+  }
+
+  // Tags
+  for (const tag of message.tags) {
+    formData.append('o:tag', tag);
+  }
+
+  // Reply threading comes from the typed fields when the message defines them,
+  // and from a custom header otherwise.  A field the message owns but left
+  // empty writes nothing, which is how a caller drops an inherited header.
+  const threading = resolveThreadingHeaders(message);
+  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+
+  // Custom headers
+  for (const [key, value] of message.headers.entries()) {
+    // Skip standard headers that are handled separately
+    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
+      formData.append(`h:${key}`, value);
+    }
+  }
+  for (const [name, value] of threading) {
+    if (value != null) formData.append(`h:${name}`, value);
+  }
+
+  // Attachments
+  for (const attachment of attachments) {
+    await appendAttachment(formData, attachment, signal);
+  }
+
+  // Tracking options
+  if (config.tracking !== undefined) {
+    formData.append('o:tracking', config.tracking ? 'yes' : 'no');
+  }
+
+  if (config.clickTracking !== undefined) {
+    formData.append('o:tracking-clicks', config.clickTracking ? 'yes' : 'no');
+  }
+
+  if (config.openTracking !== undefined) {
+    formData.append('o:tracking-opens', config.openTracking ? 'yes' : 'no');
+  }
+
+  return formData;
+};
+
+/**
+ * Formats an address for Mailgun API.
+ *
+ * @param address - The address to format
+ * @returns Formatted address string
+ */
+const formatAddress = (address) => {
+  if (address.name) {
+    // Escape quotes in the name
+    const escapedName = address.name.replace(/"/g, '\\"');
+    return `"${escapedName}" <${address.address}>`;
+  }
+  return address.address;
+};
+
+/**
+ * Appends an attachment to the FormData.
+ *
+ * @param formData - The FormData to append to
+ * @param attachment - The attachment to append
+ */
+const appendAttachment = async (formData, attachment, signal) => {
+  const content = await readAttachmentContent(attachment.content, signal);
+  // Ensure ArrayBuffer type compatibility for Blob constructor
+  const buffer =
+    content.buffer instanceof ArrayBuffer
+      ? content.buffer.slice(content.byteOffset, content.byteOffset + content.byteLength)
+      : content.slice(); // fallback to create new Uint8Array if SharedArrayBuffer
+  const blob = new Blob([buffer], {
+    type: attachment.contentType,
+  });
+
+  if (attachment.contentId) {
+    // Inline attachment
+    formData.append('inline', blob, attachment.filename);
+  } else {
+    // Regular attachment
+    formData.append('attachment', blob, attachment.filename);
+  }
+};
+
+/**
+ * Checks if a header is a standard email header that should not be prefixed with 'h:'.
+ *
+ * @param headerName - The header name to check
+ * @returns True if it's a standard header
+ */
+const isStandardHeader = (headerName) => {
+  const standardHeaders = [
+    'from',
+    'to',
+    'cc',
+    'bcc',
+    'reply-to',
+    'subject',
+    'date',
+    'message-id',
+    'content-type',
+    'content-transfer-encoding',
+    'mime-version',
+  ];
+
+  return standardHeaders.includes(headerName.toLowerCase());
+};
+
+module.exports = { convertMessage };
diff --git a/tests/e2e/mailgun-transport.e2e.test.js b/tests/e2e/mailgun-transport.e2e.test.js
new file mode 100644
index 0000000..59eb7c2
--- /dev/null
+++ b/tests/e2e/mailgun-transport.e2e.test.js
@@ -0,0 +1,380 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/mailgun-transport.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { MailgunTransport } = require('../../src/mailgun/index.js');
+const { isEmailAddress } = require('../../src/core/address.js');
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const {
+  createTestMessage,
+  getTestConfig,
+  isE2eTestingEnabled,
+} = require('../helpers/mailgun/test-config.js');
+const {
+  extractMessageId,
+  validateBatchReceipts,
+  validateErrorReceipt,
+  validateMessageDelivery,
+  waitForEmailProcessing,
+} = require('../helpers/mailgun/mailgun-delivery-utils.js');
+
+describe('Mailgun Transport E2E Tests', { skip: !isE2eTestingEnabled() }, () => {
+  if (!isE2eTestingEnabled()) return;
+
+  const setupTest = () => {
+    const config = getTestConfig();
+    const transport = new MailgunTransport(config.mailgun);
+    return { transport, config };
+  };
+
+  test('should send a basic email via Mailgun API', async () => {
+    const { transport } = setupTest();
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Basic Email',
+      content: {
+        text: 'This is a basic E2E test email sent via Mailgun API',
+      },
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] Basic Email');
+
+    if (receipt.successful) {
+      console.log(`✓ Email sent successfully with ID: ${receipt.messageId}`);
+    }
+
+    // Wait for email processing
+    await waitForEmailProcessing();
+  });
+
+  test('should send email with HTML content', async () => {
+    const { transport } = setupTest();
+
+    const message = createTestMessage({
+      subject: '[E2E Test] HTML Email',
+      content: {
+        html: '<h1>HTML E2E Test</h1><p>This is an <strong>HTML</strong> email sent via Mailgun API</p>',
+        text: 'This is the plain text version of the HTML email',
+      },
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] HTML Email');
+
+    if (receipt.successful) {
+      console.log(`✓ HTML email sent successfully with ID: ${receipt.messageId}`);
+    }
+
+    await waitForEmailProcessing();
+  });
+
+  test('should send email with multiple recipients', async () => {
+    const { transport, config } = setupTest();
+
+    if (!isEmailAddress(config.testEmails.to)) {
+      throw new Error(`Invalid test email address: ${config.testEmails.to}`);
+    }
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Multiple Recipients',
+      recipients: [{ name: 'Primary Recipient', address: config.testEmails.to }],
+      ccRecipients: [{ name: 'CC Recipient', address: config.testEmails.to }],
+      content: { text: 'This email was sent to multiple recipients' },
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] Multiple Recipients');
+
+    if (receipt.successful) {
+      console.log(`✓ Multi-recipient email sent successfully with ID: ${receipt.messageId}`);
+    }
+
+    await waitForEmailProcessing();
+  });
+
+  test('should send email with attachments', async () => {
+    const { transport } = setupTest();
+
+    const textContent = 'Hello from attachment test!';
+    const textBytes = new TextEncoder().encode(textContent);
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Email with Attachments',
+      content: { text: 'This email contains attachments' },
+      attachments: [
+        {
+          filename: 'test.txt',
+          contentType: 'text/plain',
+          content: textBytes,
+          contentId: 'test-attachment',
+          inline: false,
+        },
+        {
+          filename: 'test.json',
+          contentType: 'application/json',
+          content: new TextEncoder().encode(JSON.stringify({ test: 'data' })),
+          contentId: 'json-attachment',
+          inline: false,
+        },
+      ],
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] Email with Attachments');
+
+    if (receipt.successful) {
+      console.log(`✓ Email with attachments sent successfully with ID: ${receipt.messageId}`);
+    }
+
+    await waitForEmailProcessing();
+  });
+
+  test('should send email with custom headers', async () => {
+    const { transport } = setupTest();
+
+    const headers = new Headers();
+    headers.set('X-Custom-Header', 'E2E-Test-Value');
+    headers.set('X-Test-ID', `e2e-${Date.now()}`);
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Custom Headers',
+      content: { text: 'This email contains custom headers' },
+      headers,
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] Custom Headers');
+
+    if (receipt.successful) {
+      console.log(`✓ Email with custom headers sent successfully with ID: ${receipt.messageId}`);
+    }
+
+    await waitForEmailProcessing();
+  });
+
+  test('should send email with priority settings', async () => {
+    const { transport } = setupTest();
+
+    const message = createTestMessage({
+      subject: '[E2E Test] High Priority Email',
+      content: { text: 'This is a high priority email' },
+      priority: 'high',
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] High Priority Email');
+
+    if (receipt.successful) {
+      console.log(`✓ High priority email sent successfully with ID: ${receipt.messageId}`);
+    }
+
+    await waitForEmailProcessing();
+  });
+
+  test('should send email with tags', async () => {
+    const { transport } = setupTest();
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Tagged Email',
+      content: { text: 'This email has custom tags' },
+      tags: ['e2e-test', 'integration', 'mailgun'],
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] Tagged Email');
+
+    if (receipt.successful) {
+      console.log(`✓ Tagged email sent successfully with ID: ${receipt.messageId}`);
+    }
+
+    await waitForEmailProcessing();
+  });
+
+  test('should send email with reply-to address', async () => {
+    const { transport, config } = setupTest();
+
+    if (!isEmailAddress(config.testEmails.from)) {
+      throw new Error(`Invalid test email address: ${config.testEmails.from}`);
+    }
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Reply-To Email',
+      content: { text: 'This email has a reply-to address' },
+      replyRecipients: [{ name: 'Reply To', address: config.testEmails.from }],
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] Reply-To Email');
+
+    if (receipt.successful) {
+      console.log(`✓ Reply-to email sent successfully with ID: ${receipt.messageId}`);
+    }
+
+    await waitForEmailProcessing();
+  });
+
+  test('should send email with Unicode characters', async () => {
+    const { transport } = setupTest();
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Unicode Test - 한글 테스트 🌍',
+      content: {
+        text: '안녕하세요! This email contains Korean characters and emojis 🚀📧',
+      },
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] Unicode Test - 한글 테스트 🌍');
+
+    if (receipt.successful) {
+      console.log(`✓ Unicode email sent successfully with ID: ${receipt.messageId}`);
+    }
+
+    await waitForEmailProcessing();
+  });
+
+  test('should send multiple emails with sendMany', async () => {
+    const { transport } = setupTest();
+
+    const messages = [
+      createTestMessage({
+        subject: '[E2E Test] Batch Email 1',
+        content: { text: 'First email in batch' },
+      }),
+      createTestMessage({
+        subject: '[E2E Test] Batch Email 2',
+        content: { text: 'Second email in batch' },
+      }),
+      createTestMessage({
+        subject: '[E2E Test] Batch Email 3',
+        content: { text: 'Third email in batch' },
+      }),
+    ];
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      receipts.push(receipt);
+    }
+
+    validateBatchReceipts(receipts, 3);
+
+    console.log(`✓ Batch of ${receipts.length} emails sent successfully`);
+    receipts.forEach((receipt, index) => {
+      if (receipt.successful) {
+        console.log(`  Email ${index + 1}: ${receipt.messageId}`);
+      }
+    });
+
+    await waitForEmailProcessing();
+  });
+
+  test('should handle invalid API key gracefully', async () => {
+    const { config } = setupTest();
+
+    const transport = new MailgunTransport({
+      ...config.mailgun,
+      apiKey: 'invalid-api-key',
+    });
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Invalid API Key',
+      content: { text: 'This should fail' },
+    });
+
+    const receipt = await transport.send(message);
+    validateErrorReceipt(receipt, ['forbidden']);
+
+    if (!receipt.successful) {
+      console.log(`✓ Invalid API key handled correctly: ${receipt.errorMessages[0]}`);
+    }
+  });
+
+  test('should handle invalid domain gracefully', async () => {
+    const { config } = setupTest();
+
+    const transport = new MailgunTransport({
+      ...config.mailgun,
+      domain: 'invalid-domain.example.com',
+    });
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Invalid Domain',
+      content: { text: 'This should fail' },
+    });
+
+    const receipt = await transport.send(message);
+    validateErrorReceipt(receipt, ['forbidden']);
+
+    if (!receipt.successful) {
+      console.log(`✓ Invalid domain handled correctly: ${receipt.errorMessages[0]}`);
+    }
+  });
+
+  test('should handle network timeout gracefully', async () => {
+    const { config } = setupTest();
+
+    const transport = new MailgunTransport({
+      ...config.mailgun,
+      timeout: 1, // 1ms timeout to force timeout
+    });
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Network Timeout',
+      content: { text: 'This should timeout' },
+    });
+
+    const receipt = await transport.send(message);
+    validateErrorReceipt(receipt, ['timed out']);
+
+    if (!receipt.successful) {
+      assert.equal(receipt.errors?.[0]?.category, 'timeout');
+      assert.ok(receipt.retryable);
+      console.log(`✓ Network timeout handled correctly: ${receipt.errorMessages[0]}`);
+    }
+  });
+
+  test('should handle abort signal during send', async () => {
+    const { transport } = setupTest();
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Abort Signal',
+      content: { text: 'This should be aborted' },
+    });
+
+    const controller = new AbortController();
+
+    // Abort immediately
+    controller.abort();
+
+    try {
+      await transport.send(message, { signal: controller.signal });
+      assert.fail('Expected AbortError to be thrown');
+    } catch (error) {
+      assert.ok(error instanceof Error);
+      assert.equal(error.name, 'AbortError');
+      console.log(`✓ Abort signal handled correctly: ${error.message}`);
+    }
+  });
+
+  test('should extract message ID correctly', async () => {
+    const { transport } = setupTest();
+
+    const message = createTestMessage({
+      subject: '[E2E Test] Message ID Extraction',
+      content: { text: 'Testing message ID extraction' },
+    });
+
+    const receipt = await transport.send(message);
+    validateMessageDelivery(message, receipt, '[E2E Test] Message ID Extraction');
+
+    const messageId = extractMessageId(receipt);
+    assert.ok(messageId.length > 0, 'Message ID should not be empty');
+    assert.ok(!messageId.includes('<'), 'Message ID should not contain angle brackets');
+    assert.ok(!messageId.includes('>'), 'Message ID should not contain angle brackets');
+
+    console.log(`✓ Message ID extracted correctly: ${messageId}`);
+
+    await waitForEmailProcessing();
+  });
+});
diff --git a/tests/helpers/mailgun/mailgun-delivery-utils.js b/tests/helpers/mailgun/mailgun-delivery-utils.js
new file mode 100644
index 0000000..4a0ee6a
--- /dev/null
+++ b/tests/helpers/mailgun/mailgun-delivery-utils.js
@@ -0,0 +1,147 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/test-utils/mailgun-delivery-utils.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Validates that a Mailgun receipt indicates successful delivery.
+ *
+ * @param receipt The receipt returned from Mailgun transport.
+ */
+const validateMailgunReceipt = (receipt) => {
+  if (!receipt.successful) {
+    throw new Error(`Email delivery failed: ${receipt.errorMessages.join(', ')}`);
+  }
+
+  if (!receipt.messageId) {
+    throw new Error('No message ID returned from Mailgun');
+  }
+
+  // Mailgun message IDs typically start with < and end with >
+  if (!receipt.messageId.startsWith('<') || !receipt.messageId.endsWith('>')) {
+    console.warn(
+      `Unexpected message ID format: ${receipt.messageId}. Expected format: <id@domain>`,
+    );
+  }
+};
+
+/**
+ * Validates that multiple receipts from a batch operation are all successful.
+ *
+ * @param receipts Array of receipts from batch sending.
+ * @param expectedCount Expected number of receipts.
+ */
+const validateBatchReceipts = (receipts, expectedCount) => {
+  if (receipts.length !== expectedCount) {
+    throw new Error(`Expected ${expectedCount} receipts, but got ${receipts.length}`);
+  }
+
+  const failedReceipts = receipts.filter((r) => !r.successful);
+  if (failedReceipts.length > 0) {
+    const errors = failedReceipts.map((r) =>
+      !r.successful ? r.errorMessages.join(', ') : 'Unknown error',
+    );
+    throw new Error(
+      `${failedReceipts.length} out of ${receipts.length} emails failed: ${errors.join('; ')}`,
+    );
+  }
+
+  const receiptsWithoutIds = receipts.filter((r) => r.successful && !r.messageId);
+  if (receiptsWithoutIds.length > 0) {
+    throw new Error(`${receiptsWithoutIds.length} receipts missing message IDs`);
+  }
+};
+
+/**
+ * Waits for a specified duration to allow for email processing.
+ * This is useful in E2E tests to ensure emails have been processed.
+ *
+ * @param milliseconds Duration to wait in milliseconds.
+ */
+const waitForEmailProcessing = (milliseconds = 2000) => {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+};
+
+/**
+ * Extracts message ID from Mailgun receipt for further verification.
+ *
+ * @param receipt The receipt from Mailgun.
+ * @returns The message ID without angle brackets.
+ */
+const extractMessageId = (receipt) => {
+  if (!receipt.successful) {
+    throw new Error('Cannot extract message ID from failed receipt');
+  }
+
+  if (!receipt.messageId) {
+    throw new Error('No message ID in receipt');
+  }
+
+  // Remove angle brackets if present
+  return receipt.messageId.replace(/^<|>$/g, '');
+};
+
+/**
+ * Validates that an error receipt contains expected error information.
+ *
+ * @param receipt The receipt that should contain errors.
+ * @param expectedErrorKeywords Keywords that should be present in error messages.
+ */
+const validateErrorReceipt = (receipt, expectedErrorKeywords = []) => {
+  if (receipt.successful) {
+    throw new Error('Expected receipt to indicate failure, but it was successful');
+  }
+
+  if (receipt.errorMessages.length === 0) {
+    throw new Error('Expected error messages in failed receipt');
+  }
+
+  // Check for expected error keywords
+  if (expectedErrorKeywords.length > 0) {
+    const allErrors = receipt.errorMessages.join(' ').toLowerCase();
+    const missingKeywords = expectedErrorKeywords.filter(
+      (keyword) => !allErrors.includes(keyword.toLowerCase()),
+    );
+
+    if (missingKeywords.length > 0) {
+      throw new Error(
+        `Expected error keywords not found: ${missingKeywords.join(', ')}. ` +
+          `Actual errors: ${receipt.errorMessages.join(', ')}`,
+      );
+    }
+  }
+};
+
+/**
+ * Validates that a message was sent successfully and matches expected criteria.
+ * This function combines message validation with receipt validation.
+ *
+ * @param message The original message that was sent.
+ * @param receipt The receipt returned from the transport.
+ * @param expectedSubject Optional subject to validate against the message subject.
+ */
+const validateMessageDelivery = (message, receipt, expectedSubject) => {
+  // First validate the receipt
+  validateMailgunReceipt(receipt);
+
+  // Then validate the message subject if expected
+  if (expectedSubject !== undefined) {
+    if (message.subject !== expectedSubject) {
+      throw new Error(
+        `Message subject mismatch. Expected: "${expectedSubject}", ` +
+          `Actual: "${message.subject}"`,
+      );
+    }
+  }
+
+  if (receipt.successful) {
+    console.info(`Message "${message.subject}" sent successfully with ID: ${receipt.messageId}`);
+  }
+};
+
+module.exports = {
+  validateMailgunReceipt,
+  validateBatchReceipts,
+  waitForEmailProcessing,
+  extractMessageId,
+  validateErrorReceipt,
+  validateMessageDelivery,
+};
diff --git a/tests/helpers/mailgun/test-config.js b/tests/helpers/mailgun/test-config.js
new file mode 100644
index 0000000..5fe89aa
--- /dev/null
+++ b/tests/helpers/mailgun/test-config.js
@@ -0,0 +1,74 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isEmailAddress } = require('../../../src/core/address.js');
+const process = require('node:process');
+
+const getTestConfig = () => {
+  if (!isE2eTestingEnabled()) {
+    throw new Error(
+      'E2E testing is not enabled. Set MAILGUN_KEY, MAILGUN_FROM, MAILGUN_TO, and MAILGUN_DOMAIN environment variables.',
+    );
+  }
+
+  return {
+    mailgun: {
+      apiKey: process.env.MAILGUN_KEY,
+      domain: process.env.MAILGUN_DOMAIN,
+      region: process.env.MAILGUN_REGION ?? 'us',
+    },
+    testEmails: {
+      from: process.env.MAILGUN_FROM,
+      to: process.env.MAILGUN_TO,
+    },
+  };
+};
+
+function isE2eTestingEnabled() {
+  return !!(
+    process.env.MAILGUN_KEY &&
+    process.env.MAILGUN_FROM &&
+    process.env.MAILGUN_TO &&
+    process.env.MAILGUN_DOMAIN
+  );
+}
+
+const createTestMessage = (options = {}) => {
+  const config = getTestConfig();
+  const timestamp = Date.now();
+  const randomId = Math.random().toString(36).substr(2, 9);
+
+  const senderEmail = options.senderEmail ?? config.testEmails.from;
+  const recipientEmail = options.recipientEmail ?? config.testEmails.to;
+
+  if (!isEmailAddress(senderEmail)) {
+    throw new Error(`Invalid sender email address: ${senderEmail}`);
+  }
+  if (!isEmailAddress(recipientEmail)) {
+    throw new Error(`Invalid recipient email address: ${recipientEmail}`);
+  }
+
+  return {
+    sender: {
+      name: options.senderName ?? 'Mailgun E2E Test Sender',
+      address: senderEmail,
+    },
+    recipients: options.recipients ?? [
+      {
+        name: 'E2E Test Recipient',
+        address: recipientEmail,
+      },
+    ],
+    ccRecipients: options.ccRecipients ?? [],
+    bccRecipients: options.bccRecipients ?? [],
+    replyRecipients: options.replyRecipients ?? [],
+    subject: options.subject ?? `[Mailgun E2E Test] ${timestamp}`,
+    content: options.content ?? { text: `Test message content ${randomId}` },
+    attachments: options.attachments ?? [],
+    priority: options.priority ?? 'normal',
+    tags: options.tags ?? ['e2e-test'],
+    headers: options.headers ?? new Headers(),
+  };
+};
+
+module.exports = { getTestConfig, isE2eTestingEnabled, createTestMessage };
diff --git a/tests/types/mailgun.test-d.ts b/tests/types/mailgun.test-d.ts
new file mode 100644
index 0000000..29cb906
--- /dev/null
+++ b/tests/types/mailgun.test-d.ts
@@ -0,0 +1,20 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import { MailgunApiError, MailgunTransport, type MailgunConfig } from '../../src/mailgun/index.js';
+
+const transport = new MailgunTransport({ apiKey: 'key', domain: 'mg.example.com', region: 'eu' });
+expectAssignable<Transport<'mailgun'>>(transport);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'mailgun'>>>(transport.send(message));
+expectType<AsyncIterable<Receipt<'mailgun'>>>(transport.sendMany([message]));
+
+expectAssignable<MailgunConfig>({ apiKey: 'key', domain: 'mg.example.com', tracking: true });
+expectAssignable<Error>(new MailgunApiError('Forbidden', 403));
+expectError(new MailgunTransport({ apiKey: 'key' }));
+expectError(new MailgunTransport({ apiKey: 'key', domain: 'mg.example.com', region: 'ap' }));
diff --git a/tests/unit/mailgun-config.test.js b/tests/unit/mailgun-config.test.js
new file mode 100644
index 0000000..23b7fe2
--- /dev/null
+++ b/tests/unit/mailgun-config.test.js
@@ -0,0 +1,72 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { createMailgunConfig } = require('../../src/mailgun/config.js');
+
+describe('MailgunConfig', () => {
+  it('should create a config with default values', () => {
+    const config = {
+      apiKey: 'test-key',
+      domain: 'test-domain.com',
+    };
+
+    const resolved = createMailgunConfig(config);
+
+    assert.equal(resolved.apiKey, 'test-key');
+    assert.equal(resolved.domain, 'test-domain.com');
+    assert.equal(resolved.region, 'us');
+    assert.equal(resolved.baseUrl, 'https://api.mailgun.net/v3');
+    assert.equal(resolved.timeout, 30000);
+    assert.equal(resolved.retries, 3);
+    assert.equal(resolved.validateSsl, true);
+    assert.deepEqual(resolved.headers, {});
+    assert.equal(resolved.tracking, true);
+    assert.equal(resolved.clickTracking, true);
+    assert.equal(resolved.openTracking, true);
+  });
+
+  it('should create a config with EU region', () => {
+    const config = {
+      apiKey: 'test-key',
+      domain: 'test-domain.com',
+      region: 'eu',
+    };
+
+    const resolved = createMailgunConfig(config);
+
+    assert.equal(resolved.region, 'eu');
+    assert.equal(resolved.baseUrl, 'https://api.eu.mailgun.net/v3');
+  });
+
+  it('should create a config with custom values', () => {
+    const config = {
+      apiKey: 'test-key',
+      domain: 'test-domain.com',
+      region: 'us',
+      baseUrl: 'https://custom.api.com/v3',
+      timeout: 15000,
+      retries: 5,
+      validateSsl: false,
+      headers: { 'X-Custom': 'value' },
+      tracking: false,
+      clickTracking: false,
+      openTracking: false,
+    };
+
+    const resolved = createMailgunConfig(config);
+
+    assert.equal(resolved.apiKey, 'test-key');
+    assert.equal(resolved.domain, 'test-domain.com');
+    assert.equal(resolved.region, 'us');
+    assert.equal(resolved.baseUrl, 'https://custom.api.com/v3');
+    assert.equal(resolved.timeout, 15000);
+    assert.equal(resolved.retries, 5);
+    assert.equal(resolved.validateSsl, false);
+    assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
+    assert.equal(resolved.tracking, false);
+    assert.equal(resolved.clickTracking, false);
+    assert.equal(resolved.openTracking, false);
+  });
+});
diff --git a/tests/unit/mailgun-message-converter.test.js b/tests/unit/mailgun-message-converter.test.js
new file mode 100644
index 0000000..8bf7319
--- /dev/null
+++ b/tests/unit/mailgun-message-converter.test.js
@@ -0,0 +1,456 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/message-converter.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const { MailgunTransport } = require('../../src/mailgun/index.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { convertMessage } = require('../../src/mailgun/message-converter.js');
+
+describe('convertMessage', () => {
+  const transport = new MailgunTransport({
+    apiKey: 'test-key',
+    domain: 'test-domain.com',
+  });
+  const config = transport.config;
+
+  it('should convert a simple message', async () => {
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const formData = await convertMessage(message, config);
+
+    assert.equal(formData.get('from'), 'sender@example.com');
+    assert.equal(formData.get('to'), 'recipient@example.com');
+    assert.equal(formData.get('subject'), 'Test Subject');
+    assert.equal(formData.get('text'), 'Test content');
+  });
+
+  it('should format addresses with names', async () => {
+    const message = {
+      sender: { address: 'sender@example.com', name: 'John Doe' },
+      recipients: [{ address: 'recipient@example.com', name: 'Jane Smith' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const formData = await convertMessage(message, config);
+
+    assert.equal(formData.get('from'), '"John Doe" <sender@example.com>');
+    assert.equal(formData.get('to'), '"Jane Smith" <recipient@example.com>');
+  });
+
+  it('should handle HTML content', async () => {
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { html: '<p>Test HTML</p>', text: 'Test text' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const formData = await convertMessage(message, config);
+
+    assert.equal(formData.get('html'), '<p>Test HTML</p>');
+    assert.equal(formData.get('text'), 'Test text');
+  });
+
+  it('should handle CC and BCC recipients', async () => {
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [{ address: 'cc@example.com' }],
+      bccRecipients: [{ address: 'bcc@example.com' }],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const formData = await convertMessage(message, config);
+
+    assert.equal(formData.get('cc'), 'cc@example.com');
+    assert.equal(formData.get('bcc'), 'bcc@example.com');
+  });
+
+  it('should handle reply-to addresses', async () => {
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [{ address: 'replyto@example.com' }],
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const formData = await convertMessage(message, config);
+
+    assert.equal(formData.get('h:Reply-To'), 'replyto@example.com');
+  });
+
+  it('should handle priority', async () => {
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+      attachments: [],
+      priority: 'high',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const formData = await convertMessage(message, config);
+
+    assert.equal(formData.get('h:X-Priority'), '1');
+  });
+
+  it('should handle tags', async () => {
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+      attachments: [],
+      priority: 'normal',
+      tags: ['tag1', 'tag2'],
+      headers: new Headers(),
+    };
+
+    const formData = await convertMessage(message, config);
+
+    const tags = formData.getAll('o:tag');
+    assert.deepEqual(tags, ['tag1', 'tag2']);
+  });
+
+  it('should handle custom headers', async () => {
+    const headers = new Headers();
+    headers.set('X-Custom-Header', 'custom-value');
+
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers,
+    };
+
+    const formData = await convertMessage(message, config);
+
+    // Headers are normalized to lowercase by the Headers API
+    assert.equal(formData.get('h:x-custom-header'), 'custom-value');
+  });
+
+  it('should handle tracking options', async () => {
+    const transportWithTracking = new MailgunTransport({
+      apiKey: 'test-key',
+      domain: 'test-domain.com',
+      tracking: false,
+      clickTracking: false,
+      openTracking: false,
+    });
+    const configWithTracking = transportWithTracking.config;
+
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test content' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const formData = await convertMessage(message, configWithTracking);
+
+    assert.equal(formData.get('o:tracking'), 'no');
+    assert.equal(formData.get('o:tracking-clicks'), 'no');
+    assert.equal(formData.get('o:tracking-opens'), 'no');
+  });
+
+  it('should handle attachments', async () => {
+    const textContent = 'Hello, this is test content!';
+    const textBytes = new TextEncoder().encode(textContent);
+
+    const message = {
+      sender: { address: 'sender@example.com' },
+      recipients: [{ address: 'recipient@example.com' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject with Attachment',
+      content: { text: 'This message has an attachment' },
+      attachments: [
+        {
+          filename: 'test.txt',
+          contentType: 'text/plain',
+          content: textBytes,
+          contentId: '',
+          inline: false,
+        },
+        {
+          filename: 'data.json',
+          contentType: 'application/json',
+          content: new TextEncoder().encode(JSON.stringify({ key: 'value' })),
+          contentId: 'json-attachment',
+          inline: true,
+        },
+      ],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+    };
+
+    const formData = await convertMessage(message, config);
+
+    // Check basic message fields
+    assert.equal(formData.get('subject'), 'Test Subject with Attachment');
+    assert.equal(formData.get('text'), 'This message has an attachment');
+
+    // Check attachments were properly added to FormData
+    // The actual Blob content testing is limited in unit tests,
+    // but we can verify the FormData structure
+    const attachmentEntries = Array.from(formData.entries()).filter(
+      ([key]) => key === 'attachment' || key === 'inline',
+    );
+
+    // We should have 2 attachments (1 regular, 1 inline)
+    assert.equal(attachmentEntries.length, 2);
+
+    // Check that we have both attachment types
+    const hasAttachment = attachmentEntries.some(([key]) => key === 'attachment');
+    const hasInline = attachmentEntries.some(([key]) => key === 'inline');
+    assert.ok(hasAttachment, 'Should have regular attachment');
+    assert.ok(hasInline, 'Should have inline attachment');
+  });
+});
+
+const threadingConfig = new MailgunTransport({ apiKey: 'test-key', domain: 'test-domain.com' })
+  .config;
+
+const headerOf = (form, name) =>
+  [...form.entries()]
+    .filter(([key]) => key.toLowerCase() === `h:${name.toLowerCase()}`)
+    .map(([, value]) => String(value));
+
+describe('convertMessage() reply threading', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Re: Your request',
+    content: { text: 'Thanks for getting in touch.' },
+  };
+
+  it('writes the typed threading fields', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: '122@example.com',
+      references: ['120@example.com', '121@example.com'],
+    });
+    const result = await convertMessage(message, threadingConfig);
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<122@example.com>']);
+    assert.deepEqual(headerOf(result, 'References'), ['<120@example.com> <121@example.com>']);
+  });
+
+  it('prefers a typed field over a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: ['typed@example.com'],
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = await convertMessage(message, threadingConfig);
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<typed@example.com>']);
+  });
+
+  it('lets an empty list suppress a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: [],
+      references: [],
+      headers: {
+        'In-Reply-To': '<custom@example.com>',
+        References: '<custom@example.com>',
+      },
+    });
+    const result = await convertMessage(message, threadingConfig);
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), []);
+    assert.deepEqual(headerOf(result, 'References'), []);
+  });
+
+  it('lets a custom header through when the field is unset', async () => {
+    const message = createMessage({
+      ...base,
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = await convertMessage(message, threadingConfig);
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<custom@example.com>']);
+  });
+});
+
+const CALENDAR_ICS =
+  [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'SUMMARY:Lunch',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+describe('convertMessage() calendar', () => {
+  const transport = new MailgunTransport({
+    apiKey: 'test-key',
+    domain: 'test-domain.com',
+  });
+  const config = transport.config;
+
+  it('should carry the calendar as an invite.ics attachment', async () => {
+    const form = await convertMessage(
+      createMessage({
+        from: 'organizer@example.com',
+        to: 'attendee@example.net',
+        subject: 'Lunch',
+        content: { text: 'Lunch on Wednesday.' },
+        calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+      }),
+      config,
+    );
+
+    const attachments = form.getAll('attachment');
+    assert.equal(attachments.length, 1);
+    assert.equal(attachments[0].name, 'invite.ics');
+    // `Blob` lower-cases the media type it is given, which is harmless: RFC
+    // 6047 §2.4 compares the method ignoring case.
+    assert.equal(attachments[0].type.toUpperCase(), 'TEXT/CALENDAR; CHARSET=UTF-8; METHOD=REQUEST');
+    assert.equal(await attachments[0].text(), CALENDAR_ICS);
+    // An empty content ID keeps it out of the inline field.
+    assert.equal(form.getAll('inline').length, 0);
+  });
+
+  it('should place the invitation ahead of the other attachments', async () => {
+    const form = await convertMessage(
+      createMessage({
+        from: 'organizer@example.com',
+        to: 'attendee@example.net',
+        subject: 'Lunch',
+        content: { text: 'Lunch on Wednesday.' },
+        calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+        attachments: [
+          {
+            inline: false,
+            filename: 'agenda.txt',
+            content: new TextEncoder().encode('agenda'),
+            contentType: 'text/plain',
+            contentId: '',
+          },
+        ],
+      }),
+      config,
+    );
+
+    const attachments = form.getAll('attachment');
+    assert.deepEqual(
+      attachments.map((file) => file.name),
+      ['invite.ics', 'agenda.txt'],
+    );
+  });
+
+  it('should reject malformed calendar property syntax', async () => {
+    const message = {
+      sender: { address: 'organizer@example.com' },
+      recipients: [{ address: 'attendee@example.net' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Lunch',
+      content: { text: 'Lunch.' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+      calendar: {
+        method: 'REQUEST',
+        content: 'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nSUMMARY;BROKEN:Lunch\r\nEND:VCALENDAR\r\n',
+      },
+    };
+
+    await assert.rejects(() => convertMessage(message, config), {
+      name: 'TypeError',
+    });
+  });
+
+  it('should reject calendar content that never passed createMessage()', async () => {
+    const message = {
+      sender: { address: 'organizer@example.com' },
+      recipients: [{ address: 'attendee@example.net' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Lunch',
+      content: { text: 'Lunch.' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+      calendar: { method: 'REQUEST', content: 'not a calendar' },
+    };
+
+    await assert.rejects(() => convertMessage(message, config), {
+      name: 'TypeError',
+    });
+  });
+});
diff --git a/tests/unit/mailgun-transport.test.js b/tests/unit/mailgun-transport.test.js
new file mode 100644
index 0000000..77fe6e0
--- /dev/null
+++ b/tests/unit/mailgun-transport.test.js
@@ -0,0 +1,929 @@
+// Ported from upyo v0.7.0 (packages/mailgun/src/mailgun-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { MailgunTransport } = require('../../src/mailgun/index.js');
+const assert = require('node:assert/strict');
+const { createServer } = require('node:http');
+const { describe, it } = require('node:test');
+
+// Note: Tests are split into separate describe blocks instead of one unified block
+// because Deno runs tests within the same describe block concurrently, which causes
+// globalThis.fetch mocking to interfere between tests. Node.js runs tests sequentially
+// so it doesn't have this issue. By separating each test into its own describe block,
+// we ensure that fetch mocking is isolated between tests in both environments.
+
+const withHangingServer = async (callback) => {
+  const server = createServer((_request, _response) => {});
+  const port = await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (address == null || typeof address === 'string') {
+        reject(new TypeError('Expected TCP server address.'));
+        return;
+      }
+      resolve(address.port);
+    });
+  });
+
+  try {
+    await callback(`http://127.0.0.1:${port}`);
+  } finally {
+    const closeableServer = server;
+    await new Promise((resolve, reject) => {
+      if (!server.listening) {
+        closeableServer.closeAllConnections?.();
+        resolve();
+        return;
+      }
+
+      server.close((error) => {
+        const code =
+          typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+        if (error != null && code !== 'ERR_SERVER_NOT_RUNNING') {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+      closeableServer.closeAllConnections?.();
+    });
+  }
+};
+
+describe('MailgunTransport - Send Message', () => {
+  it('should send a message successfully', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock successful response
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            id: 'test-message-id',
+            message: 'Queued. Thank you.',
+          }),
+          {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 0,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, true);
+      if (receipt.successful) {
+        assert.equal(receipt.messageId, 'test-message-id');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - API Errors', () => {
+  it('should handle API errors', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock error response
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            message: 'Bad Request',
+          }),
+          {
+            status: 400,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 0,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages.length, 1);
+        assert.equal(receipt.errorMessages[0], 'Bad Request');
+        assert.equal(receipt.provider, 'mailgun');
+        assert.ok(!receipt.retryable);
+        assert.equal(receipt.attempts, 1);
+        assert.equal(receipt.errors?.[0]?.category, 'validation');
+        assert.equal(receipt.errors?.[0]?.statusCode, 400);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Long Error Bodies', () => {
+  it('should truncate non-JSON error response bodies', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      const longBody = 'x'.repeat(600);
+      globalThis.fetch = async () => new Response(longBody, { status: 500 });
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 0,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.ok(!receipt.successful);
+      assert.equal(receipt.errorMessages[0], `${'x'.repeat(500)}...`);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Structured Rate Limit Errors', () => {
+  it('should expose rate limit retry metadata', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            message: 'Too Many Requests',
+          }),
+          {
+            status: 429,
+            headers: {
+              'Content-Type': 'application/json',
+              'Retry-After': '45',
+            },
+          },
+        );
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 0,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.ok(receipt.retryable);
+        assert.equal(receipt.errors?.[0]?.category, 'rate-limit');
+        assert.equal(receipt.errors?.[0]?.code, 'http.429');
+        assert.equal(receipt.errors?.[0]?.retryAfterMilliseconds, 45_000);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Network Errors', () => {
+  it('should handle network errors', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock network error
+      globalThis.fetch = async () => {
+        throw new Error('Network error');
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 0,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages.length, 1);
+        assert.equal(receipt.errorMessages[0], 'Network error');
+        assert.equal(receipt.provider, 'mailgun');
+        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.attempts, 1);
+        assert.equal(receipt.errors?.[0]?.category, 'network');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Retry Backoff Abort Signal', () => {
+  it('should reject caller aborts during retry backoff', async () => {
+    const originalFetch = globalThis.fetch;
+    const controller = new AbortController();
+    const reason = new Error('Stop retrying.');
+    let attempts = 0;
+
+    try {
+      globalThis.fetch = async () => {
+        attempts++;
+        setTimeout(() => controller.abort(reason), 0);
+        return new Response('Server Error', { status: 500 });
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 1,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const startedAt = Date.now();
+      await assert.rejects(
+        () => transport.send(message, { signal: controller.signal }),
+        (error) => error === reason,
+      );
+
+      assert.equal(attempts, 1);
+      assert.ok(Date.now() - startedAt < 500);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Multiple Messages', () => {
+  it('should send multiple messages', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock successful responses
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            id: 'test-message-id',
+            message: 'Queued. Thank you.',
+          }),
+          {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 0,
+      });
+
+      const messages = [
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient1@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 1',
+          content: { text: 'Test content 1' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+        {
+          sender: { address: 'sender@example.com' },
+          recipients: [{ address: 'recipient2@example.com' }],
+          ccRecipients: [],
+          bccRecipients: [],
+          replyRecipients: [],
+          subject: 'Test Subject 2',
+          content: { text: 'Test content 2' },
+          attachments: [],
+          priority: 'normal',
+          tags: [],
+          headers: new Headers(),
+        },
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.equal(receipts[0].successful, true);
+      assert.equal(receipts[1].successful, true);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Abort Signal', () => {
+  it('should handle abort signal', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock a slow response to allow abort to happen
+      globalThis.fetch = async (_url, options) => {
+        if (options?.signal?.aborted) {
+          throw new DOMException('The operation was aborted', 'AbortError');
+        }
+
+        return new Promise((resolve, reject) => {
+          const timeout = setTimeout(() => {
+            resolve(
+              new Response(
+                JSON.stringify({
+                  id: 'test-id',
+                  message: 'Success',
+                }),
+                {
+                  status: 200,
+                  headers: { 'Content-Type': 'application/json' },
+                },
+              ),
+            );
+          }, 100);
+
+          options?.signal?.addEventListener('abort', () => {
+            clearTimeout(timeout);
+            reject(new DOMException('The operation was aborted', 'AbortError'));
+          });
+        });
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 0,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const controller = new AbortController();
+      controller.abort();
+
+      try {
+        await transport.send(message, { signal: controller.signal });
+        assert.fail('Should have thrown AbortError');
+      } catch (error) {
+        assert.equal(error.name, 'AbortError');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('should reject caller aborts during fetch', async () => {
+    const controller = new AbortController();
+
+    await withHangingServer(async (baseUrl) => {
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        baseUrl,
+        retries: 0,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const send = transport.send(message, { signal: controller.signal });
+      setTimeout(() => controller.abort(), 0);
+
+      await assert.rejects(
+        () => send,
+        (error) => error instanceof Error && error.name === 'AbortError',
+      );
+    });
+  });
+});
+
+describe('MailgunTransport - Fetch Abort Reason', () => {
+  it('should reject caller abort reasons during fetch', async () => {
+    const originalFetch = globalThis.fetch;
+    const controller = new AbortController();
+    const reason = new Error('Stop sending.');
+
+    try {
+      globalThis.fetch = (_url, options) => {
+        assert.ok(options?.signal instanceof AbortSignal);
+        controller.abort(reason);
+        return Promise.reject(options.signal.reason);
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 0,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Test Subject',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      await assert.rejects(
+        () => transport.send(message, { signal: controller.signal }),
+        (error) => error === reason,
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Rate Limiting', () => {
+  it('should handle rate limiting (429) responses', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock rate limit response
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            message: 'Too Many Requests',
+          }),
+          {
+            status: 429,
+            headers: {
+              'Content-Type': 'application/json',
+              'Retry-After': '60',
+            },
+          },
+        );
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Rate Limit Test',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, false);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages.length, 1);
+        assert.equal(receipt.errorMessages[0], 'Too Many Requests');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Authentication Errors', () => {
+  it('should handle unauthorized (401) responses', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock unauthorized response
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            message: 'Forbidden',
+          }),
+          {
+            status: 401,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'invalid-key',
+        domain: 'test-domain.com',
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Auth Test',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, false);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages.length, 1);
+        assert.equal(receipt.errorMessages[0], 'Forbidden');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Malformed Responses', () => {
+  it('should handle non-JSON responses', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock malformed response
+      globalThis.fetch = async () => {
+        return new Response('Internal Server Error', {
+          status: 500,
+          headers: { 'Content-Type': 'text/plain' },
+        });
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Malformed Response Test',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      // Should handle malformed response gracefully
+      // The implementation might handle this differently than expected
+      if (receipt.successful) {
+        // If it somehow succeeded, that's also valid
+        assert.ok(true);
+      } else {
+        assert.ok(receipt.errorMessages.length >= 1);
+        assert.ok(receipt.errorMessages.length === 0 || receipt.errorMessages[0].length >= 0);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('should handle empty responses', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock empty response
+      globalThis.fetch = async () => {
+        return new Response('', {
+          status: 500,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Empty Response Test',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, false);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages.length, 1);
+        // Should handle empty response gracefully
+        assert.ok(receipt.errorMessages[0].length > 0);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Connection Timeouts', () => {
+  it('should handle fetch timeout errors', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = (_url, options) =>
+        new Promise((_resolve, reject) => {
+          options?.signal?.addEventListener(
+            'abort',
+            () => {
+              reject(new DOMException('The operation was aborted.', 'AbortError'));
+            },
+            { once: true },
+          );
+        });
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        timeout: 100, // Short timeout
+        retries: 0,
+      });
+
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Timeout Test',
+        content: { text: 'Test content' },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages.length, 1);
+        assert.equal(receipt.errors?.[0]?.category, 'timeout');
+        assert.ok(receipt.retryable);
+        assert.equal(receipt.attempts, 1);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Concurrent Error Handling', () => {
+  it('should handle concurrent requests with mixed success/failure', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      let requestCount = 0;
+      // Mock mixed responses
+      globalThis.fetch = async () => {
+        requestCount++;
+        if (requestCount % 2 === 0) {
+          // Even requests fail
+          return new Response(
+            JSON.stringify({
+              message: 'Server Error',
+            }),
+            {
+              status: 500,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          );
+        } else {
+          // Odd requests succeed
+          return new Response(
+            JSON.stringify({
+              id: `test-message-${requestCount}`,
+              message: 'Queued. Thank you.',
+            }),
+            {
+              status: 200,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          );
+        }
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+        retries: 0,
+      });
+
+      const messages = Array.from({ length: 4 }, (_, i) => ({
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: `recipient${i}@example.com` }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: `Test Subject ${i}`,
+        content: { text: `Test content ${i}` },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      }));
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 4);
+
+      // Should have mix of success and failure
+      const successful = receipts.filter((r) => r.successful);
+      const failed = receipts.filter((r) => !r.successful);
+
+      // Should have processed all messages
+      assert.equal(successful.length + failed.length, 4);
+
+      // If the mocking works as expected, we should have some failures
+      // But the exact distribution might vary based on implementation
+      console.log(`Successful: ${successful.length}, Failed: ${failed.length}`);
+
+      // At minimum, we should have processed all messages
+      assert.ok(receipts.length === 4);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailgunTransport - Large Payload Handling', () => {
+  it('should handle large message payloads', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      // Mock success for large payload
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            id: 'large-message-id',
+            message: 'Queued. Thank you.',
+          }),
+          {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new MailgunTransport({
+        apiKey: 'test-key',
+        domain: 'test-domain.com',
+      });
+
+      // Create a large message
+      const largeContent = 'A'.repeat(100000); // 100KB content
+      const message = {
+        sender: { address: 'sender@example.com' },
+        recipients: [{ address: 'recipient@example.com' }],
+        ccRecipients: [],
+        bccRecipients: [],
+        replyRecipients: [],
+        subject: 'Large Payload Test',
+        content: { text: largeContent },
+        attachments: [],
+        priority: 'normal',
+        tags: [],
+        headers: new Headers(),
+      };
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, true);
+      if (receipt.successful) {
+        assert.equal(receipt.messageId, 'large-message-id');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
diff --git a/tests/unit/mailgun.test.js b/tests/unit/mailgun.test.js
new file mode 100644
index 0000000..5243f04
--- /dev/null
+++ b/tests/unit/mailgun.test.js
@@ -0,0 +1,54 @@
+// Paths of the ported Mailgun transport (src/mailgun/) that upstream's suites
+// leave out, against a stubbed fetch.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { MailgunTransport } = require('../../src/mailgun/index.js');
+
+const message = () =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+const config = { apiKey: 'key', domain: 'mg.example.com' };
+
+test('Mailgun: an unknown region is refused', () => {
+  assert.throws(() => new MailgunTransport({ ...config, region: 'ap' }), {
+    message: 'Unsupported region: ap',
+  });
+});
+
+test('Mailgun: custom headers are sent, and a 2xx without JSON fails', async (t) => {
+  let headers;
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    headers = new Headers(init.headers);
+    return new Response('queued', { status: 200 });
+  });
+  const transport = new MailgunTransport({ ...config, headers: { 'X-Custom': 'yes' }, retries: 0 });
+  const receipt = await transport.send(message());
+  assert.strictEqual(headers.get('x-custom'), 'yes');
+  assert.strictEqual(receipt.successful, false);
+  assert.match(
+    receipt.errorMessages[0],
+    /^Successfully received response but failed to parse JSON/,
+  );
+});
+
+test('Mailgun: sendMany reads an async iterable', async (t) => {
+  let calls = 0;
+  t.mock.method(globalThis, 'fetch', async () =>
+    Response.json({ id: `<m${++calls}@mg.example.com>`, message: 'Queued. Thank you.' }),
+  );
+  const messages = async function* () {
+    yield message();
+    yield message();
+  };
+  const ids = [];
+  for await (const receipt of new MailgunTransport(config).sendMany(messages())) {
+    ids.push(receipt.messageId);
+  }
+  assert.strictEqual(ids.length, 2);
+  assert.ok(ids.every((id) => /^<?m\d@mg\.example\.com>?$/.test(id)));
+});

From e2cbea624a40544b8975e4d4ba4ddff04b461c67 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:15:19 +0300
Subject: [PATCH 010/158] feat(mailtrap): port the Mailtrap transport from upyo
 0.7.0

./mailtrap exports MailtrapTransport, createMailtrapConfig and the
MailtrapApiError, MailtrapTimeoutError and MailtrapResponseError classes:
the Email Sending and Sandbox APIs over fetch, the batch API for sendMany,
categories, custom variables, retries on 408, 429 and 5xx with jitter and
Retry-After, a request timeout, and no retry once a 2xx body could not be
read. The User-Agent becomes @alexify/mailer/mailtrap.

Upstream's unit suites are ported and the e2e suite goes to tests/e2e.
tests/unit/mailtrap.test.js covers what they leave out: inline attachments,
id-less and unsuccessful responses, the timeout, Retry-After dates, an
abort while waiting to retry, and batches that fail whole or in part.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   2 +-
 package.json                                  |   4 +
 src/mailtrap/config.js                        |  49 ++
 src/mailtrap/http-client.js                   | 351 +++++++++
 src/mailtrap/index.d.ts                       | 322 ++++++++
 src/mailtrap/index.js                         |  26 +
 src/mailtrap/mailtrap-transport.js            | 283 +++++++
 src/mailtrap/message-converter.js             | 228 ++++++
 tests/e2e/mailtrap-transport.e2e.test.js      | 107 +++
 tests/helpers/mailtrap/test-config.js         |  85 +++
 tests/types/mailtrap.test-d.ts                |  28 +
 tests/unit/mailtrap-config.test.js            | 124 ++++
 tests/unit/mailtrap-message-converter.test.js | 395 ++++++++++
 tests/unit/mailtrap-test-config.test.js       |  39 +
 tests/unit/mailtrap-transport.test.js         | 701 ++++++++++++++++++
 tests/unit/mailtrap.test.js                   | 154 ++++
 16 files changed, 2897 insertions(+), 1 deletion(-)
 create mode 100644 src/mailtrap/config.js
 create mode 100644 src/mailtrap/http-client.js
 create mode 100644 src/mailtrap/index.d.ts
 create mode 100644 src/mailtrap/index.js
 create mode 100644 src/mailtrap/mailtrap-transport.js
 create mode 100644 src/mailtrap/message-converter.js
 create mode 100644 tests/e2e/mailtrap-transport.e2e.test.js
 create mode 100644 tests/helpers/mailtrap/test-config.js
 create mode 100644 tests/types/mailtrap.test-d.ts
 create mode 100644 tests/unit/mailtrap-config.test.js
 create mode 100644 tests/unit/mailtrap-message-converter.test.js
 create mode 100644 tests/unit/mailtrap-test-config.test.js
 create mode 100644 tests/unit/mailtrap-transport.test.js
 create mode 100644 tests/unit/mailtrap.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b7d4cc3..e6c0981 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 492afe2..4495d80 100644
--- a/package.json
+++ b/package.json
@@ -48,6 +48,10 @@
       "types": "./src/mailgun/index.d.ts",
       "default": "./src/mailgun/index.js"
     },
+    "./mailtrap": {
+      "types": "./src/mailtrap/index.d.ts",
+      "default": "./src/mailtrap/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
diff --git a/src/mailtrap/config.js b/src/mailtrap/config.js
new file mode 100644
index 0000000..6291c0f
--- /dev/null
+++ b/src/mailtrap/config.js
@@ -0,0 +1,49 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const DEFAULT_SEND_BASE_URL = 'https://send.api.mailtrap.io';
+const DEFAULT_SANDBOX_BASE_URL = 'https://sandbox.api.mailtrap.io';
+const DEFAULT_CATEGORY = 'transactional';
+const DEFAULT_USER_AGENT = '@alexify/mailer/mailtrap';
+
+/**
+ * Creates a resolved Mailtrap configuration by applying default values.
+ *
+ * @param config The Mailtrap configuration with optional fields.
+ * @returns A resolved configuration with all defaults applied.
+ * @throws {RangeError} If `sandbox` is `true` and `inboxId` is missing.
+ */
+const createMailtrapConfig = (config) => {
+  const sandbox = config.sandbox ?? false;
+
+  if (sandbox && !isValidInboxId(config.inboxId)) {
+    throw new RangeError('`inboxId` is required when Mailtrap sandbox mode is enabled.');
+  }
+
+  return {
+    apiToken: config.apiToken,
+    sandbox,
+    inboxId: config.inboxId,
+    sendBaseUrl: normalizeBaseUrl(config.sendBaseUrl ?? DEFAULT_SEND_BASE_URL),
+    sandboxBaseUrl: normalizeBaseUrl(config.sandboxBaseUrl ?? DEFAULT_SANDBOX_BASE_URL),
+    defaultCategory: config.defaultCategory ?? DEFAULT_CATEGORY,
+    metadata: config.metadata == null ? undefined : { ...config.metadata },
+    userAgent: config.userAgent ?? DEFAULT_USER_AGENT,
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    validateSsl: config.validateSsl ?? true,
+    headers: config.headers == null ? {} : { ...config.headers },
+  };
+};
+
+const isValidInboxId = (inboxId) => {
+  if (inboxId === undefined || inboxId === null) return false;
+  if (typeof inboxId === 'number') return Number.isFinite(inboxId);
+  return inboxId.trim().length > 0;
+};
+
+const normalizeBaseUrl = (baseUrl) => {
+  return baseUrl.replace(/\/+$/, '');
+};
+
+module.exports = { createMailtrapConfig };
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
new file mode 100644
index 0000000..67874f6
--- /dev/null
+++ b/src/mailtrap/http-client.js
@@ -0,0 +1,351 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/http-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+
+const maxErrorMessageLength = 500;
+const sandboxRateLimitWindowMilliseconds = 10_000;
+const sandboxRateLimitMessage = 'too many emails per second';
+
+/**
+ * Mailtrap API error class for API-specific failures.
+ */
+class MailtrapApiError extends Error {
+  statusCode;
+  retryAfterMilliseconds;
+  attempts;
+
+  /**
+   * Creates a Mailtrap API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code.
+   * @param retryAfterMilliseconds Retry delay from the response or Mailtrap's
+   * known sandbox rate-limit window.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(message, statusCode, retryAfterMilliseconds, attempts) {
+    super(message);
+    this.name = 'MailtrapApiError';
+    this.statusCode = statusCode;
+    this.retryAfterMilliseconds = retryAfterMilliseconds;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * Mailtrap request timeout error.
+ */
+class MailtrapTimeoutError extends Error {
+  /**
+   * Request timeout in milliseconds.
+   */
+  timeout;
+
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  attempts;
+
+  /**
+   * Creates a Mailtrap request timeout error.
+   *
+   * @param timeout Request timeout in milliseconds.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(timeout, attempts) {
+    super(`Mailtrap API request timed out after ${timeout} ms.`);
+    this.name = 'MailtrapTimeoutError';
+    this.timeout = timeout;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * Failure to read a successful Mailtrap response after the request was accepted.
+ * Retrying the request could send the message again.
+ */
+class MailtrapResponseError extends Error {
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  attempts;
+
+  /**
+   * Creates an error for an unreadable successful response.
+   *
+   * @param cause The response body error, including a possible timeout.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(cause, attempts) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name = 'MailtrapResponseError';
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * HTTP client wrapper for Mailtrap API requests.
+ */
+class MailtrapHttpClient {
+  config;
+
+  /**
+   * Creates a new Mailtrap HTTP client.
+   *
+   * @param config Resolved Mailtrap configuration.
+   */
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Sends a single message via Mailtrap API.
+   *
+   * @param messageData The JSON data to send to Mailtrap.
+   * @param signal Optional AbortSignal for cancellation.
+   * @returns Promise that resolves to the Mailtrap response.
+   */
+  sendMessage(messageData, signal) {
+    const url = this.resolveUrl('send');
+    return this.makeRequest(url, messageData, signal);
+  }
+
+  /**
+   * Sends multiple messages via Mailtrap batch API.
+   *
+   * @param requests The messages to send to Mailtrap.
+   * @param signal Optional AbortSignal for cancellation.
+   * @returns Promise that resolves to the Mailtrap batch response.
+   */
+  sendBatch(requests, signal) {
+    const url = this.resolveUrl('batch');
+    return this.makeRequest(url, { requests }, signal);
+  }
+
+  resolveUrl(kind) {
+    const baseUrl = this.config.sandbox ? this.config.sandboxBaseUrl : this.config.sendBaseUrl;
+    const suffix =
+      this.config.sandbox && this.config.inboxId != null ? `/${this.config.inboxId}` : '';
+    return `${baseUrl}/api/${kind}${suffix}`;
+  }
+
+  async makeRequest(url, body, signal) {
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      signal?.throwIfAborted();
+
+      let responseText;
+      try {
+        const { response, text } = await this.fetchWithAuth(url, body, signal);
+        responseText = text;
+
+        if (!response.ok) {
+          const message = parseErrorMessage(responseText, response.status);
+          throw new MailtrapApiError(
+            message,
+            response.status,
+            parseRetryAfter(response.headers.get('Retry-After')) ??
+              inferSandboxRetryAfter(message, response.status, this.config.sandbox),
+            attempt + 1,
+          );
+        }
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (error instanceof MailtrapResponseError) {
+          throw new MailtrapResponseError(error.cause, attempt + 1);
+        }
+
+        if (error instanceof MailtrapApiError && !isRetryable(error)) {
+          throw error;
+        }
+
+        if (error instanceof Error && error.name === 'AbortError' && signal?.aborted) {
+          throw error;
+        }
+
+        if (attempt === this.config.retries) {
+          throw withAttempts(lastError, attempt + 1);
+        }
+
+        await sleep(calculateRetryDelay(attempt, lastError), signal);
+        continue;
+      }
+
+      try {
+        return JSON.parse(responseText);
+      } catch (error) {
+        throw new SyntaxError(
+          `Invalid JSON response from Mailtrap API: ${
+            error instanceof Error ? error.message : String(error)
+          }.`,
+        );
+      }
+    }
+
+    throw lastError ?? new Error('Request failed after all retry attempts.');
+  }
+
+  async fetchWithAuth(url, body, signal) {
+    const headers = new Headers({
+      'Content-Type': 'application/json',
+      'Api-Token': this.config.apiToken,
+      'User-Agent': this.config.userAgent,
+    });
+
+    for (const [key, value] of Object.entries(this.config.headers)) {
+      headers.set(key, value);
+    }
+
+    const timeoutController = new AbortController();
+    const timeoutId =
+      this.config.timeout > 0
+        ? setTimeout(() => timeoutController.abort(), this.config.timeout)
+        : undefined;
+    const requestSignal = combineSignals(timeoutController.signal, signal);
+
+    let response;
+    try {
+      response = await globalThis.fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: requestSignal.signal,
+      });
+      const text = await response.text();
+      return { response, text };
+    } catch (error) {
+      signal?.throwIfAborted();
+      let cause = error;
+      if (
+        error instanceof Error &&
+        error.name === 'AbortError' &&
+        timeoutController.signal.aborted &&
+        !signal?.aborted
+      ) {
+        cause = new MailtrapTimeoutError(this.config.timeout);
+      }
+      // A 2xx response means Mailtrap may already have sent the message.
+      if (response?.ok) {
+        throw new MailtrapResponseError(cause);
+      }
+      throw cause;
+    } finally {
+      requestSignal.cleanup();
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+}
+
+const isRetryable = (error) => {
+  return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
+};
+
+const calculateRetryDelay = (attempt, error) => {
+  const baseDelay = Math.min(1000 * Math.pow(2, attempt), 10000);
+  const backoffDelay = Math.round(baseDelay / 2 + Math.random() * (baseDelay / 2));
+  if (error instanceof MailtrapApiError) {
+    return Math.max(backoffDelay, error.retryAfterMilliseconds ?? 0);
+  }
+  return backoffDelay;
+};
+
+const withAttempts = (error, attempts) => {
+  if (error instanceof MailtrapTimeoutError) {
+    return new MailtrapTimeoutError(error.timeout, attempts);
+  }
+  if (error instanceof MailtrapApiError) {
+    return new MailtrapApiError(
+      error.message,
+      error.statusCode,
+      error.retryAfterMilliseconds,
+      attempts,
+    );
+  }
+  return Object.assign(error, { attempts });
+};
+
+const parseRetryAfter = (header) => {
+  if (header == null || header === '') return undefined;
+  const asSeconds = Number(header);
+  if (Number.isFinite(asSeconds) && asSeconds >= 0) {
+    return Math.round(asSeconds * 1000);
+  }
+  const asDate = Date.parse(header);
+  if (Number.isNaN(asDate)) return undefined;
+  return Math.max(0, asDate - Date.now());
+};
+
+const inferSandboxRetryAfter = (message, statusCode, sandbox) => {
+  if (sandbox && statusCode === 429 && message.toLowerCase().includes(sandboxRateLimitMessage)) {
+    return sandboxRateLimitWindowMilliseconds;
+  }
+  return undefined;
+};
+
+const parseErrorMessage = (text, statusCode) => {
+  try {
+    const errorBody = JSON.parse(text);
+    if (typeof errorBody.message === 'string' && errorBody.message !== '') {
+      return truncateErrorMessage(errorBody.message);
+    }
+    if (Array.isArray(errorBody.errors) && errorBody.errors.length > 0) {
+      return truncateErrorMessage(errorBody.errors.join('; '));
+    }
+  } catch {
+    // Ignore if JSON parsing fails, as the body may be non-JSON.
+  }
+
+  return truncateErrorMessage(text) || `HTTP ${statusCode}`;
+};
+
+const truncateErrorMessage = (message) => {
+  return message.length > maxErrorMessageLength
+    ? `${message.slice(0, maxErrorMessageLength)}...`
+    : message;
+};
+
+const abortReason = (signal) => {
+  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+};
+
+const sleep = (ms, signal) => {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+
+    const timeoutState = {};
+    const onAbort = () => {
+      if (timeoutState.id !== undefined) {
+        clearTimeout(timeoutState.id);
+      }
+      signal?.removeEventListener('abort', onAbort);
+      reject(abortReason(signal));
+    };
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+
+    timeoutState.id = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+  });
+};
+
+module.exports = {
+  MailtrapApiError,
+  MailtrapTimeoutError,
+  MailtrapResponseError,
+  MailtrapHttpClient,
+};
diff --git a/src/mailtrap/index.d.ts b/src/mailtrap/index.d.ts
new file mode 100644
index 0000000..a771624
--- /dev/null
+++ b/src/mailtrap/index.d.ts
@@ -0,0 +1,322 @@
+// Types ported from upyo v0.7.0 (packages/mailtrap/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Configuration interface for Mailtrap transport connection settings.
+ *
+ * @example
+ * ```typescript
+ * const config: MailtrapConfig = {
+ *   apiToken: "your-api-token",
+ *   sandbox: true,
+ *   inboxId: 12345,
+ *   timeout: 30000,
+ *   retries: 3,
+ * };
+ * ```
+ */
+export interface MailtrapConfig {
+  /**
+   * Your Mailtrap API token.
+   *
+   * The token is sent as the `Api-Token` HTTP header.
+   */
+  readonly apiToken: string;
+  /**
+   * Whether to send through Mailtrap Email Sandbox instead of Email API.
+   *
+   * @default false
+   */
+  readonly sandbox?: boolean;
+  /**
+   * Sandbox inbox ID (from `mailtrap.io/sandboxes/{id}`).
+   *
+   * Required when `sandbox` is `true`.
+   */
+  readonly inboxId?: string | number;
+  /**
+   * Base URL for Mailtrap Email API (production sending).
+   *
+   * @default "https://send.api.mailtrap.io"
+   */
+  readonly sendBaseUrl?: string;
+  /**
+   * Base URL for Mailtrap Email Sandbox.
+   *
+   * @default "https://sandbox.api.mailtrap.io"
+   */
+  readonly sandboxBaseUrl?: string;
+  /**
+   * Default Mailtrap category when the Upyo message has no tags.
+   *
+   * @default "transactional"
+   */
+  readonly defaultCategory?: string;
+  /**
+   * Metadata to track with sent messages.  This metadata is not added as
+   * email headers.
+   */
+  readonly metadata?: Record<string, string>;
+  /**
+   * User-Agent header sent with every request.
+   *
+   * Mailtrap edge protection may block requests without a User-Agent.
+   *
+   * @default "@alexify/mailer/mailtrap"
+   */
+  readonly userAgent?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   *
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Whether to validate SSL certificates.
+   *
+   * @default true
+   */
+  readonly validateSsl?: boolean;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+}
+/**
+ * Resolved Mailtrap configuration with defaults applied.
+ */
+export type ResolvedMailtrapConfig = Required<
+  Omit<
+    MailtrapConfig,
+    | 'inboxId'
+    | 'sandbox'
+    | 'metadata'
+    | 'defaultCategory'
+    | 'userAgent'
+    | 'sendBaseUrl'
+    | 'sandboxBaseUrl'
+  >
+> & {
+  readonly inboxId?: string | number;
+  readonly sandbox: boolean;
+  readonly metadata?: Record<string, string>;
+  readonly defaultCategory: string;
+  readonly userAgent: string;
+  readonly sendBaseUrl: string;
+  readonly sandboxBaseUrl: string;
+};
+/**
+ * Creates a resolved Mailtrap configuration by applying default values.
+ *
+ * @param config The Mailtrap configuration with optional fields.
+ * @returns A resolved configuration with all defaults applied.
+ * @throws {RangeError} If `sandbox` is `true` and `inboxId` is missing.
+ */
+export declare function createMailtrapConfig(config: MailtrapConfig): ResolvedMailtrapConfig;
+
+/**
+ * Mailtrap transport implementation for sending emails via Mailtrap API.
+ *
+ * @example
+ * ```typescript
+ * import { createMessage } from "@alexify/mailer";
+ * import { MailtrapTransport } from "@alexify/mailer/mailtrap";
+ *
+ * const transport = new MailtrapTransport({
+ *   apiToken: "your-api-token",
+ *   sandbox: true,
+ *   inboxId: 12345,
+ * });
+ *
+ * const receipt = await transport.send(createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from Mailtrap",
+ *   content: { text: "Hello!" },
+ * }));
+ * ```
+ */
+export declare class MailtrapTransport implements Transport<'mailtrap'> {
+  readonly id = 'mailtrap';
+  /**
+   * The resolved Mailtrap configuration used by this transport.
+   */
+  readonly config: ResolvedMailtrapConfig;
+  /**
+   * Creates a new Mailtrap transport instance.
+   *
+   * @param config Mailtrap configuration including API token and options.
+   */
+  constructor(config: MailtrapConfig);
+  /**
+   * Sends a single email message via Mailtrap API.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns A receipt indicating success or failure.
+   * @throws {Error} If the caller aborts the operation.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'mailtrap'>>;
+  /**
+   * Sends multiple email messages via Mailtrap batch API.
+   *
+   * Messages are chunked into Mailtrap's maximum batch size of 500 messages.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'mailtrap'>>;
+}
+
+/**
+ * Mailtrap address object structure.
+ */
+export interface MailtrapAddress {
+  readonly email: string;
+  readonly name?: string;
+}
+/**
+ * Mailtrap attachment object structure.
+ */
+export interface MailtrapAttachment {
+  readonly content: string;
+  readonly filename: string;
+  readonly type?: string;
+  readonly disposition?: string;
+  readonly content_id?: string;
+}
+/**
+ * Mailtrap email object structure for API requests.
+ */
+export interface MailtrapEmail {
+  readonly from: MailtrapAddress;
+  readonly to: readonly MailtrapAddress[];
+  readonly subject: string;
+  readonly cc?: readonly MailtrapAddress[];
+  readonly bcc?: readonly MailtrapAddress[];
+  readonly reply_to?: MailtrapAddress;
+  readonly text?: string;
+  readonly html?: string;
+  readonly headers?: Record<string, string>;
+  readonly attachments?: readonly MailtrapAttachment[];
+  readonly category: string;
+  readonly custom_variables?: Record<string, string>;
+}
+/**
+ * Converts an Upyo message to Mailtrap API JSON format.
+ *
+ * @param message The Upyo message to convert.
+ * @param config The resolved Mailtrap configuration.
+ * @param signal Optional abort signal for cancellation.
+ * @returns JSON object ready for Mailtrap API submission.
+ * @throws {TypeError} If the message carries an invalid message identifier.
+ * @throws {RangeError} If the message has no text or HTML content.
+ * @throws {Error} If the caller aborts the operation.
+ */
+
+/**
+ * Response from Mailtrap API for sending a single message.
+ */
+export interface MailtrapSendResponse {
+  readonly success?: boolean;
+  readonly message_ids?: readonly string[];
+  readonly errors?: readonly string[];
+}
+/**
+ * Response for an individual message in a Mailtrap batch send.
+ */
+export interface MailtrapBatchItemResponse {
+  readonly success?: boolean;
+  readonly message_ids?: readonly string[];
+  readonly errors?: readonly string[];
+}
+/**
+ * Response from Mailtrap API for sending batch messages.
+ */
+export interface MailtrapBatchResponse {
+  readonly success?: boolean;
+  readonly responses?: readonly MailtrapBatchItemResponse[];
+  readonly errors?: readonly string[];
+}
+/**
+ * Error response from Mailtrap API.
+ */
+export interface MailtrapError {
+  readonly message?: string;
+  readonly errors?: readonly string[];
+}
+/**
+ * Mailtrap API error class for API-specific failures.
+ */
+export declare class MailtrapApiError extends Error {
+  readonly statusCode: number;
+  readonly retryAfterMilliseconds?: number;
+  readonly attempts?: number;
+  /**
+   * Creates a Mailtrap API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code.
+   * @param retryAfterMilliseconds Retry delay from the response or Mailtrap's
+   * known sandbox rate-limit window.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(
+    message: string,
+    statusCode: number,
+    retryAfterMilliseconds?: number,
+    attempts?: number,
+  );
+}
+/**
+ * Mailtrap request timeout error.
+ */
+export declare class MailtrapTimeoutError extends Error {
+  /**
+   * Request timeout in milliseconds.
+   */
+  readonly timeout: number;
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * Creates a Mailtrap request timeout error.
+   *
+   * @param timeout Request timeout in milliseconds.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(timeout: number, attempts?: number);
+}
+/**
+ * Failure to read a successful Mailtrap response after the request was accepted.
+ * Retrying the request could send the message again.
+ */
+export declare class MailtrapResponseError extends Error {
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * Creates an error for an unreadable successful response.
+   *
+   * @param cause The response body error, including a possible timeout.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(cause: unknown, attempts?: number);
+}
+/**
+ * HTTP client wrapper for Mailtrap API requests.
+ */
diff --git a/src/mailtrap/index.js b/src/mailtrap/index.js
new file mode 100644
index 0000000..e61d64e
--- /dev/null
+++ b/src/mailtrap/index.js
@@ -0,0 +1,26 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * @fileoverview Mailtrap transport for Upyo email library.
+ *
+ * This module provides a transport implementation for sending emails through
+ * Mailtrap's HTTP API.  It supports Email API and Email Sandbox sending,
+ * single messages, batch sending, attachments, and retry logic.
+ */
+
+const { MailtrapTransport } = require('./mailtrap-transport.js');
+const { createMailtrapConfig } = require('./config.js');
+const {
+  MailtrapApiError,
+  MailtrapResponseError,
+  MailtrapTimeoutError,
+} = require('./http-client.js');
+
+module.exports = {
+  MailtrapTransport,
+  createMailtrapConfig,
+  MailtrapApiError,
+  MailtrapResponseError,
+  MailtrapTimeoutError,
+};
diff --git a/src/mailtrap/mailtrap-transport.js b/src/mailtrap/mailtrap-transport.js
new file mode 100644
index 0000000..5f36dcf
--- /dev/null
+++ b/src/mailtrap/mailtrap-transport.js
@@ -0,0 +1,283 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/mailtrap-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createMailtrapConfig } = require('./config.js');
+const {
+  MailtrapApiError,
+  MailtrapHttpClient,
+  MailtrapResponseError,
+  MailtrapTimeoutError,
+} = require('./http-client.js');
+const { convertMessage } = require('./message-converter.js');
+
+const MAX_BATCH_SIZE = 500;
+
+/**
+ * Mailtrap transport implementation for sending emails via Mailtrap API.
+ *
+ * @example
+ * ```typescript
+ * import { createMessage } from "@alexify/mailer";
+ * import { MailtrapTransport } from "@alexify/mailer/mailtrap";
+ *
+ * const transport = new MailtrapTransport({
+ *   apiToken: "your-api-token",
+ *   sandbox: true,
+ *   inboxId: 12345,
+ * });
+ *
+ * const receipt = await transport.send(createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from Mailtrap",
+ *   content: { text: "Hello!" },
+ * }));
+ * ```
+ */
+class MailtrapTransport {
+  id = 'mailtrap';
+
+  /**
+   * The resolved Mailtrap configuration used by this transport.
+   */
+  config;
+
+  httpClient;
+
+  /**
+   * Creates a new Mailtrap transport instance.
+   *
+   * @param config Mailtrap configuration including API token and options.
+   */
+  constructor(config) {
+    this.config = createMailtrapConfig(config);
+    this.httpClient = new MailtrapHttpClient(this.config);
+  }
+
+  /**
+   * Sends a single email message via Mailtrap API.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns A receipt indicating success or failure.
+   * @throws {Error} If the caller aborts the operation.
+   */
+  async send(message, options) {
+    try {
+      options?.signal?.throwIfAborted();
+
+      const emailData = await convertMessage(message, this.config, options?.signal);
+
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendMessage(emailData, options?.signal);
+
+      return responseToReceipt(response);
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) throw error;
+      return createMailtrapFailure(error instanceof Error ? error.message : String(error), error);
+    }
+  }
+
+  /**
+   * Sends multiple email messages via Mailtrap batch API.
+   *
+   * Messages are chunked into Mailtrap's maximum batch size of 500 messages.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    let chunk = [];
+    for await (const message of messages) {
+      options?.signal?.throwIfAborted();
+      chunk.push(message);
+      if (chunk.length === MAX_BATCH_SIZE) {
+        yield* this.sendBatch(chunk, options);
+        chunk = [];
+      }
+    }
+    yield* this.sendBatch(chunk, options);
+  }
+  async *sendBatch(messages, options) {
+    if (messages.length === 0) return;
+
+    const batchData = [];
+    const receipts = [];
+
+    for (const message of messages) {
+      try {
+        batchData.push(await convertMessage(message, this.config, options?.signal));
+        receipts.push(undefined);
+      } catch (error) {
+        if (isCallerAbort(error, options?.signal)) throw error;
+        receipts.push(
+          createMailtrapFailure(error instanceof Error ? error.message : String(error), error),
+        );
+      }
+    }
+
+    if (batchData.length === 0) {
+      for (const receipt of receipts) {
+        if (receipt !== undefined) yield receipt;
+      }
+      return;
+    }
+
+    try {
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendBatch(batchData, options?.signal);
+
+      if (response.success === false) {
+        const errorMessage = formatErrors(response.errors) ?? 'Mailtrap batch request failed.';
+        for (const receipt of receipts) {
+          if (receipt !== undefined) {
+            yield receipt;
+            continue;
+          }
+          yield createFailedReceipt(errorMessage, {
+            provider: 'mailtrap',
+            category: 'rejected',
+            code: 'mailtrap.batch_failed',
+            retryable: false,
+            providerDetails: response,
+          });
+        }
+        return;
+      }
+
+      const itemResponses = response.responses ?? [];
+      let responseIndex = 0;
+
+      for (const receipt of receipts) {
+        if (receipt !== undefined) {
+          yield receipt;
+          continue;
+        }
+
+        const item = itemResponses[responseIndex++];
+        yield itemResponseToReceipt(item);
+      }
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) throw error;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      for (const receipt of receipts) {
+        if (receipt !== undefined) {
+          yield receipt;
+          continue;
+        }
+        yield createMailtrapFailure(errorMessage, error);
+      }
+    }
+  }
+}
+
+const responseToReceipt = (response) => {
+  return toReceipt(response, {
+    unsuccessfulMessage: 'Mailtrap reported send failure.',
+    unsuccessfulCode: 'mailtrap.unsuccessful',
+    missingMessageIdMessage: 'Mailtrap response is missing a message ID.',
+  });
+};
+
+const itemResponseToReceipt = (response) => {
+  return toReceipt(response, {
+    unsuccessfulMessage: 'Mailtrap reported batch item failure.',
+    unsuccessfulCode: 'mailtrap.batch_item_failed',
+    missingMessageIdMessage: 'Mailtrap batch response is missing a message ID.',
+  });
+};
+
+const toReceipt = (response, options) => {
+  if (response?.success === false) {
+    return createFailedReceipt(formatErrors(response.errors) ?? options.unsuccessfulMessage, {
+      provider: 'mailtrap',
+      category: 'rejected',
+      code: options.unsuccessfulCode,
+      retryable: false,
+      providerDetails: response,
+    });
+  }
+
+  const messageId = response?.message_ids?.[0];
+  if (messageId == null || messageId === '') {
+    return createFailedReceipt(options.missingMessageIdMessage, {
+      provider: 'mailtrap',
+      category: 'unknown',
+      code: 'mailtrap.missing_message_id',
+      retryable: false,
+      providerDetails: response,
+    });
+  }
+
+  return {
+    successful: true,
+    messageId,
+    provider: 'mailtrap',
+  };
+};
+
+const createMailtrapFailure = (message, error) => {
+  if (error instanceof MailtrapResponseError) {
+    return createFailedReceipt(message, {
+      provider: 'mailtrap',
+      ...(error.cause instanceof MailtrapTimeoutError
+        ? { category: 'timeout', code: 'timeout' }
+        : {}),
+      retryable: false,
+      attempts: error.attempts,
+    });
+  }
+
+  if (error instanceof MailtrapApiError) {
+    return createFailedReceipt(message, {
+      provider: 'mailtrap',
+      statusCode: error.statusCode,
+      retryAfterMilliseconds: error.retryAfterMilliseconds,
+      attempts: error.attempts,
+    });
+  }
+
+  if (error instanceof MailtrapTimeoutError) {
+    return createFailedReceipt(message, {
+      provider: 'mailtrap',
+      category: 'timeout',
+      code: 'timeout',
+      retryable: true,
+      attempts: error.attempts,
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'mailtrap',
+    attempts: getErrorAttempts(error),
+  });
+};
+
+const formatErrors = (errors) => {
+  if (errors == null || errors.length === 0) return undefined;
+  return errors.join('; ');
+};
+
+const getErrorAttempts = (error) => {
+  if (typeof error !== 'object' || error == null || !('attempts' in error)) {
+    return undefined;
+  }
+  const attempts = error.attempts;
+  return typeof attempts === 'number' ? attempts : undefined;
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+module.exports = { MailtrapTransport };
diff --git a/src/mailtrap/message-converter.js b/src/mailtrap/message-converter.js
new file mode 100644
index 0000000..6244a7e
--- /dev/null
+++ b/src/mailtrap/message-converter.js
@@ -0,0 +1,228 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createCalendarAttachment } = require('../core/calendar.js');
+const { combineSignals } = require('../core/abort-signal.js');
+const { readAttachmentContent } = require('../core/attachment.js');
+const { resolveThreadingHeaders } = require('../core/message-id.js');
+
+const STANDARD_HEADERS = new Set([
+  'from',
+  'to',
+  'cc',
+  'bcc',
+  'reply-to',
+  'subject',
+  'date',
+  'message-id',
+  'content-type',
+  'content-transfer-encoding',
+  'mime-version',
+  'x-priority',
+]);
+
+/**
+ * Converts an Upyo message to Mailtrap API JSON format.
+ *
+ * @param message The Upyo message to convert.
+ * @param config The resolved Mailtrap configuration.
+ * @param signal Optional abort signal for cancellation.
+ * @returns JSON object ready for Mailtrap API submission.
+ * @throws {TypeError} If the message carries an invalid message identifier.
+ * @throws {RangeError} If the message has no text or HTML content.
+ * @throws {Error} If the caller aborts the operation.
+ */
+const convertMessage = async (message, config, signal) => {
+  signal?.throwIfAborted();
+
+  // A transport that cannot compose a `text/calendar` alternative carries the
+  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
+  // own files so that a client looking for the first calendar part finds it.
+  const attachments =
+    message.calendar == null
+      ? message.attachments
+      : [createCalendarAttachment(message.calendar), ...message.attachments];
+
+  const emailData = {
+    from: formatAddress(message.sender),
+    to: message.recipients.map(formatAddress),
+    subject: message.subject,
+    category: resolveCategory(message.tags, config.defaultCategory),
+  };
+
+  if (message.ccRecipients.length > 0) {
+    emailData.cc = message.ccRecipients.map(formatAddress);
+  }
+
+  if (message.bccRecipients.length > 0) {
+    emailData.bcc = message.bccRecipients.map(formatAddress);
+  }
+
+  if (message.replyRecipients.length > 0) {
+    emailData.reply_to = formatAddress(message.replyRecipients[0]);
+  }
+
+  if ('html' in message.content) {
+    emailData.html = message.content.html;
+    if (message.content.text) {
+      emailData.text = message.content.text;
+    }
+  } else {
+    emailData.text = message.content.text;
+  }
+
+  if (!emailData.text && !emailData.html) {
+    throw new RangeError('Mailtrap requires at least one of text or HTML content.');
+  }
+
+  const customVariables = buildCustomVariables(message.tags, config.metadata);
+  if (Object.keys(customVariables).length > 0) {
+    emailData.custom_variables = customVariables;
+  }
+
+  const headers = {};
+  if (message.priority !== 'normal') {
+    const priorityMap = {
+      high: '1',
+      normal: '3',
+      low: '5',
+    };
+    headers['X-Priority'] = priorityMap[message.priority];
+  }
+
+  // Reply threading comes from the typed fields when the message defines them,
+  // and from a custom header otherwise.  A field the message owns but left
+  // empty writes nothing, which is how a caller drops an inherited header.
+  const threading = resolveThreadingHeaders(message);
+  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+
+  for (const [key, value] of message.headers.entries()) {
+    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
+      headers[key] = value;
+    }
+  }
+  for (const [name, value] of threading) {
+    if (value != null) headers[name] = value;
+  }
+
+  if (Object.keys(headers).length > 0) {
+    emailData.headers = headers;
+  }
+
+  if (attachments.length > 0) {
+    const cancellation = new AbortController();
+    const combined = combineSignals(cancellation.signal, signal);
+    try {
+      emailData.attachments = await Promise.all(
+        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
+      );
+    } finally {
+      cancellation.abort();
+      combined.cleanup();
+    }
+  }
+
+  signal?.throwIfAborted();
+
+  return emailData;
+};
+
+const resolveCategory = (tags, fallback) => {
+  return tags[0] ?? fallback;
+};
+
+const buildCustomVariables = (tags, metadata) => {
+  const customVariables = {};
+
+  if (metadata != null) {
+    for (const [key, value] of Object.entries(metadata)) {
+      customVariables[key] = value;
+    }
+  }
+
+  for (const tag of tags.slice(1)) {
+    customVariables[`tag_${tag}`] = tag;
+  }
+
+  return customVariables;
+};
+
+const formatAddress = (address) => {
+  if (address.name) {
+    return { email: address.address, name: address.name };
+  }
+  return { email: address.address };
+};
+
+const convertAttachment = async (attachment, signal) => {
+  signal?.throwIfAborted();
+  const contentBytes = await readAttachmentContent(attachment.content, signal);
+  signal?.throwIfAborted();
+  const converted = {
+    content: uint8ArrayToBase64(contentBytes),
+    filename: attachment.filename,
+  };
+
+  if (attachment.contentType) {
+    converted.type = attachment.contentType;
+  }
+
+  if (attachment.inline && attachment.contentId) {
+    converted.disposition = 'inline';
+    converted.content_id = attachment.contentId;
+  } else {
+    converted.disposition = 'attachment';
+  }
+
+  return converted;
+};
+
+const uint8ArrayToBase64 = (bytes) => {
+  const nativeToBase64 = getNativeToBase64(bytes);
+  if (nativeToBase64 != null) {
+    return nativeToBase64();
+  }
+
+  const bufferBase64 = getBufferBase64(bytes);
+  if (bufferBase64 != null) {
+    return bufferBase64;
+  }
+
+  const chunkSize = 0x1000;
+  const chunks = [];
+
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + chunkSize)));
+  }
+
+  return btoa(chunks.join(''));
+};
+
+const getNativeToBase64 = (bytes) => {
+  const candidate = bytes;
+  const toBase64 = candidate.toBase64;
+  if (typeof toBase64 !== 'function') return undefined;
+  return () => toBase64.call(bytes);
+};
+
+const getBufferBase64 = (bytes) => {
+  const candidate = globalThis.Buffer;
+  if (typeof candidate?.from !== 'function') return undefined;
+
+  try {
+    const buffer = candidate.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (buffer == null || typeof buffer.toString !== 'function') {
+      return undefined;
+    }
+    const base64 = buffer.toString('base64');
+    return typeof base64 === 'string' ? base64 : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const isStandardHeader = (headerName) => {
+  return STANDARD_HEADERS.has(headerName.toLowerCase());
+};
+
+module.exports = { convertMessage };
diff --git a/tests/e2e/mailtrap-transport.e2e.test.js b/tests/e2e/mailtrap-transport.e2e.test.js
new file mode 100644
index 0000000..80c5913
--- /dev/null
+++ b/tests/e2e/mailtrap-transport.e2e.test.js
@@ -0,0 +1,107 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/mailtrap-transport.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { MailtrapTransport } = require('../../src/mailtrap/mailtrap-transport.js');
+const {
+  createTestMessage,
+  getTestConfig,
+  isE2eTestingEnabled,
+} = require('../helpers/mailtrap/test-config.js');
+
+const describeE2E = isE2eTestingEnabled() ? describe : describe.skip;
+let e2eChain = Promise.resolve();
+
+describeE2E('MailtrapTransport E2E', { concurrency: false }, () => {
+  const waitForRateLimit = async () => {
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+  };
+
+  const runE2e = async (callback) => {
+    const previous = e2eChain;
+    let release = () => {};
+    e2eChain = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+
+    try {
+      return await callback();
+    } finally {
+      release();
+    }
+  };
+
+  const assertSuccessfulReceipt = (receipt) => {
+    assert.ok(
+      receipt.successful,
+      receipt.successful ? undefined : receipt.errorMessages.join(', '),
+    );
+    assert.ok(receipt.messageId);
+  };
+
+  it('sends a simple text email to sandbox', async () => {
+    await runE2e(async () => {
+      await waitForRateLimit();
+
+      const transport = new MailtrapTransport(getTestConfig().mailtrap);
+      const receipt = await transport.send(
+        createTestMessage({
+          subject: '[E2E] Mailtrap text email',
+          content: { text: 'This is a Mailtrap E2E test email.' },
+        }),
+      );
+
+      assertSuccessfulReceipt(receipt);
+      console.log(`Sent Mailtrap text email with ID: ${receipt.messageId}`);
+    });
+  });
+
+  it('sends an HTML email to sandbox', async () => {
+    await runE2e(async () => {
+      await waitForRateLimit();
+
+      const transport = new MailtrapTransport(getTestConfig().mailtrap);
+      const receipt = await transport.send(
+        createTestMessage({
+          subject: '[E2E] Mailtrap HTML email',
+          content: {
+            html: '<h1>Hello from Upyo</h1><p>This is a Mailtrap test.</p>',
+            text: 'Hello from Upyo\n\nThis is a Mailtrap test.',
+          },
+        }),
+      );
+
+      assertSuccessfulReceipt(receipt);
+      console.log(`Sent Mailtrap HTML email with ID: ${receipt.messageId}`);
+    });
+  });
+
+  it('sends multiple emails via batch API', async () => {
+    await runE2e(async () => {
+      await waitForRateLimit();
+
+      const transport = new MailtrapTransport(getTestConfig().mailtrap);
+      const receipts = [];
+
+      for await (const receipt of transport.sendMany([
+        createTestMessage({
+          subject: '[E2E] Mailtrap batch 1',
+          content: { text: 'Batch message 1' },
+        }),
+        createTestMessage({
+          subject: '[E2E] Mailtrap batch 2',
+          content: { text: 'Batch message 2' },
+        }),
+      ])) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      for (const receipt of receipts) {
+        assertSuccessfulReceipt(receipt);
+      }
+    });
+  });
+});
diff --git a/tests/helpers/mailtrap/test-config.js b/tests/helpers/mailtrap/test-config.js
new file mode 100644
index 0000000..3c24cc7
--- /dev/null
+++ b/tests/helpers/mailtrap/test-config.js
@@ -0,0 +1,85 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isEmailAddress } = require('../../../src/core/address.js');
+const process = require('node:process');
+
+/**
+ * Checks whether Mailtrap E2E testing is configured.
+ *
+ * @returns `true` if all required environment variables are present.
+ */
+const isE2eTestingEnabled = () => {
+  return Boolean(
+    process.env.MAILTRAP_API_TOKEN &&
+    process.env.MAILTRAP_INBOX_ID &&
+    isEmailAddress(process.env.MAILTRAP_FROM) &&
+    isEmailAddress(process.env.MAILTRAP_TO),
+  );
+};
+
+/**
+ * Reads Mailtrap E2E test configuration from environment variables.
+ *
+ * @returns Mailtrap E2E test configuration.
+ * @throws {Error} If required environment variables are missing.
+ * @throws {TypeError} If the sender or recipient is not a valid email address.
+ */
+const getTestConfig = () => {
+  const apiToken = process.env.MAILTRAP_API_TOKEN;
+  const inboxId = process.env.MAILTRAP_INBOX_ID;
+  const from = process.env.MAILTRAP_FROM;
+  const to = process.env.MAILTRAP_TO;
+
+  if (!apiToken || !inboxId || !from || !to) {
+    throw new Error(
+      'MAILTRAP_API_TOKEN, MAILTRAP_INBOX_ID, MAILTRAP_FROM, and MAILTRAP_TO are required.',
+    );
+  }
+
+  if (!isEmailAddress(from) || !isEmailAddress(to)) {
+    throw new TypeError('MAILTRAP_FROM and MAILTRAP_TO must be valid email addresses.');
+  }
+
+  return {
+    mailtrap: {
+      apiToken,
+      sandbox: process.env.MAILTRAP_SANDBOX !== 'false',
+      inboxId,
+      ...(process.env.MAILTRAP_SEND_BASE_URL && {
+        sendBaseUrl: process.env.MAILTRAP_SEND_BASE_URL,
+      }),
+      ...(process.env.MAILTRAP_SANDBOX_BASE_URL && {
+        sandboxBaseUrl: process.env.MAILTRAP_SANDBOX_BASE_URL,
+      }),
+    },
+    from,
+    to,
+  };
+};
+
+/**
+ * Creates a test message for Mailtrap E2E tests.
+ *
+ * @param overrides Message fields to override.
+ * @returns A test message.
+ */
+const createTestMessage = (overrides = {}) => {
+  const config = getTestConfig();
+  return {
+    sender: { address: config.from, name: 'Upyo Test' },
+    recipients: [{ address: config.to }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: '[E2E] Mailtrap test',
+    content: { text: 'This is a test email sent through Mailtrap.' },
+    attachments: [],
+    priority: 'normal',
+    tags: ['mailer-test'],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+module.exports = { isE2eTestingEnabled, getTestConfig, createTestMessage };
diff --git a/tests/types/mailtrap.test-d.ts b/tests/types/mailtrap.test-d.ts
new file mode 100644
index 0000000..1b3669f
--- /dev/null
+++ b/tests/types/mailtrap.test-d.ts
@@ -0,0 +1,28 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import {
+  MailtrapApiError,
+  MailtrapTimeoutError,
+  MailtrapTransport,
+  createMailtrapConfig,
+  type MailtrapConfig,
+  type ResolvedMailtrapConfig,
+} from '../../src/mailtrap/index.js';
+
+const transport = new MailtrapTransport({ apiToken: 'token', sandbox: true, inboxId: 42 });
+expectAssignable<Transport<'mailtrap'>>(transport);
+expectType<ResolvedMailtrapConfig>(createMailtrapConfig({ apiToken: 'token' }));
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'mailtrap'>>>(transport.send(message));
+expectType<AsyncIterable<Receipt<'mailtrap'>>>(transport.sendMany([message]));
+
+expectAssignable<MailtrapConfig>({ apiToken: 'token', defaultCategory: 'welcome', retries: 1 });
+expectAssignable<Error>(new MailtrapApiError('Unauthorized', 401));
+expectAssignable<Error>(new MailtrapTimeoutError(1000));
+expectError(new MailtrapTransport({ sandbox: true }));
diff --git a/tests/unit/mailtrap-config.test.js b/tests/unit/mailtrap-config.test.js
new file mode 100644
index 0000000..20441c3
--- /dev/null
+++ b/tests/unit/mailtrap-config.test.js
@@ -0,0 +1,124 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { createMailtrapConfig } = require('../../src/mailtrap/config.js');
+
+describe('createMailtrapConfig', () => {
+  it('applies default values to optional fields', () => {
+    const config = {
+      apiToken: 'test-token',
+    };
+
+    const resolved = createMailtrapConfig(config);
+
+    assert.equal(resolved.apiToken, 'test-token');
+    assert.ok(!resolved.sandbox);
+    assert.equal(resolved.inboxId, undefined);
+    assert.equal(resolved.sendBaseUrl, 'https://send.api.mailtrap.io');
+    assert.equal(resolved.sandboxBaseUrl, 'https://sandbox.api.mailtrap.io');
+    assert.equal(resolved.defaultCategory, 'transactional');
+    assert.equal(resolved.userAgent, '@alexify/mailer/mailtrap');
+    assert.equal(resolved.timeout, 30000);
+    assert.equal(resolved.retries, 3);
+    assert.ok(resolved.validateSsl);
+    assert.deepEqual(resolved.headers, {});
+    assert.equal(resolved.metadata, undefined);
+  });
+
+  it('preserves provided optional values', () => {
+    const config = {
+      apiToken: 'test-token',
+      sandbox: true,
+      inboxId: 12345,
+      sendBaseUrl: 'https://send.example.com',
+      sandboxBaseUrl: 'https://sandbox.example.com',
+      defaultCategory: 'integration-test',
+      metadata: { campaign_id: 'welcome-2026' },
+      userAgent: 'test-agent',
+      timeout: 60000,
+      retries: 5,
+      headers: { 'X-Custom': 'value' },
+    };
+
+    const resolved = createMailtrapConfig(config);
+
+    assert.equal(resolved.apiToken, 'test-token');
+    assert.ok(resolved.sandbox);
+    assert.equal(resolved.inboxId, 12345);
+    assert.equal(resolved.sendBaseUrl, 'https://send.example.com');
+    assert.equal(resolved.sandboxBaseUrl, 'https://sandbox.example.com');
+    assert.equal(resolved.defaultCategory, 'integration-test');
+    assert.deepEqual(resolved.metadata, { campaign_id: 'welcome-2026' });
+    assert.equal(resolved.userAgent, 'test-agent');
+    assert.equal(resolved.timeout, 60000);
+    assert.equal(resolved.retries, 5);
+    assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
+  });
+
+  it('copies custom headers', () => {
+    const headers = { 'X-Custom': 'value' };
+    const resolved = createMailtrapConfig({
+      apiToken: 'test-token',
+      headers,
+    });
+
+    headers['X-Custom'] = 'changed';
+
+    assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
+  });
+
+  it('preserves zero timeout and retry values', () => {
+    const resolved = createMailtrapConfig({
+      apiToken: 'test-token',
+      timeout: 0,
+      retries: 0,
+    });
+
+    assert.equal(resolved.timeout, 0);
+    assert.equal(resolved.retries, 0);
+  });
+
+  it('normalizes trailing slashes from base URLs', () => {
+    const resolved = createMailtrapConfig({
+      apiToken: 'test-token',
+      sendBaseUrl: 'https://send.example.com///',
+      sandboxBaseUrl: 'https://sandbox.example.com///',
+    });
+
+    assert.equal(resolved.sendBaseUrl, 'https://send.example.com');
+    assert.equal(resolved.sandboxBaseUrl, 'https://sandbox.example.com');
+  });
+
+  it('requires inboxId when sandbox mode is enabled', () => {
+    assert.throws(
+      () =>
+        createMailtrapConfig({
+          apiToken: 'test-token',
+          sandbox: true,
+        }),
+      {
+        name: 'RangeError',
+        message: '`inboxId` is required when Mailtrap sandbox mode is enabled.',
+      },
+    );
+  });
+
+  it('rejects non-finite numeric inbox IDs', () => {
+    for (const inboxId of [Number.NaN, Number.POSITIVE_INFINITY]) {
+      assert.throws(
+        () =>
+          createMailtrapConfig({
+            apiToken: 'test-token',
+            sandbox: true,
+            inboxId,
+          }),
+        {
+          name: 'RangeError',
+          message: '`inboxId` is required when Mailtrap sandbox mode is enabled.',
+        },
+      );
+    }
+  });
+});
diff --git a/tests/unit/mailtrap-message-converter.test.js b/tests/unit/mailtrap-message-converter.test.js
new file mode 100644
index 0000000..115832a
--- /dev/null
+++ b/tests/unit/mailtrap-message-converter.test.js
@@ -0,0 +1,395 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/message-converter.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { createMailtrapConfig } = require('../../src/mailtrap/config.js');
+const { convertMessage } = require('../../src/mailtrap/message-converter.js');
+
+const baseConfig = createMailtrapConfig({ apiToken: 'test-token' });
+
+const createBaseMessage = (overrides = {}) => {
+  return {
+    sender: { address: 'sender@example.com' },
+    recipients: [{ address: 'recipient@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test content' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+describe('convertMessage', () => {
+  it('bounds fallback Base64 calls while preserving attachment bytes', async () => {
+    const nativeDescriptor = Object.getOwnPropertyDescriptor(Uint8Array.prototype, 'toBase64');
+    const bufferDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'Buffer');
+    const fromCharCode = String.fromCharCode;
+    const bytes = Uint8Array.from({ length: 1024 * 1024 + 1 }, (_, i) => i % 256);
+    const message = createBaseMessage({
+      attachments: [
+        {
+          filename: 'bytes.bin',
+          contentType: 'application/octet-stream',
+          contentId: 'bytes',
+          content: bytes,
+          inline: false,
+        },
+      ],
+    });
+    let largestCall = 0;
+
+    try {
+      // oxlint-disable-next-line no-extend-native -- upstream
+      Object.defineProperty(Uint8Array.prototype, 'toBase64', {
+        configurable: true,
+        value: undefined,
+      });
+      Object.defineProperty(globalThis, 'Buffer', {
+        configurable: true,
+        value: undefined,
+      });
+      String.fromCharCode = (...codes) => {
+        largestCall = Math.max(largestCall, codes.length);
+        assert.ok(codes.length <= 4096, 'Fallback calls must stay within 4096 arguments.');
+        return fromCharCode(...codes);
+      };
+
+      const result = await convertMessage(message, baseConfig);
+      assert.ok(largestCall > 0);
+      assert.ok(result.attachments);
+      const decoded = Uint8Array.from(atob(result.attachments[0].content), (character) =>
+        character.charCodeAt(0),
+      );
+      assert.deepEqual(decoded, bytes);
+    } finally {
+      String.fromCharCode = fromCharCode;
+      if (nativeDescriptor == null) {
+        Reflect.deleteProperty(Uint8Array.prototype, 'toBase64');
+      } else {
+        // oxlint-disable-next-line no-extend-native -- upstream
+        Object.defineProperty(Uint8Array.prototype, 'toBase64', nativeDescriptor);
+      }
+      if (bufferDescriptor == null) {
+        Reflect.deleteProperty(globalThis, 'Buffer');
+      } else {
+        Object.defineProperty(globalThis, 'Buffer', bufferDescriptor);
+      }
+    }
+  });
+
+  it('converts a basic text message', async () => {
+    const result = await convertMessage(createBaseMessage(), baseConfig);
+
+    assert.deepEqual(result.from, { email: 'sender@example.com' });
+    assert.deepEqual(result.to, [{ email: 'recipient@example.com' }]);
+    assert.equal(result.subject, 'Test Subject');
+    assert.equal(result.text, 'Test content');
+    assert.equal(result.html, undefined);
+    assert.equal(result.category, 'transactional');
+  });
+
+  it('formats addresses with names', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        sender: { address: 'sender@example.com', name: 'Sender Name' },
+        recipients: [
+          {
+            address: 'recipient@example.com',
+            name: 'Recipient Name',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.from, {
+      email: 'sender@example.com',
+      name: 'Sender Name',
+    });
+    assert.deepEqual(result.to, [
+      {
+        email: 'recipient@example.com',
+        name: 'Recipient Name',
+      },
+    ]);
+  });
+
+  it('converts HTML content with text alternative', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        content: { html: '<h1>Hello</h1>', text: 'Hello' },
+      }),
+      baseConfig,
+    );
+
+    assert.equal(result.html, '<h1>Hello</h1>');
+    assert.equal(result.text, 'Hello');
+  });
+
+  it('handles CC, BCC, and reply-to recipients', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        ccRecipients: [{ address: 'cc@example.com' }],
+        bccRecipients: [{ address: 'bcc@example.com' }],
+        replyRecipients: [{ address: 'reply@example.com' }],
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.cc, [{ email: 'cc@example.com' }]);
+    assert.deepEqual(result.bcc, [{ email: 'bcc@example.com' }]);
+    assert.deepEqual(result.reply_to, { email: 'reply@example.com' });
+  });
+
+  it('maps tags and metadata to category and custom variables', async () => {
+    const config = createMailtrapConfig({
+      apiToken: 'test-token',
+      metadata: { user_id: '123' },
+    });
+
+    const result = await convertMessage(
+      createBaseMessage({ tags: ['newsletter', 'welcome'] }),
+      config,
+    );
+
+    assert.equal(result.category, 'newsletter');
+    assert.deepEqual(result.custom_variables, {
+      user_id: '123',
+      tag_welcome: 'welcome',
+    });
+  });
+
+  it('uses defaultCategory when message has no tags', async () => {
+    const config = createMailtrapConfig({
+      apiToken: 'test-token',
+      defaultCategory: 'integration-test',
+    });
+
+    const result = await convertMessage(createBaseMessage(), config);
+
+    assert.equal(result.category, 'integration-test');
+  });
+
+  it('maps priority and custom headers', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        priority: 'high',
+        headers: new Headers({
+          'X-Custom': 'value',
+          Subject: 'ignored',
+        }),
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.headers, {
+      'X-Priority': '1',
+      'x-custom': 'value',
+    });
+  });
+
+  it('converts attachments', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            inline: false,
+            filename: 'test.txt',
+            content: Promise.resolve(new TextEncoder().encode('hello')),
+            contentType: 'text/plain',
+            contentId: 'cid@example.com',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.equal(result.attachments?.length, 1);
+    assert.equal(result.attachments?.[0]?.filename, 'test.txt');
+    assert.equal(result.attachments?.[0]?.type, 'text/plain');
+    assert.equal(result.attachments?.[0]?.disposition, 'attachment');
+    assert.equal(result.attachments?.[0]?.content, btoa('hello'));
+  });
+
+  it('propagates aborts while converting attachments', async () => {
+    const controller = new AbortController();
+    const reason = new Error('Stop converting Mailtrap message.');
+    const content = new Promise(() => {});
+    const conversion = convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            inline: false,
+            filename: 'slow.txt',
+            content,
+            contentType: 'text/plain',
+            contentId: '',
+          },
+        ],
+      }),
+      baseConfig,
+      controller.signal,
+    );
+
+    controller.abort(reason);
+
+    await assert.rejects(
+      Promise.race([
+        conversion,
+        new Promise((_resolve, reject) => {
+          setTimeout(() => reject(new Error('Conversion did not abort.')), 50);
+        }),
+      ]),
+      (error) => error === reason,
+    );
+  });
+
+  it('rejects messages without text or HTML content', async () => {
+    await assert.rejects(
+      () => convertMessage(createBaseMessage({ content: { text: '' } }), baseConfig),
+      {
+        name: 'RangeError',
+        message: 'Mailtrap requires at least one of text or HTML content.',
+      },
+    );
+  });
+});
+
+const threadingConfig = createMailtrapConfig({ apiToken: 'test-token' });
+
+const headerOf = (headers, name) =>
+  Object.entries(headers)
+    .filter(([key]) => key.toLowerCase() === name.toLowerCase())
+    .map(([, value]) => value);
+
+describe('convertMessage() reply threading', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Re: Your request',
+    content: { text: 'Thanks for getting in touch.' },
+  };
+
+  it('writes the typed threading fields', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: '122@example.com',
+      references: ['120@example.com', '121@example.com'],
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<122@example.com>']);
+    assert.deepEqual(headerOf(result, 'References'), ['<120@example.com> <121@example.com>']);
+  });
+
+  it('prefers a typed field over a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: ['typed@example.com'],
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<typed@example.com>']);
+  });
+
+  it('lets an empty list suppress a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: [],
+      references: [],
+      headers: {
+        'In-Reply-To': '<custom@example.com>',
+        References: '<custom@example.com>',
+      },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), []);
+    assert.deepEqual(headerOf(result, 'References'), []);
+  });
+
+  it('lets a custom header through when the field is unset', async () => {
+    const message = createMessage({
+      ...base,
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<custom@example.com>']);
+  });
+});
+
+const CALENDAR_ICS =
+  [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'SUMMARY:Lunch',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+/** The invitation content as the providers below carry it: Base64. */
+const CALENDAR_BASE64 = btoa(CALENDAR_ICS);
+
+const AGENDA_ATTACHMENT = {
+  inline: false,
+  filename: 'agenda.txt',
+  content: new TextEncoder().encode('agenda'),
+  contentType: 'text/plain',
+  contentId: '',
+};
+
+describe('convertMessage() calendar', () => {
+  const invitation = (overrides = {}) =>
+    createBaseMessage({
+      calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+      ...overrides,
+    });
+
+  it('should carry the calendar as an invite.ics attachment', async () => {
+    const result = await convertMessage(invitation(), baseConfig);
+
+    assert.equal(result.attachments?.length, 1);
+    assert.equal(result.attachments?.[0].filename, 'invite.ics');
+    assert.equal(result.attachments?.[0].type, 'text/calendar; charset=utf-8; method=REQUEST');
+    assert.equal(result.attachments?.[0].content, CALENDAR_BASE64);
+    // An empty content ID keeps the part an ordinary attachment.
+    assert.equal(result.attachments?.[0].disposition, 'attachment');
+  });
+
+  it('should place the invitation ahead of the other attachments', async () => {
+    const result = await convertMessage(
+      invitation({ attachments: [AGENDA_ATTACHMENT] }),
+      baseConfig,
+    );
+
+    assert.deepEqual(
+      result.attachments?.map((attachment) => attachment.filename),
+      ['invite.ics', 'agenda.txt'],
+    );
+  });
+
+  it('should reject calendar content that never passed createMessage()', async () => {
+    await assert.rejects(
+      () =>
+        convertMessage(
+          createBaseMessage({
+            calendar: { method: 'REQUEST', content: 'not a calendar' },
+          }),
+          baseConfig,
+        ),
+      { name: 'TypeError' },
+    );
+  });
+});
diff --git a/tests/unit/mailtrap-test-config.test.js b/tests/unit/mailtrap-test-config.test.js
new file mode 100644
index 0000000..495ffd2
--- /dev/null
+++ b/tests/unit/mailtrap-test-config.test.js
@@ -0,0 +1,39 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/test-utils/test-config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const process = require('node:process');
+const { getTestConfig, isE2eTestingEnabled } = require('../helpers/mailtrap/test-config.js');
+
+const environmentKeys = ['MAILTRAP_API_TOKEN', 'MAILTRAP_INBOX_ID', 'MAILTRAP_FROM', 'MAILTRAP_TO'];
+
+describe('Mailtrap E2E test config', () => {
+  it('rejects invalid email addresses', () => {
+    const originalEnvironment = Object.fromEntries(
+      environmentKeys.map((key) => [key, process.env[key]]),
+    );
+
+    try {
+      process.env.MAILTRAP_API_TOKEN = 'test-token';
+      process.env.MAILTRAP_INBOX_ID = '12345';
+      process.env.MAILTRAP_FROM = 'not-an-email';
+      process.env.MAILTRAP_TO = 'recipient@example.com';
+
+      assert.ok(!isE2eTestingEnabled());
+      assert.throws(getTestConfig, {
+        name: 'TypeError',
+        message: 'MAILTRAP_FROM and MAILTRAP_TO must be valid email addresses.',
+      });
+    } finally {
+      for (const key of environmentKeys) {
+        const value = originalEnvironment[key];
+        if (value === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = value;
+        }
+      }
+    }
+  });
+});
diff --git a/tests/unit/mailtrap-transport.test.js b/tests/unit/mailtrap-transport.test.js
new file mode 100644
index 0000000..fbb6206
--- /dev/null
+++ b/tests/unit/mailtrap-transport.test.js
@@ -0,0 +1,701 @@
+// Ported from upyo v0.7.0 (packages/mailtrap/src/mailtrap-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { MailtrapTransport } = require('../../src/mailtrap/mailtrap-transport.js');
+const { createMailtrapConfig, MailtrapResponseError } = require('../../src/mailtrap/index.js');
+const { MailtrapHttpClient } = require('../../src/mailtrap/http-client.js');
+
+const createMessage = (overrides = {}) => {
+  return {
+    sender: { address: 'sender@example.com' },
+    recipients: [{ address: 'recipient@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test content' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+// Deno runs node:test subtests concurrently, so serialize tests that replace
+// globalThis.fetch to keep their mocks isolated.
+let testChain = Promise.resolve();
+
+const serialIt = (name, callback) => {
+  it(name, async () => {
+    const previous = testChain;
+    let release = () => {};
+    testChain = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+
+    try {
+      await callback();
+    } finally {
+      release();
+    }
+  });
+};
+
+const createDelayedJsonResponse = (signal, onBodyRead, delay) => {
+  const body = new TextEncoder().encode(
+    JSON.stringify({
+      success: true,
+      message_ids: ['test-message-id'],
+    }),
+  );
+  let started = false;
+
+  return new Response(
+    new ReadableStream({
+      pull(controller) {
+        if (started) return;
+        started = true;
+        onBodyRead();
+
+        if (signal?.aborted) {
+          controller.error(signal.reason);
+          return;
+        }
+
+        const onAbort = () => {
+          clearTimeout(timeoutId);
+          controller.error(signal?.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+
+        const timeoutId = setTimeout(() => {
+          signal?.removeEventListener('abort', onAbort);
+          controller.enqueue(body);
+          controller.close();
+        }, delay);
+      },
+    }),
+    {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    },
+  );
+};
+
+describe('MailtrapTransport - Send Message', () => {
+  serialIt('should send a message successfully', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async (input, init) => {
+        assert.equal(input, 'https://send.api.mailtrap.io/api/send');
+        const headers = new Headers(init?.headers);
+        assert.equal(headers.get('Api-Token'), 'test-token');
+        assert.equal(headers.get('User-Agent'), '@alexify/mailer/mailtrap');
+
+        return new Response(
+          JSON.stringify({
+            success: true,
+            message_ids: ['test-message-id'],
+          }),
+          {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(receipt.successful);
+      if (receipt.successful) {
+        assert.equal(receipt.messageId, 'test-message-id');
+        assert.equal(receipt.provider, 'mailtrap');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('exposes the mailtrap provider id', () => {
+    const transport = new MailtrapTransport({ apiToken: 'test-token' });
+    assert.equal(transport.id, 'mailtrap');
+  });
+});
+
+describe('MailtrapTransport - Sandbox URL', () => {
+  serialIt('should use sandbox endpoint when configured', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async (input) => {
+        assert.equal(input, 'https://sandbox.api.mailtrap.io/api/send/12345');
+
+        return new Response(
+          JSON.stringify({
+            success: true,
+            message_ids: ['sandbox-message-id'],
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+        sandbox: true,
+        inboxId: 12345,
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(receipt.successful);
+      if (receipt.successful) {
+        assert.equal(receipt.messageId, 'sandbox-message-id');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailtrapTransport - API Errors', () => {
+  serialIt('should handle API errors', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            errors: ['Invalid API token'],
+          }),
+          {
+            status: 401,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'invalid-token',
+        retries: 0,
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.match(receipt.errorMessages[0], /Invalid API token/);
+        assert.equal(receipt.provider, 'mailtrap');
+        assert.equal(receipt.errors?.[0]?.statusCode, 401);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  serialIt('uses the sandbox rate-limit window when Retry-After is missing', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            success: false,
+            errors: ['Too many emails per second. Please upgrade your plan.'],
+          }),
+          {
+            status: 429,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+        sandbox: true,
+        inboxId: 12345,
+        retries: 0,
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errors?.[0]?.statusCode, 429);
+        assert.equal(receipt.errors?.[0]?.retryAfterMilliseconds, 10_000);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  serialIt('prefers Retry-After over the sandbox rate-limit window', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            success: false,
+            errors: ['Too many emails per second.'],
+          }),
+          {
+            status: 429,
+            headers: {
+              'Content-Type': 'application/json',
+              'Retry-After': '12',
+            },
+          },
+        );
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+        sandbox: true,
+        inboxId: 12345,
+        retries: 0,
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errors?.[0]?.retryAfterMilliseconds, 12_000);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  serialIt('does not infer a delay for unrelated sandbox rate limits', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            success: false,
+            errors: ['Monthly testing limit exhausted.'],
+          }),
+          {
+            status: 429,
+            headers: { 'Content-Type': 'application/json' },
+          },
+        );
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+        sandbox: true,
+        inboxId: 12345,
+        retries: 0,
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errors?.[0]?.retryAfterMilliseconds, undefined);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  serialIt('truncates non-JSON API response bodies in failure receipts', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async () => {
+        return new Response('x'.repeat(600), {
+          status: 503,
+          headers: { 'Content-Type': 'text/html' },
+        });
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+        retries: 0,
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages[0], `${'x'.repeat(500)}...`);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  serialIt('should handle provider-reported send failures', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            success: false,
+            errors: ['Invalid from address'],
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages[0], 'Invalid from address');
+        assert.equal(receipt.provider, 'mailtrap');
+        assert.equal(receipt.errors?.[0]?.code, 'mailtrap.unsuccessful');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  serialIt('does not retry invalid JSON from successful responses', async () => {
+    const originalFetch = globalThis.fetch;
+    let requests = 0;
+    try {
+      globalThis.fetch = async () => {
+        requests++;
+        return new Response('not json', {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+        retries: 1,
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(!receipt.successful);
+      assert.equal(requests, 1);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  for (const failure of ['network', 'timeout', 'status', 'error body']) {
+    serialIt(`retries a ${failure} failure before acceptance`, async () => {
+      const originalFetch = globalThis.fetch;
+      let requests = 0;
+      try {
+        globalThis.fetch = async (_input, init) => {
+          requests++;
+          if (requests === 1) {
+            if (failure === 'network') throw new TypeError('Failed to fetch.');
+            if (failure === 'timeout') {
+              return new Promise((_resolve, reject) => {
+                init?.signal?.addEventListener(
+                  'abort',
+                  () => {
+                    reject(init.signal?.reason);
+                  },
+                  { once: true },
+                );
+              });
+            }
+            if (failure === 'error body') {
+              return new Response(
+                new ReadableStream({
+                  start(controller) {
+                    controller.error(new TypeError('Failed to fetch response body.'));
+                  },
+                }),
+                { status: 503 },
+              );
+            }
+            return new Response('Unavailable', { status: 503 });
+          }
+          return Response.json({ success: true, message_ids: ['id'] });
+        };
+        const transport = new MailtrapTransport({
+          apiToken: 'test-token',
+          retries: 1,
+          timeout: 10,
+        });
+        const receipt = await transport.send(createMessage());
+        assert.ok(receipt.successful);
+        assert.equal(requests, 2);
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+  }
+
+  serialIt('preserves the cause of an unreadable successful response', async () => {
+    const originalFetch = globalThis.fetch;
+    const cause = new TypeError('Failed to fetch response body.');
+    try {
+      globalThis.fetch = async () =>
+        new Response(
+          new ReadableStream({
+            start(controller) {
+              controller.error(cause);
+            },
+          }),
+        );
+      const client = new MailtrapHttpClient(
+        createMailtrapConfig({
+          apiToken: 'test-token',
+          retries: 1,
+        }),
+      );
+      await assert.rejects(client.sendBatch([]), (error) => {
+        assert.ok(error instanceof MailtrapResponseError);
+        assert.equal(error.cause, cause);
+        assert.equal(error.attempts, 1);
+        return true;
+      });
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  for (const batch of [false, true]) {
+    serialIt(
+      `does not retry an unreadable successful ${batch ? 'batch' : 'single'} response`,
+      async () => {
+        const originalFetch = globalThis.fetch;
+        let requests = 0;
+        try {
+          globalThis.fetch = async () => {
+            requests++;
+            return new Response(
+              new ReadableStream({
+                start(controller) {
+                  controller.error(new TypeError('Failed to fetch response body.'));
+                },
+              }),
+              { status: 200 },
+            );
+          };
+          const transport = new MailtrapTransport({
+            apiToken: 'test-token',
+            retries: 1,
+          });
+          const receipts = [];
+          if (batch) {
+            for await (const receipt of transport.sendMany([createMessage(), createMessage()])) {
+              receipts.push(receipt);
+            }
+          } else {
+            receipts.push(await transport.send(createMessage()));
+          }
+          assert.equal(requests, 1);
+          assert.equal(receipts.length, batch ? 2 : 1);
+          for (const receipt of receipts) {
+            assert.ok(!receipt.successful);
+            if (!receipt.successful) {
+              assert.equal(receipt.errorMessages[0], 'Failed to fetch response body.');
+              assert.ok(!receipt.errors?.[0]?.retryable);
+              assert.equal(receipt.attempts, 1);
+            }
+          }
+        } finally {
+          globalThis.fetch = originalFetch;
+        }
+      },
+    );
+  }
+
+  serialIt('times out while reading the response body without retrying', async () => {
+    const originalFetch = globalThis.fetch;
+    let requests = 0;
+    try {
+      globalThis.fetch = async (_input, init) => {
+        requests++;
+        return createDelayedJsonResponse(init?.signal, () => {}, 100);
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+        timeout: 10,
+        retries: 1,
+      });
+
+      const receipt = await transport.send(createMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages[0], 'Mailtrap API request timed out after 10 ms.');
+        assert.equal(receipt.errors?.[0]?.category, 'timeout');
+        assert.ok(!receipt.errors?.[0]?.retryable);
+        assert.equal(receipt.attempts, 1);
+        assert.equal(requests, 1);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  serialIt('propagates caller cancellation while reading the response body', async () => {
+    const originalFetch = globalThis.fetch;
+    const controller = new AbortController();
+    let bodyRead = () => {};
+    const bodyReading = new Promise((resolve) => {
+      bodyRead = resolve;
+    });
+
+    try {
+      globalThis.fetch = async (_input, init) => {
+        return createDelayedJsonResponse(init?.signal, bodyRead, 100);
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+        timeout: 0,
+        retries: 1,
+      });
+      const sending = transport.send(createMessage(), {
+        signal: controller.signal,
+      });
+
+      await bodyReading;
+      controller.abort();
+
+      await assert.rejects(sending, { name: 'AbortError' });
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('MailtrapTransport - Batch Send', () => {
+  serialIt('should send a batch successfully', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async (input, init) => {
+        assert.equal(input, 'https://send.api.mailtrap.io/api/batch');
+
+        const body = JSON.parse(String(init?.body));
+        assert.equal(body.requests.length, 2);
+
+        return new Response(
+          JSON.stringify({
+            success: true,
+            responses: [
+              { success: true, message_ids: ['id-1'] },
+              { success: true, message_ids: ['id-2'] },
+            ],
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+      });
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany([
+        createMessage({ subject: 'One' }),
+        createMessage({ subject: 'Two' }),
+      ])) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.ok(receipts[0]?.successful);
+      assert.ok(receipts[1]?.successful);
+      if (receipts[0]?.successful) {
+        assert.equal(receipts[0].messageId, 'id-1');
+      }
+      if (receipts[1]?.successful) {
+        assert.equal(receipts[1].messageId, 'id-2');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  serialIt('should handle per-item batch failures', async () => {
+    const originalFetch = globalThis.fetch;
+    try {
+      globalThis.fetch = async () => {
+        return new Response(
+          JSON.stringify({
+            success: true,
+            responses: [
+              { success: true, message_ids: ['id-1'] },
+              { success: false, errors: ['Invalid recipient'] },
+            ],
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      };
+
+      const transport = new MailtrapTransport({
+        apiToken: 'test-token',
+      });
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany([createMessage(), createMessage()])) {
+        receipts.push(receipt);
+      }
+
+      assert.ok(receipts[0]?.successful);
+      assert.ok(!receipts[1]?.successful);
+      if (receipts[1] && !receipts[1].successful) {
+        assert.equal(receipts[1].errorMessages[0], 'Invalid recipient');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  serialIt('chunks batches at the Mailtrap limit', async () => {
+    const originalFetch = globalThis.fetch;
+    const requestSizes = [];
+    try {
+      globalThis.fetch = async (_input, init) => {
+        const body = JSON.parse(String(init?.body));
+        assert.ok(
+          typeof body === 'object' &&
+            body !== null &&
+            'requests' in body &&
+            Array.isArray(body.requests),
+        );
+        const requests = body.requests;
+        requestSizes.push(requests.length);
+        return new Response(
+          JSON.stringify({
+            success: true,
+            responses: requests.map((_, index) => ({
+              success: true,
+              message_ids: [`id-${requestSizes.length}-${index}`],
+            })),
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      };
+
+      const transport = new MailtrapTransport({ apiToken: 'test-token' });
+      const messages = Array.from({ length: 501 }, (_, index) =>
+        createMessage({ subject: `Message ${index}` }),
+      );
+      let receipts = 0;
+
+      // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+      for await (const _receipt of transport.sendMany(messages)) {
+        receipts++;
+      }
+
+      assert.equal(receipts, 501);
+      assert.deepEqual(requestSizes, [500, 1]);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
diff --git a/tests/unit/mailtrap.test.js b/tests/unit/mailtrap.test.js
new file mode 100644
index 0000000..648c1e1
--- /dev/null
+++ b/tests/unit/mailtrap.test.js
@@ -0,0 +1,154 @@
+// Paths of the ported Mailtrap transport (src/mailtrap/) that upstream's suites
+// leave out, against a stubbed fetch.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { MailtrapTransport, createMailtrapConfig } = require('../../src/mailtrap/index.js');
+
+const message = (extra = {}) =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+    ...extra,
+  });
+const config = { apiToken: 'token', retries: 0 };
+const hang = (url, init) =>
+  new Promise((resolve, reject) => {
+    init.signal.addEventListener('abort', () => reject(init.signal.reason));
+  });
+const collect = async (iterable) => {
+  const items = [];
+  for await (const item of iterable) items.push(item);
+  return items;
+};
+
+test('Mailtrap: a sandbox inbox id may be a string, but not a blank one', () => {
+  assert.strictEqual(
+    createMailtrapConfig({ apiToken: 't', sandbox: true, inboxId: '42' }).inboxId,
+    '42',
+  );
+  assert.throws(
+    () => createMailtrapConfig({ apiToken: 't', sandbox: true, inboxId: '  ' }),
+    RangeError,
+  );
+});
+
+test('Mailtrap: custom headers and inline attachments are sent', async (t) => {
+  let request;
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    request = { headers: new Headers(init.headers), body: JSON.parse(init.body) };
+    return Response.json({ success: true, message_ids: ['mt-1'] });
+  });
+  const attachments = [
+    {
+      inline: true,
+      filename: 'logo.png',
+      content: new Uint8Array([1]),
+      contentType: 'image/png',
+      contentId: 'logo',
+    },
+  ];
+  const transport = new MailtrapTransport({ ...config, headers: { 'X-Custom': 'yes' } });
+  assert.strictEqual((await transport.send(message({ attachments }))).messageId, 'mt-1');
+  assert.strictEqual(request.headers.get('x-custom'), 'yes');
+  assert.deepStrictEqual(
+    [request.body.attachments[0].disposition, request.body.attachments[0].content_id],
+    ['inline', 'logo'],
+  );
+});
+
+test('Mailtrap: unsuccessful and id-less responses fail the send', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => Response.json({ success: true, message_ids: [] }));
+  const missing = await new MailtrapTransport(config).send(message());
+  assert.deepStrictEqual(missing.errorMessages, ['Mailtrap response is missing a message ID.']);
+
+  t.mock.restoreAll();
+  t.mock.method(globalThis, 'fetch', async () =>
+    Response.json({ message: 'Bad sender' }, { status: 400 }),
+  );
+  assert.deepStrictEqual((await new MailtrapTransport(config).send(message())).errorMessages, [
+    'Bad sender',
+  ]);
+});
+
+test('Mailtrap: the timeout fails the send as a timeout', async (t) => {
+  t.mock.method(globalThis, 'fetch', hang);
+  const receipt = await new MailtrapTransport({ ...config, timeout: 20 }).send(message());
+  assert.strictEqual(receipt.successful, false);
+  assert.strictEqual(receipt.errors[0].category, 'timeout');
+});
+
+test('Mailtrap: a past Retry-After date is retried at once; an abort stops the wait', async (t) => {
+  let calls = 0;
+  t.mock.method(globalThis, 'fetch', async () =>
+    ++calls === 1
+      ? new Response('', {
+          status: 503,
+          headers: { 'Retry-After': new Date(Date.now() - 1000).toUTCString() },
+        })
+      : Response.json({ success: true, message_ids: ['mt-2'] }),
+  );
+  const retried = await new MailtrapTransport({ ...config, retries: 1 }).send(message());
+  assert.strictEqual(retried.messageId, 'mt-2');
+
+  t.mock.restoreAll();
+  t.mock.method(
+    globalThis,
+    'fetch',
+    async () => new Response('', { status: 503, headers: { 'Retry-After': '5' } }),
+  );
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), 30);
+  await assert.rejects(
+    new MailtrapTransport({ ...config, retries: 1 }).send(message(), { signal: controller.signal }),
+    { name: 'AbortError' },
+  );
+});
+
+test('Mailtrap: batches that fail, partly or whole, fail their messages', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () =>
+    Response.json({ success: false, errors: ['Batch rejected'] }),
+  );
+  const rejected = await collect(new MailtrapTransport(config).sendMany([message(), message()]));
+  assert.deepStrictEqual(
+    rejected.map((receipt) => receipt.errorMessages),
+    [['Batch rejected'], ['Batch rejected']],
+  );
+
+  t.mock.restoreAll();
+  t.mock.method(globalThis, 'fetch', async () => new Response('Oops', { status: 400 }));
+  const failed = await collect(new MailtrapTransport(config).sendMany([message()]));
+  assert.deepStrictEqual(failed[0].errorMessages, ['Oops']);
+
+  // A message that cannot be converted fails alone; the rest of the batch goes.
+  t.mock.restoreAll();
+  t.mock.method(globalThis, 'fetch', async () =>
+    Response.json({ success: true, responses: [{ success: true, message_ids: ['mt-3'] }] }),
+  );
+  const broken = () => {
+    throw new Error('Cannot read attachment');
+  };
+  const attachments = [
+    {
+      inline: false,
+      filename: 'a.bin',
+      content: broken,
+      contentType: 'application/octet-stream',
+      contentId: '',
+    },
+  ];
+  const mixed = await collect(
+    new MailtrapTransport(config).sendMany([message({ attachments }), message()]),
+  );
+  assert.deepStrictEqual(
+    mixed.map((receipt) => receipt.successful),
+    [false, true],
+  );
+  assert.deepStrictEqual(await collect(new MailtrapTransport(config).sendMany([])), []);
+  const allBroken = await collect(
+    new MailtrapTransport(config).sendMany([message({ attachments })]),
+  );
+  assert.deepStrictEqual(allBroken[0].errorMessages, ['Cannot read attachment']);
+});

From 2902cf8704008986bea83e04b187b88cfd5ea6e3 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:17:42 +0300
Subject: [PATCH 011/158] feat(maileroo): port the Maileroo transport from upyo
 0.7.0

./maileroo exports MailerooTransport, createMailerooConfig, MailerooApiError
and MailerooTimeoutError: the Maileroo v2 sending API over fetch, with a
reference id per message reused across retries, attachments, tags and
tracking, retries on 408, 429 and 5xx with jitter and Retry-After, and a
request timeout.

Upstream's unit suites are ported, the e2e suite goes to tests/e2e, and its
test of a runtime without AbortSignal.any is left out.
tests/unit/maileroo.test.js covers the error bodies and the unsuccessful 200
they leave out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   2 +-
 package.json                                  |   4 +
 src/maileroo/config.js                        |  26 +
 src/maileroo/http-client.js                   | 282 ++++++
 src/maileroo/index.d.ts                       | 249 ++++++
 src/maileroo/index.js                         |  22 +
 src/maileroo/maileroo-transport.js            | 162 ++++
 src/maileroo/message-converter.js             | 257 ++++++
 tests/e2e/maileroo-transport.e2e.test.js      | 165 ++++
 tests/helpers/maileroo/test-config.js         |  83 ++
 tests/types/maileroo.test-d.ts                |  28 +
 tests/unit/maileroo-config.test.js            |  82 ++
 tests/unit/maileroo-message-converter.test.js | 630 +++++++++++++
 tests/unit/maileroo-transport.test.js         | 842 ++++++++++++++++++
 tests/unit/maileroo.test.js                   |  34 +
 15 files changed, 2867 insertions(+), 1 deletion(-)
 create mode 100644 src/maileroo/config.js
 create mode 100644 src/maileroo/http-client.js
 create mode 100644 src/maileroo/index.d.ts
 create mode 100644 src/maileroo/index.js
 create mode 100644 src/maileroo/maileroo-transport.js
 create mode 100644 src/maileroo/message-converter.js
 create mode 100644 tests/e2e/maileroo-transport.e2e.test.js
 create mode 100644 tests/helpers/maileroo/test-config.js
 create mode 100644 tests/types/maileroo.test-d.ts
 create mode 100644 tests/unit/maileroo-config.test.js
 create mode 100644 tests/unit/maileroo-message-converter.test.js
 create mode 100644 tests/unit/maileroo-transport.test.js
 create mode 100644 tests/unit/maileroo.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e6c0981..090e413 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 4495d80..9bcd2f6 100644
--- a/package.json
+++ b/package.json
@@ -52,6 +52,10 @@
       "types": "./src/mailtrap/index.d.ts",
       "default": "./src/mailtrap/index.js"
     },
+    "./maileroo": {
+      "types": "./src/maileroo/index.d.ts",
+      "default": "./src/maileroo/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
diff --git a/src/maileroo/config.js b/src/maileroo/config.js
new file mode 100644
index 0000000..836e2cd
--- /dev/null
+++ b/src/maileroo/config.js
@@ -0,0 +1,26 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved Maileroo configuration by applying default values.
+ *
+ * @param config The Maileroo configuration with optional fields.
+ * @returns A resolved configuration with all defaults applied.
+ */
+const createMailerooConfig = (config) => {
+  return {
+    apiKey: config.apiKey,
+    baseUrl: normalizeBaseUrl(config.baseUrl ?? 'https://smtp.maileroo.com/api/v2'),
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    headers: config.headers == null ? {} : { ...config.headers },
+    tracking: config.tracking,
+    tags: config.tags == null ? undefined : { ...config.tags },
+  };
+};
+
+const normalizeBaseUrl = (baseUrl) => {
+  return baseUrl.replace(/\/+$/, '');
+};
+
+module.exports = { createMailerooConfig };
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
new file mode 100644
index 0000000..453e20c
--- /dev/null
+++ b/src/maileroo/http-client.js
@@ -0,0 +1,282 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/http-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { parseRetryAfter } = require('../core/receipt.js');
+
+const maxErrorMessageLength = 500;
+
+/**
+ * Maileroo API error class for API-specific failures.
+ */
+class MailerooApiError extends Error {
+  statusCode;
+  retryAfterMilliseconds;
+  attempts;
+
+  /**
+   * Creates a Maileroo API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(message, statusCode, retryAfterMilliseconds, attempts) {
+    super(message);
+    this.name = 'MailerooApiError';
+    this.statusCode = statusCode;
+    this.retryAfterMilliseconds = retryAfterMilliseconds;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * Maileroo request timeout error.
+ */
+class MailerooTimeoutError extends Error {
+  /**
+   * Request timeout in milliseconds.
+   */
+  timeout;
+
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  attempts;
+
+  /**
+   * Creates a Maileroo request timeout error.
+   *
+   * @param timeout Request timeout in milliseconds.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(timeout, attempts) {
+    super(`Maileroo API request timed out after ${timeout} ms.`);
+    this.name = 'MailerooTimeoutError';
+    this.timeout = timeout;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * HTTP client wrapper for Maileroo API requests.
+ */
+class MailerooHttpClient {
+  config;
+
+  /**
+   * Creates a new Maileroo HTTP client.
+   *
+   * @param config Resolved Maileroo configuration.
+   */
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Sends a single message via Maileroo API.
+   *
+   * @param messageData The JSON data to send to Maileroo.
+   * @param signal Optional AbortSignal for cancellation.
+   * @returns Promise that resolves to the Maileroo response.
+   * @throws {MailerooApiError} If Maileroo returns an API error.
+   * @throws {MailerooTimeoutError} If the request timeout elapses.
+   */
+  sendMessage(messageData, signal) {
+    const url = `${this.config.baseUrl}/emails`;
+    return this.makeRequest(url, messageData, signal);
+  }
+
+  async makeRequest(url, body, signal) {
+    let lastError;
+
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      signal?.throwIfAborted();
+
+      let responseText;
+      try {
+        const { response, text } = await this.fetchWithAuth(url, body, signal);
+
+        if (!response.ok) {
+          throw new MailerooApiError(
+            parseErrorMessage(text, response.status),
+            response.status,
+            parseRetryAfter(response.headers.get('Retry-After')),
+            attempt + 1,
+          );
+        }
+
+        responseText = text;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (signal?.aborted) {
+          throw error;
+        }
+
+        if (error instanceof MailerooApiError && !isRetryable(error)) {
+          throw error;
+        }
+
+        if (attempt === this.config.retries) {
+          throw withAttempts(lastError, attempt + 1);
+        }
+
+        await sleep(calculateRetryDelay(attempt, lastError), signal);
+        continue;
+      }
+
+      return parseResponse(responseText);
+    }
+
+    throw lastError ?? new Error('Request failed after all retry attempts.');
+  }
+
+  async fetchWithAuth(url, body, signal) {
+    const headers = new Headers({
+      'Content-Type': 'application/json',
+      'X-API-Key': this.config.apiKey,
+    });
+
+    for (const [key, value] of Object.entries(this.config.headers)) {
+      headers.set(key, value);
+    }
+
+    const timeoutController = new AbortController();
+    const timeoutId =
+      this.config.timeout > 0
+        ? setTimeout(() => timeoutController.abort(), this.config.timeout)
+        : undefined;
+    const requestSignal = combineSignals(timeoutController.signal, signal);
+
+    try {
+      const response = await globalThis.fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: requestSignal.signal,
+      });
+      const text = await response.text();
+      return { response, text };
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        error.name === 'AbortError' &&
+        timeoutController.signal.aborted &&
+        !signal?.aborted
+      ) {
+        throw new MailerooTimeoutError(this.config.timeout);
+      }
+      throw error;
+    } finally {
+      requestSignal.cleanup();
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+}
+
+const withAttempts = (error, attempts) => {
+  if (error instanceof MailerooTimeoutError) {
+    return new MailerooTimeoutError(error.timeout, attempts);
+  }
+  if (error instanceof MailerooApiError) {
+    return error;
+  }
+  return Object.assign(error, { attempts });
+};
+
+const isRetryable = (error) => {
+  return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
+};
+
+const calculateRetryDelay = (attempt, error) => {
+  const baseDelay = Math.min(1000 * Math.pow(2, attempt), 10000);
+  const backoffDelay = Math.round(baseDelay / 2 + Math.random() * (baseDelay / 2));
+  if (error instanceof MailerooApiError) {
+    return Math.max(backoffDelay, error.retryAfterMilliseconds ?? 0);
+  }
+  return backoffDelay;
+};
+
+const parseErrorMessage = (text, statusCode) => {
+  try {
+    const errorBody = JSON.parse(text);
+    if (errorBody != null && typeof errorBody === 'object') {
+      const mailerooError = errorBody;
+      if (typeof mailerooError.message === 'string' && mailerooError.message !== '') {
+        return truncateErrorMessage(mailerooError.message);
+      }
+      if (typeof mailerooError.error === 'string' && mailerooError.error !== '') {
+        return truncateErrorMessage(mailerooError.error);
+      }
+      if (Array.isArray(mailerooError.errors) && mailerooError.errors.length > 0) {
+        return truncateErrorMessage(JSON.stringify(mailerooError.errors));
+      }
+    }
+  } catch {
+    // Ignore if JSON parsing fails, as the body may be non-JSON.
+  }
+
+  return truncateErrorMessage(text) || `HTTP ${statusCode}`;
+};
+
+const parseResponse = (text) => {
+  try {
+    const response = JSON.parse(text);
+    if (response == null || typeof response !== 'object') {
+      throw new SyntaxError('response is not an object');
+    }
+    return response;
+  } catch (error) {
+    throw new SyntaxError(
+      `Invalid JSON response from Maileroo API: ${
+        error instanceof Error ? error.message : String(error)
+      }.`,
+    );
+  }
+};
+
+const truncateErrorMessage = (message) => {
+  return message.length > maxErrorMessageLength
+    ? `${message.slice(0, maxErrorMessageLength)}...`
+    : message;
+};
+
+const abortReason = (signal) => {
+  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+};
+
+const sleep = (ms, signal) => {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+
+    const timeoutState = {};
+    const onAbort = () => {
+      if (timeoutState.id !== undefined) {
+        clearTimeout(timeoutState.id);
+      }
+      signal?.removeEventListener('abort', onAbort);
+      reject(abortReason(signal));
+    };
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+
+    timeoutState.id = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+  });
+};
+
+module.exports = { MailerooApiError, MailerooTimeoutError, MailerooHttpClient };
diff --git a/src/maileroo/index.d.ts b/src/maileroo/index.d.ts
new file mode 100644
index 0000000..ddfa482
--- /dev/null
+++ b/src/maileroo/index.d.ts
@@ -0,0 +1,249 @@
+// Types ported from upyo v0.7.0 (packages/maileroo/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Configuration interface for Maileroo transport connection settings.
+ *
+ * @example
+ * ```typescript
+ * const config: MailerooConfig = {
+ *   apiKey: "your-sending-key",
+ *   timeout: 30000,
+ *   retries: 3,
+ * };
+ * ```
+ */
+export interface MailerooConfig {
+  /**
+   * Your Maileroo sending key.
+   *
+   * The key is sent as an `X-API-Key` HTTP header.
+   */
+  readonly apiKey: string;
+  /**
+   * Base URL for the Maileroo Email API.
+   *
+   * @default "https://smtp.maileroo.com/api/v2"
+   */
+  readonly baseUrl?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   *
+   * Set to `0` to disable request timeouts.
+   *
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   *
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Whether Maileroo should track opens and clicks for sent messages.
+   *
+   * When omitted, Maileroo applies the account default.
+   */
+  readonly tracking?: boolean;
+  /**
+   * Default Maileroo tags to apply to sent messages.
+   */
+  readonly tags?: Record<string, string>;
+}
+/**
+ * Resolved Maileroo configuration with defaults applied.
+ */
+export type ResolvedMailerooConfig = Required<Omit<MailerooConfig, 'tracking' | 'tags'>> & {
+  readonly tracking?: boolean;
+  readonly tags?: Record<string, string>;
+};
+/**
+ * Creates a resolved Maileroo configuration by applying default values.
+ *
+ * @param config The Maileroo configuration with optional fields.
+ * @returns A resolved configuration with all defaults applied.
+ */
+export declare function createMailerooConfig(config: MailerooConfig): ResolvedMailerooConfig;
+
+/**
+ * Maileroo transport implementation for sending emails via Maileroo API.
+ *
+ * @example
+ * ```typescript
+ * import { createMessage } from "@alexify/mailer";
+ * import { MailerooTransport } from "@alexify/mailer/maileroo";
+ *
+ * const transport = new MailerooTransport({
+ *   apiKey: "your-sending-key",
+ * });
+ *
+ * const receipt = await transport.send(createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from Maileroo",
+ *   content: { text: "Hello!" },
+ * }));
+ * ```
+ */
+export declare class MailerooTransport implements Transport<'maileroo'> {
+  readonly id = 'maileroo';
+  /**
+   * The resolved Maileroo configuration used by this transport.
+   */
+  readonly config: ResolvedMailerooConfig;
+  /**
+   * Creates a new Maileroo transport instance.
+   *
+   * @param config Maileroo configuration including API key and options.
+   */
+  constructor(config: MailerooConfig);
+  /**
+   * Sends a single email message via Maileroo API.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns A receipt indicating success or failure.
+   * @throws {Error} If the caller aborts the operation.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'maileroo'>>;
+  /**
+   * Sends multiple email messages sequentially via Maileroo API.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'maileroo'>>;
+}
+
+/**
+ * Maileroo email address object.
+ */
+export interface MailerooEmailAddress {
+  /** Email address. */
+  readonly address: string;
+  /** Optional display name. */
+  readonly display_name?: string;
+}
+/**
+ * Maileroo attachment object.
+ */
+export interface MailerooAttachment {
+  /** Attachment filename or inline content ID. */
+  readonly file_name: string;
+  /** Attachment MIME type. */
+  readonly content_type?: string;
+  /** Base64-encoded attachment content. */
+  readonly content: string;
+  /** Whether this attachment is treated as inline content. */
+  readonly inline?: boolean;
+}
+/**
+ * Maileroo email object structure for API requests.
+ */
+export interface MailerooEmail {
+  readonly from: MailerooEmailAddress;
+  readonly to: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly cc?: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly bcc?: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly reply_to?: MailerooEmailAddress | readonly MailerooEmailAddress[];
+  readonly subject: string;
+  readonly html?: string;
+  readonly plain?: string;
+  readonly tracking?: boolean;
+  readonly tags?: Record<string, string>;
+  readonly headers?: Record<string, string>;
+  readonly attachments?: readonly MailerooAttachment[];
+  readonly reference_id?: string;
+}
+/**
+ * Converts an Upyo message to Maileroo API JSON format.
+ *
+ * @param message The Upyo message to convert.
+ * @param config The resolved Maileroo configuration.
+ * @param signal Optional abort signal for cancellation.
+ * @returns JSON object ready for Maileroo API submission.
+ * @throws {TypeError} If the message carries an invalid message identifier.
+ * @throws {Error} If the caller aborts the operation.
+ */
+
+/**
+ * Response from Maileroo API for sending a single message.
+ */
+export interface MailerooResponse {
+  /** Whether Maileroo accepted the request. */
+  readonly success: boolean;
+  /** Human-readable response message. */
+  readonly message?: string;
+  /** Response payload from Maileroo. */
+  readonly data?: {
+    /** Maileroo reference ID for tracking the message. */
+    readonly reference_id?: string;
+  };
+}
+/**
+ * Error response from Maileroo API.
+ */
+export interface MailerooError {
+  /** Error message from Maileroo. */
+  readonly message?: string;
+  /** Error detail from Maileroo. */
+  readonly error?: string;
+  /** Validation errors from Maileroo. */
+  readonly errors?: readonly unknown[];
+}
+/**
+ * Maileroo API error class for API-specific failures.
+ */
+export declare class MailerooApiError extends Error {
+  readonly statusCode: number;
+  readonly retryAfterMilliseconds?: number;
+  readonly attempts?: number;
+  /**
+   * Creates a Maileroo API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(
+    message: string,
+    statusCode: number,
+    retryAfterMilliseconds?: number,
+    attempts?: number,
+  );
+}
+/**
+ * Maileroo request timeout error.
+ */
+export declare class MailerooTimeoutError extends Error {
+  /**
+   * Request timeout in milliseconds.
+   */
+  readonly timeout: number;
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * Creates a Maileroo request timeout error.
+   *
+   * @param timeout Request timeout in milliseconds.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(timeout: number, attempts?: number);
+}
+/**
+ * HTTP client wrapper for Maileroo API requests.
+ */
diff --git a/src/maileroo/index.js b/src/maileroo/index.js
new file mode 100644
index 0000000..5a9a94c
--- /dev/null
+++ b/src/maileroo/index.js
@@ -0,0 +1,22 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * @fileoverview Maileroo transport for Upyo email library.
+ *
+ * This module provides a transport implementation for sending emails through
+ * Maileroo's HTTP API.  It supports single messages, sequential `sendMany()`,
+ * attachments, custom headers, tags, tracking settings, retry logic, and
+ * cancellation.
+ */
+
+const { MailerooTransport } = require('./maileroo-transport.js');
+const { createMailerooConfig } = require('./config.js');
+const { MailerooApiError, MailerooTimeoutError } = require('./http-client.js');
+
+module.exports = {
+  MailerooTransport,
+  createMailerooConfig,
+  MailerooApiError,
+  MailerooTimeoutError,
+};
diff --git a/src/maileroo/maileroo-transport.js b/src/maileroo/maileroo-transport.js
new file mode 100644
index 0000000..bba499a
--- /dev/null
+++ b/src/maileroo/maileroo-transport.js
@@ -0,0 +1,162 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/maileroo-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createMailerooConfig } = require('./config.js');
+const { MailerooApiError, MailerooHttpClient, MailerooTimeoutError } = require('./http-client.js');
+const { convertMessage } = require('./message-converter.js');
+
+/**
+ * Maileroo transport implementation for sending emails via Maileroo API.
+ *
+ * @example
+ * ```typescript
+ * import { createMessage } from "@alexify/mailer";
+ * import { MailerooTransport } from "@alexify/mailer/maileroo";
+ *
+ * const transport = new MailerooTransport({
+ *   apiKey: "your-sending-key",
+ * });
+ *
+ * const receipt = await transport.send(createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from Maileroo",
+ *   content: { text: "Hello!" },
+ * }));
+ * ```
+ */
+class MailerooTransport {
+  id = 'maileroo';
+
+  /**
+   * The resolved Maileroo configuration used by this transport.
+   */
+  config;
+
+  httpClient;
+
+  /**
+   * Creates a new Maileroo transport instance.
+   *
+   * @param config Maileroo configuration including API key and options.
+   */
+  constructor(config) {
+    this.config = createMailerooConfig(config);
+    this.httpClient = new MailerooHttpClient(this.config);
+  }
+
+  /**
+   * Sends a single email message via Maileroo API.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns A receipt indicating success or failure.
+   * @throws {Error} If the caller aborts the operation.
+   */
+  async send(message, options) {
+    try {
+      options?.signal?.throwIfAborted();
+
+      const emailData = await convertMessage(message, this.config, options?.signal);
+
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendMessage(emailData, options?.signal);
+
+      return responseToReceipt(response);
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) throw error;
+      return createMailerooFailure(error instanceof Error ? error.message : String(error), error);
+    }
+  }
+
+  /**
+   * Sends multiple email messages sequentially via Maileroo API.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    for await (const message of messages) {
+      options?.signal?.throwIfAborted();
+      yield await this.send(message, options);
+    }
+  }
+}
+
+const responseToReceipt = (response) => {
+  if (!response.success) {
+    return createFailedReceipt(response.message ?? 'Maileroo reported an unsuccessful response.', {
+      provider: 'maileroo',
+      category: 'rejected',
+      code: 'maileroo.unsuccessful',
+      retryable: false,
+      providerDetails: response,
+    });
+  }
+
+  const messageId = response.data?.reference_id;
+  if (messageId == null || messageId === '') {
+    return createFailedReceipt('Maileroo response is missing a reference ID.', {
+      provider: 'maileroo',
+      category: 'unknown',
+      code: 'maileroo.missing_reference_id',
+      retryable: false,
+      providerDetails: response,
+    });
+  }
+
+  return {
+    successful: true,
+    messageId,
+    provider: 'maileroo',
+  };
+};
+
+const createMailerooFailure = (message, error) => {
+  if (error instanceof MailerooApiError) {
+    return createFailedReceipt(message, {
+      provider: 'maileroo',
+      statusCode: error.statusCode,
+      retryAfterMilliseconds: error.retryAfterMilliseconds,
+      attempts: error.attempts,
+    });
+  }
+
+  if (error instanceof MailerooTimeoutError) {
+    return createFailedReceipt(message, {
+      provider: 'maileroo',
+      category: 'timeout',
+      code: 'timeout',
+      retryable: true,
+      attempts: error.attempts,
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'maileroo',
+    attempts: getErrorAttempts(error),
+  });
+};
+
+const getErrorAttempts = (error) => {
+  if (typeof error !== 'object' || error == null || !('attempts' in error)) {
+    return undefined;
+  }
+  const attempts = error.attempts;
+  return typeof attempts === 'number' ? attempts : undefined;
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+module.exports = { MailerooTransport };
diff --git a/src/maileroo/message-converter.js b/src/maileroo/message-converter.js
new file mode 100644
index 0000000..cdb2247
--- /dev/null
+++ b/src/maileroo/message-converter.js
@@ -0,0 +1,257 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createCalendarAttachment } = require('../core/calendar.js');
+const { combineSignals } = require('../core/abort-signal.js');
+const { readAttachmentContent } = require('../core/attachment.js');
+const { resolveThreadingHeaders } = require('../core/message-id.js');
+
+const STANDARD_HEADERS = new Set([
+  'from',
+  'to',
+  'cc',
+  'bcc',
+  'reply-to',
+  'subject',
+  'date',
+  'message-id',
+  'content-type',
+  'content-transfer-encoding',
+  'mime-version',
+  'x-priority',
+]);
+
+/**
+ * Converts an Upyo message to Maileroo API JSON format.
+ *
+ * @param message The Upyo message to convert.
+ * @param config The resolved Maileroo configuration.
+ * @param signal Optional abort signal for cancellation.
+ * @returns JSON object ready for Maileroo API submission.
+ * @throws {TypeError} If the message carries an invalid message identifier.
+ * @throws {Error} If the caller aborts the operation.
+ */
+const convertMessage = async (message, config, signal) => {
+  signal?.throwIfAborted();
+
+  // A transport that cannot compose a `text/calendar` alternative carries the
+  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
+  // own files so that a client looking for the first calendar part finds it.
+  const attachments =
+    message.calendar == null
+      ? message.attachments
+      : [createCalendarAttachment(message.calendar), ...message.attachments];
+
+  const emailData = {
+    from: convertAddress(message.sender),
+    to: convertAddressList(message.recipients),
+    subject: message.subject,
+    reference_id: createMailerooReference(message.idempotencyKey),
+  };
+
+  signal?.throwIfAborted();
+
+  const cc = convertOptionalAddressList(message.ccRecipients);
+  if (cc !== undefined) emailData.cc = cc;
+
+  const bcc = convertOptionalAddressList(message.bccRecipients);
+  if (bcc !== undefined) emailData.bcc = bcc;
+
+  const replyTo = convertOptionalAddressList(message.replyRecipients);
+  if (replyTo !== undefined) emailData.reply_to = replyTo;
+
+  if ('html' in message.content) {
+    emailData.html = message.content.html;
+    if (message.content.text !== undefined) {
+      emailData.plain = message.content.text;
+    }
+  } else {
+    emailData.plain = message.content.text;
+  }
+
+  if (config.tracking !== undefined) {
+    emailData.tracking = config.tracking;
+  }
+
+  const tags = convertTags(message, config);
+  if (Object.keys(tags).length > 0) {
+    emailData.tags = tags;
+  }
+
+  const headers = convertHeaders(message);
+  if (Object.keys(headers).length > 0) {
+    emailData.headers = headers;
+  }
+
+  if (attachments.length > 0) {
+    const cancellation = new AbortController();
+    const combined = combineSignals(cancellation.signal, signal);
+    try {
+      emailData.attachments = await Promise.all(
+        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
+      );
+    } finally {
+      cancellation.abort();
+      combined.cleanup();
+    }
+  }
+
+  signal?.throwIfAborted();
+
+  return emailData;
+};
+
+const createMailerooReference = (idempotencyKey) => {
+  if (idempotencyKey == null || idempotencyKey === '') {
+    const bytes = new Uint8Array(12);
+    crypto.getRandomValues(bytes);
+    return bytesToHex(bytes);
+  }
+
+  return hashReference(idempotencyKey);
+};
+
+const bytesToHex = (bytes) => {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+};
+
+const hashReference = (value) => {
+  const bytes = new TextEncoder().encode(value);
+  const seeds = [0x811c9dc5, 0x9e3779b9, 0x85ebca6b];
+
+  return seeds
+    .map((seed) => {
+      let hash = seed;
+      for (const byte of bytes) {
+        hash ^= byte;
+        hash = Math.imul(hash, 0x01000193);
+      }
+      return (hash >>> 0).toString(16).padStart(8, '0');
+    })
+    .join('');
+};
+
+const convertAddress = (address) => {
+  return address.name == null || address.name === ''
+    ? { address: address.address }
+    : { address: address.address, display_name: address.name };
+};
+
+const convertAddressList = (addresses) => {
+  const converted = addresses.map(convertAddress);
+  return converted.length === 1 ? converted[0] : converted;
+};
+
+const convertOptionalAddressList = (addresses) => {
+  return addresses.length === 0 ? undefined : convertAddressList(addresses);
+};
+
+const convertTags = (message, config) => {
+  const tags = config.tags == null ? {} : { ...config.tags };
+
+  for (const [index, tag] of message.tags.entries()) {
+    tags[`tag${index + 1}`] = tag;
+  }
+
+  return tags;
+};
+
+const convertHeaders = (message) => {
+  const headers = {};
+
+  if (message.priority !== 'normal') {
+    const priorityMap = {
+      high: '1',
+      normal: '3',
+      low: '5',
+    };
+    headers['X-Priority'] = priorityMap[message.priority];
+  }
+
+  // Reply threading comes from the typed fields when the message defines them,
+  // and from a custom header otherwise.  A field the message owns but left
+  // empty writes nothing, which is how a caller drops an inherited header.
+  const threading = resolveThreadingHeaders(message);
+  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+
+  for (const [key, value] of message.headers.entries()) {
+    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
+      headers[key] = value;
+    }
+  }
+  for (const [name, value] of threading) {
+    if (value != null) headers[name] = value;
+  }
+
+  return headers;
+};
+
+const convertAttachment = async (attachment, signal) => {
+  signal?.throwIfAborted();
+  const content = await readAttachmentContent(attachment.content, signal);
+  signal?.throwIfAborted();
+  return {
+    file_name: getAttachmentFileName(attachment),
+    content_type: attachment.contentType,
+    content: uint8ArrayToBase64(content),
+    inline: attachment.inline || undefined,
+  };
+};
+
+const getAttachmentFileName = (attachment) => {
+  return attachment.inline &&
+    typeof attachment.contentId === 'string' &&
+    attachment.contentId !== ''
+    ? attachment.contentId
+    : attachment.filename;
+};
+
+const uint8ArrayToBase64 = (bytes) => {
+  const nativeToBase64 = getNativeToBase64(bytes);
+  if (nativeToBase64 != null) {
+    return nativeToBase64();
+  }
+
+  const bufferBase64 = getBufferBase64(bytes);
+  if (bufferBase64 != null) {
+    return bufferBase64;
+  }
+
+  const chunkSize = 4096;
+  const chunks = [];
+
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + chunkSize)));
+  }
+
+  return btoa(chunks.join(''));
+};
+
+const getNativeToBase64 = (bytes) => {
+  const candidate = bytes;
+  const toBase64 = candidate.toBase64;
+  if (typeof toBase64 !== 'function') return undefined;
+  return () => toBase64.call(bytes);
+};
+
+const getBufferBase64 = (bytes) => {
+  const candidate = globalThis.Buffer;
+  if (typeof candidate?.from !== 'function') return undefined;
+
+  try {
+    const buffer = candidate.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (buffer == null || typeof buffer.toString !== 'function') {
+      return undefined;
+    }
+    const base64 = buffer.toString('base64');
+    return typeof base64 === 'string' ? base64 : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const isStandardHeader = (headerName) => {
+  return STANDARD_HEADERS.has(headerName.toLowerCase());
+};
+
+module.exports = { convertMessage };
diff --git a/tests/e2e/maileroo-transport.e2e.test.js b/tests/e2e/maileroo-transport.e2e.test.js
new file mode 100644
index 0000000..1c929f2
--- /dev/null
+++ b/tests/e2e/maileroo-transport.e2e.test.js
@@ -0,0 +1,165 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/maileroo-transport.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { MailerooTransport } = require('../../src/maileroo/maileroo-transport.js');
+const {
+  createTestMessage,
+  getTestConfig,
+  isE2eTestingEnabled,
+} = require('../helpers/maileroo/test-config.js');
+
+const describeE2E = isE2eTestingEnabled() ? describe : describe.skip;
+let e2eChain = Promise.resolve();
+
+describeE2E('MailerooTransport E2E', { concurrency: false }, () => {
+  const waitForRateLimit = async () => {
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+  };
+
+  const runE2e = async (callback) => {
+    const previous = e2eChain;
+    let release = () => {};
+    e2eChain = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+
+    try {
+      return await callback();
+    } finally {
+      release();
+    }
+  };
+
+  const assertSuccessfulReceipt = (receipt) => {
+    assert.ok(
+      receipt.successful,
+      receipt.successful ? undefined : receipt.errorMessages.join(', '),
+    );
+    assert.ok(receipt.messageId);
+  };
+
+  it('sends a simple text email', async () => {
+    await runE2e(async () => {
+      await waitForRateLimit();
+
+      const transport = new MailerooTransport(getTestConfig().maileroo);
+      const receipt = await transport.send(
+        createTestMessage({
+          subject: '[E2E] Maileroo text email',
+          content: { text: 'This is a Maileroo E2E test email.' },
+        }),
+      );
+
+      assertSuccessfulReceipt(receipt);
+      console.log(`Sent Maileroo text email with ID: ${receipt.messageId}`);
+    });
+  });
+
+  it('sends an HTML email', async () => {
+    await runE2e(async () => {
+      await waitForRateLimit();
+
+      const transport = new MailerooTransport(getTestConfig().maileroo);
+      const receipt = await transport.send(
+        createTestMessage({
+          subject: '[E2E] Maileroo HTML email',
+          content: {
+            html: '<h1>Hello from Upyo</h1><p>This is a Maileroo test.</p>',
+            text: 'Hello from Upyo\n\nThis is a Maileroo test.',
+          },
+        }),
+      );
+
+      assertSuccessfulReceipt(receipt);
+      console.log(`Sent Maileroo HTML email with ID: ${receipt.messageId}`);
+    });
+  });
+
+  it('sends an email with an attachment', async () => {
+    await runE2e(async () => {
+      await waitForRateLimit();
+
+      const transport = new MailerooTransport(getTestConfig().maileroo);
+      const receipt = await transport.send(
+        createTestMessage({
+          subject: '[E2E] Maileroo attachment email',
+          content: { text: 'This Maileroo E2E test email has an attachment.' },
+          attachments: [
+            {
+              filename: 'maileroo-e2e.txt',
+              contentType: 'text/plain',
+              content: new TextEncoder().encode(
+                'This attachment was sent by the Upyo Maileroo E2E test.',
+              ),
+              inline: false,
+              contentId: '',
+            },
+          ],
+        }),
+      );
+
+      assertSuccessfulReceipt(receipt);
+      console.log(`Sent Maileroo attachment email with ID: ${receipt.messageId}`);
+    });
+  });
+
+  it('sends an email with custom headers, tags, and tracking', async () => {
+    await runE2e(async () => {
+      await waitForRateLimit();
+
+      const headers = new Headers();
+      headers.set('X-Upyo-E2E', 'maileroo');
+
+      const transport = new MailerooTransport({
+        ...getTestConfig().maileroo,
+        tracking: true,
+        tags: { source: 'upyo-e2e' },
+      });
+      const receipt = await transport.send(
+        createTestMessage({
+          subject: '[E2E] Maileroo metadata email',
+          content: { text: 'This Maileroo E2E test email has metadata.' },
+          headers,
+          tags: ['metadata'],
+        }),
+      );
+
+      assertSuccessfulReceipt(receipt);
+      console.log(`Sent Maileroo metadata email with ID: ${receipt.messageId}`);
+    });
+  });
+
+  it('sends multiple emails with sendMany', async () => {
+    await runE2e(async () => {
+      await waitForRateLimit();
+
+      const transport = new MailerooTransport(getTestConfig().maileroo);
+      const receipts = [];
+
+      for await (const receipt of transport.sendMany([
+        createTestMessage({
+          subject: '[E2E] Maileroo sendMany email 1',
+        }),
+        createTestMessage({
+          subject: '[E2E] Maileroo sendMany email 2',
+        }),
+      ])) {
+        receipts.push(receipt);
+        await waitForRateLimit();
+      }
+
+      assert.equal(receipts.length, 2);
+      for (const receipt of receipts) {
+        assertSuccessfulReceipt(receipt);
+      }
+      console.log(
+        `Sent Maileroo sendMany emails with IDs: ${receipts
+          .map((receipt) => (receipt.successful ? receipt.messageId : 'failed'))
+          .join(', ')}`,
+      );
+    });
+  });
+});
diff --git a/tests/helpers/maileroo/test-config.js b/tests/helpers/maileroo/test-config.js
new file mode 100644
index 0000000..116ec81
--- /dev/null
+++ b/tests/helpers/maileroo/test-config.js
@@ -0,0 +1,83 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const process = require('node:process');
+
+/**
+ * Error thrown when Maileroo E2E test configuration is incomplete.
+ */
+class MailerooTestConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'MailerooTestConfigError';
+  }
+}
+
+/**
+ * Checks whether Maileroo E2E testing is configured.
+ *
+ * @returns `true` if all required environment variables are present.
+ */
+const isE2eTestingEnabled = () => {
+  return !!(process.env.MAILEROO_API_KEY && process.env.MAILEROO_FROM && process.env.MAILEROO_TO);
+};
+
+/**
+ * Reads Maileroo E2E test configuration from environment variables.
+ *
+ * @returns Maileroo E2E test configuration.
+ * @throws {MailerooTestConfigError} If required environment variables are
+ * missing.
+ */
+const getTestConfig = () => {
+  const apiKey = process.env.MAILEROO_API_KEY;
+  const from = process.env.MAILEROO_FROM;
+  const to = process.env.MAILEROO_TO;
+
+  if (!apiKey || !from || !to) {
+    throw new MailerooTestConfigError(
+      'MAILEROO_API_KEY, MAILEROO_FROM, and MAILEROO_TO are required.',
+    );
+  }
+
+  return {
+    maileroo: {
+      apiKey,
+      timeout: 60000,
+      retries: 6,
+      ...(process.env.MAILEROO_BASE_URL && {
+        baseUrl: process.env.MAILEROO_BASE_URL,
+      }),
+    },
+    from,
+    to,
+  };
+};
+
+/**
+ * Creates a test message for Maileroo E2E tests.
+ *
+ * @param overrides Message fields to override.
+ * @returns A test message.
+ * @throws {MailerooTestConfigError} If required environment variables are
+ * missing.
+ */
+const createTestMessage = (overrides = {}) => {
+  const config = getTestConfig();
+  return {
+    sender: { address: config.from, name: 'Upyo Test' },
+    recipients: [{ address: config.to }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: '[E2E] Maileroo test',
+    content: { text: 'This is a test email sent through Maileroo.' },
+    attachments: [],
+    priority: 'normal',
+    tags: ['upyo-test'],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+module.exports = { MailerooTestConfigError, isE2eTestingEnabled, getTestConfig, createTestMessage };
diff --git a/tests/types/maileroo.test-d.ts b/tests/types/maileroo.test-d.ts
new file mode 100644
index 0000000..1e7bdb9
--- /dev/null
+++ b/tests/types/maileroo.test-d.ts
@@ -0,0 +1,28 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import {
+  MailerooApiError,
+  MailerooTimeoutError,
+  MailerooTransport,
+  createMailerooConfig,
+  type MailerooConfig,
+  type ResolvedMailerooConfig,
+} from '../../src/maileroo/index.js';
+
+const transport = new MailerooTransport({ apiKey: 'key', timeout: 5000 });
+expectAssignable<Transport<'maileroo'>>(transport);
+expectType<ResolvedMailerooConfig>(createMailerooConfig({ apiKey: 'key' }));
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'maileroo'>>>(transport.send(message));
+expectType<AsyncIterable<Receipt<'maileroo'>>>(transport.sendMany([message]));
+
+expectAssignable<MailerooConfig>({ apiKey: 'key', tracking: false, retries: 1 });
+expectAssignable<Error>(new MailerooApiError('Unauthorized', 401));
+expectAssignable<Error>(new MailerooTimeoutError(1000));
+expectError(new MailerooTransport({ timeout: 5000 }));
diff --git a/tests/unit/maileroo-config.test.js b/tests/unit/maileroo-config.test.js
new file mode 100644
index 0000000..da2a961
--- /dev/null
+++ b/tests/unit/maileroo-config.test.js
@@ -0,0 +1,82 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { createMailerooConfig } = require('../../src/maileroo/config.js');
+
+describe('createMailerooConfig', () => {
+  it('applies default values to optional fields', () => {
+    const config = {
+      apiKey: 'test-key',
+    };
+
+    const resolved = createMailerooConfig(config);
+
+    assert.equal(resolved.apiKey, 'test-key');
+    assert.equal(resolved.baseUrl, 'https://smtp.maileroo.com/api/v2');
+    assert.equal(resolved.timeout, 30000);
+    assert.equal(resolved.retries, 3);
+    assert.deepEqual(resolved.headers, {});
+    assert.equal(resolved.tracking, undefined);
+    assert.equal(resolved.tags, undefined);
+  });
+
+  it('preserves provided optional values', () => {
+    const config = {
+      apiKey: 'test-key',
+      baseUrl: 'https://maileroo.example.com/api',
+      timeout: 60000,
+      retries: 5,
+      headers: { 'X-Custom': 'value' },
+      tracking: false,
+      tags: { campaign: 'welcome' },
+    };
+
+    const resolved = createMailerooConfig(config);
+
+    assert.equal(resolved.apiKey, 'test-key');
+    assert.equal(resolved.baseUrl, 'https://maileroo.example.com/api');
+    assert.equal(resolved.timeout, 60000);
+    assert.equal(resolved.retries, 5);
+    assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
+    assert.ok(!resolved.tracking);
+    assert.deepEqual(resolved.tags, { campaign: 'welcome' });
+  });
+
+  it('clones mutable header and tag defaults', () => {
+    const headers = { 'X-Custom': 'value' };
+    const tags = { campaign: 'welcome' };
+    const resolved = createMailerooConfig({
+      apiKey: 'test-key',
+      headers,
+      tags,
+    });
+
+    headers['X-Custom'] = 'changed';
+    tags.campaign = 'changed';
+
+    assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
+    assert.deepEqual(resolved.tags, { campaign: 'welcome' });
+  });
+
+  it('preserves zero timeout and retry values', () => {
+    const resolved = createMailerooConfig({
+      apiKey: 'test-key',
+      timeout: 0,
+      retries: 0,
+    });
+
+    assert.equal(resolved.timeout, 0);
+    assert.equal(resolved.retries, 0);
+  });
+
+  it('normalizes trailing slashes from the base URL', () => {
+    const resolved = createMailerooConfig({
+      apiKey: 'test-key',
+      baseUrl: 'https://maileroo.example.com/api///',
+    });
+
+    assert.equal(resolved.baseUrl, 'https://maileroo.example.com/api');
+  });
+});
diff --git a/tests/unit/maileroo-message-converter.test.js b/tests/unit/maileroo-message-converter.test.js
new file mode 100644
index 0000000..8d1646d
--- /dev/null
+++ b/tests/unit/maileroo-message-converter.test.js
@@ -0,0 +1,630 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/message-converter.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { createMailerooConfig } = require('../../src/maileroo/config.js');
+const { convertMessage } = require('../../src/maileroo/message-converter.js');
+
+const baseConfig = createMailerooConfig({ apiKey: 'test-key' });
+
+const createBaseMessage = (overrides = {}) => {
+  return {
+    sender: { address: 'sender@example.com' },
+    recipients: [{ address: 'recipient@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test content' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+let globalMutationChain = Promise.resolve();
+
+const withGlobalMutationLock = async (callback) => {
+  const previous = globalMutationChain;
+  let release = () => {};
+  globalMutationChain = new Promise((resolve) => {
+    release = resolve;
+  });
+  await previous;
+
+  try {
+    return await callback();
+  } finally {
+    release();
+  }
+};
+
+describe('convertMessage', { concurrency: false }, () => {
+  it('converts a basic text message', async () => {
+    const result = await convertMessage(createBaseMessage(), baseConfig);
+
+    assert.deepEqual(result.from, { address: 'sender@example.com' });
+    assert.deepEqual(result.to, { address: 'recipient@example.com' });
+    assert.equal(result.subject, 'Test Subject');
+    assert.equal(result.plain, 'Test content');
+    assert.equal(result.html, undefined);
+  });
+
+  it('converts addresses with display names', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        sender: { address: 'sender@example.com', name: 'Sender Name' },
+        recipients: [
+          {
+            address: 'recipient@example.com',
+            name: 'Recipient "Name"',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.from, {
+      address: 'sender@example.com',
+      display_name: 'Sender Name',
+    });
+    assert.deepEqual(result.to, {
+      address: 'recipient@example.com',
+      display_name: 'Recipient "Name"',
+    });
+  });
+
+  it('uses arrays for multiple recipients', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        recipients: [{ address: 'one@example.com' }, { address: 'two@example.com', name: 'Two' }],
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.to, [
+      { address: 'one@example.com' },
+      { address: 'two@example.com', display_name: 'Two' },
+    ]);
+  });
+
+  it('converts HTML content with text alternative', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        content: { html: '<h1>Hello</h1>', text: 'Hello' },
+      }),
+      baseConfig,
+    );
+
+    assert.equal(result.html, '<h1>Hello</h1>');
+    assert.equal(result.plain, 'Hello');
+  });
+
+  it('handles CC, BCC, and reply-to recipients', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        ccRecipients: [{ address: 'cc@example.com' }],
+        bccRecipients: [{ address: 'bcc1@example.com' }, { address: 'bcc2@example.com' }],
+        replyRecipients: [{ address: 'reply@example.com' }],
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.cc, { address: 'cc@example.com' });
+    assert.deepEqual(result.bcc, [
+      { address: 'bcc1@example.com' },
+      { address: 'bcc2@example.com' },
+    ]);
+    assert.deepEqual(result.reply_to, { address: 'reply@example.com' });
+  });
+
+  it('applies Maileroo defaults from config', async () => {
+    const config = createMailerooConfig({
+      apiKey: 'test-key',
+      tracking: false,
+      tags: {
+        campaign: 'welcome-2026',
+        environment: 'test',
+      },
+    });
+
+    const result = await convertMessage(createBaseMessage(), config);
+
+    assert.ok(!result.tracking);
+    assert.deepEqual(result.tags, {
+      campaign: 'welcome-2026',
+      environment: 'test',
+    });
+  });
+
+  it('adds message tags as generated Maileroo tag keys', async () => {
+    const config = createMailerooConfig({
+      apiKey: 'test-key',
+      tags: { campaign: 'default' },
+    });
+
+    const result = await convertMessage(createBaseMessage({ tags: ['one', 'two'] }), config);
+
+    assert.deepEqual(result.tags, {
+      campaign: 'default',
+      tag1: 'one',
+      tag2: 'two',
+    });
+  });
+
+  it('uses idempotency keys as stable Maileroo references', async () => {
+    const first = await convertMessage(
+      createBaseMessage({ idempotencyKey: 'welcome-message-1' }),
+      baseConfig,
+    );
+    const second = await convertMessage(
+      createBaseMessage({ idempotencyKey: 'welcome-message-1' }),
+      baseConfig,
+    );
+
+    assert.match(first.reference_id ?? '', /^[0-9a-f]{24}$/);
+    assert.equal(first.reference_id, second.reference_id);
+  });
+
+  it('generates Maileroo references when idempotency keys are missing', async () => {
+    const result = await convertMessage(createBaseMessage(), baseConfig);
+
+    assert.match(result.reference_id ?? '', /^[0-9a-f]{24}$/);
+  });
+
+  it('converts priority and custom headers', async () => {
+    const headers = new Headers();
+    headers.set('X-Custom-Header', 'custom-value');
+    headers.set('Subject', 'ignored');
+
+    const result = await convertMessage(
+      createBaseMessage({
+        priority: 'high',
+        headers,
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.headers, {
+      'X-Priority': '1',
+      'x-custom-header': 'custom-value',
+    });
+  });
+
+  it('converts attachments to base64 with inline content IDs', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            filename: 'hello.txt',
+            content: new TextEncoder().encode('hello'),
+            contentType: 'text/plain',
+            inline: false,
+            contentId: '',
+          },
+          {
+            filename: 'logo.png',
+            content: new Uint8Array([1, 2, 3]),
+            contentType: 'image/png',
+            inline: true,
+            contentId: 'logo',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.attachments, [
+      {
+        file_name: 'hello.txt',
+        content_type: 'text/plain',
+        content: 'aGVsbG8=',
+        inline: undefined,
+      },
+      {
+        file_name: 'logo',
+        content_type: 'image/png',
+        content: 'AQID',
+        inline: true,
+      },
+    ]);
+  });
+
+  it('uses the filename for inline attachments without content IDs', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            filename: 'logo.png',
+            content: new Uint8Array([1, 2, 3]),
+            contentType: 'image/png',
+            inline: true,
+            contentId: '',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.equal(result.attachments?.[0]?.file_name, 'logo.png');
+  });
+
+  it('propagates aborts while converting attachments', async () => {
+    const controller = new AbortController();
+    const reason = new Error('Stop converting Maileroo message.');
+    const content = new Promise(() => {});
+    const conversion = convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            filename: 'slow.txt',
+            content,
+            contentType: 'text/plain',
+            inline: false,
+            contentId: '',
+          },
+        ],
+      }),
+      baseConfig,
+      controller.signal,
+    );
+
+    controller.abort(reason);
+
+    await assert.rejects(
+      Promise.race([
+        conversion,
+        new Promise((_resolve, reject) => {
+          setTimeout(() => reject(new Error('Conversion did not abort.')), 50);
+        }),
+      ]),
+      (error) => error === reason,
+    );
+  });
+
+  it('does not attach abort listeners for immediate attachment content', async () => {
+    const controller = new AbortController();
+    const addEventListener = controller.signal.addEventListener.bind(controller.signal);
+    let abortListeners = 0;
+
+    Object.defineProperty(controller.signal, 'addEventListener', {
+      configurable: true,
+      value: (type, listener, options) => {
+        if (type === 'abort') abortListeners++;
+        addEventListener(type, listener, options);
+      },
+    });
+
+    const result = await convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            filename: 'immediate.txt',
+            content: new TextEncoder().encode('hello'),
+            contentType: 'text/plain',
+            inline: false,
+            contentId: '',
+          },
+        ],
+      }),
+      baseConfig,
+      controller.signal,
+    );
+
+    assert.equal(result.attachments?.[0]?.content, 'aGVsbG8=');
+    assert.equal(abortListeners, 0);
+  });
+
+  it('uses native Uint8Array base64 conversion when available', async () => {
+    const content = new Uint8Array([1, 2, 3]);
+    Object.defineProperty(content, 'toBase64', {
+      configurable: true,
+      value() {
+        assert.deepEqual([...this], [1, 2, 3]);
+        return 'native-base64';
+      },
+    });
+
+    const result = await convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            filename: 'native.bin',
+            content,
+            contentType: 'application/octet-stream',
+            inline: false,
+            contentId: '',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.equal(result.attachments?.[0]?.content, 'native-base64');
+  });
+
+  it('uses Buffer base64 conversion when available', async () => {
+    await withGlobalMutationLock(async () => {
+      const content = new Uint8Array([1, 2, 3]);
+      Object.defineProperty(content, 'toBase64', {
+        configurable: true,
+        value: undefined,
+      });
+      const originalBuffer = Object.getOwnPropertyDescriptor(globalThis, 'Buffer');
+      let capturedBytes;
+      Object.defineProperty(globalThis, 'Buffer', {
+        configurable: true,
+        value: {
+          from(buffer, byteOffset, byteLength) {
+            capturedBytes = new Uint8Array(buffer, byteOffset, byteLength);
+            return {
+              toString(encoding) {
+                assert.equal(encoding, 'base64');
+                return 'buffer-base64';
+              },
+            };
+          },
+        },
+      });
+
+      try {
+        const result = await convertMessage(
+          createBaseMessage({
+            attachments: [
+              {
+                filename: 'buffer.bin',
+                content,
+                contentType: 'application/octet-stream',
+                inline: false,
+                contentId: '',
+              },
+            ],
+          }),
+          baseConfig,
+        );
+
+        assert.deepEqual([...(capturedBytes ?? [])], [1, 2, 3]);
+        assert.equal(result.attachments?.[0]?.content, 'buffer-base64');
+      } finally {
+        if (originalBuffer == null) {
+          delete globalThis.Buffer;
+        } else {
+          Object.defineProperty(globalThis, 'Buffer', originalBuffer);
+        }
+      }
+    });
+  });
+
+  it('falls back when the Buffer base64 converter is incomplete', async () => {
+    await withGlobalMutationLock(async () => {
+      const content = new Uint8Array([1, 2, 3]);
+      Object.defineProperty(content, 'toBase64', {
+        configurable: true,
+        value: undefined,
+      });
+      const originalBuffer = Object.getOwnPropertyDescriptor(globalThis, 'Buffer');
+      Object.defineProperty(globalThis, 'Buffer', {
+        configurable: true,
+        value: {
+          from() {
+            return { toString: undefined };
+          },
+        },
+      });
+
+      try {
+        const result = await convertMessage(
+          createBaseMessage({
+            attachments: [
+              {
+                filename: 'fallback.bin',
+                content,
+                contentType: 'application/octet-stream',
+                inline: false,
+                contentId: '',
+              },
+            ],
+          }),
+          baseConfig,
+        );
+
+        assert.equal(result.attachments?.[0]?.content, 'AQID');
+      } finally {
+        if (originalBuffer == null) {
+          delete globalThis.Buffer;
+        } else {
+          Object.defineProperty(globalThis, 'Buffer', originalBuffer);
+        }
+      }
+    });
+  });
+
+  it('keeps fallback base64 chunks small', async () => {
+    await withGlobalMutationLock(async () => {
+      const content = new Uint8Array(9000);
+      Object.defineProperty(content, 'toBase64', {
+        configurable: true,
+        value: undefined,
+      });
+      const originalBuffer = Object.getOwnPropertyDescriptor(globalThis, 'Buffer');
+      delete globalThis.Buffer;
+      const originalFromCharCode = String.fromCharCode;
+      const chunkLengths = [];
+      Object.defineProperty(String, 'fromCharCode', {
+        configurable: true,
+        value(...codes) {
+          chunkLengths.push(codes.length);
+          return originalFromCharCode(...codes);
+        },
+      });
+
+      try {
+        await convertMessage(
+          createBaseMessage({
+            attachments: [
+              {
+                filename: 'large.bin',
+                content,
+                contentType: 'application/octet-stream',
+                inline: false,
+                contentId: '',
+              },
+            ],
+          }),
+          baseConfig,
+        );
+      } finally {
+        Object.defineProperty(String, 'fromCharCode', {
+          configurable: true,
+          value: originalFromCharCode,
+        });
+        if (originalBuffer != null) {
+          Object.defineProperty(globalThis, 'Buffer', originalBuffer);
+        }
+      }
+
+      assert.ok(chunkLengths.every((length) => length <= 4096));
+      assert.ok(chunkLengths.includes(4096));
+      assert.ok(chunkLengths.includes(808));
+    });
+  });
+});
+
+const threadingConfig = createMailerooConfig({ apiKey: 'test-key' });
+
+const headerOf = (headers, name) =>
+  Object.entries(headers)
+    .filter(([key]) => key.toLowerCase() === name.toLowerCase())
+    .map(([, value]) => value);
+
+describe('convertMessage() reply threading', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Re: Your request',
+    content: { text: 'Thanks for getting in touch.' },
+  };
+
+  it('writes the typed threading fields', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: '122@example.com',
+      references: ['120@example.com', '121@example.com'],
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<122@example.com>']);
+    assert.deepEqual(headerOf(result, 'References'), ['<120@example.com> <121@example.com>']);
+  });
+
+  it('prefers a typed field over a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: ['typed@example.com'],
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<typed@example.com>']);
+  });
+
+  it('lets an empty list suppress a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: [],
+      references: [],
+      headers: {
+        'In-Reply-To': '<custom@example.com>',
+        References: '<custom@example.com>',
+      },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), []);
+    assert.deepEqual(headerOf(result, 'References'), []);
+  });
+
+  it('lets a custom header through when the field is unset', async () => {
+    const message = createMessage({
+      ...base,
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<custom@example.com>']);
+  });
+});
+
+const CALENDAR_ICS =
+  [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'SUMMARY:Lunch',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+/** The invitation content as the providers below carry it: Base64. */
+const CALENDAR_BASE64 = btoa(CALENDAR_ICS);
+
+const AGENDA_ATTACHMENT = {
+  inline: false,
+  filename: 'agenda.txt',
+  content: new TextEncoder().encode('agenda'),
+  contentType: 'text/plain',
+  contentId: '',
+};
+
+describe('convertMessage() calendar', () => {
+  const invitation = (overrides = {}) =>
+    createBaseMessage({
+      calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+      ...overrides,
+    });
+
+  it('should carry the calendar as an invite.ics attachment', async () => {
+    const result = await convertMessage(invitation(), baseConfig);
+
+    assert.equal(result.attachments?.length, 1);
+    assert.equal(result.attachments?.[0].file_name, 'invite.ics');
+    assert.equal(
+      result.attachments?.[0].content_type,
+      'text/calendar; charset=utf-8; method=REQUEST',
+    );
+    assert.equal(result.attachments?.[0].content, CALENDAR_BASE64);
+    // Maileroo overloads the filename for an inline part, which this is not.
+    assert.equal(result.attachments?.[0].inline, undefined);
+  });
+
+  it('should place the invitation ahead of the other attachments', async () => {
+    const result = await convertMessage(
+      invitation({ attachments: [AGENDA_ATTACHMENT] }),
+      baseConfig,
+    );
+
+    assert.deepEqual(
+      result.attachments?.map((attachment) => attachment.file_name),
+      ['invite.ics', 'agenda.txt'],
+    );
+  });
+
+  it('should reject calendar content that never passed createMessage()', async () => {
+    await assert.rejects(
+      () =>
+        convertMessage(
+          createBaseMessage({
+            calendar: { method: 'REQUEST', content: 'not a calendar' },
+          }),
+          baseConfig,
+        ),
+      { name: 'TypeError' },
+    );
+  });
+});
diff --git a/tests/unit/maileroo-transport.test.js b/tests/unit/maileroo-transport.test.js
new file mode 100644
index 0000000..da5d62b
--- /dev/null
+++ b/tests/unit/maileroo-transport.test.js
@@ -0,0 +1,842 @@
+// Ported from upyo v0.7.0 (packages/maileroo/src/maileroo-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { MailerooTransport } = require('../../src/maileroo/maileroo-transport.js');
+
+const createMessage = (overrides = {}) => {
+  return {
+    sender: { address: 'sender@example.com' },
+    recipients: [{ address: 'recipient@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test content' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+let fetchMockChain = Promise.resolve();
+
+const withMockedFetch = async (fetchMock, callback) => {
+  const previous = fetchMockChain;
+  let release = () => {};
+  fetchMockChain = new Promise((resolve) => {
+    release = resolve;
+  });
+  await previous;
+
+  const originalFetch = globalThis.fetch;
+  try {
+    globalThis.fetch = fetchMock;
+    return await callback();
+  } finally {
+    globalThis.fetch = originalFetch;
+    release();
+  }
+};
+
+describe('MailerooTransport - config', { concurrency: false }, () => {
+  it('creates a transport with minimal config', () => {
+    const transport = new MailerooTransport({
+      apiKey: 'test-key',
+    });
+
+    assert.equal(transport.config.apiKey, 'test-key');
+    assert.equal(transport.config.baseUrl, 'https://smtp.maileroo.com/api/v2');
+    assert.equal(transport.config.timeout, 30000);
+    assert.equal(transport.config.retries, 3);
+  });
+
+  it('creates a transport with custom config', () => {
+    const transport = new MailerooTransport({
+      apiKey: 'test-key',
+      baseUrl: 'https://maileroo.example.com/api',
+      timeout: 10000,
+      retries: 1,
+      tracking: true,
+      tags: { source: 'upyo-test' },
+    });
+
+    assert.equal(transport.config.baseUrl, 'https://maileroo.example.com/api');
+    assert.equal(transport.config.timeout, 10000);
+    assert.equal(transport.config.retries, 1);
+    assert.ok(transport.config.tracking);
+    assert.deepEqual(transport.config.tags, { source: 'upyo-test' });
+  });
+});
+
+describe('MailerooTransport - send', { concurrency: false }, () => {
+  it('sends a message successfully', async () => {
+    let capturedUrl = '';
+    let capturedBody;
+    let capturedHeaders = new Headers();
+
+    await withMockedFetch(
+      (url, init) => {
+        capturedUrl = String(url);
+        capturedBody = JSON.parse(String(init?.body));
+        capturedHeaders = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: true,
+              message: 'The email has been scheduled for delivery.',
+              data: { reference_id: 'c843204e3af03193bd14f339' },
+            }),
+            {
+              status: 200,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          ),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          baseUrl: 'https://api.example.com',
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(capturedUrl, 'https://api.example.com/emails');
+        assert.equal(capturedHeaders.get('X-API-Key'), 'test-key');
+        const body = capturedBody;
+        assert.match(body.reference_id ?? '', /^[0-9a-f]{24}$/);
+        delete body.reference_id;
+        assert.deepEqual(body, {
+          from: { address: 'sender@example.com' },
+          to: { address: 'recipient@example.com' },
+          subject: 'Test Subject',
+          plain: 'Test content',
+        });
+        assert.ok(receipt.successful);
+        if (receipt.successful) {
+          assert.equal(receipt.messageId, 'c843204e3af03193bd14f339');
+          assert.equal(receipt.provider, 'maileroo');
+        }
+      },
+    );
+  });
+
+  it('adds configured request headers after auth defaults', async () => {
+    let capturedHeaders = new Headers();
+
+    await withMockedFetch(
+      (_url, init) => {
+        capturedHeaders = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: true,
+              data: { reference_id: 'c843204e3af03193bd14f339' },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          headers: { 'X-Trace-ID': 'trace-123' },
+        });
+
+        await transport.send(createMessage());
+
+        assert.equal(capturedHeaders.get('X-Trace-ID'), 'trace-123');
+        assert.equal(capturedHeaders.get('Content-Type'), 'application/json');
+      },
+    );
+  });
+
+  it('returns failure receipts for API errors', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(JSON.stringify({ message: 'Invalid API key' }), {
+            status: 401,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        ),
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'bad-key',
+          retries: 0,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, ['Invalid API key']);
+          assert.equal(receipt.provider, 'maileroo');
+          assert.ok(!receipt.retryable);
+          assert.equal(receipt.errors?.[0]?.category, 'auth');
+          assert.equal(receipt.errors?.[0]?.statusCode, 401);
+        }
+      },
+    );
+  });
+
+  it('truncates non-JSON API response bodies in failure receipts', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response('x'.repeat(600), {
+            status: 503,
+            headers: { 'Content-Type': 'text/html' },
+          }),
+        ),
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 0,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.equal(receipt.errorMessages[0], `${'x'.repeat(500)}...`);
+        }
+      },
+    );
+  });
+
+  it('returns failed receipts for unsuccessful JSON responses', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: false,
+              message: 'Message rejected',
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        ),
+      async () => {
+        const transport = new MailerooTransport({ apiKey: 'test-key' });
+        const receipt = await transport.send(createMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, ['Message rejected']);
+          assert.equal(receipt.provider, 'maileroo');
+          assert.ok(!receipt.retryable);
+          assert.equal(receipt.errors?.[0]?.category, 'rejected');
+          assert.equal(receipt.errors?.[0]?.code, 'maileroo.unsuccessful');
+        }
+      },
+    );
+  });
+
+  it('returns failed receipts for non-object success responses', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response('null', {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        ),
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 0,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, [
+            'Invalid JSON response from Maileroo API: response is not an object.',
+          ]);
+          assert.equal(receipt.errors?.[0]?.category, 'validation');
+          assert.ok(!receipt.retryable);
+        }
+      },
+    );
+  });
+
+  it('does not retry malformed successful responses', async () => {
+    let calls = 0;
+
+    await withMockedFetch(
+      () => {
+        calls++;
+        return Promise.resolve(
+          new Response('not json', {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 1,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(calls, 1);
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.match(receipt.errorMessages[0], /^Invalid JSON response from Maileroo API:/);
+          assert.equal(receipt.errors?.[0]?.category, 'validation');
+          assert.ok(!receipt.retryable);
+        }
+      },
+    );
+  });
+
+  it('falls back for non-object JSON API error bodies', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response('null', {
+            status: 400,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        ),
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 0,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, ['null']);
+          assert.equal(receipt.errors?.[0]?.category, 'validation');
+          assert.ok(!receipt.retryable);
+        }
+      },
+    );
+  });
+
+  it('returns failed receipts when the reference ID is missing', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(JSON.stringify({ success: true, data: {} }), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        ),
+      async () => {
+        const transport = new MailerooTransport({ apiKey: 'test-key' });
+        const receipt = await transport.send(createMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, ['Maileroo response is missing a reference ID.']);
+          assert.equal(receipt.errors?.[0]?.code, 'maileroo.missing_reference_id');
+        }
+      },
+    );
+  });
+
+  it('propagates AbortError for aborted sends', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const transport = new MailerooTransport({ apiKey: 'test-key' });
+
+    await assert.rejects(() => transport.send(createMessage(), { signal: controller.signal }), {
+      name: 'AbortError',
+    });
+  });
+
+  it('propagates custom caller abort reasons during sends', async () => {
+    const controller = new AbortController();
+    const reason = new Error('Stop Maileroo send.');
+
+    await withMockedFetch(
+      (_url, init) =>
+        new Promise((_resolve, reject) => {
+          init?.signal?.addEventListener(
+            'abort',
+            () => {
+              reject(init.signal?.reason);
+            },
+            { once: true },
+          );
+          setTimeout(() => controller.abort(reason), 0);
+        }),
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 0,
+        });
+
+        await assert.rejects(
+          () => transport.send(createMessage(), { signal: controller.signal }),
+          (error) => error === reason,
+        );
+      },
+    );
+  });
+
+  it('keeps request timeouts active while reading response bodies', async () => {
+    await withMockedFetch(
+      (_url, init) => {
+        const response = new Response(null, {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+        Object.defineProperty(response, 'text', {
+          value: () =>
+            new Promise((_resolve, reject) => {
+              init?.signal?.addEventListener(
+                'abort',
+                () => {
+                  reject(new DOMException('The operation was aborted.', 'AbortError'));
+                },
+                { once: true },
+              );
+              setTimeout(() => {
+                reject(new Error('Body read was not aborted.'));
+              }, 50);
+            }),
+        });
+        return Promise.resolve(response);
+      },
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          timeout: 1,
+          retries: 0,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.equal(receipt.errors?.[0]?.category, 'timeout');
+          assert.ok(receipt.retryable);
+        }
+      },
+    );
+  });
+
+  it('retries request timeouts from the transport config', async () => {
+    let calls = 0;
+
+    await withMockedFetch(
+      (_url, init) => {
+        calls++;
+        if (calls === 1) {
+          return new Promise((_resolve, reject) => {
+            init?.signal?.addEventListener(
+              'abort',
+              () => {
+                reject(new DOMException('The operation was aborted.', 'AbortError'));
+              },
+              { once: true },
+            );
+          });
+        }
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: true,
+              data: { reference_id: 'c843204e3af03193bd14f339' },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          timeout: 1,
+          retries: 1,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(calls, 2);
+        assert.ok(receipt.successful);
+      },
+    );
+  });
+
+  it('preserves custom caller abort reasons during retry delays', async () => {
+    const controller = new AbortController();
+    const reason = new Error('Stop retrying Maileroo send.');
+
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(JSON.stringify({ message: 'Too many requests' }), {
+            status: 429,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        ),
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 1,
+        });
+        setTimeout(() => controller.abort(reason), 0);
+
+        await assert.rejects(
+          () => transport.send(createMessage(), { signal: controller.signal }),
+          (error) => error === reason,
+        );
+      },
+    );
+  });
+
+  it('retries 429 rate limit responses', async () => {
+    let calls = 0;
+
+    await withMockedFetch(
+      () => {
+        calls++;
+        if (calls === 1) {
+          return Promise.resolve(
+            new Response(JSON.stringify({ message: 'Too many requests' }), {
+              status: 429,
+              headers: { 'Content-Type': 'application/json' },
+            }),
+          );
+        }
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: true,
+              data: { reference_id: 'c843204e3af03193bd14f339' },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 1,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(calls, 2);
+        assert.ok(receipt.successful);
+      },
+    );
+  });
+
+  it('reuses Maileroo reference IDs across retries', async () => {
+    let calls = 0;
+    const referenceIds = [];
+
+    await withMockedFetch(
+      (_url, init) => {
+        calls++;
+        const body = JSON.parse(String(init?.body));
+        if (body.reference_id != null) referenceIds.push(body.reference_id);
+
+        if (calls === 1) {
+          return Promise.resolve(
+            new Response(JSON.stringify({ message: 'Temporary server error' }), {
+              status: 500,
+              headers: { 'Content-Type': 'application/json' },
+            }),
+          );
+        }
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: true,
+              data: { reference_id: 'c843204e3af03193bd14f339' },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 1,
+        });
+        const receipt = await transport.send(
+          createMessage({ idempotencyKey: 'retry-maileroo-message' }),
+        );
+
+        assert.equal(calls, 2);
+        assert.ok(receipt.successful);
+        assert.deepEqual(referenceIds, [referenceIds[0], referenceIds[0]]);
+        assert.match(referenceIds[0] ?? '', /^[0-9a-f]{24}$/);
+      },
+    );
+  });
+
+  it('respects Retry-After delays before retrying rate limits', async () => {
+    let calls = 0;
+    const originalRandom = Math.random;
+
+    await withMockedFetch(
+      () => {
+        calls++;
+        if (calls === 1) {
+          return Promise.resolve(
+            new Response(JSON.stringify({ message: 'Too many requests' }), {
+              status: 429,
+              headers: {
+                'Content-Type': 'application/json',
+                'Retry-After': '1',
+              },
+            }),
+          );
+        }
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: true,
+              data: { reference_id: 'c843204e3af03193bd14f339' },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        Math.random = () => 0;
+        const startedAt = performance.now();
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 1,
+        });
+        try {
+          const receipt = await transport.send(createMessage());
+
+          assert.equal(calls, 2);
+          assert.ok(receipt.successful);
+          assert.ok(performance.now() - startedAt >= 900);
+        } finally {
+          Math.random = originalRandom;
+        }
+      },
+    );
+  });
+
+  it('exposes Retry-After metadata when retries are exhausted', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(JSON.stringify({ message: 'Too many requests' }), {
+            status: 429,
+            headers: { 'Retry-After': '20' },
+          }),
+        ),
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 0,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.equal(receipt.provider, 'maileroo');
+          assert.ok(receipt.retryable);
+          assert.equal(receipt.errors?.[0]?.category, 'rate-limit');
+          assert.equal(receipt.errors?.[0]?.retryAfterMilliseconds, 20_000);
+        }
+      },
+    );
+  });
+
+  it('does not retry redirection responses', async () => {
+    let calls = 0;
+
+    await withMockedFetch(
+      () => {
+        calls++;
+        return Promise.resolve(
+          new Response('', {
+            status: 302,
+            headers: { Location: 'https://api.example.com/other' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 1,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(calls, 1);
+        assert.ok(!receipt.successful);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, ['HTTP 302']);
+        }
+      },
+    );
+  });
+
+  // Upstream's "falls back when AbortSignal.any is unavailable" is not ported: Node 22 always
+  // has AbortSignal.any, and the core keeps no fallback without it.
+});
+
+describe('MailerooTransport - sendMany', { concurrency: false }, () => {
+  it('sends messages sequentially', async () => {
+    const capturedBodies = [];
+
+    await withMockedFetch(
+      (_url, init) => {
+        capturedBodies.push(JSON.parse(String(init?.body)));
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: true,
+              data: {
+                reference_id: `c843204e3af03193bd14f33${capturedBodies.length}`,
+              },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({ apiKey: 'test-key' });
+        const receipts = [];
+        for await (const receipt of transport.sendMany([
+          createMessage({ recipients: [{ address: 'one@example.com' }] }),
+          createMessage({ recipients: [{ address: 'two@example.com' }] }),
+        ])) {
+          receipts.push(receipt);
+        }
+
+        for (const body of capturedBodies) {
+          assert.match(body.reference_id ?? '', /^[0-9a-f]{24}$/);
+          delete body.reference_id;
+        }
+        assert.deepEqual(capturedBodies, [
+          {
+            from: { address: 'sender@example.com' },
+            to: { address: 'one@example.com' },
+            subject: 'Test Subject',
+            plain: 'Test content',
+          },
+          {
+            from: { address: 'sender@example.com' },
+            to: { address: 'two@example.com' },
+            subject: 'Test Subject',
+            plain: 'Test content',
+          },
+        ]);
+        assert.equal(receipts.length, 2);
+        assert.ok(receipts.every((receipt) => receipt.successful));
+      },
+    );
+  });
+
+  it('streams async input one message at a time', async () => {
+    const capturedBodies = [];
+    let generated = 0;
+
+    const messages = async function* () {
+      for (let index = 0; index < 2; index++) {
+        generated++;
+        yield createMessage({
+          recipients: [{ address: `user${index}@example.com` }],
+        });
+      }
+    };
+
+    await withMockedFetch(
+      (_url, init) => {
+        capturedBodies.push(JSON.parse(String(init?.body)));
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: true,
+              data: {
+                reference_id: `c843204e3af03193bd14f33${capturedBodies.length}`,
+              },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({ apiKey: 'test-key' });
+        const receipts = [];
+        for await (const receipt of transport.sendMany(messages())) {
+          receipts.push(receipt);
+          if (receipts.length === 1) break;
+        }
+
+        assert.equal(generated, 1);
+        assert.equal(capturedBodies.length, 1);
+        assert.equal(receipts.length, 1);
+        assert.ok(receipts.every((receipt) => receipt.successful));
+      },
+    );
+  });
+
+  it('returns no receipts for empty input', async () => {
+    const transport = new MailerooTransport({ apiKey: 'test-key' });
+    const receipts = [];
+
+    for await (const receipt of transport.sendMany([])) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 0);
+  });
+
+  it('returns per-message failures', async () => {
+    let calls = 0;
+
+    await withMockedFetch(
+      () => {
+        calls++;
+        if (calls === 2) {
+          return Promise.resolve(
+            new Response(JSON.stringify({ message: 'Message rejected' }), {
+              status: 422,
+              headers: { 'Content-Type': 'application/json' },
+            }),
+          );
+        }
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              success: true,
+              data: {
+                reference_id: `c843204e3af03193bd14f33${calls}`,
+              },
+            }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new MailerooTransport({
+          apiKey: 'test-key',
+          retries: 0,
+        });
+        const receipts = [];
+        for await (const receipt of transport.sendMany([
+          createMessage({ recipients: [{ address: 'one@example.com' }] }),
+          createMessage({ recipients: [{ address: 'two@example.com' }] }),
+          createMessage({ recipients: [{ address: 'three@example.com' }] }),
+        ])) {
+          receipts.push(receipt);
+        }
+
+        assert.equal(receipts.length, 3);
+        assert.ok(receipts[0].successful);
+        assert.ok(!receipts[1].successful);
+        assert.ok(receipts[2].successful);
+        if (!receipts[1].successful) {
+          assert.deepEqual(receipts[1].errorMessages, ['Message rejected']);
+        }
+      },
+    );
+  });
+});
diff --git a/tests/unit/maileroo.test.js b/tests/unit/maileroo.test.js
new file mode 100644
index 0000000..396df3c
--- /dev/null
+++ b/tests/unit/maileroo.test.js
@@ -0,0 +1,34 @@
+// Paths of the ported Maileroo transport (src/maileroo/) that upstream's
+// suites leave out, against a stubbed fetch.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { MailerooTransport } = require('../../src/maileroo/index.js');
+
+const message = () =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+const config = { apiKey: 'key', retries: 0 };
+
+test('Maileroo: an error body gives its message, its error or its errors', async (t) => {
+  const cases = [
+    [{ error: 'Sender not verified' }, 'Sender not verified'],
+    [{ errors: [{ field: 'to' }] }, '[{"field":"to"}]'],
+  ];
+  for (const [body, expected] of cases) {
+    t.mock.restoreAll();
+    t.mock.method(globalThis, 'fetch', async () => Response.json(body, { status: 422 }));
+    const receipt = await new MailerooTransport(config).send(message());
+    assert.deepStrictEqual(receipt.errorMessages, [expected]);
+  }
+});
+
+test('Maileroo: an unsuccessful 200 without a message fails the send', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => Response.json({ success: false }));
+  const receipt = await new MailerooTransport(config).send(message());
+  assert.deepStrictEqual(receipt.errorMessages, ['Maileroo reported an unsuccessful response.']);
+});

From cbb65073808f2597c2f985cba8bfbf8b988afad0 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:20:17 +0300
Subject: [PATCH 012/158] feat(lettermint): port the Lettermint transport from
 upyo 0.7.0

./lettermint exports LettermintTransport, createLettermintConfig,
LettermintApiError and LettermintTimeoutError: the Lettermint send and
batch APIs over fetch, with routes, tags, metadata and tracking settings,
an idempotency key per message, retries on 408, 429 and 5xx with jitter and
Retry-After, and a request timeout.

Upstream's unit suites are ported, the e2e suite goes to tests/e2e, and its
test of a runtime without AbortSignal.any is left out.
tests/unit/lettermint.test.js covers a 200 without JSON, the error bodies,
the timeout, an abort while waiting to retry, and a batch with nothing left
to send.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   2 +-
 package.json                                  |   4 +
 src/lettermint/config.js                      |  28 +
 src/lettermint/http-client.js                 | 263 +++++
 src/lettermint/index.d.ts                     | 243 +++++
 src/lettermint/index.js                       |  21 +
 src/lettermint/lettermint-transport.js        | 271 +++++
 src/lettermint/message-converter.js           | 212 ++++
 tests/e2e/lettermint-transport.e2e.test.js    | 115 +++
 tests/helpers/lettermint/test-config.js       |  70 ++
 tests/types/lettermint.test-d.ts              |  28 +
 tests/unit/lettermint-config.test.js          |  78 ++
 .../unit/lettermint-message-converter.test.js | 400 ++++++++
 tests/unit/lettermint-transport.test.js       | 941 ++++++++++++++++++
 tests/unit/lettermint.test.js                 |  94 ++
 15 files changed, 2769 insertions(+), 1 deletion(-)
 create mode 100644 src/lettermint/config.js
 create mode 100644 src/lettermint/http-client.js
 create mode 100644 src/lettermint/index.d.ts
 create mode 100644 src/lettermint/index.js
 create mode 100644 src/lettermint/lettermint-transport.js
 create mode 100644 src/lettermint/message-converter.js
 create mode 100644 tests/e2e/lettermint-transport.e2e.test.js
 create mode 100644 tests/helpers/lettermint/test-config.js
 create mode 100644 tests/types/lettermint.test-d.ts
 create mode 100644 tests/unit/lettermint-config.test.js
 create mode 100644 tests/unit/lettermint-message-converter.test.js
 create mode 100644 tests/unit/lettermint-transport.test.js
 create mode 100644 tests/unit/lettermint.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 090e413..c8d4baa 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 9bcd2f6..1bd35fa 100644
--- a/package.json
+++ b/package.json
@@ -56,6 +56,10 @@
       "types": "./src/maileroo/index.d.ts",
       "default": "./src/maileroo/index.js"
     },
+    "./lettermint": {
+      "types": "./src/lettermint/index.d.ts",
+      "default": "./src/lettermint/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
diff --git a/src/lettermint/config.js b/src/lettermint/config.js
new file mode 100644
index 0000000..1e080db
--- /dev/null
+++ b/src/lettermint/config.js
@@ -0,0 +1,28 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved Lettermint configuration by applying default values.
+ *
+ * @param config The Lettermint configuration with optional fields.
+ * @returns A resolved configuration with all defaults applied.
+ */
+const createLettermintConfig = (config) => {
+  return {
+    apiToken: config.apiToken,
+    baseUrl: normalizeBaseUrl(config.baseUrl ?? 'https://api.lettermint.co'),
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    headers: config.headers ?? {},
+    route: config.route,
+    tag: config.tag,
+    metadata: config.metadata == null ? undefined : { ...config.metadata },
+    settings: config.settings == null ? undefined : { ...config.settings },
+  };
+};
+
+const normalizeBaseUrl = (baseUrl) => {
+  return baseUrl.replace(/\/+$/, '');
+};
+
+module.exports = { createLettermintConfig };
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
new file mode 100644
index 0000000..560b7e5
--- /dev/null
+++ b/src/lettermint/http-client.js
@@ -0,0 +1,263 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/http-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { parseRetryAfter } = require('../core/receipt.js');
+
+/**
+ * Lettermint API error class for API-specific failures.
+ */
+class LettermintApiError extends Error {
+  statusCode;
+  retryAfterMilliseconds;
+  attempts;
+
+  /**
+   * Creates a Lettermint API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(message, statusCode, retryAfterMilliseconds, attempts) {
+    super(message);
+    this.name = 'LettermintApiError';
+    this.statusCode = statusCode;
+    this.retryAfterMilliseconds = retryAfterMilliseconds;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * Lettermint request timeout error.
+ */
+class LettermintTimeoutError extends Error {
+  /**
+   * Request timeout in milliseconds.
+   */
+  timeout;
+
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  attempts;
+
+  /**
+   * Creates a Lettermint request timeout error.
+   *
+   * @param timeout Request timeout in milliseconds.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(timeout, attempts) {
+    super(`Lettermint API request timed out after ${timeout} ms.`);
+    this.name = 'LettermintTimeoutError';
+    this.timeout = timeout;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * HTTP client wrapper for Lettermint API requests.
+ */
+class LettermintHttpClient {
+  config;
+
+  /**
+   * Creates a new Lettermint HTTP client.
+   *
+   * @param config Resolved Lettermint configuration.
+   */
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Sends a single message via Lettermint API.
+   *
+   * @param messageData The JSON data to send to Lettermint.
+   * @param signal Optional AbortSignal for cancellation.
+   * @param idempotencyKey Optional idempotency key for request deduplication.
+   * @returns Promise that resolves to the Lettermint response.
+   */
+  sendMessage(messageData, signal, idempotencyKey) {
+    const url = `${this.config.baseUrl}/v1/send`;
+    return this.makeRequest(url, messageData, signal, idempotencyKey);
+  }
+
+  /**
+   * Sends multiple messages via Lettermint batch API.
+   *
+   * @param messagesData The messages to send to Lettermint.
+   * @param signal Optional AbortSignal for cancellation.
+   * @param idempotencyKey Optional idempotency key for request deduplication.
+   * @returns Promise that resolves to the Lettermint batch response.
+   */
+  sendBatch(messagesData, signal, idempotencyKey) {
+    const url = `${this.config.baseUrl}/v1/send/batch`;
+    return this.makeRequest(url, messagesData, signal, idempotencyKey);
+  }
+
+  async makeRequest(url, body, signal, idempotencyKey) {
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      signal?.throwIfAborted();
+
+      try {
+        const response = await this.fetchWithAuth(url, body, signal, idempotencyKey);
+        const text = await response.text();
+
+        if (!response.ok) {
+          throw new LettermintApiError(
+            parseErrorMessage(text, response.status),
+            response.status,
+            parseRetryAfter(response.headers.get('Retry-After')),
+            attempt + 1,
+          );
+        }
+
+        try {
+          return JSON.parse(text);
+        } catch (error) {
+          throw new SyntaxError(
+            `Invalid JSON response from Lettermint API: ${
+              error instanceof Error ? error.message : String(error)
+            }.`,
+          );
+        }
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (error instanceof LettermintApiError && !isRetryable(error)) {
+          throw error;
+        }
+
+        if (error instanceof Error && error.name === 'AbortError' && signal?.aborted) {
+          throw error;
+        }
+
+        if (attempt === this.config.retries) {
+          throw withAttempts(lastError, attempt + 1);
+        }
+
+        await sleep(calculateRetryDelay(attempt), signal);
+      }
+    }
+
+    throw lastError ?? new Error('Request failed after all retry attempts.');
+  }
+
+  async fetchWithAuth(url, body, signal, idempotencyKey) {
+    const headers = new Headers({
+      'Content-Type': 'application/json',
+      'x-lettermint-token': this.config.apiToken,
+    });
+
+    if (idempotencyKey) {
+      headers.set('Idempotency-Key', idempotencyKey);
+    }
+
+    for (const [key, value] of Object.entries(this.config.headers)) {
+      headers.set(key, value);
+    }
+
+    const timeoutController = new AbortController();
+    const timeoutId =
+      this.config.timeout > 0
+        ? setTimeout(() => timeoutController.abort(), this.config.timeout)
+        : undefined;
+    const requestSignal = combineSignals(timeoutController.signal, signal);
+
+    try {
+      return await globalThis.fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: requestSignal.signal,
+      });
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        error.name === 'AbortError' &&
+        timeoutController.signal.aborted &&
+        !signal?.aborted
+      ) {
+        throw new LettermintTimeoutError(this.config.timeout);
+      }
+      throw error;
+    } finally {
+      requestSignal.cleanup();
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+}
+
+const withAttempts = (error, attempts) => {
+  if (error instanceof LettermintTimeoutError) {
+    return new LettermintTimeoutError(error.timeout, attempts);
+  }
+  if (error instanceof LettermintApiError) {
+    return error;
+  }
+  return Object.assign(error, { attempts });
+};
+
+const isRetryable = (error) => {
+  return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
+};
+
+const calculateRetryDelay = (attempt) => {
+  const baseDelay = Math.min(1000 * Math.pow(2, attempt), 10000);
+  return Math.round(baseDelay / 2 + Math.random() * (baseDelay / 2));
+};
+
+const parseErrorMessage = (text, statusCode) => {
+  try {
+    const errorBody = JSON.parse(text);
+    if (typeof errorBody.message === 'string' && errorBody.message !== '') {
+      return errorBody.message;
+    }
+    if (typeof errorBody.error === 'string' && errorBody.error !== '') {
+      return errorBody.error;
+    }
+    if (Array.isArray(errorBody.errors) && errorBody.errors.length > 0) {
+      return JSON.stringify(errorBody.errors);
+    }
+  } catch {
+    // Ignore if JSON parsing fails, as the body may be non-JSON.
+  }
+
+  return text || `HTTP ${statusCode}`;
+};
+
+const sleep = (ms, signal) => {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException('The operation was aborted.', 'AbortError'));
+      return;
+    }
+
+    const onAbort = () => {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener('abort', onAbort);
+      reject(new DOMException('The operation was aborted.', 'AbortError'));
+    };
+
+    const timeoutId = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+};
+
+module.exports = { LettermintApiError, LettermintTimeoutError, LettermintHttpClient };
diff --git a/src/lettermint/index.d.ts b/src/lettermint/index.d.ts
new file mode 100644
index 0000000..f9be7ba
--- /dev/null
+++ b/src/lettermint/index.d.ts
@@ -0,0 +1,243 @@
+// Types ported from upyo v0.7.0 (packages/lettermint/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Per-email Lettermint tracking settings.
+ *
+ * These settings are sent as provider-specific defaults for every message
+ * delivered through a {@link LettermintTransport}.
+ */
+export interface LettermintSettings {
+  /**
+   * Whether Lettermint should track email opens.
+   */
+  readonly trackOpens?: boolean;
+  /**
+   * Whether Lettermint should track link clicks.
+   */
+  readonly trackClicks?: boolean;
+}
+/**
+ * Configuration interface for Lettermint transport connection settings.
+ *
+ * @example
+ * ```typescript
+ * const config: LettermintConfig = {
+ *   apiToken: "your-project-api-token",
+ *   route: "transactional",
+ *   tag: "welcome",
+ *   timeout: 30000,
+ *   retries: 3,
+ * };
+ * ```
+ */
+export interface LettermintConfig {
+  /**
+   * Your project-specific Lettermint sending API token.
+   *
+   * The token is sent as the `x-lettermint-token` HTTP header.
+   */
+  readonly apiToken: string;
+  /**
+   * Base URL for the Lettermint API.
+   *
+   * @default "https://api.lettermint.co"
+   */
+  readonly baseUrl?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   *
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Lettermint route to apply to sent messages.
+   */
+  readonly route?: string;
+  /**
+   * Default Lettermint tag to apply when the Upyo message has no tag.
+   */
+  readonly tag?: string | null;
+  /**
+   * Metadata to track with sent messages.  This metadata is not added as
+   * email headers.
+   */
+  readonly metadata?: Record<string, string>;
+  /**
+   * Lettermint tracking settings to apply to sent messages.
+   */
+  readonly settings?: LettermintSettings;
+}
+/**
+ * Resolved Lettermint configuration with defaults applied.
+ */
+export type ResolvedLettermintConfig = Required<
+  Omit<LettermintConfig, 'route' | 'tag' | 'metadata' | 'settings'>
+> & {
+  readonly route?: string;
+  readonly tag?: string | null;
+  readonly metadata?: Record<string, string>;
+  readonly settings?: LettermintSettings;
+};
+/**
+ * Creates a resolved Lettermint configuration by applying default values.
+ *
+ * @param config The Lettermint configuration with optional fields.
+ * @returns A resolved configuration with all defaults applied.
+ */
+export declare function createLettermintConfig(config: LettermintConfig): ResolvedLettermintConfig;
+
+/**
+ * Lettermint transport implementation for sending emails via Lettermint API.
+ *
+ * @example
+ * ```typescript
+ * import { createMessage } from "@alexify/mailer";
+ * import { LettermintTransport } from "@alexify/mailer/lettermint";
+ *
+ * const transport = new LettermintTransport({
+ *   apiToken: "your-project-api-token",
+ * });
+ *
+ * const receipt = await transport.send(createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from Lettermint",
+ *   content: { text: "Hello!" },
+ * }));
+ * ```
+ */
+export declare class LettermintTransport implements Transport<'lettermint'> {
+  readonly id = 'lettermint';
+  /**
+   * The resolved Lettermint configuration used by this transport.
+   */
+  config: ResolvedLettermintConfig;
+  /**
+   * Creates a new Lettermint transport instance.
+   *
+   * @param config Lettermint configuration including API token and options.
+   */
+  constructor(config: LettermintConfig);
+  /**
+   * Sends a single email message via Lettermint API.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns A receipt indicating success or failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'lettermint'>>;
+  /**
+   * Sends multiple email messages via Lettermint batch API.
+   *
+   * Messages are chunked into Lettermint's maximum batch size of 500 messages.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'lettermint'>>;
+}
+
+/**
+ * Lettermint message status values.
+ */
+export type LettermintStatus =
+  | 'pending'
+  | 'queued'
+  | 'suppressed'
+  | 'processed'
+  | 'delivered'
+  | 'opened'
+  | 'clicked'
+  | 'soft_bounced'
+  | 'hard_bounced'
+  | 'spam_complaint'
+  | 'failed'
+  | 'blocked'
+  | 'policy_rejected'
+  | 'unsubscribed';
+/**
+ * Response from Lettermint API for sending a single message.
+ */
+export interface LettermintResponse {
+  /** The message ID returned by Lettermint. */
+  readonly message_id: string;
+  /** Current message status. */
+  readonly status: LettermintStatus;
+}
+/**
+ * Response from Lettermint API for sending batch messages.
+ */
+export type LettermintBatchResponse = readonly LettermintResponse[];
+/**
+ * Error response from Lettermint API.
+ */
+export interface LettermintError {
+  /** Error message from Lettermint. */
+  readonly message?: string;
+  /** Error detail from Lettermint. */
+  readonly error?: string;
+  /** Validation errors from Lettermint. */
+  readonly errors?: readonly unknown[];
+}
+/**
+ * Lettermint API error class for API-specific failures.
+ */
+export declare class LettermintApiError extends Error {
+  readonly statusCode: number;
+  readonly retryAfterMilliseconds?: number;
+  readonly attempts?: number;
+  /**
+   * Creates a Lettermint API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(
+    message: string,
+    statusCode: number,
+    retryAfterMilliseconds?: number,
+    attempts?: number,
+  );
+}
+/**
+ * Lettermint request timeout error.
+ */
+export declare class LettermintTimeoutError extends Error {
+  /**
+   * Request timeout in milliseconds.
+   */
+  readonly timeout: number;
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  readonly attempts?: number;
+  /**
+   * Creates a Lettermint request timeout error.
+   *
+   * @param timeout Request timeout in milliseconds.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(timeout: number, attempts?: number);
+}
+/**
+ * HTTP client wrapper for Lettermint API requests.
+ */
diff --git a/src/lettermint/index.js b/src/lettermint/index.js
new file mode 100644
index 0000000..bf81c2d
--- /dev/null
+++ b/src/lettermint/index.js
@@ -0,0 +1,21 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * @fileoverview Lettermint transport for Upyo email library.
+ *
+ * This module provides a transport implementation for sending emails through
+ * Lettermint's HTTP API.  It supports single messages, batch sending,
+ * attachments, provider-specific defaults, retry logic, and idempotency.
+ */
+
+const { LettermintTransport } = require('./lettermint-transport.js');
+const { createLettermintConfig } = require('./config.js');
+const { LettermintApiError, LettermintTimeoutError } = require('./http-client.js');
+
+module.exports = {
+  LettermintTransport,
+  createLettermintConfig,
+  LettermintApiError,
+  LettermintTimeoutError,
+};
diff --git a/src/lettermint/lettermint-transport.js b/src/lettermint/lettermint-transport.js
new file mode 100644
index 0000000..7cf0413
--- /dev/null
+++ b/src/lettermint/lettermint-transport.js
@@ -0,0 +1,271 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/lettermint-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createLettermintConfig } = require('./config.js');
+const {
+  LettermintApiError,
+  LettermintHttpClient,
+  LettermintTimeoutError,
+} = require('./http-client.js');
+const { convertMessage, generateIdempotencyKey } = require('./message-converter.js');
+
+const MAX_BATCH_SIZE = 500;
+
+/**
+ * Lettermint transport implementation for sending emails via Lettermint API.
+ *
+ * @example
+ * ```typescript
+ * import { createMessage } from "@alexify/mailer";
+ * import { LettermintTransport } from "@alexify/mailer/lettermint";
+ *
+ * const transport = new LettermintTransport({
+ *   apiToken: "your-project-api-token",
+ * });
+ *
+ * const receipt = await transport.send(createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient@example.com",
+ *   subject: "Hello from Lettermint",
+ *   content: { text: "Hello!" },
+ * }));
+ * ```
+ */
+class LettermintTransport {
+  id = 'lettermint';
+
+  /**
+   * The resolved Lettermint configuration used by this transport.
+   */
+  config;
+
+  httpClient;
+
+  /**
+   * Creates a new Lettermint transport instance.
+   *
+   * @param config Lettermint configuration including API token and options.
+   */
+  constructor(config) {
+    this.config = createLettermintConfig(config);
+    this.httpClient = new LettermintHttpClient(this.config);
+  }
+
+  /**
+   * Sends a single email message via Lettermint API.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns A receipt indicating success or failure.
+   */
+  async send(message, options) {
+    try {
+      options?.signal?.throwIfAborted();
+
+      const emailData = await convertMessage(message, this.config, options?.signal);
+      const idempotencyKey = normalizeIdempotencyKey(message.idempotencyKey);
+
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendMessage(
+        emailData,
+        options?.signal,
+        idempotencyKey,
+      );
+
+      return responseToReceipt(response);
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) throw error;
+      return createLettermintFailure(error instanceof Error ? error.message : String(error), error);
+    }
+  }
+
+  /**
+   * Sends multiple email messages via Lettermint batch API.
+   *
+   * Messages are chunked into Lettermint's maximum batch size of 500 messages.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal`.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    let chunk = [];
+    for await (const message of messages) {
+      options?.signal?.throwIfAborted();
+      chunk.push(message);
+      if (chunk.length === MAX_BATCH_SIZE) {
+        yield* this.sendBatch(chunk, options);
+        chunk = [];
+      }
+    }
+    yield* this.sendBatch(chunk, options);
+  }
+  async *sendBatch(messages, options) {
+    if (messages.length === 0) return;
+
+    if (messages.some(hasIdempotencyKey)) {
+      for (const message of messages) {
+        yield await this.send(message, options);
+      }
+      return;
+    }
+
+    const idempotencyKey = normalizeIdempotencyKey(messages[0]?.idempotencyKey);
+    const batchData = [];
+    const receipts = [];
+
+    for (const message of messages) {
+      try {
+        batchData.push(await convertMessage(message, this.config, options?.signal));
+        receipts.push(undefined);
+      } catch (error) {
+        if (isCallerAbort(error, options?.signal)) throw error;
+        receipts.push(
+          createLettermintFailure(error instanceof Error ? error.message : String(error), error),
+        );
+      }
+    }
+
+    if (batchData.length === 0) {
+      for (const receipt of receipts) {
+        if (receipt !== undefined) yield receipt;
+      }
+      return;
+    }
+
+    try {
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendBatch(batchData, options?.signal, idempotencyKey);
+
+      let responseIndex = 0;
+      for (let index = 0; index < receipts.length; index++) {
+        const receipt = receipts[index];
+        if (receipt !== undefined) {
+          yield receipt;
+          continue;
+        }
+
+        const result = response[responseIndex++];
+        yield responseToReceipt(result);
+      }
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) throw error;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      for (const receipt of receipts) {
+        if (receipt !== undefined) {
+          yield receipt;
+          continue;
+        }
+        yield {
+          ...createLettermintFailure(errorMessage, error),
+        };
+      }
+    }
+  }
+}
+
+const normalizeIdempotencyKey = (idempotencyKey) => {
+  return idempotencyKey != null && idempotencyKey !== ''
+    ? idempotencyKey
+    : generateIdempotencyKey();
+};
+
+const hasIdempotencyKey = (message) => {
+  return message.idempotencyKey != null && message.idempotencyKey !== '';
+};
+
+const responseToReceipt = (response) => {
+  if (response?.message_id == null || response.message_id === '') {
+    return createFailedReceipt('Lettermint response is missing a message ID.', {
+      provider: 'lettermint',
+      category: 'unknown',
+      code: 'lettermint.missing_message_id',
+      retryable: false,
+    });
+  }
+
+  if (isSuccessfulStatus(response.status)) {
+    return {
+      successful: true,
+      messageId: response.message_id,
+      provider: 'lettermint',
+    };
+  }
+
+  return createFailedReceipt(`Lettermint reported message status "${response.status}".`, {
+    provider: 'lettermint',
+    category: 'rejected',
+    code: `lettermint.${response.status}`,
+    retryable: response.status === 'soft_bounced',
+  });
+};
+
+const createLettermintFailure = (message, error) => {
+  if (error instanceof LettermintApiError) {
+    return createFailedReceipt(message, {
+      provider: 'lettermint',
+      statusCode: error.statusCode,
+      retryAfterMilliseconds: error.retryAfterMilliseconds,
+      attempts: error.attempts,
+    });
+  }
+
+  if (error instanceof LettermintTimeoutError) {
+    return createFailedReceipt(message, {
+      provider: 'lettermint',
+      category: 'timeout',
+      code: 'timeout',
+      retryable: true,
+      attempts: error.attempts,
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'lettermint',
+    attempts: getErrorAttempts(error),
+  });
+};
+
+const getErrorAttempts = (error) => {
+  if (typeof error !== 'object' || error == null || !('attempts' in error)) {
+    return undefined;
+  }
+  const attempts = error.attempts;
+  return typeof attempts === 'number' ? attempts : undefined;
+};
+
+const isSuccessfulStatus = (status) => {
+  switch (status) {
+    case 'pending':
+    case 'queued':
+    case 'processed':
+    case 'delivered':
+    case 'opened':
+    case 'clicked':
+      return true;
+    case 'suppressed':
+    case 'soft_bounced':
+    case 'hard_bounced':
+    case 'spam_complaint':
+    case 'failed':
+    case 'blocked':
+    case 'policy_rejected':
+    case 'unsubscribed':
+      return false;
+  }
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+module.exports = { LettermintTransport };
diff --git a/src/lettermint/message-converter.js b/src/lettermint/message-converter.js
new file mode 100644
index 0000000..5991b55
--- /dev/null
+++ b/src/lettermint/message-converter.js
@@ -0,0 +1,212 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createCalendarAttachment } = require('../core/calendar.js');
+const { combineSignals } = require('../core/abort-signal.js');
+const { readAttachmentContent } = require('../core/attachment.js');
+const { resolveThreadingHeaders } = require('../core/message-id.js');
+
+const STANDARD_HEADERS = new Set([
+  'from',
+  'to',
+  'cc',
+  'bcc',
+  'reply-to',
+  'subject',
+  'date',
+  'message-id',
+  'content-type',
+  'content-transfer-encoding',
+  'mime-version',
+  'x-priority',
+]);
+
+/**
+ * Converts an Upyo message to Lettermint API JSON format.
+ *
+ * @param message The Upyo message to convert.
+ * @param config The resolved Lettermint configuration.
+ * @returns JSON object ready for Lettermint API submission.
+ * @throws {TypeError} If the message carries an invalid message identifier.
+ * @throws {RangeError} If the message has more than one tag.
+ */
+const convertMessage = async (message, config, signal) => {
+  if (message.tags.length > 1) {
+    throw new RangeError('Lettermint supports at most one tag per message.');
+  }
+
+  // A transport that cannot compose a `text/calendar` alternative carries the
+  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
+  // own files so that a client looking for the first calendar part finds it.
+  const attachments =
+    message.calendar == null
+      ? message.attachments
+      : [createCalendarAttachment(message.calendar), ...message.attachments];
+
+  const emailData = {
+    from: formatAddress(message.sender),
+    to: message.recipients.map(formatAddress),
+    subject: message.subject,
+  };
+
+  if (message.ccRecipients.length > 0) {
+    emailData.cc = message.ccRecipients.map(formatAddress);
+  }
+
+  if (message.bccRecipients.length > 0) {
+    emailData.bcc = message.bccRecipients.map(formatAddress);
+  }
+
+  if (message.replyRecipients.length > 0) {
+    emailData.reply_to = message.replyRecipients.map(formatAddress);
+  }
+
+  if ('html' in message.content) {
+    emailData.html = message.content.html;
+    if (message.content.text) {
+      emailData.text = message.content.text;
+    }
+  } else {
+    emailData.text = message.content.text;
+  }
+
+  if (config.route) {
+    emailData.route = config.route;
+  }
+
+  if (message.tags.length === 1) {
+    emailData.tag = message.tags[0];
+  } else if (config.tag !== undefined) {
+    emailData.tag = config.tag;
+  }
+
+  if (config.metadata != null && Object.keys(config.metadata).length > 0) {
+    emailData.metadata = { ...config.metadata };
+  }
+
+  const settings = convertSettings(config);
+  if (settings != null) {
+    emailData.settings = settings;
+  }
+
+  const headers = {};
+  if (message.priority !== 'normal') {
+    const priorityMap = {
+      high: '1',
+      normal: '3',
+      low: '5',
+    };
+    headers['X-Priority'] = priorityMap[message.priority];
+  }
+
+  // Reply threading comes from the typed fields when the message defines them,
+  // and from a custom header otherwise.  A field the message owns but left
+  // empty writes nothing, which is how a caller drops an inherited header.
+  const threading = resolveThreadingHeaders(message);
+  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+
+  for (const [key, value] of message.headers.entries()) {
+    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
+      headers[key] = value;
+    }
+  }
+  for (const [name, value] of threading) {
+    if (value != null) headers[name] = value;
+  }
+
+  if (Object.keys(headers).length > 0) {
+    emailData.headers = headers;
+  }
+
+  if (attachments.length > 0) {
+    const cancellation = new AbortController();
+    const combined = combineSignals(cancellation.signal, signal);
+    try {
+      emailData.attachments = await Promise.all(
+        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
+      );
+    } finally {
+      cancellation.abort();
+      combined.cleanup();
+    }
+  }
+
+  return emailData;
+};
+
+const convertSettings = (config) => {
+  if (config.settings == null) return undefined;
+
+  const settings = {};
+
+  if (config.settings.trackOpens !== undefined) {
+    settings.track_opens = config.settings.trackOpens;
+  }
+
+  if (config.settings.trackClicks !== undefined) {
+    settings.track_clicks = config.settings.trackClicks;
+  }
+
+  return Object.keys(settings).length > 0 ? settings : undefined;
+};
+
+const formatAddress = (address) => {
+  if (address.name) {
+    const escapedName = address.name.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `"${escapedName}" <${address.address}>`;
+  }
+  return address.address;
+};
+
+const convertAttachment = async (attachment, signal) => {
+  const content = await readAttachmentContent(attachment.content, signal);
+  const converted = {
+    filename: attachment.filename,
+    content: uint8ArrayToBase64(content),
+    content_type: attachment.contentType,
+  };
+
+  if (attachment.inline && attachment.contentId) {
+    converted.content_id = attachment.contentId;
+  }
+
+  return converted;
+};
+
+const uint8ArrayToBase64 = (bytes) => {
+  const nativeToBase64 = getNativeToBase64(bytes);
+  if (nativeToBase64 != null) {
+    return nativeToBase64();
+  }
+
+  const chunkSize = 0x8000;
+  const chunks = [];
+
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + chunkSize)));
+  }
+
+  return btoa(chunks.join(''));
+};
+
+const getNativeToBase64 = (bytes) => {
+  const candidate = bytes;
+  const toBase64 = candidate.toBase64;
+  if (typeof toBase64 !== 'function') return undefined;
+  return () => toBase64.call(bytes);
+};
+
+const isStandardHeader = (headerName) => {
+  return STANDARD_HEADERS.has(headerName.toLowerCase());
+};
+
+/**
+ * Generates a random idempotency key for request deduplication.
+ *
+ * @returns A unique string suitable for use as an idempotency key.
+ */
+const generateIdempotencyKey = () => {
+  return globalThis.crypto.randomUUID();
+};
+
+module.exports = { convertMessage, generateIdempotencyKey };
diff --git a/tests/e2e/lettermint-transport.e2e.test.js b/tests/e2e/lettermint-transport.e2e.test.js
new file mode 100644
index 0000000..e3c973b
--- /dev/null
+++ b/tests/e2e/lettermint-transport.e2e.test.js
@@ -0,0 +1,115 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/lettermint-transport.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { LettermintTransport } = require('../../src/lettermint/lettermint-transport.js');
+const {
+  createTestMessage,
+  getTestConfig,
+  isE2eTestingEnabled,
+} = require('../helpers/lettermint/test-config.js');
+
+const describeE2E = isE2eTestingEnabled() ? describe : describe.skip;
+
+describeE2E('LettermintTransport E2E', { concurrency: false }, () => {
+  const waitForRateLimit = async () => {
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  };
+
+  const assertSuccessfulReceipt = (receipt) => {
+    assert.equal(
+      receipt.successful,
+      true,
+      receipt.successful ? undefined : receipt.errorMessages.join(', '),
+    );
+    assert.ok(receipt.messageId);
+  };
+
+  it('sends a simple text email', async () => {
+    await waitForRateLimit();
+
+    const transport = new LettermintTransport(getTestConfig().lettermint);
+    const receipt = await transport.send(
+      createTestMessage({
+        subject: '[E2E] Lettermint text email',
+        content: { text: 'This is a Lettermint E2E test email.' },
+      }),
+    );
+
+    assertSuccessfulReceipt(receipt);
+    console.log(`Sent Lettermint text email with ID: ${receipt.messageId}`);
+  });
+
+  it('sends an HTML email', async () => {
+    await waitForRateLimit();
+
+    const transport = new LettermintTransport(getTestConfig().lettermint);
+    const receipt = await transport.send(
+      createTestMessage({
+        subject: '[E2E] Lettermint HTML email',
+        content: {
+          html: '<h1>Hello from Upyo</h1><p>This is a Lettermint test.</p>',
+          text: 'Hello from Upyo\n\nThis is a Lettermint test.',
+        },
+      }),
+    );
+
+    assertSuccessfulReceipt(receipt);
+    console.log(`Sent Lettermint HTML email with ID: ${receipt.messageId}`);
+  });
+
+  it('sends an email with an attachment', async () => {
+    await waitForRateLimit();
+
+    const transport = new LettermintTransport(getTestConfig().lettermint);
+    const receipt = await transport.send(
+      createTestMessage({
+        subject: '[E2E] Lettermint attachment email',
+        content: { text: 'This Lettermint E2E test email has an attachment.' },
+        attachments: [
+          {
+            filename: 'lettermint-e2e.txt',
+            contentType: 'text/plain',
+            content: new TextEncoder().encode(
+              'This attachment was sent by the Upyo Lettermint E2E test.',
+            ),
+            inline: false,
+            contentId: '',
+          },
+        ],
+      }),
+    );
+
+    assertSuccessfulReceipt(receipt);
+    console.log(`Sent Lettermint attachment email with ID: ${receipt.messageId}`);
+  });
+
+  it('sends multiple emails with sendMany', async () => {
+    await waitForRateLimit();
+
+    const transport = new LettermintTransport(getTestConfig().lettermint);
+    const receipts = [];
+
+    for await (const receipt of transport.sendMany([
+      createTestMessage({
+        subject: '[E2E] Lettermint batch email 1',
+      }),
+      createTestMessage({
+        subject: '[E2E] Lettermint batch email 2',
+      }),
+    ])) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 2);
+    for (const receipt of receipts) {
+      assertSuccessfulReceipt(receipt);
+    }
+    console.log(
+      `Sent Lettermint batch emails with IDs: ${receipts
+        .map((receipt) => (receipt.successful ? receipt.messageId : 'failed'))
+        .join(', ')}`,
+    );
+  });
+});
diff --git a/tests/helpers/lettermint/test-config.js b/tests/helpers/lettermint/test-config.js
new file mode 100644
index 0000000..0e534a0
--- /dev/null
+++ b/tests/helpers/lettermint/test-config.js
@@ -0,0 +1,70 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const process = require('node:process');
+
+/**
+ * Checks whether Lettermint E2E testing is configured.
+ *
+ * @returns `true` if all required environment variables are present.
+ */
+const isE2eTestingEnabled = () => {
+  return !!(
+    process.env.LETTERMINT_API_TOKEN &&
+    process.env.LETTERMINT_FROM &&
+    process.env.LETTERMINT_TO
+  );
+};
+
+/**
+ * Reads Lettermint E2E test configuration from environment variables.
+ *
+ * @returns Lettermint E2E test configuration.
+ * @throws {Error} If required environment variables are missing.
+ */
+const getTestConfig = () => {
+  const apiToken = process.env.LETTERMINT_API_TOKEN;
+  const from = process.env.LETTERMINT_FROM;
+  const to = process.env.LETTERMINT_TO;
+
+  if (!apiToken || !from || !to) {
+    throw new Error('LETTERMINT_API_TOKEN, LETTERMINT_FROM, and LETTERMINT_TO are required.');
+  }
+
+  return {
+    lettermint: {
+      apiToken,
+      ...(process.env.LETTERMINT_BASE_URL && {
+        baseUrl: process.env.LETTERMINT_BASE_URL,
+      }),
+    },
+    from,
+    to,
+  };
+};
+
+/**
+ * Creates a test message for Lettermint E2E tests.
+ *
+ * @param overrides Message fields to override.
+ * @returns A test message.
+ */
+const createTestMessage = (overrides = {}) => {
+  const config = getTestConfig();
+  return {
+    sender: { address: config.from, name: 'Upyo Test' },
+    recipients: [{ address: config.to }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: '[E2E] Lettermint test',
+    content: { text: 'This is a test email sent through Lettermint.' },
+    attachments: [],
+    priority: 'normal',
+    tags: ['upyo-test'],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+module.exports = { isE2eTestingEnabled, getTestConfig, createTestMessage };
diff --git a/tests/types/lettermint.test-d.ts b/tests/types/lettermint.test-d.ts
new file mode 100644
index 0000000..bd1587f
--- /dev/null
+++ b/tests/types/lettermint.test-d.ts
@@ -0,0 +1,28 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import {
+  LettermintApiError,
+  LettermintTimeoutError,
+  LettermintTransport,
+  createLettermintConfig,
+  type LettermintConfig,
+  type ResolvedLettermintConfig,
+} from '../../src/lettermint/index.js';
+
+const transport = new LettermintTransport({ apiToken: 'token', route: 'outgoing' });
+expectAssignable<Transport<'lettermint'>>(transport);
+expectType<ResolvedLettermintConfig>(createLettermintConfig({ apiToken: 'token' }));
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'lettermint'>>>(transport.send(message));
+expectType<AsyncIterable<Receipt<'lettermint'>>>(transport.sendMany([message]));
+
+expectAssignable<LettermintConfig>({ apiToken: 'token', tag: null, metadata: { app: 'x' } });
+expectAssignable<Error>(new LettermintApiError('Unauthorized', 401));
+expectAssignable<Error>(new LettermintTimeoutError(1000));
+expectError(new LettermintTransport({ route: 'outgoing' }));
diff --git a/tests/unit/lettermint-config.test.js b/tests/unit/lettermint-config.test.js
new file mode 100644
index 0000000..036686c
--- /dev/null
+++ b/tests/unit/lettermint-config.test.js
@@ -0,0 +1,78 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { createLettermintConfig } = require('../../src/lettermint/config.js');
+
+describe('createLettermintConfig', () => {
+  it('applies default values to optional fields', () => {
+    const config = {
+      apiToken: 'test-token',
+    };
+
+    const resolved = createLettermintConfig(config);
+
+    assert.equal(resolved.apiToken, 'test-token');
+    assert.equal(resolved.baseUrl, 'https://api.lettermint.co');
+    assert.equal(resolved.timeout, 30000);
+    assert.equal(resolved.retries, 3);
+    assert.deepEqual(resolved.headers, {});
+    assert.equal(resolved.route, undefined);
+    assert.equal(resolved.tag, undefined);
+    assert.equal(resolved.metadata, undefined);
+    assert.equal(resolved.settings, undefined);
+  });
+
+  it('preserves provided optional values', () => {
+    const config = {
+      apiToken: 'test-token',
+      baseUrl: 'https://lettermint.example.com',
+      timeout: 60000,
+      retries: 5,
+      headers: { 'X-Custom': 'value' },
+      route: 'transactional',
+      tag: 'welcome',
+      metadata: { campaign_id: 'welcome-2026' },
+      settings: {
+        trackOpens: false,
+        trackClicks: true,
+      },
+    };
+
+    const resolved = createLettermintConfig(config);
+
+    assert.equal(resolved.apiToken, 'test-token');
+    assert.equal(resolved.baseUrl, 'https://lettermint.example.com');
+    assert.equal(resolved.timeout, 60000);
+    assert.equal(resolved.retries, 5);
+    assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
+    assert.equal(resolved.route, 'transactional');
+    assert.equal(resolved.tag, 'welcome');
+    assert.deepEqual(resolved.metadata, { campaign_id: 'welcome-2026' });
+    assert.deepEqual(resolved.settings, {
+      trackOpens: false,
+      trackClicks: true,
+    });
+  });
+
+  it('preserves zero timeout and retry values', () => {
+    const resolved = createLettermintConfig({
+      apiToken: 'test-token',
+      timeout: 0,
+      retries: 0,
+    });
+
+    assert.equal(resolved.timeout, 0);
+    assert.equal(resolved.retries, 0);
+  });
+
+  it('normalizes trailing slashes from the base URL', () => {
+    const resolved = createLettermintConfig({
+      apiToken: 'test-token',
+      baseUrl: 'https://lettermint.example.com///',
+    });
+
+    assert.equal(resolved.baseUrl, 'https://lettermint.example.com');
+  });
+});
diff --git a/tests/unit/lettermint-message-converter.test.js b/tests/unit/lettermint-message-converter.test.js
new file mode 100644
index 0000000..8f125d6
--- /dev/null
+++ b/tests/unit/lettermint-message-converter.test.js
@@ -0,0 +1,400 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/message-converter.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { createLettermintConfig } = require('../../src/lettermint/config.js');
+const {
+  convertMessage,
+  generateIdempotencyKey,
+} = require('../../src/lettermint/message-converter.js');
+
+const baseConfig = createLettermintConfig({ apiToken: 'test-token' });
+
+const createBaseMessage = (overrides = {}) => {
+  return {
+    sender: { address: 'sender@example.com' },
+    recipients: [{ address: 'recipient@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test content' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+describe('convertMessage', () => {
+  it('converts a basic text message', async () => {
+    const result = await convertMessage(createBaseMessage(), baseConfig);
+
+    assert.equal(result.from, 'sender@example.com');
+    assert.deepEqual(result.to, ['recipient@example.com']);
+    assert.equal(result.subject, 'Test Subject');
+    assert.equal(result.text, 'Test content');
+    assert.equal(result.html, undefined);
+  });
+
+  it('formats addresses with names', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        sender: { address: 'sender@example.com', name: 'Sender Name' },
+        recipients: [
+          {
+            address: 'recipient@example.com',
+            name: 'Recipient "Name"',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.equal(result.from, '"Sender Name" <sender@example.com>');
+    assert.deepEqual(result.to, ['"Recipient \\"Name\\"" <recipient@example.com>']);
+  });
+
+  it('escapes backslashes in address display names', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        sender: {
+          address: 'sender@example.com',
+          name: String.raw`Sender \ "Name"`,
+        },
+      }),
+      baseConfig,
+    );
+
+    assert.equal(result.from, String.raw`"Sender \\ \"Name\"" <sender@example.com>`);
+  });
+
+  it('converts HTML content with text alternative', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        content: { html: '<h1>Hello</h1>', text: 'Hello' },
+      }),
+      baseConfig,
+    );
+
+    assert.equal(result.html, '<h1>Hello</h1>');
+    assert.equal(result.text, 'Hello');
+  });
+
+  it('handles CC, BCC, and reply-to recipients', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        ccRecipients: [{ address: 'cc@example.com' }],
+        bccRecipients: [{ address: 'bcc@example.com' }],
+        replyRecipients: [{ address: 'reply@example.com' }],
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.cc, ['cc@example.com']);
+    assert.deepEqual(result.bcc, ['bcc@example.com']);
+    assert.deepEqual(result.reply_to, ['reply@example.com']);
+  });
+
+  it('applies Lettermint defaults from config', async () => {
+    const config = createLettermintConfig({
+      apiToken: 'test-token',
+      route: 'transactional',
+      tag: 'welcome',
+      metadata: {
+        user_id: '123',
+        campaign_id: 'welcome-2026',
+      },
+      settings: {
+        trackOpens: false,
+        trackClicks: true,
+      },
+    });
+
+    const result = await convertMessage(createBaseMessage(), config);
+
+    assert.equal(result.route, 'transactional');
+    assert.equal(result.tag, 'welcome');
+    assert.deepEqual(result.metadata, {
+      user_id: '123',
+      campaign_id: 'welcome-2026',
+    });
+    assert.deepEqual(result.settings, {
+      track_opens: false,
+      track_clicks: true,
+    });
+  });
+
+  it('lets a single message tag override config tag', async () => {
+    const config = createLettermintConfig({
+      apiToken: 'test-token',
+      tag: 'default-tag',
+    });
+
+    const result = await convertMessage(createBaseMessage({ tags: ['message-tag'] }), config);
+
+    assert.equal(result.tag, 'message-tag');
+  });
+
+  it('rejects messages with multiple tags', async () => {
+    await assert.rejects(
+      () => convertMessage(createBaseMessage({ tags: ['one', 'two'] }), baseConfig),
+      {
+        name: 'RangeError',
+        message: 'Lettermint supports at most one tag per message.',
+      },
+    );
+  });
+
+  it('converts priority and custom headers', async () => {
+    const headers = new Headers();
+    headers.set('X-Custom-Header', 'custom-value');
+    headers.set('Subject', 'ignored');
+
+    const result = await convertMessage(
+      createBaseMessage({
+        priority: 'high',
+        headers,
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.headers, {
+      'X-Priority': '1',
+      'x-custom-header': 'custom-value',
+    });
+  });
+
+  it('converts attachments to base64 with inline content IDs', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            filename: 'hello.txt',
+            content: new TextEncoder().encode('hello'),
+            contentType: 'text/plain',
+            inline: false,
+            contentId: '',
+          },
+          {
+            filename: 'logo.png',
+            content: new Uint8Array([1, 2, 3]),
+            contentType: 'image/png',
+            inline: true,
+            contentId: 'logo',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.deepEqual(result.attachments, [
+      {
+        filename: 'hello.txt',
+        content: 'aGVsbG8=',
+        content_type: 'text/plain',
+      },
+      {
+        filename: 'logo.png',
+        content: 'AQID',
+        content_type: 'image/png',
+        content_id: 'logo',
+      },
+    ]);
+  });
+
+  it('preserves attachment content types with parameters', async () => {
+    const result = await convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            filename: 'invite.ics',
+            content: new TextEncoder().encode('BEGIN:VCALENDAR'),
+            contentType: 'text/calendar; charset=utf-8; method=REQUEST',
+            inline: false,
+            contentId: '',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.equal(
+      result.attachments?.[0]?.content_type,
+      'text/calendar; charset=utf-8; method=REQUEST',
+    );
+  });
+
+  it('uses native Uint8Array base64 conversion when available', async () => {
+    const content = new Uint8Array([1, 2, 3]);
+    Object.defineProperty(content, 'toBase64', {
+      configurable: true,
+      value() {
+        assert.deepEqual([...this], [1, 2, 3]);
+        return 'native-base64';
+      },
+    });
+
+    const result = await convertMessage(
+      createBaseMessage({
+        attachments: [
+          {
+            filename: 'native.bin',
+            content,
+            contentType: 'application/octet-stream',
+            inline: false,
+            contentId: '',
+          },
+        ],
+      }),
+      baseConfig,
+    );
+
+    assert.equal(result.attachments?.[0]?.content, 'native-base64');
+  });
+});
+
+describe('generateIdempotencyKey', () => {
+  it('generates non-empty keys', () => {
+    const key = generateIdempotencyKey();
+    assert.match(key, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+  });
+});
+
+const threadingConfig = createLettermintConfig({ apiToken: 'test-token' });
+
+const headerOf = (headers, name) =>
+  Object.entries(headers)
+    .filter(([key]) => key.toLowerCase() === name.toLowerCase())
+    .map(([, value]) => value);
+
+describe('convertMessage() reply threading', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Re: Your request',
+    content: { text: 'Thanks for getting in touch.' },
+  };
+
+  it('writes the typed threading fields', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: '122@example.com',
+      references: ['120@example.com', '121@example.com'],
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<122@example.com>']);
+    assert.deepEqual(headerOf(result, 'References'), ['<120@example.com> <121@example.com>']);
+  });
+
+  it('prefers a typed field over a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: ['typed@example.com'],
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<typed@example.com>']);
+  });
+
+  it('lets an empty list suppress a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: [],
+      references: [],
+      headers: {
+        'In-Reply-To': '<custom@example.com>',
+        References: '<custom@example.com>',
+      },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), []);
+    assert.deepEqual(headerOf(result, 'References'), []);
+  });
+
+  it('lets a custom header through when the field is unset', async () => {
+    const message = createMessage({
+      ...base,
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<custom@example.com>']);
+  });
+});
+
+const CALENDAR_ICS =
+  [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'SUMMARY:Lunch',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+/** The invitation content as the providers below carry it: Base64. */
+const CALENDAR_BASE64 = btoa(CALENDAR_ICS);
+
+const AGENDA_ATTACHMENT = {
+  inline: false,
+  filename: 'agenda.txt',
+  content: new TextEncoder().encode('agenda'),
+  contentType: 'text/plain',
+  contentId: '',
+};
+
+describe('convertMessage() calendar', () => {
+  const invitation = (overrides = {}) =>
+    createBaseMessage({
+      calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+      ...overrides,
+    });
+
+  it('should carry the calendar as an invite.ics attachment', async () => {
+    const result = await convertMessage(invitation(), baseConfig);
+
+    assert.equal(result.attachments?.length, 1);
+    assert.equal(result.attachments?.[0].filename, 'invite.ics');
+    assert.equal(
+      result.attachments?.[0].content_type,
+      'text/calendar; charset=utf-8; method=REQUEST',
+    );
+    assert.equal(result.attachments?.[0].content, CALENDAR_BASE64);
+    // An empty content ID keeps the part from being treated as inline.
+    assert.equal(result.attachments?.[0].content_id, undefined);
+  });
+
+  it('should place the invitation ahead of the other attachments', async () => {
+    const result = await convertMessage(
+      invitation({ attachments: [AGENDA_ATTACHMENT] }),
+      baseConfig,
+    );
+
+    assert.deepEqual(
+      result.attachments?.map((attachment) => attachment.filename),
+      ['invite.ics', 'agenda.txt'],
+    );
+  });
+
+  it('should reject calendar content that never passed createMessage()', async () => {
+    await assert.rejects(
+      () =>
+        convertMessage(
+          createBaseMessage({
+            calendar: { method: 'REQUEST', content: 'not a calendar' },
+          }),
+          baseConfig,
+        ),
+      { name: 'TypeError' },
+    );
+  });
+});
diff --git a/tests/unit/lettermint-transport.test.js b/tests/unit/lettermint-transport.test.js
new file mode 100644
index 0000000..41d869c
--- /dev/null
+++ b/tests/unit/lettermint-transport.test.js
@@ -0,0 +1,941 @@
+// Ported from upyo v0.7.0 (packages/lettermint/src/lettermint-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { LettermintTransport } = require('../../src/lettermint/lettermint-transport.js');
+
+it('rejects a singleton batch canceled during attachment acquisition', async () => {
+  const transport = new LettermintTransport({ apiToken: 'test' });
+  const controller = new AbortController();
+  const reason = new TypeError('Canceled.');
+  const message = createMessage({
+    attachments: [
+      {
+        inline: false,
+        filename: 'a',
+        contentType: 'application/octet-stream',
+        contentId: 'a',
+        content: () => {
+          controller.abort(reason);
+          return new Promise(() => {});
+        },
+      },
+    ],
+  });
+  await assert.rejects(
+    async () => {
+      // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+      for await (const _receipt of transport.sendMany([message], {
+        signal: controller.signal,
+      })) {
+        /* Drain the batch. */
+      }
+    },
+    (error) => error === reason,
+  );
+});
+
+function createMessage(overrides = {}) {
+  return {
+    sender: { address: 'sender@example.com' },
+    recipients: [{ address: 'recipient@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test content' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  };
+}
+
+let fetchMockChain = Promise.resolve();
+
+const withMockedFetch = async (fetchMock, callback) => {
+  const previous = fetchMockChain;
+  let release = () => {};
+  fetchMockChain = new Promise((resolve) => {
+    release = resolve;
+  });
+  await previous;
+
+  const originalFetch = globalThis.fetch;
+  try {
+    globalThis.fetch = fetchMock;
+    return await callback();
+  } finally {
+    globalThis.fetch = originalFetch;
+    release();
+  }
+};
+
+describe('LettermintTransport - config', { concurrency: false }, () => {
+  it('creates a transport with minimal config', () => {
+    const transport = new LettermintTransport({
+      apiToken: 'test-token',
+    });
+
+    assert.equal(transport.config.apiToken, 'test-token');
+    assert.equal(transport.config.baseUrl, 'https://api.lettermint.co');
+    assert.equal(transport.config.timeout, 30000);
+    assert.equal(transport.config.retries, 3);
+  });
+
+  it('creates a transport with custom config', () => {
+    const transport = new LettermintTransport({
+      apiToken: 'test-token',
+      baseUrl: 'https://lettermint.example.com',
+      timeout: 10000,
+      retries: 1,
+      route: 'transactional',
+      tag: 'welcome',
+    });
+
+    assert.equal(transport.config.baseUrl, 'https://lettermint.example.com');
+    assert.equal(transport.config.timeout, 10000);
+    assert.equal(transport.config.retries, 1);
+    assert.equal(transport.config.route, 'transactional');
+    assert.equal(transport.config.tag, 'welcome');
+  });
+});
+
+describe('LettermintTransport - send', { concurrency: false }, () => {
+  it('sends a message successfully', async () => {
+    let capturedUrl = '';
+    let capturedBody;
+    let capturedHeaders = new Headers();
+
+    await withMockedFetch(
+      (url, init) => {
+        capturedUrl = String(url);
+        capturedBody = JSON.parse(String(init?.body));
+        capturedHeaders = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(JSON.stringify({ message_id: 'msg_123', status: 'pending' }), {
+            status: 202,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          baseUrl: 'https://api.example.com',
+        });
+        const receipt = await transport.send(
+          createMessage({
+            idempotencyKey: 'idem-123',
+          }),
+        );
+
+        assert.equal(capturedUrl, 'https://api.example.com/v1/send');
+        assert.equal(capturedHeaders.get('x-lettermint-token'), 'test-token');
+        assert.equal(capturedHeaders.get('Idempotency-Key'), 'idem-123');
+        assert.deepEqual(capturedBody, {
+          from: 'sender@example.com',
+          to: ['recipient@example.com'],
+          subject: 'Test Subject',
+          text: 'Test content',
+        });
+        assert.equal(receipt.successful, true);
+        if (receipt.successful) {
+          assert.equal(receipt.messageId, 'msg_123');
+        }
+      },
+    );
+  });
+
+  it('returns failure receipts for API errors', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(JSON.stringify({ message: 'Invalid API token' }), {
+            status: 401,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        ),
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'bad-token',
+          retries: 0,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(receipt.successful, false);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, ['Invalid API token']);
+          assert.equal(receipt.provider, 'lettermint');
+          assert.equal(receipt.retryable, false);
+          assert.equal(receipt.errors?.[0]?.category, 'auth');
+          assert.equal(receipt.errors?.[0]?.statusCode, 401);
+        }
+      },
+    );
+  });
+
+  it('returns failure receipts for non-delivery statuses', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify({
+              message_id: 'msg_rejected',
+              status: 'policy_rejected',
+            }),
+            { status: 202, headers: { 'Content-Type': 'application/json' } },
+          ),
+        ),
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(receipt.successful, false);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, [
+            'Lettermint reported message status "policy_rejected".',
+          ]);
+          assert.equal(receipt.provider, 'lettermint');
+          assert.equal(receipt.retryable, false);
+          assert.equal(receipt.errors?.[0]?.category, 'rejected');
+          assert.equal(receipt.errors?.[0]?.code, 'lettermint.policy_rejected');
+        }
+      },
+    );
+  });
+
+  it('propagates AbortError for aborted sends', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const transport = new LettermintTransport({ apiToken: 'test-token' });
+
+    await assert.rejects(() => transport.send(createMessage(), { signal: controller.signal }), {
+      name: 'AbortError',
+    });
+  });
+
+  it('propagates custom caller abort reasons during sends', async () => {
+    const controller = new AbortController();
+    const reason = new Error('Stop Lettermint send.');
+
+    await withMockedFetch(
+      (_url, init) =>
+        new Promise((_resolve, reject) => {
+          init?.signal?.addEventListener(
+            'abort',
+            () => {
+              reject(init.signal?.reason);
+            },
+            { once: true },
+          );
+          setTimeout(() => controller.abort(reason), 0);
+        }),
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          retries: 0,
+        });
+
+        await assert.rejects(
+          () => transport.send(createMessage(), { signal: controller.signal }),
+          (error) => error === reason,
+        );
+      },
+    );
+  });
+
+  it('generates an idempotency key when not provided', async () => {
+    let capturedHeaders = new Headers();
+
+    await withMockedFetch(
+      (_url, init) => {
+        capturedHeaders = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(JSON.stringify({ message_id: 'msg_123', status: 'pending' }), {
+            status: 202,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({ apiToken: 'test-token' });
+        await transport.send(createMessage());
+
+        const idempotencyKey = capturedHeaders.get('Idempotency-Key');
+        assert.ok(idempotencyKey);
+        assert.ok(idempotencyKey.length > 10);
+      },
+    );
+  });
+
+  it('generates an idempotency key when the provided key is empty', async () => {
+    let capturedHeaders = new Headers();
+
+    await withMockedFetch(
+      (_url, init) => {
+        capturedHeaders = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(JSON.stringify({ message_id: 'msg_123', status: 'pending' }), {
+            status: 202,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({ apiToken: 'test-token' });
+        await transport.send(createMessage({ idempotencyKey: '' }));
+
+        const idempotencyKey = capturedHeaders.get('Idempotency-Key');
+        assert.ok(idempotencyKey);
+        assert.notEqual(idempotencyKey, '');
+      },
+    );
+  });
+
+  it('retries request timeouts from the transport config', async () => {
+    let calls = 0;
+
+    await withMockedFetch(
+      (_url, init) => {
+        calls++;
+        if (calls === 1) {
+          return new Promise((_resolve, reject) => {
+            init?.signal?.addEventListener(
+              'abort',
+              () => {
+                reject(new DOMException('The operation was aborted.', 'AbortError'));
+              },
+              { once: true },
+            );
+          });
+        }
+        return Promise.resolve(
+          new Response(JSON.stringify({ message_id: 'msg_retry', status: 'pending' }), {
+            status: 202,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          timeout: 1,
+          retries: 1,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(calls, 2);
+        assert.equal(receipt.successful, true);
+        if (receipt.successful) {
+          assert.equal(receipt.messageId, 'msg_retry');
+        }
+      },
+    );
+  });
+
+  it('retries 429 rate limit responses', async () => {
+    let calls = 0;
+
+    await withMockedFetch(
+      () => {
+        calls++;
+        if (calls === 1) {
+          return Promise.resolve(
+            new Response(JSON.stringify({ message: 'Too many requests' }), {
+              status: 429,
+              headers: { 'Content-Type': 'application/json' },
+            }),
+          );
+        }
+        return Promise.resolve(
+          new Response(JSON.stringify({ message_id: 'msg_rate_limit', status: 'pending' }), {
+            status: 202,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          retries: 1,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(calls, 2);
+        assert.equal(receipt.successful, true);
+        if (receipt.successful) {
+          assert.equal(receipt.messageId, 'msg_rate_limit');
+        }
+      },
+    );
+  });
+
+  it('retries 408 timeout responses', async () => {
+    let calls = 0;
+
+    await withMockedFetch(
+      () => {
+        calls++;
+        if (calls === 1) {
+          return Promise.resolve(
+            new Response(JSON.stringify({ message: 'Request timeout' }), {
+              status: 408,
+              headers: { 'Content-Type': 'application/json' },
+            }),
+          );
+        }
+        return Promise.resolve(
+          new Response(JSON.stringify({ message_id: 'msg_timeout', status: 'pending' }), {
+            status: 202,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          retries: 1,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(calls, 2);
+        assert.equal(receipt.successful, true);
+        if (receipt.successful) {
+          assert.equal(receipt.messageId, 'msg_timeout');
+        }
+      },
+    );
+  });
+
+  it('does not retry redirection responses', async () => {
+    let calls = 0;
+
+    await withMockedFetch(
+      () => {
+        calls++;
+        return Promise.resolve(
+          new Response('', {
+            status: 302,
+            headers: { Location: 'https://api.example.com/other' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          retries: 1,
+        });
+        const receipt = await transport.send(createMessage());
+
+        assert.equal(calls, 1);
+        assert.equal(receipt.successful, false);
+        if (!receipt.successful) {
+          assert.deepEqual(receipt.errorMessages, ['HTTP 302']);
+        }
+      },
+    );
+  });
+
+  it('removes abort listeners after retry backoff completes', async () => {
+    let calls = 0;
+    let addedAbortListeners = 0;
+    let removedAbortListeners = 0;
+    const controller = new AbortController();
+    const addEventListener = controller.signal.addEventListener.bind(controller.signal);
+    const removeEventListener = controller.signal.removeEventListener.bind(controller.signal);
+
+    Object.defineProperty(controller.signal, 'addEventListener', {
+      value: (type, listener, options) => {
+        if (type === 'abort') addedAbortListeners++;
+        addEventListener(type, listener, options);
+      },
+    });
+    Object.defineProperty(controller.signal, 'removeEventListener', {
+      value: (type, listener, options) => {
+        if (type === 'abort') removedAbortListeners++;
+        removeEventListener(type, listener, options);
+      },
+    });
+
+    await withMockedFetch(
+      () => {
+        calls++;
+        if (calls === 1) {
+          return Promise.resolve(
+            new Response(JSON.stringify({ message: 'Too many requests' }), {
+              status: 429,
+              headers: { 'Content-Type': 'application/json' },
+            }),
+          );
+        }
+        return Promise.resolve(
+          new Response(JSON.stringify({ message_id: 'msg_rate_limit', status: 'pending' }), {
+            status: 202,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          retries: 1,
+        });
+        const receipt = await transport.send(createMessage(), { signal: controller.signal });
+
+        assert.equal(receipt.successful, true);
+        assert.ok(addedAbortListeners > 0);
+        assert.equal(removedAbortListeners, addedAbortListeners);
+      },
+    );
+  });
+
+  // Upstream's "falls back when AbortSignal.any is unavailable" is not ported: Node 22 always
+  // has AbortSignal.any, and the core keeps no fallback without it.
+});
+
+describe('LettermintTransport - sendMany', { concurrency: false }, () => {
+  it('uses the batch API for multiple messages', async () => {
+    let capturedUrl = '';
+    let capturedBody;
+    let capturedHeaders = new Headers();
+
+    await withMockedFetch(
+      (url, init) => {
+        capturedUrl = String(url);
+        capturedBody = JSON.parse(String(init?.body));
+        capturedHeaders = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(
+            JSON.stringify([
+              { message_id: 'msg_1', status: 'pending' },
+              { message_id: 'msg_2', status: 'queued' },
+            ]),
+            { status: 202, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          baseUrl: 'https://api.example.com',
+        });
+        const messages = [
+          createMessage({
+            recipients: [{ address: 'one@example.com' }],
+          }),
+          createMessage({
+            recipients: [{ address: 'two@example.com' }],
+          }),
+        ];
+
+        const receipts = [];
+        for await (const receipt of transport.sendMany(messages)) {
+          receipts.push(receipt);
+        }
+
+        assert.equal(capturedUrl, 'https://api.example.com/v1/send/batch');
+        assert.ok(capturedHeaders.get('Idempotency-Key'));
+        assert.deepEqual(capturedBody, [
+          {
+            from: 'sender@example.com',
+            to: ['one@example.com'],
+            subject: 'Test Subject',
+            text: 'Test content',
+          },
+          {
+            from: 'sender@example.com',
+            to: ['two@example.com'],
+            subject: 'Test Subject',
+            text: 'Test content',
+          },
+        ]);
+        assert.equal(receipts.length, 2);
+        assert.equal(receipts[0].successful, true);
+        assert.equal(receipts[1].successful, true);
+        if (receipts[0].successful && receipts[1].successful) {
+          assert.equal(receipts[0].messageId, 'msg_1');
+          assert.equal(receipts[1].messageId, 'msg_2');
+        }
+      },
+    );
+  });
+
+  it('uses per-message idempotency keys outside the batch API', async () => {
+    const capturedUrls = [];
+    const capturedHeaders = [];
+    const capturedBodies = [];
+
+    await withMockedFetch(
+      (url, init) => {
+        capturedUrls.push(String(url));
+        capturedHeaders.push(new Headers(init?.headers));
+        capturedBodies.push(JSON.parse(String(init?.body)));
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              message_id: `msg_${capturedUrls.length}`,
+              status: 'pending',
+            }),
+            { status: 202, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          baseUrl: 'https://api.example.com',
+        });
+        const receipts = [];
+        for await (const receipt of transport.sendMany([
+          createMessage({
+            recipients: [{ address: 'one@example.com' }],
+            idempotencyKey: 'key-1',
+          }),
+          createMessage({
+            recipients: [{ address: 'two@example.com' }],
+            idempotencyKey: 'key-2',
+          }),
+        ])) {
+          receipts.push(receipt);
+        }
+
+        assert.deepEqual(capturedUrls, [
+          'https://api.example.com/v1/send',
+          'https://api.example.com/v1/send',
+        ]);
+        assert.deepEqual(
+          capturedHeaders.map((headers) => headers.get('Idempotency-Key')),
+          ['key-1', 'key-2'],
+        );
+        assert.deepEqual(capturedBodies, [
+          {
+            from: 'sender@example.com',
+            to: ['one@example.com'],
+            subject: 'Test Subject',
+            text: 'Test content',
+          },
+          {
+            from: 'sender@example.com',
+            to: ['two@example.com'],
+            subject: 'Test Subject',
+            text: 'Test content',
+          },
+        ]);
+        assert.equal(receipts.length, 2);
+        assert.ok(receipts.every((receipt) => receipt.successful));
+      },
+    );
+  });
+
+  it('generates a batch idempotency key when the first key is empty', async () => {
+    let capturedHeaders = new Headers();
+
+    await withMockedFetch(
+      (_url, init) => {
+        capturedHeaders = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(
+            JSON.stringify([
+              { message_id: 'msg_1', status: 'pending' },
+              { message_id: 'msg_2', status: 'pending' },
+            ]),
+            { status: 202, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({ apiToken: 'test-token' });
+        const receipts = [];
+        for await (const receipt of transport.sendMany([
+          createMessage({ idempotencyKey: '' }),
+          createMessage(),
+        ])) {
+          receipts.push(receipt);
+        }
+
+        const idempotencyKey = capturedHeaders.get('Idempotency-Key');
+        assert.ok(idempotencyKey);
+        assert.notEqual(idempotencyKey, '');
+        assert.ok(receipts.every((receipt) => receipt.successful));
+      },
+    );
+  });
+
+  it('chunks batches over 500 messages', async () => {
+    const bodySizes = [];
+
+    await withMockedFetch(
+      (_url, init) => {
+        const body = JSON.parse(String(init?.body));
+        bodySizes.push(body.length);
+        return Promise.resolve(
+          new Response(
+            JSON.stringify(
+              body.map((_, index) => ({
+                message_id: `msg_${bodySizes.length}_${index}`,
+                status: 'pending',
+              })),
+            ),
+            { status: 202, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({ apiToken: 'test-token' });
+        const messages = Array.from({ length: 501 }, (_, index) =>
+          createMessage({
+            recipients: [{ address: `user${index}@example.com` }],
+          }),
+        );
+
+        const receipts = [];
+        for await (const receipt of transport.sendMany(messages)) {
+          receipts.push(receipt);
+        }
+
+        assert.deepEqual(bodySizes, [500, 1]);
+        assert.equal(receipts.length, 501);
+        assert.ok(receipts.every((receipt) => receipt.successful));
+      },
+    );
+  });
+
+  it('streams async batches as each chunk fills', async () => {
+    const bodySizes = [];
+    let generated = 0;
+
+    const messages = async function* () {
+      for (let index = 0; index < 501; index++) {
+        generated++;
+        yield createMessage({
+          recipients: [{ address: `user${index}@example.com` }],
+        });
+      }
+    };
+
+    await withMockedFetch(
+      (_url, init) => {
+        const body = JSON.parse(String(init?.body));
+        bodySizes.push(body.length);
+        return Promise.resolve(
+          new Response(
+            JSON.stringify(
+              body.map((_, index) => ({
+                message_id: `msg_${bodySizes.length}_${index}`,
+                status: 'pending',
+              })),
+            ),
+            { status: 202, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({ apiToken: 'test-token' });
+        const receipts = [];
+        for await (const receipt of transport.sendMany(messages())) {
+          receipts.push(receipt);
+          if (receipts.length === 500) break;
+        }
+
+        assert.deepEqual(bodySizes, [500]);
+        assert.equal(generated, 500);
+        assert.equal(receipts.length, 500);
+        assert.ok(receipts.every((receipt) => receipt.successful));
+      },
+    );
+  });
+
+  it('returns no receipts for empty input', async () => {
+    const transport = new LettermintTransport({ apiToken: 'test-token' });
+    const receipts = [];
+
+    for await (const receipt of transport.sendMany([])) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 0);
+  });
+
+  it('returns per-message failures for batch conversion errors', async () => {
+    let capturedBody;
+
+    await withMockedFetch(
+      (_url, init) => {
+        capturedBody = JSON.parse(String(init?.body));
+        return Promise.resolve(
+          new Response(
+            JSON.stringify([
+              { message_id: 'msg_1', status: 'pending' },
+              { message_id: 'msg_2', status: 'pending' },
+            ]),
+            { status: 202, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      },
+      async () => {
+        const transport = new LettermintTransport({ apiToken: 'test-token' });
+        const receipts = [];
+        for await (const receipt of transport.sendMany([
+          createMessage({
+            recipients: [{ address: 'one@example.com' }],
+          }),
+          createMessage({
+            recipients: [{ address: 'bad@example.com' }],
+            tags: ['one', 'two'],
+          }),
+          createMessage({
+            recipients: [{ address: 'two@example.com' }],
+          }),
+        ])) {
+          receipts.push(receipt);
+        }
+
+        assert.deepEqual(capturedBody, [
+          {
+            from: 'sender@example.com',
+            to: ['one@example.com'],
+            subject: 'Test Subject',
+            text: 'Test content',
+          },
+          {
+            from: 'sender@example.com',
+            to: ['two@example.com'],
+            subject: 'Test Subject',
+            text: 'Test content',
+          },
+        ]);
+        assert.equal(receipts.length, 3);
+        assert.equal(receipts[0].successful, true);
+        assert.equal(receipts[1].successful, false);
+        assert.equal(receipts[2].successful, true);
+        if (receipts[0].successful && receipts[2].successful) {
+          assert.equal(receipts[0].messageId, 'msg_1');
+          assert.equal(receipts[2].messageId, 'msg_2');
+        }
+        if (!receipts[1].successful) {
+          assert.deepEqual(receipts[1].errorMessages, [
+            'Lettermint supports at most one tag per message.',
+          ]);
+        }
+      },
+    );
+  });
+
+  it('returns per-message failures for batch non-delivery statuses', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify([
+              { message_id: 'msg_1', status: 'queued' },
+              { message_id: 'msg_2', status: 'suppressed' },
+              { message_id: 'msg_3', status: 'failed' },
+            ]),
+            { status: 202, headers: { 'Content-Type': 'application/json' } },
+          ),
+        ),
+      async () => {
+        const transport = new LettermintTransport({ apiToken: 'test-token' });
+        const receipts = [];
+        for await (const receipt of transport.sendMany([
+          createMessage({ recipients: [{ address: 'one@example.com' }] }),
+          createMessage({ recipients: [{ address: 'two@example.com' }] }),
+          createMessage({ recipients: [{ address: 'three@example.com' }] }),
+        ])) {
+          receipts.push(receipt);
+        }
+
+        assert.equal(receipts.length, 3);
+        assert.equal(receipts[0].successful, true);
+        assert.equal(receipts[1].successful, false);
+        assert.equal(receipts[2].successful, false);
+        if (receipts[0].successful) {
+          assert.equal(receipts[0].messageId, 'msg_1');
+        }
+        if (!receipts[1].successful && !receipts[2].successful) {
+          assert.deepEqual(receipts[1].errorMessages, [
+            'Lettermint reported message status "suppressed".',
+          ]);
+          assert.deepEqual(receipts[2].errorMessages, [
+            'Lettermint reported message status "failed".',
+          ]);
+        }
+      },
+    );
+  });
+
+  it('preserves local batch failures when the request fails', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(JSON.stringify({ message: 'Batch rejected' }), {
+            status: 422,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        ),
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          retries: 0,
+        });
+        const receipts = [];
+        for await (const receipt of transport.sendMany([
+          createMessage({ recipients: [{ address: 'one@example.com' }] }),
+          createMessage({
+            recipients: [{ address: 'bad@example.com' }],
+            tags: ['one', 'two'],
+          }),
+          createMessage({ recipients: [{ address: 'two@example.com' }] }),
+        ])) {
+          receipts.push(receipt);
+        }
+
+        assert.equal(receipts.length, 3);
+        assert.ok(receipts.every((receipt) => !receipt.successful));
+        if (!receipts[0].successful && !receipts[1].successful && !receipts[2].successful) {
+          assert.deepEqual(receipts[0].errorMessages, ['Batch rejected']);
+          assert.deepEqual(receipts[1].errorMessages, [
+            'Lettermint supports at most one tag per message.',
+          ]);
+          assert.deepEqual(receipts[2].errorMessages, ['Batch rejected']);
+        }
+      },
+    );
+  });
+
+  it('returns one failed receipt per message when a batch fails', async () => {
+    await withMockedFetch(
+      () =>
+        Promise.resolve(
+          new Response(JSON.stringify({ message: 'Batch rejected' }), {
+            status: 422,
+            headers: { 'Content-Type': 'application/json' },
+          }),
+        ),
+      async () => {
+        const transport = new LettermintTransport({
+          apiToken: 'test-token',
+          retries: 0,
+        });
+        const receipts = [];
+        for await (const receipt of transport.sendMany([createMessage(), createMessage()])) {
+          receipts.push(receipt);
+        }
+
+        assert.equal(receipts.length, 2);
+        assert.ok(receipts.every((receipt) => !receipt.successful));
+        for (const receipt of receipts) {
+          if (!receipt.successful) {
+            assert.deepEqual(receipt.errorMessages, ['Batch rejected']);
+          }
+        }
+      },
+    );
+  });
+});
diff --git a/tests/unit/lettermint.test.js b/tests/unit/lettermint.test.js
new file mode 100644
index 0000000..9d87789
--- /dev/null
+++ b/tests/unit/lettermint.test.js
@@ -0,0 +1,94 @@
+// Paths of the ported Lettermint transport (src/lettermint/) that upstream's
+// suites leave out, against a stubbed fetch.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { LettermintTransport } = require('../../src/lettermint/index.js');
+
+const message = (extra = {}) =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+    ...extra,
+  });
+const config = { apiToken: 'token', retries: 0 };
+const hang = (url, init) =>
+  new Promise((resolve, reject) => {
+    init.signal.addEventListener('abort', () => reject(init.signal.reason));
+  });
+
+test('Lettermint: custom headers are sent, and a 200 without JSON fails', async (t) => {
+  let headers;
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    headers = new Headers(init.headers);
+    return new Response('<html>', { status: 200 });
+  });
+  const receipt = await new LettermintTransport({
+    ...config,
+    headers: { 'X-Custom': 'yes' },
+  }).send(message());
+  assert.strictEqual(headers.get('x-custom'), 'yes');
+  assert.match(receipt.errorMessages[0], /^Invalid JSON response from Lettermint API: /);
+});
+
+test('Lettermint: an error body gives its error or its errors', async (t) => {
+  const cases = [
+    [{ error: 'Route not found' }, 'Route not found'],
+    [{ errors: { to: ['invalid'] } }, null],
+    [{ errors: [{ field: 'to' }] }, '[{"field":"to"}]'],
+  ];
+  for (const [body, expected] of cases) {
+    t.mock.restoreAll();
+    t.mock.method(globalThis, 'fetch', async () => Response.json(body, { status: 422 }));
+    const receipt = await new LettermintTransport(config).send(message());
+    assert.strictEqual(receipt.successful, false);
+    if (expected !== null) assert.deepStrictEqual(receipt.errorMessages, [expected]);
+  }
+});
+
+test('Lettermint: the timeout fails the send, and an abort stops a retry', async (t) => {
+  t.mock.method(globalThis, 'fetch', hang);
+  const slow = await new LettermintTransport({ ...config, timeout: 20 }).send(message());
+  assert.strictEqual(slow.errors[0].category, 'timeout');
+
+  t.mock.restoreAll();
+  t.mock.method(globalThis, 'fetch', async () => new Response('', { status: 503 }));
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), 30);
+  await assert.rejects(
+    new LettermintTransport({ ...config, retries: 1 }).send(message(), {
+      signal: controller.signal,
+    }),
+    { name: 'AbortError' },
+  );
+});
+
+test('Lettermint: a batch whose every message fails to convert sends nothing', async (t) => {
+  let calls = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    calls++;
+    return Response.json([]);
+  });
+  const broken = () => {
+    throw new Error('Cannot read attachment');
+  };
+  const attachments = [
+    {
+      inline: false,
+      filename: 'a.bin',
+      content: broken,
+      contentType: 'application/octet-stream',
+      contentId: '',
+    },
+  ];
+  const receipts = [];
+  for await (const receipt of new LettermintTransport(config).sendMany([
+    message({ attachments }),
+  ])) {
+    receipts.push(receipt);
+  }
+  assert.strictEqual(calls, 0);
+  assert.deepStrictEqual(receipts[0].errorMessages, ['Cannot read attachment']);
+});

From 068bd9236c77dd4e9d5bf7a5a4d1c2e026a2e6ef Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:23:05 +0300
Subject: [PATCH 013/158] feat(plunk): port the Plunk transport from upyo 0.7.0

./plunk exports PlunkTransport: the Plunk send API over fetch (hosted or
self-hosted through baseUrl), with attachments, retries with exponential
backoff for 5xx and network errors, and a request timeout. Its types are
PlunkConfig, ResolvedPlunkConfig, PlunkResponse and PlunkError.

The base64 fallback for runtimes without btoa is dropped (Node always has
it), like the core's fallbacks. Upstream's unit suites are ported, the e2e
suite goes to tests/e2e, and its test of a runtime without AbortSignal.any
is left out. tests/unit/plunk.test.js covers malformed response bodies, an
unreadable error body, the timeout, a retried 5xx and a dropped attachment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                   |   2 +-
 package.json                               |   4 +
 src/plunk/config.js                        |  26 ++
 src/plunk/http-client.js                   | 259 +++++++++++++
 src/plunk/index.d.ts                       | 258 +++++++++++++
 src/plunk/index.js                         |  13 +
 src/plunk/message-converter.js             | 174 +++++++++
 src/plunk/plunk-transport.js               | 235 ++++++++++++
 tests/e2e/plunk-transport.e2e.test.js      | 262 +++++++++++++
 tests/helpers/plunk/test-config.js         |  70 ++++
 tests/types/plunk.test-d.ts                |  26 ++
 tests/unit/plunk-config.test.js            |  98 +++++
 tests/unit/plunk-message-converter.test.js | 417 +++++++++++++++++++++
 tests/unit/plunk-transport.test.js         | 311 +++++++++++++++
 tests/unit/plunk.test.js                   | 103 +++++
 15 files changed, 2257 insertions(+), 1 deletion(-)
 create mode 100644 src/plunk/config.js
 create mode 100644 src/plunk/http-client.js
 create mode 100644 src/plunk/index.d.ts
 create mode 100644 src/plunk/index.js
 create mode 100644 src/plunk/message-converter.js
 create mode 100644 src/plunk/plunk-transport.js
 create mode 100644 tests/e2e/plunk-transport.e2e.test.js
 create mode 100644 tests/helpers/plunk/test-config.js
 create mode 100644 tests/types/plunk.test-d.ts
 create mode 100644 tests/unit/plunk-config.test.js
 create mode 100644 tests/unit/plunk-message-converter.test.js
 create mode 100644 tests/unit/plunk-transport.test.js
 create mode 100644 tests/unit/plunk.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c8d4baa..ea53103 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 1bd35fa..53b8b7b 100644
--- a/package.json
+++ b/package.json
@@ -60,6 +60,10 @@
       "types": "./src/lettermint/index.d.ts",
       "default": "./src/lettermint/index.js"
     },
+    "./plunk": {
+      "types": "./src/plunk/index.d.ts",
+      "default": "./src/plunk/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
diff --git a/src/plunk/config.js b/src/plunk/config.js
new file mode 100644
index 0000000..744ec96
--- /dev/null
+++ b/src/plunk/config.js
@@ -0,0 +1,26 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved Plunk configuration by applying default values to optional fields.
+ *
+ * This function takes a partial Plunk configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the Plunk transport.
+ *
+ * @param config - The Plunk configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ * @internal
+ */
+const createPlunkConfig = (config) => {
+  return {
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl ?? 'https://next-api.useplunk.com',
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    validateSsl: config.validateSsl ?? true,
+    headers: config.headers ?? {},
+  };
+};
+
+module.exports = { createPlunkConfig };
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
new file mode 100644
index 0000000..fdbbe2d
--- /dev/null
+++ b/src/plunk/http-client.js
@@ -0,0 +1,259 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/http-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { parseRetryAfter } = require('../core/receipt.js');
+
+/**
+ * Error thrown when a Plunk API request fails.
+ */
+class PlunkApiError extends Error {
+  /**
+   * HTTP status code returned by Plunk, if the request reached the API.
+   */
+  statusCode;
+
+  /**
+   * Retry delay from Plunk's `Retry-After` response header.
+   */
+  retryAfterMilliseconds;
+
+  /**
+   * Number of attempts made before this error was produced.
+   */
+  attempts;
+
+  /**
+   * Creates a Plunk API error.
+   *
+   * @param message Error message.
+   * @param statusCode HTTP status code returned by Plunk.
+   * @param retryAfterMilliseconds Retry delay from the response.
+   * @param attempts Number of attempts made before this error.
+   */
+  constructor(message, statusCode, retryAfterMilliseconds, attempts) {
+    super(message);
+    this.name = 'PlunkApiError';
+    this.statusCode = statusCode;
+    this.retryAfterMilliseconds = retryAfterMilliseconds;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * HTTP client wrapper for Plunk API requests.
+ *
+ * This class handles authentication, request formatting, error handling,
+ * and retry logic for the Plunk HTTP API.
+ */
+class PlunkHttpClient {
+  config;
+
+  /**
+   * Creates a new Plunk HTTP client instance.
+   *
+   * @param config - Resolved Plunk configuration
+   */
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Sends a message via the Plunk API.
+   *
+   * This method makes a POST request to the `/v1/send` endpoint with proper
+   * authentication, retry logic, and error handling.
+   *
+   * @param emailData - The email data in Plunk API format
+   * @param signal - Optional AbortSignal for request cancellation
+   * @returns Promise that resolves to Plunk API response
+   * @throws PlunkError if the request fails after all retries
+   */
+  async sendMessage(emailData, signal) {
+    const url = `${this.config.baseUrl}/v1/send`;
+
+    let lastError = null;
+
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      signal?.throwIfAborted();
+
+      try {
+        const response = await this.makeRequest(url, emailData, signal);
+        return await this.parseResponse(response);
+      } catch (error) {
+        if (isCallerAbort(error, signal)) {
+          throw error;
+        }
+
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        // Don't retry on client errors (4xx) or AbortError
+        if (error instanceof Error && error.name === 'AbortError') {
+          throw error;
+        }
+
+        if (
+          error instanceof PlunkApiError &&
+          error.statusCode !== undefined &&
+          error.statusCode >= 400 &&
+          error.statusCode < 500
+        ) {
+          throw new PlunkApiError(
+            error.message,
+            error.statusCode,
+            error.retryAfterMilliseconds,
+            attempt + 1,
+          );
+        }
+
+        // If this was the last attempt, throw the error
+        if (attempt === this.config.retries) {
+          break;
+        }
+
+        // Wait before retrying (exponential backoff)
+        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
+        await this.sleep(delay);
+      }
+    }
+
+    // All retries failed
+    const errorMessage = lastError?.message ?? 'Unknown error occurred';
+    if (lastError instanceof PlunkApiError) {
+      throw new PlunkApiError(
+        lastError.message,
+        lastError.statusCode,
+        lastError.retryAfterMilliseconds,
+        this.config.retries + 1,
+      );
+    }
+    throw new PlunkApiError(errorMessage, undefined, undefined, this.config.retries + 1);
+  }
+
+  /**
+   * Makes an HTTP request to the Plunk API.
+   *
+   * @param url - The request URL
+   * @param emailData - The email data to send
+   * @param signal - Optional AbortSignal for cancellation
+   * @returns Promise that resolves to the Response object
+   */
+  async makeRequest(url, emailData, signal) {
+    const headers = {
+      Authorization: `Bearer ${this.config.apiKey}`,
+      'Content-Type': 'application/json',
+      ...this.config.headers,
+    };
+
+    const timeoutController = new AbortController();
+    const timeoutId =
+      this.config.timeout > 0
+        ? setTimeout(() => timeoutController.abort(), this.config.timeout)
+        : undefined;
+    const combinedSignal = combineSignals(timeoutController.signal, signal);
+
+    let response;
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(emailData),
+        signal: combinedSignal.signal,
+      });
+    } catch (error) {
+      if (isAbortError(error) && timeoutController.signal.aborted && !signal?.aborted) {
+        // oxlint-disable-next-line preserve-caught-error -- upstream
+        throw new Error(`Plunk API request timed out after ${this.config.timeout} ms.`);
+      }
+      throw error;
+    } finally {
+      combinedSignal.cleanup();
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    }
+
+    if (!response.ok) {
+      let errorBody;
+      try {
+        errorBody = await response.text();
+      } catch {
+        errorBody = 'Failed to read error response';
+      }
+
+      throw new PlunkApiError(
+        `HTTP ${response.status}: ${response.statusText}. ${truncateErrorBody(errorBody)}`,
+        response.status,
+        parseRetryAfter(response.headers.get('Retry-After')),
+      );
+    }
+
+    return response;
+  }
+
+  /**
+   * Parses the response from the Plunk API.
+   *
+   * @param response - The Response object from fetch
+   * @returns Promise that resolves to parsed PlunkResponse
+   */
+  async parseResponse(response) {
+    try {
+      const data = await response.json();
+
+      // Validate response structure
+      if (typeof data !== 'object' || data === null) {
+        throw new Error('Invalid response format: expected object');
+      }
+
+      if (typeof data.success !== 'boolean') {
+        throw new Error('Invalid response format: missing success field');
+      }
+
+      if (!data.success) {
+        throw new Error(data.message ?? 'Send operation failed without error details');
+      }
+
+      const responseData = 'data' in data ? data.data : data;
+      if (typeof responseData !== 'object' || responseData === null) {
+        throw new Error('Invalid response format: missing data field');
+      }
+
+      return {
+        success: true,
+        emails: responseData.emails,
+        timestamp: responseData.timestamp,
+      };
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        // oxlint-disable-next-line preserve-caught-error -- upstream
+        throw new Error('Invalid JSON response from Plunk API');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Sleeps for the specified number of milliseconds.
+   *
+   * @param ms - Milliseconds to sleep
+   * @returns Promise that resolves after the delay
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+const truncateErrorBody = (text) => {
+  return text.length > 500 ? `${text.slice(0, 500)}...` : text;
+};
+
+module.exports = { PlunkApiError, PlunkHttpClient };
diff --git a/src/plunk/index.d.ts b/src/plunk/index.d.ts
new file mode 100644
index 0000000..b0eef69
--- /dev/null
+++ b/src/plunk/index.d.ts
@@ -0,0 +1,258 @@
+// Types ported from upyo v0.7.0 (packages/plunk/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Configuration interface for Plunk transport connection settings.
+ *
+ * This interface defines all available options for configuring a Plunk
+ * API connection including authentication, HTTP options, and base URL for
+ * self-hosted instances.
+ *
+ * @example
+ * ```typescript
+ * const config: PlunkConfig = {
+ *   apiKey: 'your-api-key',
+ *   baseUrl: 'https://next-api.useplunk.com', // or self-hosted URL
+ *   timeout: 30000,
+ *   retries: 3
+ * };
+ * ```
+ */
+export interface PlunkConfig {
+  /**
+   * Your Plunk API key.
+   *
+   * You can find your API key in your Plunk dashboard under Settings > API Keys.
+   * The key will be used as a Bearer token for authentication.
+   */
+  readonly apiKey: string;
+  /**
+   * Base URL for the Plunk API.
+   *
+   * For Plunk's hosted service, use "https://next-api.useplunk.com" (default).
+   * For self-hosted instances, use your domain with "/api" path
+   * (e.g., "https://plunk.example.com/api").
+   *
+   * @default "https://next-api.useplunk.com"
+   */
+  readonly baseUrl?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   *
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Whether to validate SSL certificates.
+   *
+   * @default true
+   */
+  readonly validateSsl?: boolean;
+  /**
+   * Additional HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+}
+/**
+ * Resolved Plunk configuration with all optional fields filled with default values.
+ *
+ * This type represents the final configuration after applying defaults,
+ * used internally by the Plunk transport implementation.
+ */
+export type ResolvedPlunkConfig = Required<PlunkConfig>;
+/**
+ * Creates a resolved Plunk configuration by applying default values to optional fields.
+ *
+ * This function takes a partial Plunk configuration and returns a complete
+ * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the Plunk transport.
+ *
+ * @param config - The Plunk configuration with optional fields
+ * @returns A resolved configuration with all defaults applied
+ * @internal
+ */
+
+/**
+ * Plunk transport implementation for sending emails via Plunk API.
+ *
+ * This transport provides efficient email delivery using Plunk's HTTP API,
+ * with support for both cloud-hosted and self-hosted instances, authentication,
+ * retry logic, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { PlunkTransport } from '@alexify/mailer/plunk';
+ *
+ * const transport = new PlunkTransport({
+ *   apiKey: 'your-plunk-api-key',
+ *   baseUrl: 'https://next-api.useplunk.com', // or self-hosted URL
+ *   timeout: 30000,
+ *   retries: 3
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
+ * ```
+ */
+export declare class PlunkTransport implements Transport<'plunk'> {
+  readonly id = 'plunk';
+  /**
+   * The resolved Plunk configuration used by this transport.
+   */
+  config: ResolvedPlunkConfig;
+  /**
+   * Creates a new Plunk transport instance.
+   *
+   * @param config Plunk configuration including API key and options.
+   */
+  constructor(config: PlunkConfig);
+  /**
+   * Sends a single email message via Plunk API.
+   *
+   * This method converts the message to Plunk format, makes an HTTP request
+   * to the Plunk API, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent successfully');
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'plunk'>>;
+  /**
+   * Sends multiple email messages efficiently via Plunk API.
+   *
+   * This method sends each message individually but provides a streamlined
+   * interface for processing multiple messages. Each message is sent as a
+   * separate API request to Plunk.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'plunk'>>;
+}
+
+/**
+ * Response from Plunk API for sending messages.
+ */
+export interface PlunkResponse {
+  /**
+   * Indicates whether the API call was successful.
+   */
+  readonly success: boolean;
+  /**
+   * Array of sent email details.
+   */
+  readonly emails: readonly {
+    readonly contact: {
+      readonly id: string;
+      readonly email: string;
+    };
+    /**
+     * Plunk email record ID used to correlate webhook events.
+     */
+    readonly email: string;
+  }[];
+  /**
+   * Timestamp of the send operation.
+   */
+  readonly timestamp: string;
+}
+/**
+ * Error response from Plunk API.
+ */
+export interface PlunkError {
+  /**
+   * Error message from Plunk.
+   */
+  readonly message: string;
+  /**
+   * HTTP status code.
+   */
+  readonly statusCode?: number;
+  /**
+   * Additional error details from Plunk API.
+   */
+  readonly details?: unknown;
+}
+/**
+ * Error thrown when a Plunk API request fails.
+ */
diff --git a/src/plunk/index.js b/src/plunk/index.js
new file mode 100644
index 0000000..6c3ca6f
--- /dev/null
+++ b/src/plunk/index.js
@@ -0,0 +1,13 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * @fileoverview Plunk transport for Upyo email library.
+ *
+ * This module provides a transport implementation for sending emails through
+ * Plunk's HTTP API, supporting both cloud-hosted and self-hosted instances.
+ */
+
+const { PlunkTransport } = require('./plunk-transport.js');
+
+module.exports = { PlunkTransport };
diff --git a/src/plunk/message-converter.js b/src/plunk/message-converter.js
new file mode 100644
index 0000000..6d3fb35
--- /dev/null
+++ b/src/plunk/message-converter.js
@@ -0,0 +1,174 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { readAttachmentContent } = require('../core/attachment.js');
+const { resolveThreadingHeaders } = require('../core/message-id.js');
+const { createCalendarAttachment } = require('../core/calendar.js');
+
+/**
+ * Converts a Upyo message to Plunk API format.
+ *
+ * This function transforms the standardized Upyo message format into the
+ * format expected by the Plunk HTTP API, handling email addresses,
+ * content conversion, attachments, and headers.
+ *
+ * @param message - The Upyo message to convert
+ * @param config - Resolved Plunk configuration
+ * @returns Promise that resolves to Plunk-formatted email data
+ * @throws {TypeError} If the message carries an invalid message identifier, or
+ *                     calendar content that is not a single well-formed
+ *                     iCalendar object.
+ * @throws {RangeError} If a calendar message carries so many attachments that
+ *                      one would have to be dropped.
+ */
+const convertMessage = async (message, _config, signal) => {
+  // Convert recipients - Plunk accepts either string or array
+  const recipients = message.recipients.map((addr) => addr.address);
+  const to = recipients.length === 1 ? recipients[0] : recipients;
+
+  // Convert sender information
+  const senderName = message.sender.name;
+  const senderEmail = message.sender.address;
+
+  // Convert reply-to (use first reply recipient)
+  const replyTo =
+    message.replyRecipients.length > 0 ? message.replyRecipients[0].address : undefined;
+
+  // Convert content - HTML takes precedence over text
+  let body;
+  if ('html' in message.content && message.content.html) {
+    body = message.content.html;
+  } else if ('text' in message.content && message.content.text) {
+    body = message.content.text;
+  } else {
+    body = '';
+  }
+
+  // Reply threading comes from the typed fields when the message defines them,
+  // and from a custom header otherwise.  A field the message owns but left
+  // empty writes nothing, which is how a caller drops an inherited header.
+  const threading = resolveThreadingHeaders(message);
+  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+
+  // Convert headers - merge custom headers but exclude standard ones
+  const customHeaders = {};
+  if (message.headers) {
+    for (const [key, value] of message.headers.entries()) {
+      // Skip headers that are handled by dedicated fields
+      const lowerKey = key.toLowerCase();
+      if (
+        !['to', 'from', 'reply-to', 'subject', 'content-type'].includes(lowerKey) &&
+        !ownedHeaders.has(lowerKey)
+      ) {
+        customHeaders[lowerKey] = value;
+      }
+    }
+  }
+  for (const [name, value] of threading) {
+    if (value != null) customHeaders[name] = value;
+  }
+
+  // A transport that cannot compose a `text/calendar` alternative carries the
+  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
+  // own files so that a client looking for the first calendar part finds it.
+  // Built here rather than inside the loop below, whose error handling drops a
+  // part it cannot convert: an invitation must not disappear that quietly.
+  const sourceAttachments =
+    message.calendar == null
+      ? message.attachments
+      : [createCalendarAttachment(message.calendar), ...message.attachments];
+
+  // Plunk documents a limit of five attachments, and quietly sending the first
+  // five is only acceptable while nothing important is at the end.  Once the
+  // invitation occupies a slot, going over the limit would silently drop one of
+  // the caller's own files, so it is refused instead.
+  if (message.calendar != null && sourceAttachments.length > 5) {
+    throw new RangeError(
+      'Plunk supports at most five attachments, and a calendar message needs ' +
+        'one of them for the invitation.',
+    );
+  }
+
+  // Convert attachments (limit to 5 as per Plunk documentation)
+  const attachments = [];
+  const maxAttachments = Math.min(sourceAttachments.length, 5);
+
+  for (let i = 0; i < maxAttachments; i++) {
+    const attachment = sourceAttachments[i];
+    const convertedAttachment = await convertAttachment(attachment, signal);
+    if (convertedAttachment) {
+      attachments.push(convertedAttachment);
+    }
+  }
+
+  // Build Plunk email object
+  const plunkEmail = {
+    to,
+    subject: message.subject,
+    body,
+  };
+
+  // Add optional fields if present
+  if (senderName) {
+    plunkEmail.name = senderName;
+  }
+
+  if (senderEmail) {
+    plunkEmail.from = senderEmail;
+  }
+
+  if (replyTo) {
+    plunkEmail.reply = replyTo;
+  }
+
+  if (Object.keys(customHeaders).length > 0) {
+    plunkEmail.headers = customHeaders;
+  }
+
+  if (attachments.length > 0) {
+    plunkEmail.attachments = attachments;
+  }
+
+  return plunkEmail;
+};
+
+/**
+ * Converts a Upyo attachment to Plunk format.
+ *
+ * @param attachment - The Upyo attachment to convert
+ * @returns Promise that resolves to Plunk attachment or null if conversion fails
+ */
+const convertAttachment = async (attachment, signal) => {
+  try {
+    // Get content as Uint8Array
+    const content = await readAttachmentContent(attachment.content, signal);
+
+    // Convert to base64
+    const base64Content = arrayBufferToBase64(content);
+
+    return {
+      filename: attachment.filename,
+      content: base64Content,
+      contentType: attachment.contentType,
+    };
+  } catch (error) {
+    signal?.throwIfAborted();
+    // Log error but don't fail the entire send operation
+    // oxlint-disable-next-line no-console -- upstream
+    console.warn(`Failed to convert attachment ${attachment.filename}:`, error);
+    return null;
+  }
+};
+
+/**
+ * Converts an ArrayBuffer or Uint8Array to base64 string.
+ *
+ * @param buffer - The buffer to convert
+ * @returns Base64 encoded string
+ */
+const arrayBufferToBase64 = (buffer) => {
+  const binaryString = Array.from(buffer, (byte) => String.fromCharCode(byte)).join('');
+  return btoa(binaryString);
+};
+
+module.exports = { convertMessage };
diff --git a/src/plunk/plunk-transport.js b/src/plunk/plunk-transport.js
new file mode 100644
index 0000000..95bdf76
--- /dev/null
+++ b/src/plunk/plunk-transport.js
@@ -0,0 +1,235 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/plunk-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { createPlunkConfig } = require('./config.js');
+const { PlunkApiError, PlunkHttpClient } = require('./http-client.js');
+const { convertMessage } = require('./message-converter.js');
+
+/**
+ * Plunk transport implementation for sending emails via Plunk API.
+ *
+ * This transport provides efficient email delivery using Plunk's HTTP API,
+ * with support for both cloud-hosted and self-hosted instances, authentication,
+ * retry logic, and batch sending capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { PlunkTransport } from '@alexify/mailer/plunk';
+ *
+ * const transport = new PlunkTransport({
+ *   apiKey: 'your-plunk-api-key',
+ *   baseUrl: 'https://next-api.useplunk.com', // or self-hosted URL
+ *   timeout: 30000,
+ *   retries: 3
+ * });
+ *
+ * const receipt = await transport.send(message);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
+ * ```
+ */
+class PlunkTransport {
+  id = 'plunk';
+
+  /**
+   * The resolved Plunk configuration used by this transport.
+   */
+  config;
+
+  httpClient;
+
+  /**
+   * Creates a new Plunk transport instance.
+   *
+   * @param config Plunk configuration including API key and options.
+   */
+  constructor(config) {
+    this.config = createPlunkConfig(config);
+    this.httpClient = new PlunkHttpClient(this.config);
+  }
+
+  /**
+   * Sends a single email message via Plunk API.
+   *
+   * This method converts the message to Plunk format, makes an HTTP request
+   * to the Plunk API, and returns a receipt with the result.
+   *
+   * @example
+   * ```typescript
+   * const receipt = await transport.send({
+   *   sender: { address: 'from@example.com' },
+   *   recipients: [{ address: 'to@example.com' }],
+   *   ccRecipients: [],
+   *   bccRecipients: [],
+   *   replyRecipients: [],
+   *   subject: 'Hello',
+   *   content: { text: 'Hello World!' },
+   *   attachments: [],
+   *   priority: 'normal',
+   *   tags: [],
+   *   headers: new Headers()
+   * });
+   *
+   * if (receipt.successful) {
+   *   console.log('Message sent successfully');
+   * }
+   * ```
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns A promise that resolves to a receipt indicating success or
+   *          failure.
+   */
+  async send(message, options) {
+    try {
+      options?.signal?.throwIfAborted();
+
+      const emailData = await convertMessage(message, this.config, options?.signal);
+
+      options?.signal?.throwIfAborted();
+
+      const response = await this.httpClient.sendMessage(emailData, options?.signal);
+
+      // Extract message ID from response
+      const messageId = this.extractMessageId(response, message);
+
+      return {
+        successful: true,
+        messageId,
+        provider: 'plunk',
+      };
+    } catch (error) {
+      if (isCallerAbort(error, options?.signal)) {
+        throw error;
+      }
+
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      return createPlunkFailure(errorMessage, error);
+    }
+  }
+
+  /**
+   * Sends multiple email messages efficiently via Plunk API.
+   *
+   * This method sends each message individually but provides a streamlined
+   * interface for processing multiple messages. Each message is sent as a
+   * separate API request to Plunk.
+   *
+   * @example
+   * ```typescript
+   * const messages = [
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user1@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 1',
+   *     content: { text: 'Hello User 1!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   },
+   *   {
+   *     sender: { address: 'from@example.com' },
+   *     recipients: [{ address: 'user2@example.com' }],
+   *     ccRecipients: [],
+   *     bccRecipients: [],
+   *     replyRecipients: [],
+   *     subject: 'Message 2',
+   *     content: { text: 'Hello User 2!' },
+   *     attachments: [],
+   *     priority: 'normal',
+   *     tags: [],
+   *     headers: new Headers()
+   *   }
+   * ];
+   *
+   * for await (const receipt of transport.sendMany(messages)) {
+   *   if (receipt.successful) {
+   *     console.log('Sent:', receipt.messageId);
+   *   } else {
+   *     console.error('Failed:', receipt.errorMessages);
+   *   }
+   * }
+   * ```
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including `AbortSignal` for
+   *                cancellation.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    const isAsyncIterable = Symbol.asyncIterator in messages;
+
+    if (isAsyncIterable) {
+      for await (const message of messages) {
+        options?.signal?.throwIfAborted();
+        yield await this.send(message, options);
+      }
+    } else {
+      for (const message of messages) {
+        options?.signal?.throwIfAborted();
+        yield await this.send(message, options);
+      }
+    }
+  }
+
+  /**
+   * Extracts or generates a message ID from the Plunk response.
+   *
+   * Plunk returns its email record ID in the response. This ID can be used to
+   * correlate the send operation with webhook events.
+   *
+   * @param response The Plunk API response.
+   * @param message The original message for fallback ID generation.
+   * @returns A message ID string.
+   */
+  extractMessageId(response, message) {
+    const emailId = response.emails?.[0]?.email;
+    if (emailId) {
+      return emailId;
+    }
+
+    // Fallback: generate synthetic message ID
+    const timestamp = Date.now();
+    const recipientHash = message.recipients[0]?.address.split('@')[0].substring(0, 8) ?? 'unknown';
+    const random = Math.random().toString(36).substring(2, 8);
+
+    return `plunk-${timestamp}-${recipientHash}-${random}`;
+  }
+}
+
+const createPlunkFailure = (message, error) => {
+  if (error instanceof PlunkApiError) {
+    return createFailedReceipt(message, {
+      provider: 'plunk',
+      statusCode: error.statusCode,
+      retryAfterMilliseconds: error.retryAfterMilliseconds,
+      attempts: error.attempts,
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'plunk',
+  });
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+module.exports = { PlunkTransport };
diff --git a/tests/e2e/plunk-transport.e2e.test.js b/tests/e2e/plunk-transport.e2e.test.js
new file mode 100644
index 0000000..d7d9ff8
--- /dev/null
+++ b/tests/e2e/plunk-transport.e2e.test.js
@@ -0,0 +1,262 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/plunk-transport.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../../src/core/receipt.js');
+const { PlunkTransport } = require('../../src/plunk/index.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const {
+  createTestMessage,
+  getTestConfig,
+  isE2eTestingEnabled,
+} = require('../helpers/plunk/test-config.js');
+
+// Only run E2E tests if environment is configured
+const describeE2E = isE2eTestingEnabled() ? describe : describe.skip;
+
+describeE2E('PlunkTransport E2E', () => {
+  let transport;
+
+  it('should initialize transport with test config', () => {
+    const config = getTestConfig();
+    transport = new PlunkTransport(config.plunk);
+    assert.ok(transport);
+  });
+
+  it('should send a simple text email', async () => {
+    const message = createTestMessage({
+      subject: '[E2E] Simple text email',
+      content: { text: 'This is a test email sent via Plunk API' },
+    });
+
+    const receipt = await transport.send(message);
+
+    if (acceptQuotaLimit(receipt, 'Simple text email')) return;
+
+    assertSuccessful(receipt);
+
+    if (receipt.successful) {
+      console.log(`Sent email with ID: ${receipt.messageId}`);
+    }
+  });
+
+  it('should send an HTML email', async () => {
+    const message = createTestMessage({
+      subject: '[E2E] HTML email',
+      content: {
+        text: 'This is the plain text version.',
+        html: '<h1>HTML Email</h1><p>This is a <strong>test email</strong> sent via Plunk API.</p>',
+      },
+    });
+
+    const receipt = await transport.send(message);
+
+    if (acceptQuotaLimit(receipt, 'HTML email')) return;
+
+    assertSuccessful(receipt);
+
+    if (receipt.successful) {
+      console.log(`Sent HTML email with ID: ${receipt.messageId}`);
+    }
+  });
+
+  it('should send an email with attachments', async () => {
+    const textContent = new TextEncoder().encode('Hello from attachment!');
+
+    const message = createTestMessage({
+      subject: '[E2E] Email with attachment',
+      content: { text: 'This email has an attachment.' },
+      attachments: [
+        {
+          filename: 'test.txt',
+          contentType: 'text/plain',
+          content: Promise.resolve(textContent),
+          inline: false,
+          contentId: '',
+        },
+      ],
+    });
+
+    const receipt = await transport.send(message);
+
+    // Attachment failures are acceptable - some APIs may have restrictions
+    if (receipt.successful) {
+      assert.ok(receipt.messageId, 'Should have a message ID');
+      console.log(`Sent email with attachment, ID: ${receipt.messageId}`);
+    } else {
+      console.log(`Attachment test failed (acceptable): ${receipt.errorMessages.join(', ')}`);
+      // Still pass the test as attachment restrictions are common
+    }
+  });
+
+  it('should send an email with custom headers', async () => {
+    const headers = new Headers();
+    headers.set('X-Custom-Source', 'Upyo E2E Test');
+    headers.set('X-Test-ID', `e2e-${Date.now()}`);
+
+    const message = createTestMessage({
+      subject: '[E2E] Email with custom headers',
+      content: { text: 'This email includes custom headers.' },
+      headers,
+    });
+
+    const receipt = await transport.send(message);
+
+    if (acceptQuotaLimit(receipt, 'Custom headers email')) return;
+
+    assertSuccessful(receipt);
+
+    if (receipt.successful) {
+      console.log(`Sent email with custom headers, ID: ${receipt.messageId}`);
+    }
+  });
+
+  it('should send an email with reply-to address', async () => {
+    const config = getTestConfig();
+    const message = createTestMessage({
+      subject: '[E2E] Email with reply-to',
+      content: { text: 'This email has a custom reply-to address.' },
+      replyRecipients: [
+        {
+          name: 'No Reply',
+          address: config.testEmails.from, // Use from address as reply-to for testing
+        },
+      ],
+    });
+
+    const receipt = await transport.send(message);
+
+    if (acceptQuotaLimit(receipt, 'Reply-to email')) return;
+
+    assertSuccessful(receipt);
+
+    if (receipt.successful) {
+      console.log(`Sent email with reply-to, ID: ${receipt.messageId}`);
+    }
+  });
+
+  it('should send multiple emails sequentially', async () => {
+    const messages = [
+      createTestMessage({
+        subject: '[E2E] Batch email 1',
+        content: { text: 'This is the first email in a batch.' },
+      }),
+      createTestMessage({
+        subject: '[E2E] Batch email 2',
+        content: { text: 'This is the second email in a batch.' },
+      }),
+      createTestMessage({
+        subject: '[E2E] Batch email 3',
+        content: {
+          html: '<p>This is the <strong>third</strong> email in a batch.</p>',
+        },
+      }),
+    ];
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 3, 'Should send all three emails');
+    if (isQuotaLimitedBatch(receipts)) {
+      console.log('Batch email test skipped due to Plunk transactional limit.');
+      return;
+    }
+    assert.ok(
+      receipts.every((r) => r.successful),
+      'All sends should be successful',
+    );
+
+    for (let i = 0; i < receipts.length; i++) {
+      const receipt = receipts[i];
+      if (receipt.successful) {
+        console.log(`Batch email ${i + 1} sent with ID: ${receipt.messageId}`);
+      }
+    }
+  });
+
+  it('should handle cancellation with AbortSignal', async () => {
+    const controller = new AbortController();
+
+    // Abort immediately
+    controller.abort();
+
+    const message = createTestMessage({
+      subject: '[E2E] Cancelled email',
+      content: { text: 'This email should be cancelled.' },
+    });
+
+    await assert.rejects(
+      () =>
+        transport.send(message, {
+          signal: controller.signal,
+        }),
+      { name: 'AbortError' },
+    );
+  });
+
+  it('should handle timeout gracefully', async () => {
+    // Create transport with very short timeout for testing
+    const timeoutTransport = new PlunkTransport({
+      ...getTestConfig().plunk,
+      timeout: 1, // 1ms timeout - should fail quickly
+      retries: 0,
+    });
+
+    const message = createTestMessage({
+      subject: '[E2E] Timeout test',
+      content: { text: 'This should timeout quickly.' },
+    });
+
+    const receipt = await timeoutTransport.send(message);
+
+    // Should fail due to timeout, but gracefully return a failed receipt
+    assert.equal(receipt.successful, false);
+    assert.ok(receipt.errorMessages.length > 0);
+
+    console.log(`Timeout test failed as expected: ${receipt.errorMessages[0]}`);
+  });
+});
+
+describe('PlunkTransport E2E quota helpers', () => {
+  it('only skips batches when all failures are quota limits', () => {
+    const success = { successful: true, messageId: 'sent' };
+    const quotaLimit = createFailedReceipt('Plunk transactional limit.', {
+      provider: 'plunk',
+      statusCode: 402,
+    });
+    const authFailure = createFailedReceipt('Unauthorized.', {
+      provider: 'plunk',
+      statusCode: 401,
+    });
+
+    assert.ok(!isQuotaLimitedBatch([success]));
+    assert.ok(isQuotaLimitedBatch([success, quotaLimit]));
+    assert.ok(!isQuotaLimitedBatch([success, quotaLimit, authFailure]));
+  });
+});
+
+function assertSuccessful(receipt) {
+  assert.ok(receipt.successful, 'Send should be successful');
+  assert.ok(receipt.messageId, 'Should have a message ID');
+}
+
+function acceptQuotaLimit(receipt, label) {
+  if (!isQuotaLimitReceipt(receipt)) return false;
+  console.log(`${label} test skipped due to Plunk transactional limit.`);
+  return true;
+}
+
+function isQuotaLimitedBatch(receipts) {
+  const failures = receipts.filter((receipt) => !receipt.successful);
+  return failures.length > 0 && failures.every(isQuotaLimitReceipt);
+}
+
+function isQuotaLimitReceipt(receipt) {
+  return (
+    !receipt.successful &&
+    receipt.errors?.some((error) => error.statusCode === 402) === true &&
+    receipt.errorMessages.some((message) => message.includes('transactional limit'))
+  );
+}
diff --git a/tests/helpers/plunk/test-config.js b/tests/helpers/plunk/test-config.js
new file mode 100644
index 0000000..cd2fc8e
--- /dev/null
+++ b/tests/helpers/plunk/test-config.js
@@ -0,0 +1,70 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { isEmailAddress } = require('../../../src/core/address.js');
+const process = require('node:process');
+
+const getTestConfig = () => {
+  if (!isE2eTestingEnabled()) {
+    throw new Error(
+      'E2E testing is not enabled. Set PLUNK_API_KEY, PLUNK_FROM, and PLUNK_TO environment variables.',
+    );
+  }
+
+  const baseUrl = process.env.PLUNK_BASE_URL || 'https://next-api.useplunk.com';
+
+  return {
+    plunk: {
+      apiKey: process.env.PLUNK_API_KEY,
+      baseUrl,
+    },
+    testEmails: {
+      from: process.env.PLUNK_FROM,
+      to: process.env.PLUNK_TO,
+    },
+  };
+};
+
+function isE2eTestingEnabled() {
+  return !!(process.env.PLUNK_API_KEY && process.env.PLUNK_FROM && process.env.PLUNK_TO);
+}
+
+const createTestMessage = (options = {}) => {
+  const config = getTestConfig();
+  const timestamp = Date.now();
+  const randomId = Math.random().toString(36).substr(2, 9);
+
+  const senderEmail = options.senderEmail ?? config.testEmails.from;
+  const recipientEmail = options.recipientEmail ?? config.testEmails.to;
+
+  if (!isEmailAddress(senderEmail)) {
+    throw new Error(`Invalid sender email address: ${senderEmail}`);
+  }
+  if (!isEmailAddress(recipientEmail)) {
+    throw new Error(`Invalid recipient email address: ${recipientEmail}`);
+  }
+
+  return {
+    sender: {
+      name: options.senderName ?? 'Plunk E2E Test Sender',
+      address: senderEmail,
+    },
+    recipients: options.recipients ?? [
+      {
+        name: 'E2E Test Recipient',
+        address: recipientEmail,
+      },
+    ],
+    ccRecipients: options.ccRecipients ?? [],
+    bccRecipients: options.bccRecipients ?? [],
+    replyRecipients: options.replyRecipients ?? [],
+    subject: options.subject ?? `[Plunk E2E Test] ${timestamp}`,
+    content: options.content ?? { text: `Test message content ${randomId}` },
+    attachments: options.attachments ?? [],
+    priority: options.priority ?? 'normal',
+    tags: options.tags ?? ['e2e-test'],
+    headers: options.headers ?? new Headers(),
+  };
+};
+
+module.exports = { getTestConfig, isE2eTestingEnabled, createTestMessage };
diff --git a/tests/types/plunk.test-d.ts b/tests/types/plunk.test-d.ts
new file mode 100644
index 0000000..0e43762
--- /dev/null
+++ b/tests/types/plunk.test-d.ts
@@ -0,0 +1,26 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import {
+  PlunkTransport,
+  type PlunkConfig,
+  type PlunkResponse,
+  type ResolvedPlunkConfig,
+} from '../../src/plunk/index.js';
+
+const transport = new PlunkTransport({ apiKey: 'sk_key', baseUrl: 'https://plunk.example.com' });
+expectAssignable<Transport<'plunk'>>(transport);
+expectType<ResolvedPlunkConfig>(transport.config);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'plunk'>>>(transport.send(message));
+expectType<AsyncIterable<Receipt<'plunk'>>>(transport.sendMany([message]));
+
+expectAssignable<PlunkConfig>({ apiKey: 'sk_key', retries: 1, timeout: 5000 });
+declare const response: PlunkResponse;
+expectType<boolean>(response.success);
+expectError(new PlunkTransport({ baseUrl: 'https://plunk.example.com' }));
diff --git a/tests/unit/plunk-config.test.js b/tests/unit/plunk-config.test.js
new file mode 100644
index 0000000..6f0411e
--- /dev/null
+++ b/tests/unit/plunk-config.test.js
@@ -0,0 +1,98 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { createPlunkConfig } = require('../../src/plunk/config.js');
+
+describe('createPlunkConfig', () => {
+  it('should apply default values for optional fields', () => {
+    const config = {
+      apiKey: 'test-api-key',
+    };
+
+    const resolved = createPlunkConfig(config);
+
+    assert.equal(resolved.apiKey, 'test-api-key');
+    assert.equal(resolved.baseUrl, 'https://next-api.useplunk.com');
+    assert.equal(resolved.timeout, 30000);
+    assert.equal(resolved.retries, 3);
+    assert.equal(resolved.validateSsl, true);
+    assert.deepEqual(resolved.headers, {});
+  });
+
+  it('should preserve provided values', () => {
+    const config = {
+      apiKey: 'test-api-key',
+      baseUrl: 'https://plunk.example.com/api',
+      timeout: 60000,
+      retries: 5,
+      validateSsl: false,
+      headers: { 'X-Custom-Header': 'value' },
+    };
+
+    const resolved = createPlunkConfig(config);
+
+    assert.equal(resolved.apiKey, 'test-api-key');
+    assert.equal(resolved.baseUrl, 'https://plunk.example.com/api');
+    assert.equal(resolved.timeout, 60000);
+    assert.equal(resolved.retries, 5);
+    assert.equal(resolved.validateSsl, false);
+    assert.deepEqual(resolved.headers, { 'X-Custom-Header': 'value' });
+  });
+
+  it('should handle self-hosted instance URLs', () => {
+    const config = {
+      apiKey: 'self-hosted-key',
+      baseUrl: 'https://mail.company.com/api',
+    };
+
+    const resolved = createPlunkConfig(config);
+
+    assert.equal(resolved.baseUrl, 'https://mail.company.com/api');
+    assert.equal(resolved.apiKey, 'self-hosted-key');
+  });
+
+  it('should handle empty headers object', () => {
+    const config = {
+      apiKey: 'test-key',
+      headers: {},
+    };
+
+    const resolved = createPlunkConfig(config);
+
+    assert.deepEqual(resolved.headers, {});
+  });
+
+  it('should handle multiple custom headers', () => {
+    const config = {
+      apiKey: 'test-key',
+      headers: {
+        'X-Source': 'upyo',
+        'X-Version': '0.3.0',
+        'User-Agent': 'custom-agent',
+      },
+    };
+
+    const resolved = createPlunkConfig(config);
+
+    assert.deepEqual(resolved.headers, {
+      'X-Source': 'upyo',
+      'X-Version': '0.3.0',
+      'User-Agent': 'custom-agent',
+    });
+  });
+
+  it('should handle zero timeout and retries', () => {
+    const config = {
+      apiKey: 'test-key',
+      timeout: 0,
+      retries: 0,
+    };
+
+    const resolved = createPlunkConfig(config);
+
+    assert.equal(resolved.timeout, 0);
+    assert.equal(resolved.retries, 0);
+  });
+});
diff --git a/tests/unit/plunk-message-converter.test.js b/tests/unit/plunk-message-converter.test.js
new file mode 100644
index 0000000..30b13f8
--- /dev/null
+++ b/tests/unit/plunk-message-converter.test.js
@@ -0,0 +1,417 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/message-converter.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { convertMessage } = require('../../src/plunk/message-converter.js');
+const { createPlunkConfig } = require('../../src/plunk/config.js');
+
+describe('convertMessage', () => {
+  const config = createPlunkConfig({ apiKey: 'test-key' });
+
+  const createTestMessage = (overrides = {}) => {
+    return {
+      sender: { address: 'from@example.com', name: 'Sender Name' },
+      recipients: [{ address: 'to@example.com', name: 'Recipient Name' }],
+      ccRecipients: [],
+      bccRecipients: [],
+      replyRecipients: [],
+      subject: 'Test Subject',
+      content: { text: 'Test message content' },
+      attachments: [],
+      priority: 'normal',
+      tags: [],
+      headers: new Headers(),
+      ...overrides,
+    };
+  };
+
+  it('should convert basic message fields', async () => {
+    const message = createTestMessage();
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.to, 'to@example.com');
+    assert.equal(result.subject, 'Test Subject');
+    assert.equal(result.body, 'Test message content');
+    assert.ok(!('subscribed' in result));
+    assert.equal(result.name, 'Sender Name');
+    assert.equal(result.from, 'from@example.com');
+  });
+
+  it('should handle multiple recipients', async () => {
+    const message = createTestMessage({
+      recipients: [
+        { address: 'user1@example.com' },
+        { address: 'user2@example.com' },
+        { address: 'user3@example.com' },
+      ],
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.deepEqual(result.to, ['user1@example.com', 'user2@example.com', 'user3@example.com']);
+  });
+
+  it('should handle single recipient as string', async () => {
+    const message = createTestMessage({
+      recipients: [{ address: 'single@example.com' }],
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.to, 'single@example.com');
+  });
+
+  it('should prefer HTML content over text', async () => {
+    const message = createTestMessage({
+      content: {
+        text: 'Plain text content',
+        html: '<h1>HTML content</h1>',
+      },
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.body, '<h1>HTML content</h1>');
+  });
+
+  it('should use text content when HTML is not available', async () => {
+    const message = createTestMessage({
+      content: { text: 'Plain text only' },
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.body, 'Plain text only');
+  });
+
+  it('should handle empty content', async () => {
+    const message = createTestMessage({
+      content: { text: '' },
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.body, '');
+  });
+
+  it('should convert reply-to address', async () => {
+    const message = createTestMessage({
+      replyRecipients: [
+        { address: 'reply@example.com', name: 'Reply Person' },
+        { address: 'noreply@example.com' }, // Should use first one
+      ],
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.reply, 'reply@example.com');
+  });
+
+  it('should not include reply field when no reply recipients', async () => {
+    const message = createTestMessage({
+      replyRecipients: [],
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.reply, undefined);
+  });
+
+  it('should convert custom headers', async () => {
+    const headers = new Headers();
+    headers.set('X-Custom-Header', 'custom-value');
+    headers.set('X-Source', 'upyo');
+    headers.set('To', 'should-be-filtered'); // Should be filtered out
+    headers.set('From', 'should-be-filtered'); // Should be filtered out
+
+    const message = createTestMessage({ headers });
+    const result = await convertMessage(message, config);
+
+    assert.deepEqual(result.headers, {
+      'x-custom-header': 'custom-value',
+      'x-source': 'upyo',
+    });
+  });
+
+  it('should not include headers field when no custom headers', async () => {
+    const message = createTestMessage();
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.headers, undefined);
+  });
+
+  it('should filter out standard headers', async () => {
+    const headers = new Headers();
+    headers.set('content-type', 'text/html');
+    headers.set('subject', 'filtered');
+    headers.set('reply-to', 'filtered');
+    headers.set('X-Keep-This', 'keep');
+
+    const message = createTestMessage({ headers });
+    const result = await convertMessage(message, config);
+
+    assert.deepEqual(result.headers, {
+      'x-keep-this': 'keep',
+    });
+  });
+
+  it('should convert attachments', async () => {
+    const textContent = new TextEncoder().encode('Hello, attachment!');
+
+    const message = createTestMessage({
+      attachments: [
+        {
+          filename: 'test.txt',
+          contentType: 'text/plain',
+          content: Promise.resolve(textContent),
+          inline: false,
+          contentId: '',
+        },
+      ],
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.attachments?.length, 1);
+    assert.equal(result.attachments?.[0].filename, 'test.txt');
+    assert.equal(result.attachments?.[0].contentType, 'text/plain');
+
+    // Verify base64 encoding
+    const expectedBase64 = btoa('Hello, attachment!');
+    assert.equal(result.attachments?.[0].content, expectedBase64);
+  });
+
+  it('should limit attachments to 5', async () => {
+    const content = new TextEncoder().encode('test');
+    const attachments = Array.from({ length: 10 }, (_, i) => ({
+      filename: `test${i}.txt`,
+      contentType: 'text/plain',
+      content: Promise.resolve(content),
+      inline: false,
+      contentId: '',
+    }));
+
+    const message = createTestMessage({ attachments });
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.attachments?.length, 5);
+  });
+
+  it('should handle attachment conversion errors gracefully', async () => {
+    const message = createTestMessage({
+      attachments: [
+        {
+          filename: 'failing.txt',
+          contentType: 'text/plain',
+          content: Promise.reject(new Error('Failed to read')),
+          inline: false,
+          contentId: '',
+        },
+        {
+          filename: 'working.txt',
+          contentType: 'text/plain',
+          content: Promise.resolve(new TextEncoder().encode('works')),
+          inline: false,
+          contentId: '',
+        },
+      ],
+    });
+
+    const result = await convertMessage(message, config);
+
+    // Should only include the working attachment
+    assert.equal(result.attachments?.length, 1);
+    assert.equal(result.attachments?.[0].filename, 'working.txt');
+  });
+
+  it('should not include optional fields when not present', async () => {
+    const message = createTestMessage({
+      sender: { address: 'from@example.com' }, // No name
+      replyRecipients: [],
+      headers: new Headers(),
+      attachments: [],
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.name, undefined);
+    assert.equal(result.reply, undefined);
+    assert.equal(result.headers, undefined);
+    assert.equal(result.attachments, undefined);
+  });
+
+  it('should include sender name when provided', async () => {
+    const message = createTestMessage({
+      sender: { address: 'from@example.com', name: 'John Doe' },
+    });
+
+    const result = await convertMessage(message, config);
+
+    assert.equal(result.name, 'John Doe');
+    assert.equal(result.from, 'from@example.com');
+  });
+});
+
+const threadingConfig = createPlunkConfig({ apiKey: 'test-key' });
+
+const headerOf = (headers, name) =>
+  Object.entries(headers)
+    .filter(([key]) => key.toLowerCase() === name.toLowerCase())
+    .map(([, value]) => value);
+
+describe('convertMessage() reply threading', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Re: Your request',
+    content: { text: 'Thanks for getting in touch.' },
+  };
+
+  it('writes the typed threading fields', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: '122@example.com',
+      references: ['120@example.com', '121@example.com'],
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<122@example.com>']);
+    assert.deepEqual(headerOf(result, 'References'), ['<120@example.com> <121@example.com>']);
+  });
+
+  it('prefers a typed field over a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: ['typed@example.com'],
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<typed@example.com>']);
+  });
+
+  it('lets an empty list suppress a custom header', async () => {
+    const message = createMessage({
+      ...base,
+      inReplyTo: [],
+      references: [],
+      headers: {
+        'In-Reply-To': '<custom@example.com>',
+        References: '<custom@example.com>',
+      },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), []);
+    assert.deepEqual(headerOf(result, 'References'), []);
+  });
+
+  it('lets a custom header through when the field is unset', async () => {
+    const message = createMessage({
+      ...base,
+      headers: { 'In-Reply-To': '<custom@example.com>' },
+    });
+    const result = (await convertMessage(message, threadingConfig)).headers ?? {};
+
+    assert.deepEqual(headerOf(result, 'In-Reply-To'), ['<custom@example.com>']);
+  });
+});
+
+const CALENDAR_ICS =
+  [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'SUMMARY:Lunch',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+const CALENDAR_BASE64 = btoa(CALENDAR_ICS);
+
+const AGENDA_ATTACHMENT = {
+  inline: false,
+  filename: 'agenda.txt',
+  content: new TextEncoder().encode('agenda'),
+  contentType: 'text/plain',
+  contentId: '',
+};
+
+describe('convertMessage() calendar', () => {
+  const calendarConfig = createPlunkConfig({ apiKey: 'test-key' });
+
+  const invitation = (attachments = []) =>
+    createMessage({
+      from: 'organizer@example.com',
+      to: 'attendee@example.net',
+      subject: 'Lunch',
+      content: { text: 'Lunch on Wednesday.' },
+      calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+      attachments,
+    });
+
+  it('should carry the calendar as an invite.ics attachment', async () => {
+    const result = await convertMessage(invitation(), calendarConfig);
+
+    assert.equal(result.attachments?.length, 1);
+    assert.equal(result.attachments?.[0].filename, 'invite.ics');
+    assert.equal(
+      result.attachments?.[0].contentType,
+      'text/calendar; charset=utf-8; method=REQUEST',
+    );
+    assert.equal(result.attachments?.[0].content, CALENDAR_BASE64);
+  });
+
+  it('should place the invitation ahead of the other attachments', async () => {
+    const result = await convertMessage(invitation([AGENDA_ATTACHMENT]), calendarConfig);
+
+    assert.deepEqual(
+      result.attachments?.map((attachment) => attachment.filename),
+      ['invite.ics', 'agenda.txt'],
+    );
+  });
+
+  it('should refuse to drop a file to make room for the invitation', async () => {
+    // Five files already fill Plunk's limit, so the invitation could only be
+    // carried by silently discarding one of them.
+    await assert.rejects(
+      () => convertMessage(invitation(Array(5).fill(AGENDA_ATTACHMENT)), calendarConfig),
+      { name: 'RangeError', message: /at most five attachments/ },
+    );
+  });
+
+  it('should still truncate at five when there is no calendar', async () => {
+    const result = await convertMessage(
+      createMessage({
+        from: 'organizer@example.com',
+        to: 'attendee@example.net',
+        subject: 'Files',
+        content: { text: 'Files.' },
+        attachments: Array(6).fill(AGENDA_ATTACHMENT),
+      }),
+      calendarConfig,
+    );
+
+    assert.equal(result.attachments?.length, 5);
+  });
+
+  it('should reject calendar content that never passed createMessage()', async () => {
+    const message = {
+      ...createMessage({
+        from: 'organizer@example.com',
+        to: 'attendee@example.net',
+        subject: 'Lunch',
+        content: { text: 'Lunch.' },
+      }),
+      calendar: { method: 'REQUEST', content: 'not a calendar' },
+    };
+
+    await assert.rejects(() => convertMessage(message, calendarConfig), {
+      name: 'TypeError',
+    });
+  });
+});
diff --git a/tests/unit/plunk-transport.test.js b/tests/unit/plunk-transport.test.js
new file mode 100644
index 0000000..9e1c3ce
--- /dev/null
+++ b/tests/unit/plunk-transport.test.js
@@ -0,0 +1,311 @@
+// Ported from upyo v0.7.0 (packages/plunk/src/plunk-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { createServer } = require('node:http');
+const { PlunkTransport } = require('../../src/plunk/plunk-transport.js');
+
+// Bun runs tests within a describe block concurrently. Keeping tests that
+// replace globals in separate describe blocks prevents their mocks from
+// interfering with other tests.
+
+const successfulResponse = {
+  success: true,
+  data: {
+    emails: [
+      {
+        contact: {
+          id: 'contact-id',
+          email: 'to@example.com',
+        },
+        email: 'email-record-id',
+      },
+    ],
+    timestamp: '2023-01-01T12:00:00Z',
+  },
+};
+
+const withPlunkServer = async (fixture, run) => {
+  const server = createServer((_request, response) => {
+    response.writeHead(fixture.status ?? 200, {
+      Connection: 'close',
+      'Content-Type': 'application/json',
+    });
+    response.end(typeof fixture.body === 'string' ? fixture.body : JSON.stringify(fixture.body));
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+
+  try {
+    const address = server.address();
+    assert.ok(address && typeof address !== 'string');
+    await run(`http://127.0.0.1:${address.port}`);
+  } finally {
+    await new Promise((resolve, reject) => {
+      server.close((error) => (error ? reject(error) : resolve()));
+    });
+  }
+};
+
+const createTestMessage = (overrides = {}) => {
+  return {
+    sender: { address: 'from@example.com' },
+    recipients: [{ address: 'to@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test message content' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+describe('PlunkTransport - Configuration', () => {
+  it('should create transport with config', () => {
+    const transport = new PlunkTransport({
+      apiKey: 'test-api-key',
+    });
+
+    assert.ok(transport);
+    assert.equal(transport.config.apiKey, 'test-api-key');
+    assert.equal(transport.config.baseUrl, 'https://next-api.useplunk.com');
+  });
+
+  it('should create transport with custom config', () => {
+    const transport = new PlunkTransport({
+      apiKey: 'test-key',
+      baseUrl: 'https://plunk.example.com/api',
+      timeout: 60000,
+      retries: 5,
+    });
+
+    assert.equal(transport.config.apiKey, 'test-key');
+    assert.equal(transport.config.baseUrl, 'https://plunk.example.com/api');
+    assert.equal(transport.config.timeout, 60000);
+    assert.equal(transport.config.retries, 5);
+  });
+});
+
+describe('PlunkTransport - AbortSignal (send)', () => {
+  it('should handle AbortSignal in send method', async () => {
+    const transport = new PlunkTransport({
+      apiKey: 'test-key',
+    });
+
+    const controller = new AbortController();
+    controller.abort();
+
+    const message = createTestMessage();
+    try {
+      await transport.send(message, { signal: controller.signal });
+      assert.fail('Should have thrown AbortError');
+    } catch (error) {
+      assert.ok(error instanceof Error);
+      assert.equal(error.name, 'AbortError');
+    }
+  });
+
+  // Upstream's "should preserve abort reasons without AbortSignal.any" is not ported: Node 22 always
+  // has AbortSignal.any, and the core keeps no fallback without it.
+});
+
+describe('PlunkTransport - AbortSignal (sendMany)', () => {
+  it('should handle AbortSignal in sendMany method', async () => {
+    const transport = new PlunkTransport({
+      apiKey: 'test-key',
+    });
+
+    const controller = new AbortController();
+    controller.abort();
+
+    const messages = [createTestMessage()];
+
+    try {
+      const receipts = transport.sendMany(messages, {
+        signal: controller.signal,
+      });
+      const iterator = receipts[Symbol.asyncIterator]();
+      await iterator.next();
+      assert.fail('Should have thrown AbortError');
+    } catch (error) {
+      assert.ok(error instanceof Error);
+      assert.equal(error.name, 'AbortError');
+    }
+  });
+});
+
+describe('PlunkTransport - HTTP 500 error', () => {
+  it('should handle errors gracefully and return failed receipt', async () => {
+    await withPlunkServer({ status: 500, body: 'Internal Server Error' }, async (baseUrl) => {
+      const transport = new PlunkTransport({
+        apiKey: 'test-key',
+        baseUrl,
+        retries: 0,
+      });
+
+      const receipt = await transport.send(createTestMessage());
+
+      assert.equal(receipt.successful, false);
+      if (!receipt.successful) {
+        assert.equal(receipt.provider, 'plunk');
+        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.errors?.[0]?.category, 'server-error');
+        assert.equal(receipt.errors?.[0]?.statusCode, 500);
+      }
+    });
+  });
+
+  it('should truncate long error response bodies', async () => {
+    const longBody = 'x'.repeat(600);
+    await withPlunkServer({ status: 500, body: longBody }, async (baseUrl) => {
+      const transport = new PlunkTransport({
+        apiKey: 'test-key',
+        baseUrl,
+        retries: 0,
+      });
+
+      const receipt = await transport.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      assert.equal(
+        receipt.errorMessages[0],
+        `HTTP 500: Internal Server Error. ${'x'.repeat(500)}...`,
+      );
+    });
+  });
+});
+
+describe('PlunkTransport - HTTP 400 error', () => {
+  it('should return a failed receipt for a client error', async () => {
+    await withPlunkServer({ status: 400, body: 'Bad Request' }, async (baseUrl) => {
+      const transport = new PlunkTransport({
+        apiKey: 'test-key',
+        baseUrl,
+        retries: 0,
+      });
+
+      const receipt = await transport.send(createTestMessage());
+
+      assert.equal(receipt.successful, false);
+      assert.ok(Array.isArray(receipt.errorMessages));
+      if (!receipt.successful) {
+        assert.equal(receipt.provider, 'plunk');
+        assert.equal(receipt.retryable, false);
+        assert.equal(receipt.errors?.[0]?.category, 'validation');
+        assert.equal(receipt.errors?.[0]?.statusCode, 400);
+      }
+    });
+  });
+});
+
+describe('PlunkTransport - sendMany async iterable', () => {
+  it('should process async iterable messages', async () => {
+    await withPlunkServer({ body: successfulResponse }, async (baseUrl) => {
+      const transport = new PlunkTransport({
+        apiKey: 'test-key',
+        baseUrl,
+        retries: 0,
+      });
+
+      const generateMessages = async function* () {
+        yield createTestMessage({ subject: 'Message 1' });
+        yield createTestMessage({ subject: 'Message 2' });
+      };
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(generateMessages())) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.ok(receipts.every((receipt) => receipt.successful));
+    });
+  });
+});
+
+describe('PlunkTransport - sendMany sync iterable', () => {
+  it('should process sync iterable messages', async () => {
+    await withPlunkServer({ body: successfulResponse }, async (baseUrl) => {
+      const transport = new PlunkTransport({
+        apiKey: 'test-key',
+        baseUrl,
+        retries: 0,
+      });
+
+      const messages = [
+        createTestMessage({ subject: 'Message 1' }),
+        createTestMessage({ subject: 'Message 2' }),
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.ok(receipts.every((receipt) => receipt.successful));
+    });
+  });
+});
+
+describe('PlunkTransport - fallback message ID', () => {
+  it('should generate fallback message ID when response lacks details', async () => {
+    await withPlunkServer(
+      {
+        body: {
+          success: true,
+          data: {
+            emails: [],
+            timestamp: '2023-01-01T12:00:00Z',
+          },
+        },
+      },
+      async (baseUrl) => {
+        const transport = new PlunkTransport({
+          apiKey: 'test-key',
+          baseUrl,
+          retries: 0,
+        });
+
+        const receipt = await transport.send(createTestMessage());
+
+        assert.equal(receipt.successful, true);
+        if (receipt.successful) {
+          assert.match(receipt.messageId, /^plunk-/);
+          assert.ok(receipt.messageId.includes('to'));
+        }
+      },
+    );
+  });
+});
+
+describe('PlunkTransport - response message ID', () => {
+  it('should use the Plunk email record ID from the response', async () => {
+    await withPlunkServer({ body: successfulResponse }, async (baseUrl) => {
+      const transport = new PlunkTransport({
+        apiKey: 'test-key',
+        baseUrl,
+        retries: 0,
+      });
+
+      const receipt = await transport.send(createTestMessage());
+
+      assert.deepEqual(receipt, {
+        successful: true,
+        messageId: 'email-record-id',
+        provider: 'plunk',
+      });
+    });
+  });
+});
diff --git a/tests/unit/plunk.test.js b/tests/unit/plunk.test.js
new file mode 100644
index 0000000..4ab4526
--- /dev/null
+++ b/tests/unit/plunk.test.js
@@ -0,0 +1,103 @@
+// Paths of the ported Plunk transport (src/plunk/) that upstream's suites
+// leave out, against a stubbed fetch.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { PlunkTransport } = require('../../src/plunk/index.js');
+
+const message = (extra = {}) =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+    ...extra,
+  });
+const config = { apiKey: 'key', retries: 0 };
+const send = async (t, respond, options = config, extra) => {
+  t.mock.restoreAll();
+  t.mock.method(globalThis, 'fetch', respond);
+  return new PlunkTransport(options).send(message(extra));
+};
+
+test('Plunk: a malformed response body fails the send', async (t) => {
+  const cases = [
+    [() => Response.json(null), 'Invalid response format: expected object'],
+    [() => Response.json({}), 'Invalid response format: missing success field'],
+    [() => Response.json({ success: false }), 'Send operation failed without error details'],
+    [() => Response.json({ success: false, message: 'Nope' }), 'Nope'],
+    [
+      () => Response.json({ success: true, data: null }),
+      'Invalid response format: missing data field',
+    ],
+    [() => new Response('<html>'), 'Invalid JSON response from Plunk API'],
+  ];
+  for (const [respond, expected] of cases) {
+    const receipt = await send(t, async () => respond());
+    assert.deepStrictEqual(receipt.errorMessages, [expected]);
+  }
+});
+
+test('Plunk: an unreadable error body and the timeout fail the send', async (t) => {
+  const unreadable = await send(
+    t,
+    async () =>
+      new Response(
+        new ReadableStream({
+          start(controller) {
+            controller.error(new Error('broken'));
+          },
+        }),
+        { status: 500, statusText: 'Internal Server Error' },
+      ),
+  );
+  assert.match(unreadable.errorMessages[0], /Failed to read error response/);
+
+  const slow = await send(
+    t,
+    (url, init) =>
+      new Promise((resolve, reject) => {
+        init.signal.addEventListener('abort', () => reject(init.signal.reason));
+      }),
+    { ...config, timeout: 20 },
+  );
+  assert.deepStrictEqual(slow.errorMessages, ['Plunk API request timed out after 20 ms.']);
+});
+
+test('Plunk: a 5xx is retried after a backoff', async (t) => {
+  let calls = 0;
+  const receipt = await send(
+    t,
+    async () =>
+      ++calls === 1
+        ? new Response('', { status: 502, statusText: 'Bad Gateway' })
+        : Response.json({ success: true, emails: [{ contact: { id: 'c1' } }], timestamp: 'now' }),
+    { ...config, retries: 1 },
+  );
+  assert.strictEqual(calls, 2);
+  assert.strictEqual(receipt.successful, true);
+});
+
+test('Plunk: an attachment that cannot be read is left out with a warning', async (t) => {
+  let body;
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    body = JSON.parse(init.body);
+    return Response.json({ success: true, emails: [], timestamp: 'now' });
+  });
+  const warn = t.mock.method(console, 'warn', () => {});
+  const broken = () => {
+    throw new Error('Cannot read attachment');
+  };
+  const attachments = [
+    {
+      inline: false,
+      filename: 'a.bin',
+      content: broken,
+      contentType: 'application/octet-stream',
+      contentId: '',
+    },
+  ];
+  await new PlunkTransport(config).send(message({ attachments }));
+  assert.strictEqual(warn.mock.callCount(), 1);
+  assert.strictEqual(body.attachments, undefined);
+});

From bc7a2cee982ff896c8bdd296591fa8e329dee59b Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:28:30 +0300
Subject: [PATCH 014/158] feat(jmap): port the JMAP transport from upyo 0.7.0

./jmap exports JmapTransport (send, sendRaw, sendMany, verify) for RFC 8620
and 8621 servers over fetch: session discovery with a cache, bearer or basic
authentication, drafts mailbox and identity lookup, blob uploads for
attachments and streamed raw messages, Email/set plus EmailSubmission/set,
and batched sendMany. createJmapConfig, JmapApiError, JMAP_ERROR_TYPES,
isCapabilityError and uploadBlob come with it. Its AbortSignal.any fallback
is dropped, like the core's.

Upstream's unit and local-server suites are ported; its e2e suite against
Stalwart goes to tests/e2e, with the compose file and the setup script in
tests/e2e/jmap. On Node 24, fetch answers a 401 to a streamed body with a
network error instead of the response; the seven tests of that are todo on
Node 24 (they pass on 22), and the bug is listed in CLAUDE.md.
tests/unit/jmap.test.js covers what upstream reached only end to end:
account, mailbox and identity discovery failures, rejected creations and
submissions, a foreign abort and verification of a session without the
submission capability.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |    2 +-
 CLAUDE.md                                     |    4 +
 package.json                                  |    4 +
 src/jmap/blob-uploader.js                     |   73 ++
 src/jmap/config.js                            |   28 +
 src/jmap/errors.js                            |   46 +
 src/jmap/http-client.js                       |  224 ++++
 src/jmap/index.d.ts                           |  265 +++++
 src/jmap/index.js                             |   23 +
 src/jmap/jmap-transport.js                    | 1035 +++++++++++++++++
 src/jmap/message-converter.js                 |  392 +++++++
 src/jmap/raw-delivery.js                      |  290 +++++
 src/jmap/raw-upload.js                        |  205 ++++
 src/jmap/session.js                           |   18 +
 tests/e2e/jmap-transport.e2e.test.js          |  543 +++++++++
 tests/e2e/jmap/docker-compose.yml             |   28 +
 tests/e2e/jmap/setup-stalwart.sh              |  163 +++
 tests/helpers/jmap/test-config.js             |  110 ++
 tests/types/jmap.test-d.ts                    |   44 +
 tests/unit/jmap-blob-uploader.test.js         |  152 +++
 tests/unit/jmap-config.test.js                |   81 ++
 tests/unit/jmap-errors.test.js                |   81 ++
 tests/unit/jmap-http-client.test.js           |  284 +++++
 tests/unit/jmap-message-converter.test.js     |  610 ++++++++++
 .../unit/jmap-raw-message.integration.test.js |  714 ++++++++++++
 tests/unit/jmap-retry-attempts.test.js        |  126 ++
 tests/unit/jmap-send-error.test.js            |  169 +++
 tests/unit/jmap-send-success.test.js          |  148 +++
 tests/unit/jmap-sendmany.test.js              |  516 ++++++++
 tests/unit/jmap-session.test.js               |   91 ++
 tests/unit/jmap-transport.test.js             |  202 ++++
 tests/unit/jmap-verify.test.js                |  334 ++++++
 tests/unit/jmap.test.js                       |  167 +++
 33 files changed, 7171 insertions(+), 1 deletion(-)
 create mode 100644 src/jmap/blob-uploader.js
 create mode 100644 src/jmap/config.js
 create mode 100644 src/jmap/errors.js
 create mode 100644 src/jmap/http-client.js
 create mode 100644 src/jmap/index.d.ts
 create mode 100644 src/jmap/index.js
 create mode 100644 src/jmap/jmap-transport.js
 create mode 100644 src/jmap/message-converter.js
 create mode 100644 src/jmap/raw-delivery.js
 create mode 100644 src/jmap/raw-upload.js
 create mode 100644 src/jmap/session.js
 create mode 100644 tests/e2e/jmap-transport.e2e.test.js
 create mode 100644 tests/e2e/jmap/docker-compose.yml
 create mode 100755 tests/e2e/jmap/setup-stalwart.sh
 create mode 100644 tests/helpers/jmap/test-config.js
 create mode 100644 tests/types/jmap.test-d.ts
 create mode 100644 tests/unit/jmap-blob-uploader.test.js
 create mode 100644 tests/unit/jmap-config.test.js
 create mode 100644 tests/unit/jmap-errors.test.js
 create mode 100644 tests/unit/jmap-http-client.test.js
 create mode 100644 tests/unit/jmap-message-converter.test.js
 create mode 100644 tests/unit/jmap-raw-message.integration.test.js
 create mode 100644 tests/unit/jmap-retry-attempts.test.js
 create mode 100644 tests/unit/jmap-send-error.test.js
 create mode 100644 tests/unit/jmap-send-success.test.js
 create mode 100644 tests/unit/jmap-sendmany.test.js
 create mode 100644 tests/unit/jmap-session.test.js
 create mode 100644 tests/unit/jmap-transport.test.js
 create mode 100644 tests/unit/jmap-verify.test.js
 create mode 100644 tests/unit/jmap.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ea53103..bc9d744 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/CLAUDE.md b/CLAUDE.md
index 7edff70..b37e991 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -137,6 +137,10 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 13. mime: the first encoded word of a header shares its line with the field name
     (`Subject: =?UTF-8?B?…?=`, 84 characters), past the 76 that RFC 2047 allows a line with
     encoded words.
+14. jmap: on Node 24, `fetch` answers a 401 to a streamed request body (raw upload, import,
+    submission) with `TypeError: fetch failed` ("expected non-null body source") instead of the
+    response, so an authentication rejection becomes a retryable network error. Node 22 returns
+    the 401. The tests of it are `todo` on Node 24 until the fix.
 
 ## Repository layout
 
diff --git a/package.json b/package.json
index 53b8b7b..33effeb 100644
--- a/package.json
+++ b/package.json
@@ -32,6 +32,10 @@
       "types": "./src/smtp/index.d.ts",
       "default": "./src/smtp/index.js"
     },
+    "./jmap": {
+      "types": "./src/jmap/index.d.ts",
+      "default": "./src/jmap/index.js"
+    },
     "./ses": {
       "types": "./src/ses/index.d.ts",
       "default": "./src/ses/index.js"
diff --git a/src/jmap/blob-uploader.js b/src/jmap/blob-uploader.js
new file mode 100644
index 0000000..ccddf53
--- /dev/null
+++ b/src/jmap/blob-uploader.js
@@ -0,0 +1,73 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/blob-uploader.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { JmapApiError } = require('./errors.js');
+
+/**
+ * Upload a blob to the JMAP server.
+ *
+ * @param config - The resolved JMAP configuration
+ * @param uploadUrl - The upload URL template from the session (e.g., "https://server/upload/{accountId}")
+ * @param accountId - The account ID to upload to
+ * @param blob - The blob or file to upload
+ * @param signal - Optional abort signal
+ * @returns The upload response containing the blobId
+ */
+const uploadBlob = async (config, uploadUrl, accountId, blob, signal) => {
+  signal?.throwIfAborted();
+
+  const url = uploadUrl.replace('{accountId}', accountId);
+
+  let authHeader;
+  if (config.bearerToken) {
+    authHeader = `Bearer ${config.bearerToken}`;
+  } else if (config.basicAuth) {
+    const credentials = btoa(`${config.basicAuth.username}:${config.basicAuth.password}`);
+    authHeader = `Basic ${credentials}`;
+  } else {
+    throw new Error('No authentication method configured');
+  }
+
+  const headers = {
+    Authorization: authHeader,
+    'Content-Type': blob.type || 'application/octet-stream',
+  };
+
+  // Add custom headers from config
+  for (const [key, value] of Object.entries(config.headers)) {
+    headers[key] = value;
+  }
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeout);
+
+  // Combine signals if an external signal is provided
+  const combinedSignal = combineSignals(controller.signal, signal);
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: blob,
+      signal: combinedSignal.signal,
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new JmapApiError(
+        `Blob upload failed: ${response.status} ${response.statusText}`,
+        response.status,
+        body,
+      );
+    }
+
+    const result = await response.json();
+    return result;
+  } finally {
+    combinedSignal.cleanup();
+    clearTimeout(timeoutId);
+  }
+};
+
+module.exports = { uploadBlob };
diff --git a/src/jmap/config.js b/src/jmap/config.js
new file mode 100644
index 0000000..150a69b
--- /dev/null
+++ b/src/jmap/config.js
@@ -0,0 +1,28 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved JMAP configuration with default values applied.
+ * @param config The user-provided configuration.
+ * @returns The resolved configuration with all fields populated.
+ * @throws Error if neither bearerToken nor basicAuth is provided.
+ */
+const createJmapConfig = (config) => {
+  if (!config.bearerToken && !config.basicAuth) {
+    throw new Error('Either bearerToken or basicAuth must be provided');
+  }
+  return {
+    sessionUrl: config.sessionUrl,
+    bearerToken: config.bearerToken ?? null,
+    basicAuth: config.basicAuth ?? null,
+    accountId: config.accountId ?? null,
+    identityId: config.identityId ?? null,
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    headers: config.headers ?? {},
+    sessionCacheTtl: config.sessionCacheTtl ?? 300000,
+    baseUrl: config.baseUrl ?? null,
+  };
+};
+
+module.exports = { createJmapConfig };
diff --git a/src/jmap/errors.js b/src/jmap/errors.js
new file mode 100644
index 0000000..6f5c72b
--- /dev/null
+++ b/src/jmap/errors.js
@@ -0,0 +1,46 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/errors.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Error class for JMAP API errors.
+ */
+class JmapApiError extends Error {
+  statusCode;
+  responseBody;
+  jmapErrorType;
+  retryAfterMilliseconds;
+  attempts;
+
+  constructor(message, statusCode, responseBody, jmapErrorType, retryAfterMilliseconds, attempts) {
+    super(message);
+    this.name = 'JmapApiError';
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.jmapErrorType = jmapErrorType;
+    this.retryAfterMilliseconds = retryAfterMilliseconds;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * JMAP-specific error types from RFC 8620.
+ */
+const JMAP_ERROR_TYPES = {
+  unknownCapability: 'urn:ietf:params:jmap:error:unknownCapability',
+  notJSON: 'urn:ietf:params:jmap:error:notJSON',
+  notRequest: 'urn:ietf:params:jmap:error:notRequest',
+  limit: 'urn:ietf:params:jmap:error:limit',
+};
+
+/**
+ * Checks if the given error is a JMAP capability error.
+ * @param error The error to check.
+ * @returns `true` if the error is a JMAP capability error, `false` otherwise.
+ */
+const isCapabilityError = (error) => {
+  return (
+    error instanceof JmapApiError && error.jmapErrorType === JMAP_ERROR_TYPES.unknownCapability
+  );
+};
+
+module.exports = { JmapApiError, JMAP_ERROR_TYPES, isCapabilityError };
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
new file mode 100644
index 0000000..50c1868
--- /dev/null
+++ b/src/jmap/http-client.js
@@ -0,0 +1,224 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/http-client.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { parseRetryAfter } = require('../core/receipt.js');
+const { JmapApiError } = require('./errors.js');
+
+/**
+ * HTTP client for JMAP API requests.
+ */
+class JmapHttpClient {
+  config;
+  replayableRequests;
+
+  /**
+   * @param config HTTP and authentication settings.
+   * @param replayableRequests Whether request bodies and failed requests may be replayed.
+   */
+  constructor(config, replayableRequests = true) {
+    this.config = config;
+    this.replayableRequests = replayableRequests;
+  }
+
+  /**
+   * Fetches the JMAP session from the session URL.
+   * @param signal Optional abort signal.
+   * @returns The JMAP session response.
+   */
+  async fetchSession(signal) {
+    signal?.throwIfAborted();
+
+    const response = await this.fetchWithAuth(this.config.sessionUrl, { method: 'GET' }, signal);
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new JmapApiError(
+        `Session fetch failed: ${response.status}`,
+        response.status,
+        text,
+        undefined,
+        parseRetryAfter(response.headers.get('Retry-After')),
+        1,
+      );
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Executes a JMAP API request.
+   * @param apiUrl The JMAP API URL.
+   * @param request The JMAP request payload.
+   * @param signal Optional abort signal.
+   * @returns The JMAP response.
+   */
+  async executeRequest(apiUrl, request, signal) {
+    signal?.throwIfAborted();
+
+    let lastError = null;
+
+    const retries = this.replayableRequests ? this.config.retries : 0;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      signal?.throwIfAborted();
+
+      try {
+        const response = await this.fetchWithAuth(
+          apiUrl,
+          {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            // A stream prevents runtime-level replay of a POST after a lost
+            // response (observed with Deno even when application retries are 0).
+            body: this.replayableRequests
+              ? JSON.stringify(request)
+              : new ReadableStream({
+                  start(controller) {
+                    controller.enqueue(new TextEncoder().encode(JSON.stringify(request)));
+                    controller.close();
+                  },
+                }),
+            ...(this.replayableRequests ? {} : { duplex: 'half', redirect: 'error' }),
+          },
+          signal,
+        );
+
+        if (!response.ok) {
+          const text = await response.text();
+          const error = new JmapApiError(
+            `JMAP request failed: ${response.status}`,
+            response.status,
+            text,
+            undefined,
+            parseRetryAfter(response.headers.get('Retry-After')),
+            attempt + 1,
+          );
+
+          // Don't retry on 4xx errors (client errors)
+          if (response.status >= 400 && response.status < 500) {
+            throw error;
+          }
+
+          throw error;
+        }
+
+        return await response.json();
+      } catch (error) {
+        // Don't retry if aborted
+        if (isCallerAbort(error, signal)) {
+          throw error;
+        }
+
+        // Don't retry on 4xx errors
+        if (error instanceof JmapApiError && error.statusCode !== undefined) {
+          if (error.statusCode >= 400 && error.statusCode < 500) {
+            throw error;
+          }
+        }
+
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (attempt === retries) {
+          if (error instanceof JmapApiError) {
+            throw error;
+          }
+          if (isAbortError(error)) {
+            throw new JmapApiError(
+              'JMAP request timed out.',
+              undefined,
+              undefined,
+              undefined,
+              undefined,
+              attempt + 1,
+            );
+          }
+          throw new JmapApiError(
+            lastError.message,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            attempt + 1,
+          );
+        }
+
+        // Exponential backoff
+        const delay = Math.pow(2, attempt) * 1000;
+        await new Promise((resolve, reject) => {
+          const cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+          };
+          const onAbort = () => {
+            cleanup();
+            reject(signal?.reason);
+          };
+          const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+          }, delay);
+          signal?.addEventListener('abort', onAbort, { once: true });
+          if (signal?.aborted) onAbort();
+        });
+      }
+    }
+
+    if (lastError != null) {
+      throw lastError;
+    }
+    throw new Error('Request failed after all retries');
+  }
+
+  /**
+   * Makes an authenticated fetch request.
+   * @param url The URL to fetch.
+   * @param options Fetch options.
+   * @param signal Optional abort signal.
+   * @returns The fetch response.
+   */
+  async fetchWithAuth(url, options, signal) {
+    const headers = new Headers(options.headers);
+    if (this.config.bearerToken) {
+      headers.set('Authorization', `Bearer ${this.config.bearerToken}`);
+    } else if (this.config.basicAuth) {
+      const credentials = btoa(
+        `${this.config.basicAuth.username}:${this.config.basicAuth.password}`,
+      );
+      headers.set('Authorization', `Basic ${credentials}`);
+    }
+
+    // Add custom headers from config
+    for (const [key, value] of Object.entries(this.config.headers)) {
+      headers.set(key, value);
+    }
+
+    // Setup timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+
+    // Combine with external signal if provided
+    let combinedSignal = controller.signal;
+    if (signal) {
+      combinedSignal = AbortSignal.any([signal, controller.signal]);
+    }
+
+    try {
+      return await globalThis.fetch(url, {
+        ...options,
+        headers,
+        signal: combinedSignal,
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+module.exports = { JmapHttpClient };
diff --git a/src/jmap/index.d.ts b/src/jmap/index.d.ts
new file mode 100644
index 0000000..1b83963
--- /dev/null
+++ b/src/jmap/index.d.ts
@@ -0,0 +1,265 @@
+// Types ported from upyo v0.7.0 (packages/jmap/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import type {
+  Message,
+  RawMessage,
+  RawTransport,
+  Receipt,
+  TransportOptions,
+  VerifiableTransport,
+} from '../../index.js';
+
+/**
+ * Configuration interface for JMAP transport connection settings.
+ */
+export interface JmapConfig {
+  /**
+   * The JMAP session URL (e.g., `https://server/.well-known/jmap`).
+   * This is used for session discovery per RFC 8620 Section 2.
+   */
+  readonly sessionUrl: string;
+  /**
+   * Bearer token for authentication.
+   * Used in Authorization header as `Bearer {token}`.
+   * Either `bearerToken` or `basicAuth` must be provided.
+   */
+  readonly bearerToken?: string;
+  /**
+   * Basic authentication credentials.
+   * Used in Authorization header as `Basic {base64(username:password)}`.
+   * Either `bearerToken` or `basicAuth` must be provided.
+   */
+  readonly basicAuth?: {
+    readonly username: string;
+    readonly password: string;
+  };
+  /**
+   * The JMAP account ID to use.
+   * If not provided, will be auto-detected from the session response
+   * (first account with mail capability).
+   */
+  readonly accountId?: string;
+  /**
+   * The identity ID to use for email submission.
+   * If not provided, will be auto-resolved based on sender email address.
+   */
+  readonly identityId?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Custom HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Session cache TTL in milliseconds.
+   * Sessions are refreshed when capabilities errors occur or after this duration.
+   * @default 300000 (5 minutes)
+   */
+  readonly sessionCacheTtl?: number;
+  /**
+   * Base URL to use for rewriting session URLs.
+   * Some JMAP servers return internal hostnames in session responses.
+   * When set, URLs from the session (apiUrl, uploadUrl, etc.) will be rewritten
+   * to use this base URL instead.
+   * Example: If the session returns `http://internal-host:8080/jmap/` and
+   * baseUrl is `http://localhost:8080`, URLs will be rewritten to use localhost.
+   */
+  readonly baseUrl?: string;
+}
+/**
+ * Resolved JMAP configuration with all fields populated.
+ */
+export type ResolvedJmapConfig = {
+  readonly sessionUrl: string;
+  readonly bearerToken: string | null;
+  readonly basicAuth: {
+    readonly username: string;
+    readonly password: string;
+  } | null;
+  readonly accountId: string | null;
+  readonly identityId: string | null;
+  readonly timeout: number;
+  readonly retries: number;
+  readonly headers: Record<string, string>;
+  readonly sessionCacheTtl: number;
+  readonly baseUrl: string | null;
+};
+/**
+ * Creates a resolved JMAP configuration with default values applied.
+ * @param config The user-provided configuration.
+ * @returns The resolved configuration with all fields populated.
+ * @throws Error if neither bearerToken nor basicAuth is provided.
+ */
+export declare function createJmapConfig(config: JmapConfig): ResolvedJmapConfig;
+
+/**
+ * JMAP transport for sending emails via JMAP protocol (RFC 8620/8621).
+ */
+export declare class JmapTransport implements RawTransport<'jmap'>, VerifiableTransport<'jmap'> {
+  readonly id = 'jmap';
+  readonly config: ResolvedJmapConfig;
+  /**
+   * Creates a new JMAP transport instance.
+   * @param config The JMAP transport configuration.
+   */
+  constructor(config: JmapConfig);
+  /**
+   * Checks a fresh Session, the account used by send(), its drafts mailbox,
+   * and the configured or available identity without creating or sending mail.
+   * Does not read or update the session cache. Each discovery operation has
+   * config.timeout as its total budget, including response bodies and retries.
+   * Success does not guarantee acceptance of a particular sender or message.
+   * @param options Optional cancellation signal.
+   * @returns A promise that resolves when live verification succeeds.
+   * @throws {JmapApiError} If discovery, authentication, or validation fails.
+   * @throws The caller's abort reason if cancelled.
+   */
+  verify(options?: TransportOptions): Promise<void>;
+  /**
+   * Sends a single email message.
+   * @param message The message to send.
+   * @param options Optional transport options.
+   * @returns A receipt indicating success or failure.
+   * @throws The abort reason or an `AbortError` when the caller aborts the
+   *         operation.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<'jmap'>>;
+  /**
+   * Uploads serialized MIME, imports it, and submits it with an explicit envelope.
+   * JMAP servers may modify imported or submitted messages, including removing
+   * Bcc. Import and submission are never retried automatically.
+   * @param message Original MIME and delivery envelope.
+   * @param options Optional cancellation signal.
+   * @returns A receipt; uncertain submission outcomes are non-retryable.
+   * @throws {Error} If cancellation is requested.
+   */
+  sendRaw(message: RawMessage, options?: TransportOptions): Promise<Receipt<'jmap'>>;
+  /**
+   * Sends multiple messages in a single batched JMAP request.
+   * @param messages The messages to send.
+   * @param options Optional transport options.
+   * @yields Receipts for each message.
+   * @throws The abort reason or an `AbortError` when the caller aborts the
+   *         operation.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<'jmap'>>;
+}
+
+/**
+ * Error class for JMAP API errors.
+ */
+export declare class JmapApiError extends Error {
+  readonly statusCode?: number;
+  readonly responseBody?: string;
+  readonly jmapErrorType?: string;
+  readonly retryAfterMilliseconds?: number;
+  readonly attempts?: number;
+  constructor(
+    message: string,
+    statusCode?: number,
+    responseBody?: string,
+    jmapErrorType?: string,
+    retryAfterMilliseconds?: number,
+    attempts?: number,
+  );
+}
+/**
+ * JMAP-specific error types from RFC 8620.
+ */
+export declare const JMAP_ERROR_TYPES: {
+  readonly unknownCapability: 'urn:ietf:params:jmap:error:unknownCapability';
+  readonly notJSON: 'urn:ietf:params:jmap:error:notJSON';
+  readonly notRequest: 'urn:ietf:params:jmap:error:notRequest';
+  readonly limit: 'urn:ietf:params:jmap:error:limit';
+};
+/**
+ * Checks if the given error is a JMAP capability error.
+ * @param error The error to check.
+ * @returns `true` if the error is a JMAP capability error, `false` otherwise.
+ */
+export declare function isCapabilityError(error: unknown): boolean;
+
+/**
+ * JMAP Session response structure (RFC 8620 Section 2).
+ */
+export interface JmapSession {
+  readonly capabilities: Record<string, unknown>;
+  readonly accounts: Record<string, JmapAccount>;
+  readonly primaryAccounts: Record<string, string>;
+  readonly username: string;
+  readonly apiUrl: string;
+  readonly downloadUrl: string;
+  readonly uploadUrl: string;
+  readonly eventSourceUrl?: string;
+  readonly state: string;
+}
+/**
+ * JMAP Account structure from session response.
+ */
+export interface JmapAccount {
+  readonly name: string;
+  readonly isPersonal: boolean;
+  readonly isReadOnly: boolean;
+  readonly accountCapabilities: Record<string, unknown>;
+}
+/**
+ * JMAP Identity object for sender authorization (RFC 8621 Section 6).
+ */
+export interface JmapIdentity {
+  readonly id: string;
+  readonly name: string;
+  readonly email: string;
+  readonly replyTo?: readonly {
+    readonly email: string;
+    readonly name?: string;
+  }[];
+  readonly bcc?: readonly {
+    readonly email: string;
+    readonly name?: string;
+  }[];
+  readonly textSignature?: string;
+  readonly htmlSignature?: string;
+  readonly mayDelete: boolean;
+}
+/**
+ * Cached session data with metadata.
+ */
+
+/**
+ * Response from a successful blob upload.
+ */
+export interface BlobUploadResponse {
+  readonly accountId: string;
+  readonly blobId: string;
+  readonly type: string;
+  readonly size: number;
+}
+/**
+ * Upload a blob to the JMAP server.
+ *
+ * @param config - The resolved JMAP configuration
+ * @param uploadUrl - The upload URL template from the session (e.g., "https://server/upload/{accountId}")
+ * @param accountId - The account ID to upload to
+ * @param blob - The blob or file to upload
+ * @param signal - Optional abort signal
+ * @returns The upload response containing the blobId
+ */
+export declare function uploadBlob(
+  config: ResolvedJmapConfig,
+  uploadUrl: string,
+  accountId: string,
+  blob: Blob | File,
+  signal?: AbortSignal,
+): Promise<BlobUploadResponse>;
diff --git a/src/jmap/index.js b/src/jmap/index.js
new file mode 100644
index 0000000..8708d4c
--- /dev/null
+++ b/src/jmap/index.js
@@ -0,0 +1,23 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * @alexify/mailer/jmap - JMAP transport for Upyo email library
+ * RFC 8620 (core) and RFC 8621 (mail) compliant
+ * @module
+ */
+
+const { JmapTransport } = require('./jmap-transport.js');
+const { createJmapConfig } = require('./config.js');
+const { isCapabilityError, JMAP_ERROR_TYPES, JmapApiError } = require('./errors.js');
+
+const { uploadBlob } = require('./blob-uploader.js');
+
+module.exports = {
+  JmapTransport,
+  createJmapConfig,
+  isCapabilityError,
+  JMAP_ERROR_TYPES,
+  JmapApiError,
+  uploadBlob,
+};
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
new file mode 100644
index 0000000..d16567f
--- /dev/null
+++ b/src/jmap/jmap-transport.js
@@ -0,0 +1,1035 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/jmap-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { createRawMessagePlan, RawMessageValidationError } = require('../core/raw-message.js');
+const { deliverRawMessage, rawDiscoveryResult } = require('./raw-delivery.js');
+const { isRecord, rawOperation } = require('./raw-upload.js');
+const { readAttachmentContent } = require('../core/attachment.js');
+const { createFailedReceipt } = require('../core/receipt.js');
+const { uploadBlob } = require('./blob-uploader.js');
+const { createJmapConfig } = require('./config.js');
+const { JmapApiError } = require('./errors.js');
+const { JmapHttpClient } = require('./http-client.js');
+const { convertMessage } = require('./message-converter.js');
+const { findMailAccount } = require('./session.js');
+
+/**
+ * JMAP capabilities required for email sending.
+ */
+const JMAP_CAPABILITIES = {
+  core: 'urn:ietf:params:jmap:core',
+  mail: 'urn:ietf:params:jmap:mail',
+  submission: 'urn:ietf:params:jmap:submission',
+};
+
+/**
+ * JMAP transport for sending emails via JMAP protocol (RFC 8620/8621).
+ */
+class JmapTransport {
+  id = 'jmap';
+
+  config;
+  httpClient;
+  cachedSession = null;
+
+  /**
+   * Creates a new JMAP transport instance.
+   * @param config The JMAP transport configuration.
+   */
+  constructor(config) {
+    this.config = createJmapConfig(config);
+    this.httpClient = new JmapHttpClient(this.config);
+  }
+
+  /**
+   * Checks a fresh Session, the account used by send(), its drafts mailbox,
+   * and the configured or available identity without creating or sending mail.
+   * Does not read or update the session cache. Each discovery operation has
+   * config.timeout as its total budget, including response bodies and retries.
+   * Success does not guarantee acceptance of a particular sender or message.
+   * @param options Optional cancellation signal.
+   * @returns A promise that resolves when live verification succeeds.
+   * @throws {JmapApiError} If discovery, authentication, or validation fails.
+   * @throws The caller's abort reason if cancelled.
+   */
+  async verify(options) {
+    const signal = options?.signal;
+    signal?.throwIfAborted();
+    try {
+      let session = await verificationOperation(
+        this.config.timeout,
+        (owned) => this.httpClient.fetchSession(owned),
+        signal,
+      );
+      validateVerificationSession(session);
+      if (this.config.baseUrl) session = this.rewriteSessionUrls(session);
+      validateVerificationApiUrl(session.apiUrl);
+      if (!Object.values(JMAP_CAPABILITIES).every((cap) => cap in session.capabilities)) {
+        throw new JmapApiError('JMAP session lacks core, mail, or submission capability.');
+      }
+      const accountId = this.config.accountId ?? findMailAccount(session);
+      const account = accountId == null ? undefined : session.accounts[accountId];
+      if (accountId == null || account == null) {
+        throw new JmapApiError(`No JMAP mail account found: ${accountId ?? 'automatic selection'}`);
+      }
+      if (
+        account.isReadOnly ||
+        !(JMAP_CAPABILITIES.mail in account.accountCapabilities) ||
+        !(JMAP_CAPABILITIES.submission in account.accountCapabilities)
+      ) {
+        throw new JmapApiError(
+          `JMAP account must be writable with mail and submission capability: ${accountId}`,
+        );
+      }
+      // oxlint-disable-next-line no-shadow -- upstream
+      const get = async (method, args, signal) => {
+        const response = await verificationOperation(
+          this.config.timeout,
+          (owned) =>
+            this.httpClient.executeRequest(
+              session.apiUrl,
+              {
+                using:
+                  method === 'Mailbox/get'
+                    ? [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.mail]
+                    : [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.submission],
+                methodCalls: [[method, { accountId, ...args }, 'verify']],
+              },
+              owned,
+            ),
+          signal,
+        );
+        return verificationResult(response, method, accountId);
+      };
+      const mailboxes = await get('Mailbox/get', { properties: ['id', 'role'] }, signal);
+      if (!mailboxes.list.some((mailbox) => mailbox.role === 'drafts')) {
+        throw new JmapApiError(`No drafts mailbox found in JMAP account: ${accountId}`);
+      }
+      const identityId = this.config.identityId;
+      const identities = await get(
+        'Identity/get',
+        {
+          ids: identityId == null ? null : [identityId],
+          properties: ['id', 'email'],
+        },
+        signal,
+      );
+      if (
+        identities.notFound.length > 0 ||
+        identities.list.length === 0 ||
+        !identities.list.every(
+          (identity) => typeof identity.email === 'string' && identity.email.length > 0,
+        ) ||
+        (identityId != null &&
+          (identities.list.length !== 1 || identities.list[0].id !== identityId))
+      ) {
+        throw new JmapApiError(`No valid JMAP identity found: ${identityId ?? accountId}`);
+      }
+      signal?.throwIfAborted();
+    } catch (error) {
+      signal?.throwIfAborted();
+      if (error instanceof JmapApiError) throw error;
+      throw new JmapApiError(
+        `JMAP verification failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  /**
+   * Sends a single email message.
+   * @param message The message to send.
+   * @param options Optional transport options.
+   * @returns A receipt indicating success or failure.
+   * @throws The abort reason or an `AbortError` when the caller aborts the
+   *         operation.
+   */
+  async send(message, options) {
+    const signal = options?.signal;
+    signal?.throwIfAborted();
+
+    try {
+      // Get or refresh session
+      const session = await this.getSession(signal);
+      signal?.throwIfAborted();
+
+      // Get account ID
+      const accountId = this.config.accountId ?? findMailAccount(session);
+      if (!accountId) {
+        return createJmapFailure('No mail-capable account found in JMAP session', undefined, {
+          category: 'configuration',
+          code: 'jmap.no_mail_account',
+          retryable: false,
+        });
+      }
+
+      // Get drafts mailbox ID
+      const draftsMailboxId = await this.getDraftsMailboxId(session, accountId, signal);
+      signal?.throwIfAborted();
+
+      // Get identity ID
+      const identityId = await this.getIdentityId(
+        session,
+        accountId,
+        message.sender.address,
+        signal,
+      );
+      signal?.throwIfAborted();
+
+      // Upload attachments
+      const uploadedBlobs = await this.uploadAttachments(
+        session,
+        accountId,
+        message.attachments,
+        signal,
+      );
+      signal?.throwIfAborted();
+
+      // Convert message and send
+      const emailCreate = convertMessage(message, draftsMailboxId, uploadedBlobs);
+
+      // Execute Email/set + EmailSubmission/set batch request
+      const response = await this.httpClient.executeRequest(
+        session.apiUrl,
+        {
+          using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.mail, JMAP_CAPABILITIES.submission],
+          methodCalls: [
+            [
+              'Email/set',
+              {
+                accountId,
+                create: { draft: emailCreate },
+              },
+              'c0',
+            ],
+            [
+              'EmailSubmission/set',
+              {
+                accountId,
+                create: {
+                  submission: {
+                    identityId,
+                    emailId: '#draft',
+                  },
+                },
+              },
+              'c1',
+            ],
+          ],
+        },
+        signal,
+      );
+
+      // Parse response
+      return this.parseResponse(response);
+    } catch (error) {
+      if (signal?.aborted) {
+        throw getAbortReason(signal, error);
+      }
+
+      if (error instanceof Error && error.name === 'AbortError') {
+        return createJmapFailure(`Request aborted: ${error.message}`, error, {
+          category: 'timeout',
+          code: 'abort',
+          retryable: true,
+        });
+      }
+
+      if (error instanceof JmapApiError) {
+        return createJmapFailure(error.message, error);
+      }
+
+      return createJmapFailure(error instanceof Error ? error.message : String(error), error);
+    }
+  }
+
+  /**
+   * Uploads serialized MIME, imports it, and submits it with an explicit envelope.
+   * JMAP servers may modify imported or submitted messages, including removing
+   * Bcc. Import and submission are never retried automatically.
+   * @param message Original MIME and delivery envelope.
+   * @param options Optional cancellation signal.
+   * @returns A receipt; uncertain submission outcomes are non-retryable.
+   * @throws {Error} If cancellation is requested.
+   */
+  async sendRaw(message, options) {
+    if (message?.content instanceof Promise) message.content.catch(() => {});
+    const signal = options?.signal;
+    signal?.throwIfAborted();
+    try {
+      const plan = createRawMessagePlan(message);
+      const session = await rawOperation(
+        this.config.timeout,
+        (owned) => this.getSession(owned),
+        signal,
+      );
+      const capable = (id) => {
+        const account = session.accounts[id];
+        return (
+          account != null &&
+          !account.isReadOnly &&
+          JMAP_CAPABILITIES.mail in account.accountCapabilities &&
+          JMAP_CAPABILITIES.submission in account.accountCapabilities
+        );
+      };
+      const accountId = this.config.accountId ?? Object.keys(session.accounts).find(capable);
+      if (
+        accountId == null ||
+        !capable(accountId) ||
+        !Object.values(JMAP_CAPABILITIES).every((capability) => capability in session.capabilities)
+      ) {
+        return createJmapFailure('No writable mail and submission account found.', undefined, {
+          category: 'configuration',
+          code: 'jmap.no_mail_account',
+          retryable: false,
+        });
+      }
+      const drafts = await rawOperation(
+        this.config.timeout,
+        (owned) => this.getDraftsMailboxId(session, accountId, owned, true),
+        signal,
+      );
+      const identity = await rawOperation(
+        this.config.timeout,
+        (owned) => this.getIdentityId(session, accountId, plan.envelope.from ?? '', owned, true),
+        signal,
+      );
+      return await deliverRawMessage(
+        this.config,
+        session,
+        accountId,
+        drafts,
+        identity,
+        plan,
+        signal,
+      );
+    } catch (error) {
+      signal?.throwIfAborted();
+      return createJmapFailure(
+        error instanceof Error ? error.message : String(error),
+        error,
+        error instanceof RawMessageValidationError
+          ? {
+              category: 'validation',
+              code: 'jmap.raw_message_invalid',
+              retryable: false,
+            }
+          : undefined,
+      );
+    }
+  }
+
+  /**
+   * Sends multiple messages in a single batched JMAP request.
+   * @param messages The messages to send.
+   * @param options Optional transport options.
+   * @yields Receipts for each message.
+   * @throws The abort reason or an `AbortError` when the caller aborts the
+   *         operation.
+   */
+  async *sendMany(messages, options) {
+    const signal = options?.signal;
+
+    // Collect all messages into an array first
+    const messageArray = [];
+    for await (const message of messages) {
+      messageArray.push(message);
+    }
+
+    // If no messages, return early
+    if (messageArray.length === 0) {
+      return;
+    }
+
+    // Track processing stage for better error messages
+    let processingStage = 'initialization';
+    let attachmentsUploadedCount = 0;
+
+    try {
+      signal?.throwIfAborted();
+
+      // Get or refresh session (once)
+      processingStage = 'session fetch';
+      const session = await this.getSession(signal);
+      signal?.throwIfAborted();
+
+      // Get account ID (once)
+      processingStage = 'account discovery';
+      const accountId = this.config.accountId ?? findMailAccount(session);
+      if (!accountId) {
+        for (let i = 0; i < messageArray.length; i++) {
+          yield createJmapFailure('No mail-capable account found in JMAP session', undefined, {
+            category: 'configuration',
+            code: 'jmap.no_mail_account',
+            retryable: false,
+          });
+        }
+        return;
+      }
+
+      // Get drafts mailbox ID (once)
+      processingStage = 'mailbox discovery';
+      const draftsMailboxId = await this.getDraftsMailboxId(session, accountId, signal);
+      signal?.throwIfAborted();
+
+      // Get identities (once) and build a map
+      processingStage = 'identity resolution';
+      const identityMap = await this.getIdentityMap(session, accountId, signal);
+      signal?.throwIfAborted();
+
+      // Upload all attachments for all messages
+      processingStage = 'attachment upload';
+      const allUploadedBlobs = new Map();
+      for (let i = 0; i < messageArray.length; i++) {
+        const message = messageArray[i];
+        const uploadedBlobs = await this.uploadAttachments(
+          session,
+          accountId,
+          message.attachments,
+          signal,
+        );
+        allUploadedBlobs.set(i, uploadedBlobs);
+        attachmentsUploadedCount = i + 1;
+        signal?.throwIfAborted();
+      }
+
+      // Build batch Email/set and EmailSubmission/set create objects
+      processingStage = 'message conversion';
+      const emailCreates = {};
+      const submissionCreates = {};
+
+      for (let i = 0; i < messageArray.length; i++) {
+        const message = messageArray[i];
+        const uploadedBlobs = allUploadedBlobs.get(i);
+        const emailCreate = convertMessage(message, draftsMailboxId, uploadedBlobs);
+
+        // Find identity for this sender
+        const senderEmail = message.sender.address.toLowerCase();
+        const identityId = identityMap.get(senderEmail) ?? identityMap.values().next().value;
+
+        emailCreates[`draft${i}`] = emailCreate;
+        submissionCreates[`sub${i}`] = {
+          identityId,
+          emailId: `#draft${i}`,
+        };
+      }
+
+      // Execute batch request
+      processingStage = 'batch request execution';
+      const response = await this.httpClient.executeRequest(
+        session.apiUrl,
+        {
+          using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.mail, JMAP_CAPABILITIES.submission],
+          methodCalls: [
+            [
+              'Email/set',
+              {
+                accountId,
+                create: emailCreates,
+              },
+              'c0',
+            ],
+            [
+              'EmailSubmission/set',
+              {
+                accountId,
+                create: submissionCreates,
+              },
+              'c1',
+            ],
+          ],
+        },
+        signal,
+      );
+
+      // Parse batch response and yield individual receipts
+      for (let i = 0; i < messageArray.length; i++) {
+        yield this.parseBatchResponseForIndex(response, i);
+      }
+    } catch (error) {
+      if (signal?.aborted) {
+        throw getAbortReason(signal, error);
+      }
+
+      const timeoutOverride =
+        error instanceof Error && error.name === 'AbortError'
+          ? {
+              category: 'timeout',
+              code: 'abort',
+              retryable: true,
+            }
+          : undefined;
+
+      // For any error during batch processing, yield failure for all messages
+      // with detailed stage information
+      const baseMessage =
+        error instanceof Error && error.name === 'AbortError'
+          ? `Request aborted: ${error.message}`
+          : error instanceof JmapApiError
+            ? error.message
+            : error instanceof Error
+              ? error.message
+              : String(error);
+
+      // Build detailed error message with stage and progress info
+      let detailedMessage = `Failed during ${processingStage}: ${baseMessage}`;
+      if (processingStage === 'attachment upload' && attachmentsUploadedCount > 0) {
+        detailedMessage += ` (${attachmentsUploadedCount}/${messageArray.length} messages had attachments uploaded before failure)`;
+      }
+
+      for (let i = 0; i < messageArray.length; i++) {
+        yield createJmapFailure(detailedMessage, error, timeoutOverride);
+      }
+    }
+  }
+
+  /**
+   * Gets or refreshes the JMAP session.
+   * @param signal Optional abort signal.
+   * @returns The JMAP session.
+   */
+  async getSession(signal) {
+    const now = Date.now();
+
+    // Check cache
+    if (this.cachedSession && now - this.cachedSession.fetchedAt < this.config.sessionCacheTtl) {
+      return this.cachedSession.session;
+    }
+
+    // Fetch new session
+    let session = await this.httpClient.fetchSession(signal);
+
+    // Rewrite URLs if baseUrl is configured
+    if (this.config.baseUrl) {
+      session = this.rewriteSessionUrls(session);
+    }
+
+    // Cache it
+    this.cachedSession = {
+      session,
+      fetchedAt: now,
+    };
+
+    return session;
+  }
+
+  /**
+   * Rewrites session URLs to use the configured baseUrl.
+   * @param session The original session from the server.
+   * @returns A new session with rewritten URLs.
+   */
+  rewriteSessionUrls(session) {
+    const baseUrl = this.config.baseUrl;
+
+    const rewriteUrl = (url) => {
+      try {
+        // Parse just the base URL to get the target protocol and host
+        const base = new URL(baseUrl);
+        // Use regex to replace the protocol and host, preserving templates like {accountId}
+        return url.replace(/^(\w+):\/\/[^/]+/, `${base.protocol}//${base.host}`);
+      } catch {
+        return url;
+      }
+    };
+
+    return {
+      ...session,
+      apiUrl: rewriteUrl(session.apiUrl),
+      downloadUrl: rewriteUrl(session.downloadUrl),
+      uploadUrl: rewriteUrl(session.uploadUrl),
+      eventSourceUrl: session.eventSourceUrl ? rewriteUrl(session.eventSourceUrl) : undefined,
+    };
+  }
+
+  /**
+   * Gets the drafts mailbox ID from the session.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param signal Optional abort signal.
+   * @returns The drafts mailbox ID.
+   */
+  async getDraftsMailboxId(session, accountId, signal, strict = false) {
+    const response = await this.httpClient.executeRequest(
+      session.apiUrl,
+      {
+        using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.mail],
+        methodCalls: [
+          [
+            'Mailbox/get',
+            {
+              accountId,
+              properties: ['id', 'role', 'name'],
+            },
+            'c0',
+          ],
+        ],
+      },
+      signal,
+    );
+
+    const mailboxResponse = strict
+      ? rawDiscoveryResult(response, 'Mailbox/get', accountId)
+      : response.methodResponses.find((r) => r[0] === 'Mailbox/get')?.[1];
+
+    if (!mailboxResponse) {
+      throw new JmapApiError('No Mailbox/get response received');
+    }
+
+    const mailboxes = mailboxResponse.list;
+
+    if (!mailboxes) {
+      throw new JmapApiError('No mailboxes found');
+    }
+
+    if (
+      strict &&
+      (!Array.isArray(mailboxes) ||
+        !mailboxes.every(
+          (mailbox) => isRecord(mailbox) && typeof mailbox.id === 'string' && mailbox.id.length > 0,
+        ))
+    ) {
+      throw new JmapApiError('Invalid mailbox identifiers in raw discovery.');
+    }
+    // Find drafts mailbox
+    const drafts = mailboxes.find((m) => m.role === 'drafts');
+
+    if (!drafts) {
+      throw new JmapApiError('No drafts mailbox found');
+    }
+
+    return drafts.id;
+  }
+
+  /**
+   * Gets the identity ID for the sender.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param senderEmail The sender's email address.
+   * @param signal Optional abort signal.
+   * @returns The identity ID.
+   */
+  async getIdentityId(session, accountId, senderEmail, signal, strict = false) {
+    // If identity ID is configured, use it
+    if (this.config.identityId) {
+      return this.config.identityId;
+    }
+
+    const identityMap = await this.getIdentityMap(session, accountId, signal, strict);
+    const matching = identityMap.get(senderEmail.toLowerCase());
+    if (matching) {
+      return matching;
+    }
+
+    // Fall back to first identity
+    return identityMap.values().next().value;
+  }
+
+  /**
+   * Gets all identities and builds a map of email to identity ID.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param signal Optional abort signal.
+   * @returns Map of lowercase email to identity ID.
+   */
+  async getIdentityMap(session, accountId, signal, strict = false) {
+    // If identity ID is configured, return a map with just that
+    if (this.config.identityId) {
+      return new Map([['*', this.config.identityId]]);
+    }
+
+    const response = await this.httpClient.executeRequest(
+      session.apiUrl,
+      {
+        using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.submission],
+        methodCalls: [
+          [
+            'Identity/get',
+            {
+              accountId,
+            },
+            'c0',
+          ],
+        ],
+      },
+      signal,
+    );
+
+    const identityResponse = strict
+      ? rawDiscoveryResult(response, 'Identity/get', accountId)
+      : response.methodResponses.find((r) => r[0] === 'Identity/get')?.[1];
+
+    if (!identityResponse) {
+      throw new JmapApiError('No Identity/get response received');
+    }
+
+    const identities = identityResponse.list;
+
+    if (!identities || identities.length === 0) {
+      throw new JmapApiError('No identities found');
+    }
+
+    if (
+      strict &&
+      (!Array.isArray(identities) ||
+        !identities.every(
+          (identity) =>
+            isRecord(identity) &&
+            typeof identity.id === 'string' &&
+            identity.id.length > 0 &&
+            typeof identity.email === 'string',
+        ))
+    ) {
+      throw new JmapApiError('Invalid identity identifiers in raw discovery.');
+    }
+    const identityMap = new Map();
+    for (const identity of identities) {
+      identityMap.set(identity.email.toLowerCase(), identity.id);
+    }
+
+    return identityMap;
+  }
+
+  /**
+   * Uploads all attachments and returns a map of contentId to blobId.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param attachments Array of attachments to upload.
+   * @param signal Optional abort signal.
+   * @returns Map of contentId to blobId.
+   */
+  async uploadAttachments(session, accountId, attachments, signal) {
+    const uploadedBlobs = new Map();
+
+    for (const attachment of attachments) {
+      signal?.throwIfAborted();
+
+      const content = await readAttachmentContent(attachment.content, signal);
+
+      // Create a Blob from the Uint8Array
+      // Extract the ArrayBuffer portion to ensure TypeScript compatibility
+      const arrayBuffer = content.buffer.slice(
+        content.byteOffset,
+        content.byteOffset + content.byteLength,
+      );
+      const blob = new Blob([arrayBuffer], { type: attachment.contentType });
+
+      const result = await uploadBlob(this.config, session.uploadUrl, accountId, blob, signal);
+
+      uploadedBlobs.set(attachment.contentId, result.blobId);
+    }
+
+    return uploadedBlobs;
+  }
+
+  /**
+   * Parses the JMAP response to extract receipt information.
+   * @param response The JMAP response.
+   * @returns A receipt indicating success or failure.
+   */
+  parseResponse(response) {
+    const errors = [];
+
+    // Check Email/set response
+    const emailResponse = response.methodResponses.find((r) => r[0] === 'Email/set');
+
+    if (emailResponse) {
+      const emailResult = emailResponse[1];
+
+      if (emailResult.notCreated) {
+        for (const [key, error] of Object.entries(emailResult.notCreated)) {
+          errors.push(
+            `Email creation failed (${key}): ${error.type}${
+              error.description ? ` - ${error.description}` : ''
+            }`,
+          );
+        }
+      }
+    }
+
+    // Check EmailSubmission/set response
+    const submissionResponse = response.methodResponses.find((r) => r[0] === 'EmailSubmission/set');
+
+    if (submissionResponse) {
+      const submissionResult = submissionResponse[1];
+
+      if (submissionResult.notCreated) {
+        for (const [key, error] of Object.entries(submissionResult.notCreated)) {
+          errors.push(
+            `Email submission failed (${key}): ${error.type}${
+              error.description ? ` - ${error.description}` : ''
+            }`,
+          );
+        }
+      }
+
+      // Success case
+      if (submissionResult.created?.submission) {
+        return {
+          successful: true,
+          messageId: submissionResult.created.submission.id,
+          provider: 'jmap',
+        };
+      }
+    }
+
+    // If no errors but no success either, something is wrong
+    if (errors.length === 0) {
+      errors.push('Unknown error: No submission result received');
+    }
+
+    return createFailedReceipt(errors, {
+      provider: 'jmap',
+      category: 'rejected',
+      code: 'jmap.submission_failed',
+      retryable: false,
+    });
+  }
+
+  /**
+   * Parses the JMAP batch response to extract receipt for a specific index.
+   * @param response The JMAP response.
+   * @param index The message index in the batch.
+   * @returns A receipt indicating success or failure for that message.
+   */
+  parseBatchResponseForIndex(response, index) {
+    const errors = [];
+    const draftKey = `draft${index}`;
+    const subKey = `sub${index}`;
+
+    // Check Email/set response
+    const emailResponse = response.methodResponses.find((r) => r[0] === 'Email/set');
+
+    if (emailResponse) {
+      const emailResult = emailResponse[1];
+
+      if (emailResult.notCreated?.[draftKey]) {
+        const error = emailResult.notCreated[draftKey];
+        errors.push(
+          `Email creation failed: ${error.type}${
+            error.description ? ` - ${error.description}` : ''
+          }`,
+        );
+      }
+    }
+
+    // Check EmailSubmission/set response
+    const submissionResponse = response.methodResponses.find((r) => r[0] === 'EmailSubmission/set');
+
+    if (submissionResponse) {
+      const submissionResult = submissionResponse[1];
+
+      if (submissionResult.notCreated?.[subKey]) {
+        const error = submissionResult.notCreated[subKey];
+        errors.push(
+          `Email submission failed: ${error.type}${
+            error.description ? ` - ${error.description}` : ''
+          }`,
+        );
+      }
+
+      // Success case
+      if (submissionResult.created?.[subKey]) {
+        return {
+          successful: true,
+          messageId: submissionResult.created[subKey].id,
+          provider: 'jmap',
+        };
+      }
+    }
+
+    // If no errors but no success either
+    if (errors.length === 0) {
+      errors.push('Unknown error: No submission result received');
+    }
+
+    return createFailedReceipt(errors, {
+      provider: 'jmap',
+      category: 'rejected',
+      code: 'jmap.submission_failed',
+      retryable: false,
+    });
+  }
+}
+
+const createJmapFailure = (message, error, override = {}) => {
+  const attempts = getAttemptCount(error);
+
+  if (error instanceof JmapApiError) {
+    return createFailedReceipt(message, {
+      provider: 'jmap',
+      statusCode: error.statusCode,
+      retryAfterMilliseconds: error.retryAfterMilliseconds,
+      attempts,
+      providerDetails: {
+        responseBody: error.responseBody,
+        jmapErrorType: error.jmapErrorType,
+      },
+      category: override.category,
+      code: override.code,
+      retryable: override.retryable,
+    });
+  }
+
+  return createFailedReceipt(message, {
+    provider: 'jmap',
+    attempts,
+    category: override.category,
+    code: override.code,
+    retryable: override.retryable,
+  });
+};
+
+const getAttemptCount = (error) => {
+  if (error instanceof JmapApiError) {
+    return error.attempts ?? 1;
+  }
+
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    'attempts' in error &&
+    typeof error.attempts === 'number'
+  ) {
+    return error.attempts;
+  }
+
+  return 1;
+};
+
+const getAbortReason = (signal, fallback) => {
+  return (
+    signal.reason ??
+    (isAbortError(fallback) ? fallback : undefined) ??
+    new DOMException('The operation was aborted.', 'AbortError')
+  );
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+/** Bounds verification through body consumption, not just receipt of headers. */
+const verificationOperation = async (timeout, operation, signal) => {
+  const controller = new AbortController();
+  const combined = combineSignals(controller.signal, signal);
+  let onAbort;
+  const timer = setTimeout(
+    () => controller.abort(new JmapApiError('JMAP verification timed out.')),
+    timeout,
+  );
+  try {
+    combined.signal.throwIfAborted();
+    return await new Promise((resolve, reject) => {
+      onAbort = () => reject(combined.signal.reason);
+      combined.signal.addEventListener('abort', onAbort, { once: true });
+      Promise.resolve()
+        .then(() => {
+          combined.signal.throwIfAborted();
+          return operation(combined.signal);
+        })
+        .then(resolve, reject);
+      if (combined.signal.aborted) onAbort();
+    });
+  } finally {
+    clearTimeout(timer);
+    if (onAbort) combined.signal.removeEventListener('abort', onAbort);
+    controller.abort();
+    combined.cleanup();
+  }
+};
+
+const validateVerificationApiUrl = (value) => {
+  if (typeof value === 'string' && URL.canParse(value)) {
+    const url = new URL(value);
+    if (url.protocol === 'https:' || url.protocol === 'http:') return;
+  }
+  throw new JmapApiError('Invalid JMAP Session field: apiUrl');
+};
+
+const validateVerificationSession = (session) => {
+  if (!isRecord(session)) {
+    throw new JmapApiError('Invalid JMAP Session response.');
+  }
+  if (!isRecord(session.capabilities)) {
+    throw new JmapApiError('Invalid JMAP Session field: capabilities');
+  }
+  if (!isRecord(session.accounts)) {
+    throw new JmapApiError('Invalid JMAP Session field: accounts');
+  }
+  for (const [id, account] of Object.entries(session.accounts)) {
+    if (
+      !isRecord(account) ||
+      typeof account.isReadOnly !== 'boolean' ||
+      !isRecord(account.accountCapabilities)
+    ) {
+      throw new JmapApiError(`Invalid JMAP Session account: ${id}`);
+    }
+  }
+  validateVerificationApiUrl(session.apiUrl);
+};
+
+/** Validates only the discovery fields used by verification. */
+const verificationResult = (response, method, accountId) => {
+  if (!isRecord(response) || !Array.isArray(response.methodResponses)) {
+    throw new JmapApiError('Invalid JMAP verification response.');
+  }
+  const matches = response.methodResponses.filter(
+    (entry) => Array.isArray(entry) && entry[2] === 'verify',
+  );
+  if (matches.length !== 1) {
+    throw new JmapApiError('Missing or duplicate JMAP verification response.');
+  }
+  const entry = matches[0];
+  if (!Array.isArray(entry) || entry.length !== 3 || !isRecord(entry[1])) {
+    throw new JmapApiError('Invalid JMAP verification method response.');
+  }
+  const result = entry[1];
+  if (entry[0] === 'error') {
+    if (typeof result.type !== 'string' || !result.type) {
+      throw new JmapApiError('Invalid JMAP method error.');
+    }
+    throw new JmapApiError(
+      typeof result.description === 'string'
+        ? result.description
+        : `JMAP method failed: ${result.type}`,
+      undefined,
+      undefined,
+      result.type,
+    );
+  }
+  if (
+    entry[0] !== method ||
+    result.accountId !== accountId ||
+    !Array.isArray(result.list) ||
+    !Array.isArray(result.notFound)
+  ) {
+    throw new JmapApiError(`Invalid JMAP discovery result: ${method}`);
+  }
+  const list = [];
+  const ids = new Set();
+  for (const item of result.list) {
+    if (!isRecord(item) || typeof item.id !== 'string' || !item.id || ids.has(item.id)) {
+      throw new JmapApiError(`Invalid JMAP discovery identifiers: ${method}`);
+    }
+    ids.add(item.id);
+    list.push(item);
+  }
+  const notFound = [];
+  for (const id of result.notFound) {
+    if (typeof id !== 'string' || !id || ids.has(id)) {
+      throw new JmapApiError(`Contradictory JMAP discovery identifiers: ${method}`);
+    }
+    ids.add(id);
+    notFound.push(id);
+  }
+  if (
+    method === 'Mailbox/get' &&
+    (notFound.length > 0 ||
+      !list.every((item) => item.role == null || typeof item.role === 'string'))
+  ) {
+    throw new JmapApiError('Invalid JMAP mailbox discovery result.');
+  }
+  return { list, notFound };
+};
+
+module.exports = { JmapTransport };
diff --git a/src/jmap/message-converter.js b/src/jmap/message-converter.js
new file mode 100644
index 0000000..dbc0360
--- /dev/null
+++ b/src/jmap/message-converter.js
@@ -0,0 +1,392 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { resolveCalendarContent } = require('../core/calendar.js');
+const { parseMessageId } = require('../core/message-id.js');
+
+/**
+ * Formats an Upyo Address to JMAP email address format.
+ * @param address The Upyo address to format.
+ * @returns The JMAP email address object.
+ */
+const formatAddress = (address) => {
+  const result = {
+    email: address.address,
+  };
+
+  if (address.name) {
+    return { ...result, name: address.name };
+  }
+
+  return result;
+};
+
+/**
+ * Gets priority headers based on message priority.
+ * @param priority The message priority.
+ * @returns Array of JMAP headers for priority, or empty array for normal.
+ */
+const getPriorityHeaders = (priority) => {
+  switch (priority) {
+    case 'high':
+      return [
+        { name: 'X-Priority', value: '1' },
+        { name: 'Importance', value: 'high' },
+      ];
+    case 'low':
+      return [
+        { name: 'X-Priority', value: '5' },
+        { name: 'Importance', value: 'low' },
+      ];
+    default:
+      return [];
+  }
+};
+
+/**
+ * Header field names that must not be written as a raw header property.
+ *
+ * RFC 8621 §4.6 forbids two properties representing the same header field, and
+ * the `Email` here already carries a structured property for each of these.
+ * `Bcc` matters most: it travels in the submission envelope, so writing it into
+ * the message would disclose recipients meant to stay hidden.  `Content-*`
+ * belongs on an `EmailBodyPart` rather than on the `Email`.
+ */
+const structuredHeaders = new Set([
+  'bcc',
+  'cc',
+  'from',
+  'mime-version',
+  'reply-to',
+  'subject',
+  'to',
+]);
+
+/**
+ * Extracts the custom headers of a message, dropping those the `Email` object
+ * expresses through a structured property of its own.
+ *
+ * @param message The message to extract headers from.
+ * @returns Array of JMAP headers.
+ * @throws {TypeError} If a header value contains a carriage return or line
+ * feed, which would forge further header fields.
+ */
+const extractCustomHeaders = (message) => {
+  const headers = [];
+
+  for (const [name, value] of message.headers.entries()) {
+    const lowered = name.toLowerCase();
+    if (structuredHeaders.has(lowered) || lowered.startsWith('content-')) {
+      continue;
+    }
+    if (/[\r\n]/.test(value)) {
+      throw new TypeError(`Header field ${name} must not contain a carriage return or line feed.`);
+    }
+    headers.push({ name, value });
+  }
+
+  return headers;
+};
+
+/**
+ * Builds body structure for the message content.
+ * @param message The message to build body structure for.
+ * @param uploadedBlobs Map of contentId to blobId for attachments.
+ * @returns Object containing bodyStructure and bodyValues.
+ */
+const buildBodyStructure = (message, uploadedBlobs) => {
+  const bodyValues = {};
+  const parts = [];
+
+  // The bodies are tested for presence rather than for content, the way the
+  // SMTP composer does.  An empty string is a body the caller asked for, and
+  // dropping it would leave a scheduling message with the calendar as its only
+  // part, which RFC 6047 §2.1 asks not to happen: a recipient whose client
+  // knows nothing about scheduling would then see nothing at all.  An
+  // undefined one is not a body: `createMessage()` passes `content` through
+  // unchecked and `Message` is structural, so it can arrive that way, and it
+  // must not become a `bodyValues` entry holding a non-string.
+
+  // Text part (charset is inferred from bodyValues, not specified with partId)
+  if ('text' in message.content && message.content.text !== undefined) {
+    bodyValues['text'] = { value: message.content.text };
+    parts.push({ partId: 'text', type: 'text/plain; charset=utf-8' });
+  }
+
+  // HTML part
+  if ('html' in message.content && message.content.html !== undefined) {
+    bodyValues['html'] = { value: message.content.html };
+    parts.push({ partId: 'html', type: 'text/html; charset=utf-8' });
+  }
+
+  // Calendar part, last so that a client which schedules prefers it over the
+  // prose describing the same appointment (RFC 2046 §5.1.4).
+  if (message.calendar != null) {
+    // Re-validated rather than trusted: `Message` is a structural interface,
+    // and the method is written into a `Content-Type` parameter.
+    const calendar = resolveCalendarContent(message.calendar);
+    bodyValues['calendar'] = { value: calendar.content };
+    parts.push({
+      partId: 'calendar',
+      // RFC 8621 §4.1.4 describes `type` as the media type without parameters,
+      // and offers no property for the `method` RFC 6047 §2.4 requires.  The
+      // two ways of supplying it were measured against Stalwart: writing the
+      // field as `header:Content-Type` makes it emit that field *and* a
+      // derived one, so the part arrives with two `Content-Type` fields, while
+      // parameters on `type` are passed through and yield a single correct
+      // field.  The charset is left to the server, which appends its own and
+      // would otherwise duplicate the parameter.
+      type: `text/calendar; method=${calendar.method}`,
+    });
+  }
+
+  let contentPart;
+
+  if (parts.length === 1) {
+    // Simple single-part message
+    contentPart = parts[0];
+  } else if (parts.length > 1) {
+    // multipart/alternative for text + HTML
+    contentPart = {
+      type: 'multipart/alternative',
+      subParts: parts,
+    };
+  } else {
+    // Fallback to empty text
+    bodyValues['text'] = { value: '' };
+    contentPart = { partId: 'text', type: 'text/plain; charset=utf-8' };
+  }
+
+  // Separate inline and regular attachments
+  const inlineParts = buildInlineAttachmentParts(message.attachments, uploadedBlobs);
+  const attachmentParts = buildAttachmentParts(message.attachments, uploadedBlobs);
+
+  // If there are inline attachments, wrap content in multipart/related
+  let mainBodyPart;
+  if (inlineParts.length > 0) {
+    mainBodyPart = {
+      type: 'multipart/related',
+      subParts: [contentPart, ...inlineParts],
+    };
+  } else {
+    mainBodyPart = contentPart;
+  }
+
+  let bodyStructure;
+
+  // If there are regular attachments, wrap in multipart/mixed
+  if (attachmentParts.length > 0) {
+    bodyStructure = {
+      type: 'multipart/mixed',
+      subParts: [mainBodyPart, ...attachmentParts],
+    };
+  } else {
+    bodyStructure = mainBodyPart;
+  }
+
+  return { bodyStructure, bodyValues };
+};
+
+/**
+ * Build inline attachment parts from uploaded blobs.
+ * @param attachments Array of attachments from the message.
+ * @param uploadedBlobs Map of contentId to blobId.
+ * @returns Array of JmapBodyPart for inline attachments.
+ */
+const buildInlineAttachmentParts = (attachments, uploadedBlobs) => {
+  const parts = [];
+
+  for (const attachment of attachments) {
+    const blobId = uploadedBlobs.get(attachment.contentId);
+    if (!blobId) continue;
+
+    if (attachment.inline) {
+      parts.push({
+        type: attachment.contentType,
+        blobId,
+        name: attachment.filename,
+        disposition: 'inline',
+        cid: attachment.contentId,
+      });
+    }
+  }
+
+  return parts;
+};
+
+/**
+ * Build regular attachment parts from uploaded blobs.
+ * @param attachments Array of attachments from the message.
+ * @param uploadedBlobs Map of contentId to blobId.
+ * @returns Array of JmapBodyPart for regular attachments.
+ */
+const buildAttachmentParts = (attachments, uploadedBlobs) => {
+  const parts = [];
+
+  for (const attachment of attachments) {
+    const blobId = uploadedBlobs.get(attachment.contentId);
+    if (!blobId) continue;
+
+    if (!attachment.inline) {
+      parts.push({
+        type: attachment.contentType,
+        blobId,
+        name: attachment.filename,
+        disposition: 'attachment',
+      });
+    }
+  }
+
+  return parts;
+};
+
+/**
+ * Converts an Upyo Message to JMAP Email/set create format.
+ * @param message The Upyo message to convert.
+ * @param draftMailboxId The mailbox ID to store the draft in.
+ * @param uploadedBlobs Map of contentId to blobId for attachments.
+ * @returns The JMAP Email/set create object.
+ * @throws {TypeError} If the message carries an invalid message identifier or
+ * date, or a header value containing a carriage return or line feed.
+ * @throws {RangeError} If the year of the date is outside what an RFC 3339
+ * date-time can express.
+ */
+const convertMessage = (message, draftMailboxId, uploadedBlobs) => {
+  const { bodyStructure, bodyValues } = buildBodyStructure(message, uploadedBlobs);
+
+  const identity = resolveIdentity(message);
+
+  // RFC 8621 §4.6 allows only individual `header:Name` properties on create,
+  // never the `headers` list, and forbids a raw header that duplicates a
+  // structured property.
+  const headerProperties = {};
+  for (const { name, value } of getPriorityHeaders(message.priority)) {
+    headerProperties[`header:${name}`] = value;
+  }
+  for (const { name, value } of extractCustomHeaders(message)) {
+    if (identity.owned.has(name.toLowerCase())) continue;
+    headerProperties[`header:${name}`] = value;
+  }
+
+  const email = {
+    mailboxIds: { [draftMailboxId]: true },
+    from: [formatAddress(message.sender)],
+    subject: message.subject,
+    bodyStructure,
+    bodyValues,
+    ...(message.recipients.length > 0 && {
+      to: message.recipients.map(formatAddress),
+    }),
+    ...(message.ccRecipients.length > 0 && {
+      cc: message.ccRecipients.map(formatAddress),
+    }),
+    ...(message.bccRecipients.length > 0 && {
+      bcc: message.bccRecipients.map(formatAddress),
+    }),
+    ...(message.replyRecipients.length > 0 && {
+      replyTo: message.replyRecipients.map(formatAddress),
+    }),
+    ...identity.properties,
+    ...headerProperties,
+  };
+
+  return email;
+};
+
+/**
+ * Works out the identity and threading properties of an `Email` from the typed
+ * fields of a message.
+ *
+ * A field the message leaves unset is not owned, so a header supplied through
+ * {@link Message.headers} still reaches the server, and the server falls back
+ * to generating an identifier and a date of its own.  A threading field set to
+ * an empty list is owned but writes no property, which suppresses such a
+ * header.
+ *
+ * @param message The message being converted.
+ * @returns The properties to set, and the field names the message owns.
+ * @throws {TypeError} If a message identifier is invalid, or the date is not a
+ * valid one.
+ * @throws {RangeError} If the year of the date is outside what an RFC 3339
+ * date-time can express.
+ */
+const resolveIdentity = (message) => {
+  const owned = new Set();
+  const properties = {};
+
+  if (message.priority !== 'normal') {
+    owned.add('x-priority');
+    owned.add('importance');
+  }
+  if (message.messageId != null) {
+    owned.add('message-id');
+    properties.messageId = [checkMessageId(message.messageId)];
+  }
+  if (message.date != null) {
+    owned.add('date');
+    properties.sentAt = formatSentAt(message.date);
+  }
+  if (message.inReplyTo != null) {
+    owned.add('in-reply-to');
+    if (message.inReplyTo.length > 0) {
+      properties.inReplyTo = message.inReplyTo.map(checkMessageId);
+    }
+  }
+  if (message.references != null) {
+    owned.add('references');
+    if (message.references.length > 0) {
+      properties.references = message.references.map(checkMessageId);
+    }
+  }
+
+  return { properties, owned };
+};
+
+/**
+ * Checks a message identifier a message carries.
+ *
+ * `createMessage()` validates these, but `Message` is a structural type that a
+ * caller can build without it.
+ *
+ * @param id The identifier to check.
+ * @returns The identifier, unchanged.
+ * @throws {TypeError} If the value is not a valid message identifier.
+ */
+const checkMessageId = (id) => {
+  const parsed = parseMessageId(id);
+  if (parsed == null) {
+    throw new TypeError(`Invalid message ID: ${JSON.stringify(id)}`);
+  }
+  return parsed;
+};
+
+/**
+ * Formats a date as the RFC 3339 date-time JMAP calls a `Date`.
+ *
+ * RFC 8620 §1.4 omits a fractional-seconds part that is zero, which
+ * `Date.toISOString()` always writes.
+ *
+ * @param date The date to format.
+ * @returns The formatted date.
+ * @throws {TypeError} If the date is not a valid one.
+ * @throws {RangeError} If its year cannot be written as four digits.
+ */
+const formatSentAt = (date) => {
+  const time = date instanceof Date ? date.getTime() : Number.NaN;
+  if (Number.isNaN(time)) {
+    throw new TypeError(`Invalid date: ${JSON.stringify(date)}`);
+  }
+  const year = date.getUTCFullYear();
+  if (year < 1 || year > 9999) {
+    throw new RangeError(`Year out of range for an RFC 3339 date: ${year}`);
+  }
+  return date.toISOString().replace('.000Z', 'Z');
+};
+
+module.exports = {
+  formatAddress,
+  getPriorityHeaders,
+  extractCustomHeaders,
+  buildBodyStructure,
+  convertMessage,
+};
diff --git a/src/jmap/raw-delivery.js b/src/jmap/raw-delivery.js
new file mode 100644
index 0000000..0fe6dd9
--- /dev/null
+++ b/src/jmap/raw-delivery.js
@@ -0,0 +1,290 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/raw-delivery.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createFailedReceipt } = require('../core/receipt.js');
+const { RawMessageValidationError } = require('../core/raw-message.js');
+const { JMAP_ERROR_TYPES, JmapApiError } = require('./errors.js');
+const { JmapHttpClient } = require('./http-client.js');
+const { isRecord, rawOperation, uploadRawMessage } = require('./raw-upload.js');
+
+const using = [
+  'urn:ietf:params:jmap:core',
+  'urn:ietf:params:jmap:mail',
+  'urn:ietf:params:jmap:submission',
+];
+
+const failure = (message, stage, retryable, unknown = false, error) => {
+  return createFailedReceipt(message, {
+    provider: 'jmap',
+    code: `jmap.raw_${stage}_${unknown ? 'unknown' : 'failed'}`,
+    category: unknown
+      ? 'unknown'
+      : error?.statusCode !== undefined || retryable
+        ? undefined
+        : 'rejected',
+    statusCode: error?.statusCode,
+    retryAfterMilliseconds: error?.retryAfterMilliseconds,
+    providerDetails: error
+      ? {
+          responseBody: error.responseBody,
+          jmapErrorType: error.jmapErrorType,
+        }
+      : undefined,
+    retryable,
+    attempts: 1,
+  });
+};
+
+const methodResult = (response, name, id, accountId) => {
+  if (!isRecord(response) || !Array.isArray(response.methodResponses)) {
+    throw new JmapApiError('Invalid raw JMAP method response.');
+  }
+  const matches = response.methodResponses.filter(
+    (entry) => Array.isArray(entry) && entry[2] === id,
+  );
+  if (matches.length !== 1) {
+    throw new JmapApiError('Missing or contradictory raw JMAP method response.');
+  }
+  const result = matches[0];
+  if (
+    !Array.isArray(result) ||
+    result.length !== 3 ||
+    !isRecord(result[1]) ||
+    (result[0] !== name && result[0] !== 'error')
+  ) {
+    throw new JmapApiError('Invalid raw JMAP method result.');
+  }
+  if (result[0] === 'error') {
+    if (typeof result[1].type !== 'string' || !result[1].type) {
+      throw new JmapApiError('Invalid raw JMAP method error.');
+    }
+  } else if (result[1].accountId !== accountId) {
+    throw new JmapApiError('Wrong account in raw JMAP response.');
+  }
+  return { name: result[0], args: result[1] };
+};
+
+const creation = (args) => {
+  const created = isRecord(args.created) ? args.created.raw : undefined;
+  const rejected = isRecord(args.notCreated) ? args.notCreated.raw : undefined;
+  if (created !== undefined && rejected !== undefined) {
+    throw new JmapApiError('Contradictory raw JMAP creation result.');
+  }
+  if (isRecord(created) && typeof created.id === 'string' && created.id) {
+    return { created };
+  }
+  if (isRecord(rejected) && typeof rejected.type === 'string' && rejected.type) return { rejected };
+  throw new JmapApiError('Missing raw JMAP creation result.');
+};
+
+const errorDescription = (error) => {
+  return `Raw JMAP operation rejected: ${String(error.type)}${
+    typeof error.description === 'string' ? `: ${error.description}` : ''
+  }`;
+};
+
+const isRequestRejection = (error) => {
+  if (!(error instanceof JmapApiError)) return false;
+  // HTTP authentication failures reject the request regardless of body format.
+  if (error.statusCode === 401 || error.statusCode === 403) return true;
+  if (
+    !error.responseBody ||
+    error.statusCode === undefined ||
+    error.statusCode < 400 ||
+    error.statusCode > 599
+  ) {
+    return false;
+  }
+  try {
+    const body = JSON.parse(error.responseBody);
+    if (!isRecord(body) || (body.status !== undefined && body.status !== error.statusCode)) {
+      return false;
+    }
+    if (body.type === JMAP_ERROR_TYPES.limit) {
+      return typeof body.limit === 'string' && body.limit.length > 0;
+    }
+    return (
+      body.type === JMAP_ERROR_TYPES.notJSON ||
+      body.type === JMAP_ERROR_TYPES.notRequest ||
+      body.type === JMAP_ERROR_TYPES.unknownCapability
+    );
+  } catch {
+    return false;
+  }
+};
+
+/** Uploads, imports, then submits exactly once; uncertain submission must not be retried. @internal */
+const deliverRawMessage = async (
+  config,
+  session,
+  accountId,
+  draftsMailboxId,
+  identityId,
+  plan,
+  signal,
+) => {
+  // Mutations must never inherit the composed transport's automatic retries.
+  const client = new JmapHttpClient({ ...config, retries: 0 }, false);
+  const execute = (request) =>
+    rawOperation(
+      config.timeout,
+      (owned) => client.executeRequest(session.apiUrl, request, owned),
+      signal,
+    );
+  let stage = 'upload';
+  try {
+    const uploaded = await uploadRawMessage(config, session.uploadUrl, accountId, plan, signal);
+    signal?.throwIfAborted();
+    stage = 'import';
+    const imported = methodResult(
+      await execute({
+        using,
+        methodCalls: [
+          [
+            'Email/import',
+            {
+              accountId,
+              emails: {
+                raw: {
+                  blobId: uploaded.blobId,
+                  mailboxIds: { [draftsMailboxId]: true },
+                },
+              },
+            },
+            'raw-import',
+          ],
+        ],
+      }),
+      'Email/import',
+      'raw-import',
+      accountId,
+    );
+    if (imported.name === 'error') {
+      return failure(
+        errorDescription(imported.args),
+        'import',
+        imported.args.type === 'serverPartialFail',
+      );
+    }
+    const { created, rejected } = creation(imported.args);
+    let emailId;
+    if (created && typeof created.id === 'string') emailId = created.id;
+    else if (
+      rejected?.type === 'alreadyExists' &&
+      typeof rejected.existingId === 'string' &&
+      rejected.existingId
+    ) {
+      const existing = methodResult(
+        await execute({
+          using,
+          methodCalls: [
+            [
+              'Email/get',
+              {
+                accountId,
+                ids: [rejected.existingId],
+                properties: ['id', 'blobId'],
+              },
+              'raw-existing',
+            ],
+          ],
+        }),
+        'Email/get',
+        'raw-existing',
+        accountId,
+      );
+      const list = existing.args.list;
+      if (
+        existing.name === 'error' ||
+        !Array.isArray(list) ||
+        list.length !== 1 ||
+        !isRecord(list[0]) ||
+        list[0].id !== rejected.existingId ||
+        list[0].blobId !== uploaded.blobId
+      ) {
+        return failure('Existing Email does not match the uploaded raw blob.', 'import', false);
+      }
+      emailId = rejected.existingId;
+    } else {
+      return failure(errorDescription(rejected ?? { type: 'invalidResult' }), 'import', false);
+    }
+    signal?.throwIfAborted();
+    stage = 'submission';
+    const submitted = methodResult(
+      await execute({
+        using,
+        methodCalls: [
+          [
+            'EmailSubmission/set',
+            {
+              accountId,
+              create: {
+                raw: {
+                  emailId,
+                  identityId,
+                  envelope: {
+                    mailFrom: { email: plan.envelope.from ?? '' },
+                    rcptTo: plan.envelope.to.map((email) => ({ email })),
+                  },
+                },
+              },
+            },
+            'raw-submit',
+          ],
+        ],
+      }),
+      'EmailSubmission/set',
+      'raw-submit',
+      accountId,
+    );
+    if (submitted.name === 'error') {
+      // RFC 8620 permits partial state changes for serverPartialFail.
+      return failure(
+        errorDescription(submitted.args),
+        'submission',
+        false,
+        submitted.args.type === 'serverPartialFail',
+      );
+    }
+    const result = creation(submitted.args);
+    if (result.rejected) {
+      return failure(errorDescription(result.rejected), 'submission', false);
+    }
+    if (!result.created || typeof result.created.id !== 'string') {
+      throw new JmapApiError('Missing raw submission ID.');
+    }
+    signal?.throwIfAborted();
+    return { successful: true, provider: 'jmap', messageId: result.created.id };
+  } catch (error) {
+    signal?.throwIfAborted();
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof RawMessageValidationError) {
+      return createFailedReceipt(message, {
+        provider: 'jmap',
+        code: 'jmap.raw_message_invalid',
+        category: 'validation',
+        retryable: false,
+        attempts: 1,
+      });
+    }
+    const definite = isRequestRejection(error);
+    return failure(
+      message,
+      stage,
+      stage !== 'submission' && !definite,
+      stage === 'submission' && !definite,
+      error instanceof JmapApiError ? error : undefined,
+    );
+  }
+};
+
+/** Validates raw discovery responses before accepting delivery identifiers. @internal */
+const rawDiscoveryResult = (response, method, accountId) => {
+  const result = methodResult(response, method, 'c0', accountId);
+  if (result.name === 'error') {
+    throw new JmapApiError(errorDescription(result.args));
+  }
+  return result.args;
+};
+
+module.exports = { deliverRawMessage, rawDiscoveryResult };
diff --git a/src/jmap/raw-upload.js b/src/jmap/raw-upload.js
new file mode 100644
index 0000000..6fec3e9
--- /dev/null
+++ b/src/jmap/raw-upload.js
@@ -0,0 +1,205 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/raw-upload.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { analyzeRawMessage, iterateRawMessage } = require('../core/raw-message.js');
+const { combineSignals } = require('../core/abort-signal.js');
+const { parseRetryAfter } = require('../core/receipt.js');
+const { JmapApiError } = require('./errors.js');
+
+/** Runs a raw operation with a progress-resettable deadline through response parsing. @internal */
+const rawOperation = async (timeout, operation, signal) => {
+  const controller = new AbortController();
+  const combined = combineSignals(controller.signal, signal);
+  let timer;
+  let finished = false;
+  const progress = () => {
+    if (finished) return;
+    clearTimeout(timer);
+    timer = setTimeout(
+      () => controller.abort(new JmapApiError('Raw JMAP operation timed out.')),
+      timeout,
+    );
+  };
+  let abort;
+  try {
+    combined.signal.throwIfAborted();
+    progress();
+    return await new Promise((resolve, reject) => {
+      abort = () => reject(combined.signal.reason);
+      combined.signal.addEventListener('abort', abort, { once: true });
+      Promise.resolve()
+        .then(() => {
+          combined.signal.throwIfAborted();
+          return operation(combined.signal, progress);
+        })
+        .then(resolve, reject);
+      if (combined.signal.aborted) abort();
+    });
+  } finally {
+    finished = true;
+    clearTimeout(timer);
+    if (abort) combined.signal.removeEventListener('abort', abort);
+    controller.abort();
+    combined.cleanup();
+  }
+};
+
+/** @internal */
+const isRecord = (value) => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+/** Streams validated MIME bytes without relying on fetch to cancel its body. @internal */
+const uploadRawMessage = async (config, uploadUrl, accountId, plan, signal) => {
+  return await rawOperation(
+    config.timeout,
+    async (outerSignal, progress) => {
+      const analysis =
+        plan.encoding === undefined
+          ? await analyzeRawMessage(plan, outerSignal, progress)
+          : { encoding: plan.encoding, size: plan.size };
+      outerSignal.throwIfAborted();
+      const controller = new AbortController();
+      const combined = combineSignals(controller.signal, outerSignal);
+      const owned = combined.signal;
+      const iterator = iterateRawMessage(plan, {
+        signal: owned,
+        encoding: analysis.encoding,
+        expectedSize: analysis.size,
+        onProgress: progress,
+      })[Symbol.asyncIterator]();
+      let closed = false;
+      let eof = false;
+      let size = 0;
+      let sourceError;
+      let hasSourceError = false;
+      let bodyController;
+      const close = (reason) => {
+        if (closed) return;
+        closed = true;
+        controller.abort(reason);
+        if (!eof) {
+          try {
+            Promise.resolve(iterator.return?.()).catch(() => {});
+          } catch {
+            /* Preserve the original failure. */
+          }
+        }
+      };
+      const abort = () => {
+        try {
+          bodyController?.error(owned.reason);
+        } catch {
+          /* Already closed. */
+        }
+        close(owned.reason);
+      };
+      const body = new ReadableStream(
+        {
+          start(stream) {
+            bodyController = stream;
+            owned.addEventListener('abort', abort, { once: true });
+            if (owned.aborted) abort();
+          },
+          async pull(stream) {
+            try {
+              owned.throwIfAborted();
+              const item = await iterator.next();
+              owned.throwIfAborted();
+              if (item.done) {
+                eof = true;
+                progress();
+                stream.close();
+              } else {
+                size += item.value.length;
+                stream.enqueue(new Uint8Array(item.value));
+              }
+            } catch (error) {
+              if (!owned.aborted && !hasSourceError) {
+                hasSourceError = true;
+                sourceError = error;
+              }
+              try {
+                stream.error(error);
+              } catch {
+                /* Already closed. */
+              }
+              close(error);
+            }
+          },
+          cancel: close,
+        },
+        { highWaterMark: 0 },
+      );
+      const headers = new Headers(config.headers);
+      if (!headers.has('Authorization')) {
+        if (config.bearerToken) {
+          headers.set('Authorization', `Bearer ${config.bearerToken}`);
+        } else if (config.basicAuth) {
+          headers.set(
+            'Authorization',
+            `Basic ${btoa(`${config.basicAuth.username}:${config.basicAuth.password}`)}`,
+          );
+        }
+      }
+      headers.set('Content-Type', 'message/rfc822');
+      const request = {
+        method: 'POST',
+        headers,
+        body,
+        duplex: 'half',
+        redirect: 'error',
+        // Runtime cancellation of the request body must not discard a response.
+        // The owned signal stops source reads; the outer signal controls HTTP.
+        signal: outerSignal,
+      };
+      try {
+        const response = await fetch(
+          uploadUrl.replace('{accountId}', encodeURIComponent(accountId)),
+          request,
+        );
+        outerSignal.throwIfAborted();
+        if (!response.ok) {
+          throw new JmapApiError(
+            `Raw upload failed: ${response.status}`,
+            response.status,
+            await response.text(),
+            undefined,
+            parseRetryAfter(response.headers.get('Retry-After')),
+          );
+        }
+        if (!eof) {
+          throw new JmapApiError('Raw upload responded before validated EOF.');
+        }
+        const result = await response.json();
+        outerSignal.throwIfAborted();
+        if (
+          !isRecord(result) ||
+          result.accountId !== accountId ||
+          typeof result.blobId !== 'string' ||
+          !result.blobId ||
+          result.size !== size
+        ) {
+          throw new JmapApiError('Invalid raw upload response.');
+        }
+        return {
+          accountId,
+          blobId: result.blobId,
+          size,
+          type: typeof result.type === 'string' ? result.type : 'message/rfc822',
+        };
+      } catch (error) {
+        outerSignal.throwIfAborted();
+        if (hasSourceError) throw sourceError;
+        throw error;
+      } finally {
+        owned.removeEventListener('abort', abort);
+        close();
+        combined.cleanup();
+      }
+    },
+    signal,
+  );
+};
+
+module.exports = { rawOperation, isRecord, uploadRawMessage };
diff --git a/src/jmap/session.js b/src/jmap/session.js
new file mode 100644
index 0000000..73830e0
--- /dev/null
+++ b/src/jmap/session.js
@@ -0,0 +1,18 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/session.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Finds the first account with mail capability from a JMAP session.
+ * @param session The JMAP session response.
+ * @returns The account ID with mail capability, or `null` if none found.
+ */
+const findMailAccount = (session) => {
+  for (const [accountId, account] of Object.entries(session.accounts)) {
+    if ('urn:ietf:params:jmap:mail' in account.accountCapabilities) {
+      return accountId;
+    }
+  }
+  return null;
+};
+
+module.exports = { findMailAccount };
diff --git a/tests/e2e/jmap-transport.e2e.test.js b/tests/e2e/jmap-transport.e2e.test.js
new file mode 100644
index 0000000..b44a2ca
--- /dev/null
+++ b/tests/e2e/jmap-transport.e2e.test.js
@@ -0,0 +1,543 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/jmap-transport.e2e.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * End-to-end tests for JmapTransport with Stalwart Mail Server.
+ *
+ * These tests require a running Stalwart Mail Server instance with JMAP enabled.
+ * Set the following environment variables:
+ * - STALWART_SESSION_URL: The JMAP session URL (e.g., http://localhost:8080/.well-known/jmap)
+ * - STALWART_BEARER_TOKEN: A valid bearer token for authentication
+ *
+ * To run these tests:
+ * 1. Start Stalwart: docker-compose up -d
+ * 2. Configure a test account in Stalwart
+ * 3. Set the environment variables
+ * 4. Run: deno test src/jmap-transport.e2e.test.ts
+ *
+ * @module
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+const {
+  createTestMessage,
+  getTestConfig,
+  isStalwartTestingEnabled,
+} = require('../helpers/jmap/test-config.js');
+
+describe('JmapTransport E2E Tests', { skip: !isStalwartTestingEnabled(), concurrency: 1 }, () => {
+  if (!isStalwartTestingEnabled()) return;
+
+  for (const encoding of ['7bit', undefined]) {
+    it(`should upload and import raw MIME unchanged (${encoding ?? 'automatic'})`, async () => {
+      const config = getTestConfig();
+      const transport = new JmapTransport(config.jmap);
+      const subject = `Raw JMAP ${crypto.randomUUID()}`;
+      const metadata = createTestMessage({ subject });
+      const original = [
+        `From: ${metadata.sender.address}`,
+        `To: ${metadata.recipients[0].address}`,
+        `Bcc: ${metadata.recipients[0].address}`,
+        `Subject: ${subject}`,
+        `Message-ID: <${crypto.randomUUID()}@mail.example.com>`,
+        'Date: Tue, 1 Sep 2026 00:00:00 +0000',
+        'MIME-Version: 1.0',
+        'Content-Type: text/plain; charset=utf-8',
+        'X-Preserved: first',
+        ' second',
+        '',
+        '.original raw body',
+        '',
+      ].join('\r\n');
+      let opens = 0;
+      const receipt = await transport.sendRaw({
+        envelope: {
+          from: metadata.sender.address,
+          to: metadata.recipients.map((r) => r.address),
+        },
+        encoding,
+        content: async function* () {
+          opens++;
+          yield new TextEncoder().encode(original);
+        },
+      });
+      assert.ok(receipt.successful, JSON.stringify(receipt));
+      assert.equal(opens, encoding === undefined ? 2 : 1);
+      // Inspect the imported Email, separately from any outgoing server
+      // transformations such as stripping Bcc during submission.
+      assert.equal(await downloadComposedMime(config, subject), original);
+    });
+  }
+
+  it('should send a basic text email', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    const message = createTestMessage({
+      subject: 'E2E Test - Basic Text',
+      content: { text: 'This is a test email sent via JMAP E2E test.' },
+    });
+
+    const receipt = await transport.send(message);
+
+    assert.ok(receipt.successful);
+    if (receipt.successful) {
+      assert.ok(receipt.messageId.length > 0);
+    }
+  });
+
+  it('should preserve the identity and threading fields', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    const subject = `E2E Test - Identity ${Date.now()}`;
+    const messageId = `ticket-${Date.now()}@mail.example.com`;
+    const receipt = await transport.send(
+      createTestMessage({
+        subject,
+        content: { text: 'Correlating a reply back to a conversation.' },
+        messageId,
+        date: new Date('2026-09-01T10:00:00Z'),
+        inReplyTo: ['122@mail.example.com'],
+        references: ['120@mail.example.com', '121@mail.example.com'],
+      }),
+    );
+    assert.ok(receipt.successful);
+
+    // Read the stored Email back, so what is asserted is what the server
+    // kept rather than what the client sent.
+    const stored = await fetchStoredEmail(config, subject);
+
+    assert.deepEqual(stored.messageId, [messageId]);
+    assert.equal(stored.sentAt, '2026-09-01T10:00:00Z');
+    assert.deepEqual(stored.inReplyTo, ['122@mail.example.com']);
+    assert.deepEqual(stored.references, ['120@mail.example.com', '121@mail.example.com']);
+  });
+
+  it('should send an HTML email', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    const message = createTestMessage({
+      subject: 'E2E Test - HTML Content',
+      content: {
+        html: '<h1>Test Email</h1><p>This is an <strong>HTML</strong> email.</p>',
+      },
+    });
+
+    const receipt = await transport.send(message);
+
+    if (!receipt.successful) {
+      console.error('HTML email test failed:', receipt.errorMessages);
+    }
+    assert.ok(receipt.successful);
+  });
+
+  it('should send an email with both text and HTML', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    const message = createTestMessage({
+      subject: 'E2E Test - Text and HTML',
+      content: {
+        text: 'Plain text version',
+        html: '<p>HTML version</p>',
+      },
+    });
+
+    const receipt = await transport.send(message);
+
+    assert.ok(receipt.successful);
+  });
+
+  it('should compose a text/calendar alternative carrying the method', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+    const subject = `E2E Test - Calendar ${crypto.randomUUID()}`;
+    const ics =
+      [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        'PRODID:-//Upyo//E2E//EN',
+        'METHOD:REQUEST',
+        'BEGIN:VEVENT',
+        'UID:e2e-calendar@example.com',
+        'DTSTAMP:20260901T100000Z',
+        'DTSTART:20260902T100000Z',
+        'SUMMARY:점심 식사',
+        'END:VEVENT',
+        'END:VCALENDAR',
+      ].join('\r\n') + '\r\n';
+
+    const receipt = await transport.send(
+      createTestMessage({
+        subject,
+        content: { text: 'Lunch on Wednesday.' },
+        calendar: { method: 'REQUEST', content: ics },
+      }),
+    );
+
+    assert.ok(receipt.successful);
+
+    const mime = await downloadComposedMime(config, subject);
+
+    // The media type and the method parameter both have to survive: RFC 6047
+    // §2.4 makes the parameter the thing a client keys on.
+    const contentType = mime
+      .split(/\r?\n/)
+      .find((line) => /^Content-Type:\s*text\/calendar/i.test(line));
+    assert.ok(contentType != null, `no text/calendar part in the composed message:\n${mime}`);
+    assert.match(contentType, /method=["]?REQUEST["]?/i);
+    assert.match(mime, /multipart\/alternative/i);
+
+    // And the object itself has to come back byte for byte, the multi-byte
+    // SUMMARY included, whatever transfer encoding the server chose.
+    assert.equal(decodeCalendarPart(mime), ics);
+  });
+
+  /**
+   * Extracts and decodes the `text/calendar` part of a composed message,
+   * whichever transfer encoding the server chose for it.
+   */
+  function decodeCalendarPart(mime) {
+    const marker = mime.search(/^Content-Type:\s*text\/calendar/im);
+    assert.ok(marker >= 0, 'no text/calendar part');
+    const headerEnd = mime.indexOf('\r\n\r\n', marker);
+    const partHeaders = mime.slice(marker, headerEnd);
+    const body = mime.slice(headerEnd + 4);
+    // The CRLF that introduces the boundary delimiter belongs to the
+    // boundary, not to the body (RFC 2046 §5.1.1).
+    const boundary = body.search(/\r\n--/);
+    const payload = boundary < 0 ? body : body.slice(0, boundary);
+    const encoding =
+      /Content-Transfer-Encoding:\s*(\S+)/i.exec(partHeaders)?.[1]?.toLowerCase() ?? '7bit';
+
+    if (encoding === 'base64') {
+      return new TextDecoder().decode(
+        Uint8Array.from(atob(payload.replace(/\s/g, '')), (character) => character.charCodeAt(0)),
+      );
+    }
+    if (encoding === 'quoted-printable') {
+      // Undo the soft line breaks, then read the escapes back as the bytes
+      // they name, so that a multi-byte character survives the round trip.
+      const unwrapped = payload.replace(/=\r\n/g, '');
+      const bytes = [];
+      for (let i = 0; i < unwrapped.length; i++) {
+        if (unwrapped[i] === '=' && i + 2 < unwrapped.length) {
+          bytes.push(parseInt(unwrapped.slice(i + 1, i + 3), 16));
+          i += 2;
+        } else bytes.push(unwrapped.charCodeAt(i));
+      }
+      return new TextDecoder().decode(Uint8Array.from(bytes));
+    }
+    return payload;
+  }
+
+  it('should send an email with attachment', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    const textContent = 'Hello from attachment!';
+    const textBytes = new TextEncoder().encode(textContent);
+
+    const message = createTestMessage({
+      subject: 'E2E Test - Attachment',
+      content: { text: 'This email has an attachment.' },
+      attachments: [
+        {
+          filename: 'test.txt',
+          contentType: 'text/plain',
+          content: textBytes,
+          contentId: 'test-attachment',
+          inline: false,
+        },
+      ],
+    });
+
+    const receipt = await transport.send(message);
+
+    if (!receipt.successful) {
+      console.error('Attachment test failed:', receipt.errorMessages);
+    }
+    assert.ok(receipt.successful);
+  });
+
+  it('should send an email with inline image', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    // 1x1 transparent PNG
+    const pngBytes = new Uint8Array([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
+      0x52, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1f,
+      0x15, 0xc4, 0x89, 0x00, 0x00, 0x00, 0x0a, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x63, 0x00,
+      0x01, 0x00, 0x00, 0x05, 0x00, 0x01, 0x0d, 0x0a, 0x2d, 0xb4, 0x00, 0x00, 0x00, 0x00, 0x49,
+      0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
+    ]);
+
+    const message = createTestMessage({
+      subject: 'E2E Test - Inline Image',
+      content: {
+        html: '<p>This email has an inline image:</p><img src="cid:inline-image">',
+      },
+      attachments: [
+        {
+          filename: 'image.png',
+          contentType: 'image/png',
+          content: pngBytes,
+          contentId: 'inline-image',
+          inline: true,
+        },
+      ],
+    });
+
+    const receipt = await transport.send(message);
+
+    if (!receipt.successful) {
+      console.error('Inline image test failed:', receipt.errorMessages);
+    }
+    assert.ok(receipt.successful);
+  });
+
+  it('should handle Korean characters in subject and body', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    const message = createTestMessage({
+      subject: 'E2E Test - 한글 테스트 🌍',
+      content: {
+        text: '안녕하세요! 이것은 한국어 테스트입니다. 🚀',
+        html: '<p>안녕하세요! 이것은 한국어 테스트입니다. 🚀</p>',
+      },
+    });
+
+    const receipt = await transport.send(message);
+
+    assert.ok(receipt.successful);
+  });
+
+  it('should send multiple emails with sendMany in a single batch', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    const messages = [
+      createTestMessage({
+        subject: 'E2E Test - Batch 1',
+        content: { text: 'First email in batch' },
+      }),
+      createTestMessage({
+        subject: 'E2E Test - Batch 2',
+        content: { text: 'Second email in batch' },
+      }),
+      createTestMessage({
+        subject: 'E2E Test - Batch 3',
+        content: { text: 'Third email in batch' },
+      }),
+    ];
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      if (!receipt.successful) {
+        console.error('sendMany test failed:', receipt.errorMessages);
+      }
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 3);
+    assert.ok(receipts.every((r) => r.successful));
+
+    // Verify each message has a unique submission ID
+    if (receipts.every((r) => r.successful)) {
+      const messageIds = receipts.map((r) => (r.successful ? r.messageId : null));
+      const uniqueIds = new Set(messageIds);
+      assert.equal(uniqueIds.size, 3, 'Each message should have a unique submission ID');
+    }
+  });
+
+  it('should batch emails with attachments via sendMany', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    const textBytes = new TextEncoder().encode('Attachment content');
+
+    const messages = [
+      createTestMessage({
+        subject: 'E2E Test - Batch with Attachment 1',
+        content: { text: 'First email with attachment' },
+        attachments: [
+          {
+            filename: 'file1.txt',
+            contentType: 'text/plain',
+            content: textBytes,
+            contentId: 'attachment-1',
+            inline: false,
+          },
+        ],
+      }),
+      createTestMessage({
+        subject: 'E2E Test - Batch with Attachment 2',
+        content: { text: 'Second email with attachment' },
+        attachments: [
+          {
+            filename: 'file2.txt',
+            contentType: 'text/plain',
+            content: textBytes,
+            contentId: 'attachment-2',
+            inline: false,
+          },
+        ],
+      }),
+    ];
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany(messages)) {
+      if (!receipt.successful) {
+        console.error('sendMany with attachments failed:', receipt.errorMessages);
+      }
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 2);
+    assert.ok(receipts.every((r) => r.successful));
+  });
+
+  it('should respect abort signal', async () => {
+    const config = getTestConfig();
+    const transport = new JmapTransport(config.jmap);
+
+    const controller = new AbortController();
+    controller.abort();
+
+    const message = createTestMessage({
+      subject: 'E2E Test - Should be aborted',
+      content: { text: 'This should not be sent' },
+    });
+
+    await assert.rejects(
+      () => transport.send(message, { signal: controller.signal }),
+      (error) => error instanceof Error && error.name === 'AbortError',
+    );
+  });
+
+  /**
+   * Downloads the RFC 5322 message the server composed for a subject, which
+   * is the only way to see whether a part header survived `Email/set`.
+   */
+  async function downloadComposedMime(config, subject) {
+    const { sessionUrl, basicAuth, bearerToken, baseUrl } = config.jmap;
+    const authorization =
+      bearerToken == null
+        ? `Basic ${btoa(`${basicAuth.username}:${basicAuth.password}`)}`
+        : `Bearer ${bearerToken}`;
+    const headers = {
+      authorization,
+      'content-type': 'application/json',
+    };
+
+    const session = await (await fetch(sessionUrl, { headers })).json();
+    const accountId = session.primaryAccounts['urn:ietf:params:jmap:mail'];
+    const rebase = (url) =>
+      baseUrl == null ? url : new URL(new URL(url).pathname + new URL(url).search, baseUrl).href;
+    const apiUrl = rebase(session.apiUrl);
+
+    const response = await (
+      await fetch(apiUrl, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'],
+          methodCalls: [
+            ['Email/query', { accountId, filter: { subject } }, 'query'],
+            [
+              'Email/get',
+              {
+                accountId,
+                '#ids': {
+                  resultOf: 'query',
+                  name: 'Email/query',
+                  path: '/ids',
+                },
+                properties: ['blobId'],
+              },
+              'get',
+            ],
+          ],
+        }),
+      })
+    ).json();
+
+    const emails = response.methodResponses.find((call) => call[2] === 'get')?.[1]?.list;
+    assert.ok(
+      emails != null && emails.length > 0,
+      `no stored Email found for subject ${JSON.stringify(subject)}`,
+    );
+
+    const downloadUrl = session.downloadUrl
+      .replace('{accountId}', encodeURIComponent(accountId))
+      .replace('{blobId}', encodeURIComponent(emails[0].blobId))
+      .replace('{type}', encodeURIComponent('message/rfc822'))
+      .replace('{name}', encodeURIComponent('message.eml'));
+    const download = await fetch(rebase(downloadUrl), {
+      headers: { authorization },
+    });
+    assert.ok(download.ok, `download failed: ${download.status}`);
+    return await download.text();
+  }
+
+  /**
+   * Reads back the stored Email with a given subject through raw JMAP, so
+   * that an assertion sees the server's own representation.
+   */
+  async function fetchStoredEmail(config, subject) {
+    const { sessionUrl, basicAuth, bearerToken, baseUrl } = config.jmap;
+    const authorization =
+      bearerToken == null
+        ? `Basic ${btoa(`${basicAuth.username}:${basicAuth.password}`)}`
+        : `Bearer ${bearerToken}`;
+    const headers = {
+      authorization,
+      'content-type': 'application/json',
+    };
+
+    const session = await (await fetch(sessionUrl, { headers })).json();
+    const accountId = session.primaryAccounts['urn:ietf:params:jmap:mail'];
+    // The session advertises the server's own hostname, which is not what
+    // reaches it from outside its container.
+    const apiUrl =
+      baseUrl == null ? session.apiUrl : new URL(new URL(session.apiUrl).pathname, baseUrl).href;
+    const response = await (
+      await fetch(apiUrl, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          using: ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'],
+          methodCalls: [
+            ['Email/query', { accountId, filter: { subject } }, 'query'],
+            [
+              'Email/get',
+              {
+                accountId,
+                '#ids': {
+                  resultOf: 'query',
+                  name: 'Email/query',
+                  path: '/ids',
+                },
+                properties: ['messageId', 'inReplyTo', 'references', 'sentAt'],
+              },
+              'get',
+            ],
+          ],
+        }),
+      })
+    ).json();
+
+    const emails = response.methodResponses.find((call) => call[2] === 'get')?.[1]?.list;
+    assert.ok(
+      emails != null && emails.length > 0,
+      `no stored Email found for subject ${JSON.stringify(subject)}`,
+    );
+    return emails[0];
+  }
+});
diff --git a/tests/e2e/jmap/docker-compose.yml b/tests/e2e/jmap/docker-compose.yml
new file mode 100644
index 0000000..7fec748
--- /dev/null
+++ b/tests/e2e/jmap/docker-compose.yml
@@ -0,0 +1,28 @@
+# Ported from upyo v0.7.0 (packages/jmap/docker-compose.yml)
+# A local Stalwart for the JMAP e2e suite; tests/e2e/jmap/setup-stalwart.sh
+# configures it.
+services:
+  stalwart:
+    # Stalwart 0.16 removed the REST management API used by setup-stalwart.sh.
+    image: docker.io/stalwartlabs/stalwart:v0.15.5
+    container_name: mailer-stalwart
+    ports:
+      - "8080:8080"   # HTTP/JMAP port
+    volumes:
+      - stalwart-data:/opt/stalwart
+    environment:
+      - STALWART_ADMIN_PASSWORD=admin123
+    restart: unless-stopped
+    healthcheck:
+      test:
+        - CMD
+        - curl
+        - -f
+        - http://localhost:8080/
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+volumes:
+  stalwart-data:
diff --git a/tests/e2e/jmap/setup-stalwart.sh b/tests/e2e/jmap/setup-stalwart.sh
new file mode 100755
index 0000000..53a8feb
--- /dev/null
+++ b/tests/e2e/jmap/setup-stalwart.sh
@@ -0,0 +1,163 @@
+#!/bin/bash
+# Ported from upyo v0.7.0 (packages/jmap/scripts/setup-stalwart.sh)
+# https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+#
+# Run after `docker compose -f tests/e2e/jmap/docker-compose.yml up -d`; it
+# writes tests/e2e/jmap/.env, which `pnpm test:e2e` reads through the shell:
+#   set -a; . tests/e2e/jmap/.env; set +a; pnpm test:e2e
+# Setup script for Stalwart Mail Server E2E testing environment
+# This script waits for Stalwart to start and configures test accounts
+
+set -e
+
+STALWART_URL="${STALWART_URL:-http://localhost:8080}"
+ADMIN_PASSWORD="${STALWART_ADMIN_PASSWORD:-admin123}"
+MAX_WAIT=60
+WAIT_INTERVAL=2
+TEST_USERNAME="test@mail.example.com"
+TEST_PASSWORD="password123"
+
+wait_for_authenticated_session() {
+  echo "Waiting for authenticated JMAP session..."
+
+  elapsed=0
+  while [ $elapsed -lt $MAX_WAIT ]; do
+    if curl -s -w "%{http_code}" -u "${TEST_USERNAME}:${TEST_PASSWORD}" \
+      "${STALWART_URL}/jmap/session" -o /dev/null 2>/dev/null | grep -q "200"
+    then
+      echo "Authenticated JMAP session is ready!"
+      return 0
+    fi
+    sleep $WAIT_INTERVAL
+    elapsed=$((elapsed + WAIT_INTERVAL))
+    echo "Waiting for authenticated session... ($elapsed/$MAX_WAIT seconds)"
+  done
+
+  echo "Error: authenticated JMAP session did not become ready in time"
+  return 1
+}
+
+get_mail_account_id() {
+  curl -s -u "${TEST_USERNAME}:${TEST_PASSWORD}" \
+    "${STALWART_URL}/jmap/session" 2>/dev/null |
+    sed -n 's/.*"primaryAccounts":{[^}]*"urn:ietf:params:jmap:mail":"\([^"]*\)".*/\1/p'
+}
+
+wait_for_mailbox_ready() {
+  echo "Waiting for JMAP mailboxes..."
+
+  elapsed=0
+  while [ $elapsed -lt $MAX_WAIT ]; do
+    account_id=$(get_mail_account_id)
+    if [ -z "$account_id" ]; then
+      sleep $WAIT_INTERVAL
+      elapsed=$((elapsed + WAIT_INTERVAL))
+      echo "Waiting for mail account... ($elapsed/$MAX_WAIT seconds)"
+      continue
+    fi
+
+    response=$(curl -s -u "${TEST_USERNAME}:${TEST_PASSWORD}" \
+      -H "Content-Type: application/json" \
+      -d "{
+        \"using\": [
+          \"urn:ietf:params:jmap:core\",
+          \"urn:ietf:params:jmap:mail\"
+        ],
+        \"methodCalls\": [[
+          \"Mailbox/get\",
+          {
+            \"accountId\": \"${account_id}\",
+            \"properties\": [\"id\", \"role\", \"name\"]
+          },
+          \"c0\"
+        ]]
+      }" \
+      "${STALWART_URL}/jmap" 2>/dev/null || true)
+
+    if echo "$response" | grep -q '"Mailbox/get"' &&
+      echo "$response" | grep -q '"role":"drafts"'
+    then
+      echo "JMAP mailboxes are ready!"
+      return 0
+    fi
+    sleep $WAIT_INTERVAL
+    elapsed=$((elapsed + WAIT_INTERVAL))
+    echo "Waiting for JMAP mailboxes... ($elapsed/$MAX_WAIT seconds)"
+  done
+
+  echo "Error: JMAP mailboxes did not become ready in time"
+  return 1
+}
+
+echo "Waiting for Stalwart to be ready..."
+
+# Wait for Stalwart to be ready
+elapsed=0
+while [ $elapsed -lt $MAX_WAIT ]; do
+  if curl -s "${STALWART_URL}/jmap/session" > /dev/null 2>&1; then
+    echo "Stalwart is ready!"
+    break
+  fi
+  sleep $WAIT_INTERVAL
+  elapsed=$((elapsed + WAIT_INTERVAL))
+  echo "Waiting... ($elapsed/$MAX_WAIT seconds)"
+done
+
+if [ $elapsed -ge $MAX_WAIT ]; then
+  echo "Error: Stalwart did not become ready in time"
+  exit 1
+fi
+
+# Check if test user already exists and works
+if curl -s -w "%{http_code}" -u "${TEST_USERNAME}:${TEST_PASSWORD}" "${STALWART_URL}/jmap/session" -o /dev/null 2>/dev/null | grep -q "200"; then
+  echo "Test user already configured, skipping setup..."
+else
+  echo "Setting up test accounts..."
+
+  # Create domain
+  echo "Creating domain mail.example.com..."
+  curl -fsS -u "admin:${ADMIN_PASSWORD}" -X POST "${STALWART_URL}/api/principal" \
+    -H "Content-Type: application/json" \
+    -d '{"type": "domain", "name": "mail.example.com"}' > /dev/null || true
+
+  # Create test user with "user" role for JMAP access
+  echo "Creating test user..."
+  curl -fsS -u "admin:${ADMIN_PASSWORD}" -X POST "${STALWART_URL}/api/principal" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "type": "individual",
+      "name": "'"${TEST_USERNAME}"'",
+      "secrets": ["'"${TEST_PASSWORD}"'"],
+      "emails": ["'"${TEST_USERNAME}"'"],
+      "description": "Test user for E2E tests",
+      "roles": ["user"]
+    }' > /dev/null
+
+  # Create recipient user with "user" role
+  echo "Creating recipient user..."
+  curl -fsS -u "admin:${ADMIN_PASSWORD}" -X POST "${STALWART_URL}/api/principal" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "type": "individual",
+      "name": "recipient@mail.example.com",
+      "secrets": ["password123"],
+      "emails": ["recipient@mail.example.com"],
+      "description": "Recipient user for E2E tests",
+      "roles": ["user"]
+    }' > /dev/null
+fi
+
+wait_for_authenticated_session
+wait_for_mailbox_ready
+
+# Create .env file for tests
+ENV_FILE="$(dirname "$0")/.env"
+cat > "$ENV_FILE" << EOF
+STALWART_SESSION_URL=http://localhost:8080/jmap/session
+STALWART_USERNAME=${TEST_USERNAME}
+STALWART_PASSWORD=${TEST_PASSWORD}
+STALWART_BASE_URL=http://localhost:8080
+EOF
+
+echo "Environment file created at $ENV_FILE"
+echo "Setup complete! Run: set -a; . tests/e2e/jmap/.env; set +a; pnpm test:e2e"
diff --git a/tests/helpers/jmap/test-config.js b/tests/helpers/jmap/test-config.js
new file mode 100644
index 0000000..bda7438
--- /dev/null
+++ b/tests/helpers/jmap/test-config.js
@@ -0,0 +1,110 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const process = require('node:process');
+
+/**
+ * Check if Stalwart testing is enabled via environment variables.
+ * @returns true if STALWART_SESSION_URL and authentication credentials are set.
+ */
+const isStalwartTestingEnabled = () => {
+  const sessionUrl = process.env.STALWART_SESSION_URL;
+  const bearerToken = process.env.STALWART_BEARER_TOKEN;
+  const basicUsername = process.env.STALWART_USERNAME;
+  const basicPassword = process.env.STALWART_PASSWORD;
+  return !!sessionUrl && (!!bearerToken || (!!basicUsername && !!basicPassword));
+};
+
+/**
+ * Get test configuration from environment variables.
+ * @returns Test configuration object.
+ * @throws Error if required environment variables are not set.
+ */
+const getTestConfig = () => {
+  const sessionUrl = process.env.STALWART_SESSION_URL;
+  const bearerToken = process.env.STALWART_BEARER_TOKEN;
+  const basicUsername = process.env.STALWART_USERNAME;
+  const basicPassword = process.env.STALWART_PASSWORD;
+  const apiUrl = process.env.STALWART_API_URL;
+  const adminToken = process.env.STALWART_ADMIN_TOKEN;
+
+  if (!sessionUrl) {
+    throw new Error('STALWART_SESSION_URL environment variable must be set for E2E tests');
+  }
+
+  if (!bearerToken && (!basicUsername || !basicPassword)) {
+    throw new Error(
+      'Either STALWART_BEARER_TOKEN or (STALWART_USERNAME and STALWART_PASSWORD) must be set for E2E tests',
+    );
+  }
+
+  // Extract base URL from session URL for URL rewriting
+  const baseUrl =
+    process.env.STALWART_BASE_URL ||
+    sessionUrl.replace(/\/jmap\/session$/, '').replace(/\/.well-known\/jmap$/, '');
+
+  const jmap = bearerToken
+    ? {
+        sessionUrl,
+        bearerToken,
+        timeout: 30000,
+        retries: 3,
+        baseUrl,
+      }
+    : {
+        sessionUrl,
+        basicAuth: {
+          username: basicUsername,
+          password: basicPassword,
+        },
+        timeout: 30000,
+        retries: 3,
+        baseUrl,
+      };
+
+  return {
+    jmap,
+    stalwart: {
+      apiUrl: apiUrl || sessionUrl.replace('/jmap/session', ''),
+      adminToken: adminToken || bearerToken || '',
+    },
+  };
+};
+
+/**
+ * Create a test message for E2E tests.
+ * @param options Options for the test message.
+ * @returns A message object.
+ */
+const createTestMessage = (options = {}) => {
+  const content = options.content || { text: 'This is a test email.' };
+  const attachments = options.attachments || [];
+
+  return {
+    sender: {
+      address: options.senderEmail || 'test@mail.example.com',
+      name: options.senderName,
+    },
+    recipients: [
+      {
+        address: options.recipientEmail || 'recipient@mail.example.com',
+      },
+    ],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    attachments,
+    subject: options.subject || 'Test Email',
+    content,
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+    messageId: options.messageId,
+    date: options.date,
+    inReplyTo: options.inReplyTo,
+    references: options.references,
+    calendar: options.calendar,
+  };
+};
+
+module.exports = { isStalwartTestingEnabled, getTestConfig, createTestMessage };
diff --git a/tests/types/jmap.test-d.ts b/tests/types/jmap.test-d.ts
new file mode 100644
index 0000000..f41a26d
--- /dev/null
+++ b/tests/types/jmap.test-d.ts
@@ -0,0 +1,44 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import {
+  createMessage,
+  type RawTransport,
+  type Receipt,
+  type VerifiableTransport,
+} from '../../index.js';
+import {
+  JMAP_ERROR_TYPES,
+  JmapApiError,
+  JmapTransport,
+  createJmapConfig,
+  isCapabilityError,
+  type JmapConfig,
+  type ResolvedJmapConfig,
+} from '../../src/jmap/index.js';
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+  bearerToken: 'token',
+});
+expectAssignable<RawTransport<'jmap'>>(transport);
+expectAssignable<VerifiableTransport<'jmap'>>(transport);
+expectType<ResolvedJmapConfig>(
+  createJmapConfig({
+    sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+    basicAuth: { username: 'alex', password: 'secret' },
+  }),
+);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'jmap'>>>(transport.send(message));
+expectType<Promise<void>>(transport.verify());
+
+expectAssignable<JmapConfig>({ sessionUrl: 'https://x', bearerToken: 't', accountId: 'a1' });
+expectAssignable<Error>(new JmapApiError('Bad request', 400));
+expectType<boolean>(isCapabilityError(new Error('x')));
+expectType<'urn:ietf:params:jmap:error:unknownCapability'>(JMAP_ERROR_TYPES.unknownCapability);
+expectError(new JmapTransport({ bearerToken: 'token' }));
diff --git a/tests/unit/jmap-blob-uploader.test.js b/tests/unit/jmap-blob-uploader.test.js
new file mode 100644
index 0000000..edd3287
--- /dev/null
+++ b/tests/unit/jmap-blob-uploader.test.js
@@ -0,0 +1,152 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/blob-uploader.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { uploadBlob } = require('../../src/jmap/blob-uploader.js');
+const { createJmapConfig } = require('../../src/jmap/config.js');
+
+describe('uploadBlob', () => {
+  const config = createJmapConfig({
+    sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+    bearerToken: 'test-token',
+    retries: 0,
+    timeout: 1000,
+  });
+
+  it('should upload a blob and return blobId', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      const capturedRequest = {
+        url: '',
+        headers: new Headers(),
+        body: new Blob(),
+      };
+
+      globalThis.fetch = (input, init) => {
+        const url =
+          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        capturedRequest.url = url;
+        capturedRequest.headers = new Headers(init?.headers);
+        capturedRequest.body = init?.body;
+
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              accountId: 'acc-1',
+              blobId: 'blob-123',
+              type: 'image/png',
+              size: 1024,
+            }),
+            { status: 201 },
+          ),
+        );
+      };
+
+      const blob = new Blob(['test content'], { type: 'image/png' });
+      const result = await uploadBlob(
+        config,
+        'https://jmap.example.com/upload/{accountId}',
+        'acc-1',
+        blob,
+      );
+
+      assert.equal(capturedRequest.url, 'https://jmap.example.com/upload/acc-1');
+      assert.equal(capturedRequest.headers.get('Authorization'), 'Bearer test-token');
+      assert.equal(capturedRequest.headers.get('Content-Type'), 'image/png');
+
+      assert.equal(result.blobId, 'blob-123');
+      assert.equal(result.type, 'image/png');
+      assert.equal(result.size, 1024);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('should handle File objects with name', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      const capturedHeaders = { value: new Headers() };
+
+      globalThis.fetch = (_input, init) => {
+        capturedHeaders.value = new Headers(init?.headers);
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              accountId: 'acc-1',
+              blobId: 'blob-456',
+              type: 'application/pdf',
+              size: 2048,
+            }),
+            { status: 201 },
+          ),
+        );
+      };
+
+      const file = new File(['pdf content'], 'document.pdf', {
+        type: 'application/pdf',
+      });
+      const result = await uploadBlob(
+        config,
+        'https://jmap.example.com/upload/{accountId}',
+        'acc-1',
+        file,
+      );
+
+      assert.equal(capturedHeaders.value.get('Content-Type'), 'application/pdf');
+      assert.equal(result.blobId, 'blob-456');
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('should throw on upload failure', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      globalThis.fetch = () => {
+        return Promise.resolve(new Response('Unauthorized', { status: 401 }));
+      };
+
+      const blob = new Blob(['test'], { type: 'text/plain' });
+
+      await assert.rejects(
+        async () =>
+          await uploadBlob(config, 'https://jmap.example.com/upload/{accountId}', 'acc-1', blob),
+        (error) => {
+          assert.ok(error.message.includes('401'));
+          return true;
+        },
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('should respect abort signal', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const blob = new Blob(['test'], { type: 'text/plain' });
+
+    await assert.rejects(
+      async () =>
+        await uploadBlob(
+          config,
+          'https://jmap.example.com/upload/{accountId}',
+          'acc-1',
+          blob,
+          controller.signal,
+        ),
+      (error) => {
+        return (
+          error.name === 'AbortError' ||
+          error.message.includes('aborted') ||
+          error.message.includes('abort')
+        );
+      },
+    );
+  });
+});
diff --git a/tests/unit/jmap-config.test.js b/tests/unit/jmap-config.test.js
new file mode 100644
index 0000000..5adfa23
--- /dev/null
+++ b/tests/unit/jmap-config.test.js
@@ -0,0 +1,81 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { createJmapConfig } = require('../../src/jmap/config.js');
+
+describe('createJmapConfig', () => {
+  it('should create config with required fields only', () => {
+    const config = createJmapConfig({
+      sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+      bearerToken: 'test-token',
+    });
+
+    assert.equal(config.sessionUrl, 'https://jmap.example.com/.well-known/jmap');
+    assert.equal(config.bearerToken, 'test-token');
+    assert.equal(config.accountId, null);
+    assert.equal(config.identityId, null);
+    assert.equal(config.timeout, 30000);
+    assert.equal(config.retries, 3);
+    assert.deepEqual(config.headers, {});
+    assert.equal(config.sessionCacheTtl, 300000);
+  });
+
+  it('should create config with all optional fields', () => {
+    const config = createJmapConfig({
+      sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+      bearerToken: 'test-token',
+      accountId: 'account-123',
+      identityId: 'identity-456',
+      timeout: 60000,
+      retries: 5,
+      headers: { 'X-Custom': 'value' },
+      sessionCacheTtl: 600000,
+    });
+
+    assert.equal(config.accountId, 'account-123');
+    assert.equal(config.identityId, 'identity-456');
+    assert.equal(config.timeout, 60000);
+    assert.equal(config.retries, 5);
+    assert.deepEqual(config.headers, { 'X-Custom': 'value' });
+    assert.equal(config.sessionCacheTtl, 600000);
+  });
+
+  it('should preserve zero values for timeout and retries', () => {
+    const config = createJmapConfig({
+      sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+      bearerToken: 'test-token',
+      timeout: 0,
+      retries: 0,
+    });
+
+    // 0 is a valid value and should be preserved
+    // e.g., timeout: 0 for immediate timeout, retries: 0 to disable retries
+    assert.equal(config.timeout, 0);
+    assert.equal(config.retries, 0);
+  });
+
+  it('should create config with basic auth', () => {
+    const config = createJmapConfig({
+      sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+      basicAuth: {
+        username: 'user',
+        password: 'pass',
+      },
+    });
+
+    assert.equal(config.bearerToken, null);
+    assert.deepEqual(config.basicAuth, { username: 'user', password: 'pass' });
+  });
+
+  it('should throw when neither bearerToken nor basicAuth is provided', () => {
+    assert.throws(
+      () =>
+        createJmapConfig({
+          sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        }),
+      { message: 'Either bearerToken or basicAuth must be provided' },
+    );
+  });
+});
diff --git a/tests/unit/jmap-errors.test.js b/tests/unit/jmap-errors.test.js
new file mode 100644
index 0000000..a33133b
--- /dev/null
+++ b/tests/unit/jmap-errors.test.js
@@ -0,0 +1,81 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/errors.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { isCapabilityError, JmapApiError } = require('../../src/jmap/errors.js');
+
+describe('JmapApiError', () => {
+  it('should create an error with message only', () => {
+    const error = new JmapApiError('Something went wrong');
+
+    assert.equal(error.message, 'Something went wrong');
+    assert.equal(error.name, 'JmapApiError');
+    assert.equal(error.statusCode, undefined);
+    assert.equal(error.responseBody, undefined);
+    assert.equal(error.jmapErrorType, undefined);
+    assert.ok(error instanceof Error);
+  });
+
+  it('should create an error with status code', () => {
+    const error = new JmapApiError('Not found', 404);
+
+    assert.equal(error.message, 'Not found');
+    assert.equal(error.statusCode, 404);
+  });
+
+  it('should create an error with response body', () => {
+    const error = new JmapApiError('Server error', 500, '{"error": "details"}');
+
+    assert.equal(error.message, 'Server error');
+    assert.equal(error.statusCode, 500);
+    assert.equal(error.responseBody, '{"error": "details"}');
+  });
+
+  it('should create an error with JMAP error type', () => {
+    const error = new JmapApiError(
+      'Unknown capability',
+      400,
+      undefined,
+      'urn:ietf:params:jmap:error:unknownCapability',
+    );
+
+    assert.equal(error.jmapErrorType, 'urn:ietf:params:jmap:error:unknownCapability');
+  });
+});
+
+describe('isCapabilityError', () => {
+  it('should return true for capability error', () => {
+    const error = new JmapApiError(
+      'Unknown capability',
+      400,
+      undefined,
+      'urn:ietf:params:jmap:error:unknownCapability',
+    );
+
+    assert.equal(isCapabilityError(error), true);
+  });
+
+  it('should return false for other JMAP errors', () => {
+    const error = new JmapApiError(
+      'Invalid arguments',
+      400,
+      undefined,
+      'urn:ietf:params:jmap:error:invalidArguments',
+    );
+
+    assert.equal(isCapabilityError(error), false);
+  });
+
+  it('should return false for non-JmapApiError', () => {
+    const error = new Error('Regular error');
+
+    assert.equal(isCapabilityError(error), false);
+  });
+
+  it('should return false for non-error values', () => {
+    assert.equal(isCapabilityError('string'), false);
+    assert.equal(isCapabilityError(null), false);
+    assert.equal(isCapabilityError(undefined), false);
+  });
+});
diff --git a/tests/unit/jmap-http-client.test.js b/tests/unit/jmap-http-client.test.js
new file mode 100644
index 0000000..0701f82
--- /dev/null
+++ b/tests/unit/jmap-http-client.test.js
@@ -0,0 +1,284 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/http-client.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it, test } = require('node:test');
+const assert = require('node:assert/strict');
+const { JmapHttpClient } = require('../../src/jmap/http-client.js');
+const { createJmapConfig } = require('../../src/jmap/config.js');
+const { JmapApiError } = require('../../src/jmap/errors.js');
+
+describe('JmapHttpClient', () => {
+  const config = createJmapConfig({
+    sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+    bearerToken: 'test-token',
+    retries: 0, // Disable retries for tests
+    timeout: 1000,
+  });
+
+  describe('constructor', () => {
+    it('should create an instance with config', () => {
+      const client = new JmapHttpClient(config);
+      assert.ok(client);
+    });
+  });
+
+  describe('fetchSession', () => {
+    it('should fetch session with Bearer token auth', async () => {
+      const originalFetch = globalThis.fetch;
+
+      try {
+        const captured = { headers: null };
+
+        globalThis.fetch = (_input, init) => {
+          captured.headers = new Headers(init?.headers);
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                capabilities: {},
+                accounts: {
+                  'acc-1': {
+                    name: 'Test',
+                    isPersonal: true,
+                    isReadOnly: false,
+                    accountCapabilities: { 'urn:ietf:params:jmap:mail': {} },
+                  },
+                },
+                primaryAccounts: {},
+                username: 'test@example.com',
+                apiUrl: 'https://jmap.example.com/api',
+                downloadUrl: 'https://jmap.example.com/download/{blobId}',
+                uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+                state: '123',
+              }),
+              { status: 200, headers: { 'Content-Type': 'application/json' } },
+            ),
+          );
+        };
+
+        const client = new JmapHttpClient(config);
+        const session = await client.fetchSession();
+
+        assert.ok(captured.headers);
+        assert.equal(captured.headers.get('Authorization'), 'Bearer test-token');
+        assert.equal(session.apiUrl, 'https://jmap.example.com/api');
+        assert.ok(session.accounts['acc-1']);
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+
+    it('should throw JmapApiError on HTTP error', async () => {
+      const originalFetch = globalThis.fetch;
+
+      try {
+        globalThis.fetch = () => {
+          return Promise.resolve(new Response('Unauthorized', { status: 401 }));
+        };
+
+        const client = new JmapHttpClient(config);
+
+        await assert.rejects(
+          async () => await client.fetchSession(),
+          (error) => {
+            assert.ok(error instanceof JmapApiError);
+            assert.equal(error.statusCode, 401);
+            return true;
+          },
+        );
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+  });
+
+  describe('executeRequest', () => {
+    it('should send JMAP request with proper structure', async () => {
+      const originalFetch = globalThis.fetch;
+
+      try {
+        let capturedBody = null;
+
+        globalThis.fetch = (_input, init) => {
+          if (init?.body) {
+            capturedBody = JSON.parse(init.body);
+          }
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Email/set',
+                    {
+                      created: { draft: { id: 'email-1' } },
+                    },
+                    'c0',
+                  ],
+                ],
+                sessionState: 'state-1',
+              }),
+              { status: 200 },
+            ),
+          );
+        };
+
+        const client = new JmapHttpClient(config);
+        const response = await client.executeRequest('https://jmap.example.com/api', {
+          using: ['urn:ietf:params:jmap:core'],
+          methodCalls: [['Email/set', { accountId: 'acc-1' }, 'c0']],
+        });
+
+        assert.ok(capturedBody);
+        assert.deepEqual(capturedBody.using, ['urn:ietf:params:jmap:core']);
+        assert.ok(response.methodResponses);
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+
+    it('should throw on 4xx errors without retry', async () => {
+      const originalFetch = globalThis.fetch;
+      let fetchCount = 0;
+
+      try {
+        globalThis.fetch = () => {
+          fetchCount++;
+          return Promise.resolve(new Response('Bad Request', { status: 400 }));
+        };
+
+        const clientWithRetries = new JmapHttpClient(
+          createJmapConfig({
+            sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+            bearerToken: 'test-token',
+            retries: 3,
+          }),
+        );
+
+        await assert.rejects(
+          async () =>
+            await clientWithRetries.executeRequest('https://jmap.example.com/api', {
+              using: [],
+              methodCalls: [],
+            }),
+          JmapApiError,
+        );
+
+        // Should not retry on 4xx errors
+        assert.equal(fetchCount, 1);
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+  });
+
+  describe('abort signal', () => {
+    it('should abort request when signal is aborted', async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const client = new JmapHttpClient(config);
+
+      await assert.rejects(
+        async () => await client.fetchSession(controller.signal),
+        (error) => {
+          return (
+            error instanceof Error &&
+            (error.name === 'AbortError' ||
+              error.message.includes('aborted') ||
+              error.message.includes('abort'))
+          );
+        },
+      );
+    });
+
+    it('should preserve custom abort reasons during requests', async () => {
+      const originalFetch = globalThis.fetch;
+      const abortReason = new Error('Stop JMAP request.');
+      const controller = new AbortController();
+
+      try {
+        globalThis.fetch = (_input, init) =>
+          new Promise((_resolve, reject) => {
+            assert.ok(init?.signal instanceof AbortSignal);
+            init.signal.addEventListener(
+              'abort',
+              () => {
+                reject(init.signal?.reason);
+              },
+              { once: true },
+            );
+            setTimeout(() => controller.abort(abortReason), 0);
+          });
+
+        const clientWithRetries = new JmapHttpClient(
+          createJmapConfig({
+            sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+            bearerToken: 'test-token',
+            retries: 3,
+          }),
+        );
+        const startedAt = Date.now();
+
+        await assert.rejects(
+          () =>
+            clientWithRetries.executeRequest(
+              'https://jmap.example.com/api',
+              { using: [], methodCalls: [] },
+              controller.signal,
+            ),
+          (error) => error === abortReason,
+        );
+        assert.ok(Date.now() - startedAt < 500);
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+  });
+});
+
+test('caller cancellation clears the retry backoff', async () => {
+  const originalFetch = globalThis.fetch;
+  const controller = new AbortController();
+  let calls = 0;
+  let abortedAt = 0;
+  globalThis.fetch = () => {
+    calls++;
+    const response = new Response('Unavailable.', { status: 503 });
+    const text = response.text.bind(response);
+    response.text = async () => {
+      const body = await text();
+      setTimeout(() => {
+        abortedAt = Date.now();
+        controller.abort('stop retry');
+      }, 0);
+      return body;
+    };
+    return Promise.resolve(response);
+  };
+  try {
+    const client = new JmapHttpClient(
+      createJmapConfig({
+        sessionUrl: 'https://example.com/session',
+        bearerToken: 'token',
+        retries: 3,
+      }),
+    );
+    await assert.rejects(
+      client.executeRequest(
+        'https://example.com/api',
+        {
+          using: [],
+          methodCalls: [],
+        },
+        controller.signal,
+      ),
+      (e) => e === 'stop retry',
+    );
+    assert.ok(
+      Date.now() - abortedAt < 800,
+      'Cancellation must not wait for the one-second retry backoff.',
+    );
+    assert.equal(calls, 1);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
diff --git a/tests/unit/jmap-message-converter.test.js b/tests/unit/jmap-message-converter.test.js
new file mode 100644
index 0000000..d1ea5a3
--- /dev/null
+++ b/tests/unit/jmap-message-converter.test.js
@@ -0,0 +1,610 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/message-converter.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { convertMessage, formatAddress } = require('../../src/jmap/message-converter.js');
+
+describe('formatAddress', () => {
+  it('should format address with name', () => {
+    const address = {
+      address: 'test@example.com',
+      name: 'Test User',
+    };
+
+    const result = formatAddress(address);
+
+    assert.deepEqual(result, {
+      email: 'test@example.com',
+      name: 'Test User',
+    });
+  });
+
+  it('should format address without name', () => {
+    const address = {
+      address: 'test@example.com',
+    };
+
+    const result = formatAddress(address);
+
+    assert.deepEqual(result, {
+      email: 'test@example.com',
+    });
+  });
+
+  it('should omit name property if undefined', () => {
+    const address = {
+      address: 'test@example.com',
+      name: undefined,
+    };
+
+    const result = formatAddress(address);
+
+    assert.equal('name' in result, false);
+  });
+});
+
+describe('convertMessage', () => {
+  const baseMessage = {
+    sender: { address: 'sender@example.com' },
+    recipients: [{ address: 'recipient@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    attachments: [],
+    subject: 'Test Subject',
+    content: { text: 'Hello, World!' },
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+  };
+
+  it('should convert a basic text message', () => {
+    const result = convertMessage(baseMessage, 'drafts-123', new Map());
+
+    assert.deepEqual(result.from, [{ email: 'sender@example.com' }]);
+    assert.deepEqual(result.to, [{ email: 'recipient@example.com' }]);
+    assert.equal(result.subject, 'Test Subject');
+    assert.deepEqual(result.mailboxIds, { 'drafts-123': true });
+    assert.ok('text' in result.bodyValues);
+    assert.equal(result.bodyValues.text.value, 'Hello, World!');
+  });
+
+  it('should convert a message with HTML content', () => {
+    const message = {
+      ...baseMessage,
+      content: { html: '<p>Hello, World!</p>' },
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.ok('html' in result.bodyValues);
+    assert.equal(result.bodyValues.html.value, '<p>Hello, World!</p>');
+  });
+
+  it('should convert a message with both text and HTML', () => {
+    const message = {
+      ...baseMessage,
+      content: { text: 'Hello, World!', html: '<p>Hello, World!</p>' },
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.ok('text' in result.bodyValues);
+    assert.ok('html' in result.bodyValues);
+    assert.equal(result.bodyStructure?.type, 'multipart/alternative');
+  });
+
+  it('should add a calendar part carrying the method parameter', () => {
+    const ics =
+      [
+        'BEGIN:VCALENDAR',
+        'METHOD:REQUEST',
+        'BEGIN:VEVENT',
+        'UID:1@example.com',
+        'END:VEVENT',
+        'END:VCALENDAR',
+      ].join('\r\n') + '\r\n';
+    const message = {
+      ...baseMessage,
+      content: { text: 'Lunch on Wednesday.' },
+      calendar: { method: 'REQUEST', content: ics },
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.equal(result.bodyStructure?.type, 'multipart/alternative');
+    const parts = result.bodyStructure?.subParts ?? [];
+    const calendarPart = parts[parts.length - 1];
+    assert.equal(calendarPart.partId, 'calendar');
+    // The charset is left to the server, which appends its own.
+    assert.equal(calendarPart.type, 'text/calendar; method=REQUEST');
+    assert.equal(calendarPart.charset, undefined);
+    assert.equal(result.bodyValues.calendar.value, ics);
+  });
+
+  it('should place the calendar after the other alternatives', () => {
+    const message = {
+      ...baseMessage,
+      content: { text: 'Lunch', html: '<p>Lunch</p>' },
+      calendar: {
+        method: 'CANCEL',
+        content: 'BEGIN:VCALENDAR\r\nMETHOD:CANCEL\r\nEND:VCALENDAR\r\n',
+      },
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.deepEqual(
+      (result.bodyStructure?.subParts ?? []).map((part) => part.partId),
+      ['text', 'html', 'calendar'],
+    );
+  });
+
+  it('should keep an empty prose body beside the calendar', () => {
+    // RFC 6047 §2.1 wants a human-readable alternative, and a recipient whose
+    // client does not schedule sees only that.  An empty string is still a
+    // body the caller asked for, so the calendar must not become the sole part.
+    const message = {
+      ...baseMessage,
+      content: { text: '' },
+      calendar: {
+        method: 'REQUEST',
+        content: 'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR\r\n',
+      },
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.equal(result.bodyStructure?.type, 'multipart/alternative');
+    assert.deepEqual(
+      (result.bodyStructure?.subParts ?? []).map((part) => part.partId),
+      ['text', 'calendar'],
+    );
+    assert.equal(result.bodyValues.text.value, '');
+  });
+
+  it('should keep an empty HTML body beside the calendar', () => {
+    const message = {
+      ...baseMessage,
+      content: { html: '' },
+      calendar: {
+        method: 'REQUEST',
+        content: 'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR\r\n',
+      },
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.equal(result.bodyStructure?.type, 'multipart/alternative');
+    assert.deepEqual(
+      (result.bodyStructure?.subParts ?? []).map((part) => part.partId),
+      ['html', 'calendar'],
+    );
+  });
+
+  it('should not send an undefined HTML body value', () => {
+    // `createMessage()` passes `content` through without checking it, and
+    // `Message` is structural, so a body can reach here undefined.  Sending
+    // `{ value: undefined }` would hand the server a non-string.
+    const message = {
+      ...baseMessage,
+      content: { text: 'Lunch.', html: undefined },
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.ok(!('html' in result.bodyValues));
+    assert.deepEqual(
+      (result.bodyStructure?.subParts ?? []).map((part) => part.partId),
+      [],
+    );
+    assert.equal(result.bodyStructure?.partId, 'text');
+  });
+
+  it('should reject malformed calendar property syntax', () => {
+    const message = {
+      ...baseMessage,
+      calendar: {
+        method: 'REQUEST',
+        content: 'BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nSUMMARY;BROKEN:Lunch\r\nEND:VCALENDAR\r\n',
+      },
+    };
+    assert.throws(() => convertMessage(message, 'drafts-123', new Map()), TypeError);
+  });
+
+  it('should reject calendar content that never passed createMessage()', () => {
+    const message = {
+      ...baseMessage,
+      calendar: { method: 'REQUEST', content: 'not a calendar' },
+    };
+
+    assert.throws(() => convertMessage(message, 'drafts-123', new Map()), {
+      name: 'TypeError',
+    });
+  });
+
+  it('should convert cc and bcc recipients', () => {
+    const message = {
+      ...baseMessage,
+      ccRecipients: [{ address: 'cc@example.com', name: 'CC User' }],
+      bccRecipients: [{ address: 'bcc@example.com' }],
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.deepEqual(result.cc, [{ email: 'cc@example.com', name: 'CC User' }]);
+    assert.deepEqual(result.bcc, [{ email: 'bcc@example.com' }]);
+  });
+
+  it('should convert replyTo recipients', () => {
+    const message = {
+      ...baseMessage,
+      replyRecipients: [{ address: 'reply@example.com' }],
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.deepEqual(result.replyTo, [{ email: 'reply@example.com' }]);
+  });
+
+  it('should add priority headers for high priority', () => {
+    const message = {
+      ...baseMessage,
+      priority: 'high',
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.equal(result['header:X-Priority'], '1');
+    assert.equal(result['header:Importance'], 'high');
+  });
+
+  it('should add priority headers for low priority', () => {
+    const message = {
+      ...baseMessage,
+      priority: 'low',
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    assert.equal(result['header:X-Priority'], '5');
+    assert.equal(result['header:Importance'], 'low');
+  });
+
+  it('should not add priority headers for normal priority', () => {
+    const result = convertMessage(baseMessage, 'drafts-123', new Map());
+
+    assert.equal(result['header:X-Priority'], undefined);
+  });
+
+  it('should include custom headers', () => {
+    const headers = new Headers();
+    headers.set('X-Custom-Header', 'custom-value');
+
+    const message = {
+      ...baseMessage,
+      headers,
+    };
+
+    const result = convertMessage(message, 'drafts-123', new Map());
+
+    // Headers.entries() returns lowercase names per HTTP spec
+    assert.equal(result['header:x-custom-header'], 'custom-value');
+    assert.ok(!('headers' in result));
+  });
+
+  it('should convert a message with attachments', () => {
+    const message = {
+      ...baseMessage,
+      attachments: [
+        {
+          inline: false,
+          filename: 'document.pdf',
+          content: new Uint8Array([0x25, 0x50, 0x44, 0x46]),
+          contentType: 'application/pdf',
+          contentId: 'attachment-1',
+        },
+      ],
+    };
+
+    const uploadedBlobs = new Map();
+    uploadedBlobs.set('attachment-1', 'blob-uploaded-123');
+
+    const result = convertMessage(message, 'drafts-123', uploadedBlobs);
+
+    // Should be multipart/mixed when attachments are present
+    assert.equal(result.bodyStructure?.type, 'multipart/mixed');
+    assert.ok(result.bodyStructure?.subParts);
+    assert.equal(result.bodyStructure.subParts.length, 2);
+
+    // First part should be the text content
+    const textPart = result.bodyStructure.subParts[0];
+    assert.equal(textPart.type, 'text/plain; charset=utf-8');
+
+    // Second part should be the attachment
+    const attachmentPart = result.bodyStructure.subParts[1];
+    assert.equal(attachmentPart.type, 'application/pdf');
+    assert.equal(attachmentPart.blobId, 'blob-uploaded-123');
+    assert.equal(attachmentPart.name, 'document.pdf');
+    assert.equal(attachmentPart.disposition, 'attachment');
+  });
+
+  it('should convert a message with multiple attachments', () => {
+    const message = {
+      ...baseMessage,
+      content: { text: 'Hello', html: '<p>Hello</p>' },
+      attachments: [
+        {
+          inline: false,
+          filename: 'doc1.pdf',
+          content: new Uint8Array([0x25, 0x50, 0x44, 0x46]),
+          contentType: 'application/pdf',
+          contentId: 'att-1',
+        },
+        {
+          inline: false,
+          filename: 'image.png',
+          content: new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+          contentType: 'image/png',
+          contentId: 'att-2',
+        },
+      ],
+    };
+
+    const uploadedBlobs = new Map();
+    uploadedBlobs.set('att-1', 'blob-1');
+    uploadedBlobs.set('att-2', 'blob-2');
+
+    const result = convertMessage(message, 'drafts-123', uploadedBlobs);
+
+    // multipart/mixed with alternative body + 2 attachments
+    assert.equal(result.bodyStructure?.type, 'multipart/mixed');
+    assert.ok(result.bodyStructure?.subParts);
+    assert.equal(result.bodyStructure.subParts.length, 3);
+
+    // First part should be multipart/alternative for text+html
+    const alternativePart = result.bodyStructure.subParts[0];
+    assert.equal(alternativePart.type, 'multipart/alternative');
+
+    // Second and third parts are attachments
+    assert.equal(result.bodyStructure.subParts[1].blobId, 'blob-1');
+    assert.equal(result.bodyStructure.subParts[2].blobId, 'blob-2');
+  });
+
+  it('should convert a message with inline attachments', () => {
+    const message = {
+      ...baseMessage,
+      content: { html: '<p>Hello</p><img src="cid:inline-img">' },
+      attachments: [
+        {
+          inline: true,
+          filename: 'logo.png',
+          content: new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+          contentType: 'image/png',
+          contentId: 'inline-img',
+        },
+      ],
+    };
+
+    const uploadedBlobs = new Map();
+    uploadedBlobs.set('inline-img', 'blob-inline-123');
+
+    const result = convertMessage(message, 'drafts-123', uploadedBlobs);
+
+    // Should be multipart/related for HTML + inline images
+    assert.equal(result.bodyStructure?.type, 'multipart/related');
+    assert.ok(result.bodyStructure?.subParts);
+    assert.equal(result.bodyStructure.subParts.length, 2);
+
+    // First part should be the HTML content
+    const htmlPart = result.bodyStructure.subParts[0];
+    assert.equal(htmlPart.type, 'text/html; charset=utf-8');
+
+    // Second part should be the inline image
+    const inlinePart = result.bodyStructure.subParts[1];
+    assert.equal(inlinePart.type, 'image/png');
+    assert.equal(inlinePart.blobId, 'blob-inline-123');
+    assert.equal(inlinePart.disposition, 'inline');
+    assert.equal(inlinePart.cid, 'inline-img');
+  });
+
+  it('should convert a message with both inline and regular attachments', () => {
+    const message = {
+      ...baseMessage,
+      content: { text: 'Hello', html: '<p>Hello</p><img src="cid:logo">' },
+      attachments: [
+        {
+          inline: true,
+          filename: 'logo.png',
+          content: new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+          contentType: 'image/png',
+          contentId: 'logo',
+        },
+        {
+          inline: false,
+          filename: 'document.pdf',
+          content: new Uint8Array([0x25, 0x50, 0x44, 0x46]),
+          contentType: 'application/pdf',
+          contentId: 'att-doc',
+        },
+      ],
+    };
+
+    const uploadedBlobs = new Map();
+    uploadedBlobs.set('logo', 'blob-logo');
+    uploadedBlobs.set('att-doc', 'blob-doc');
+
+    const result = convertMessage(message, 'drafts-123', uploadedBlobs);
+
+    // multipart/mixed: [multipart/related, attachment]
+    assert.equal(result.bodyStructure?.type, 'multipart/mixed');
+    assert.ok(result.bodyStructure?.subParts);
+    assert.equal(result.bodyStructure.subParts.length, 2);
+
+    // First part should be multipart/related (HTML + inline images)
+    const relatedPart = result.bodyStructure.subParts[0];
+    assert.equal(relatedPart.type, 'multipart/related');
+    assert.ok(relatedPart.subParts);
+    assert.equal(relatedPart.subParts.length, 2);
+
+    // Inside related: alternative body + inline attachment
+    const alternativePart = relatedPart.subParts[0];
+    assert.equal(alternativePart.type, 'multipart/alternative');
+
+    const inlinePart = relatedPart.subParts[1];
+    assert.equal(inlinePart.disposition, 'inline');
+    assert.equal(inlinePart.cid, 'logo');
+
+    // Second part should be regular attachment
+    const attachmentPart = result.bodyStructure.subParts[1];
+    assert.equal(attachmentPart.disposition, 'attachment');
+    assert.equal(attachmentPart.blobId, 'blob-doc');
+  });
+});
+
+describe('convertMessage() identity and threading', () => {
+  const base = {
+    sender: { address: 'sender@example.com' },
+    recipients: [{ address: 'recipient@example.com' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Re: Your request',
+    content: { text: 'Thanks for getting in touch.' },
+    attachments: [],
+    priority: 'normal',
+    tags: [],
+    headers: new Headers(),
+  };
+
+  const convert = (overrides = {}) =>
+    convertMessage({ ...base, ...overrides }, 'drafts-123', new Map());
+
+  it('sets the structured identity properties', () => {
+    const result = convert({
+      messageId: 'ticket-4821@example.com',
+      date: new Date('2026-09-01T10:00:00Z'),
+      inReplyTo: ['122@example.com'],
+      references: ['120@example.com', '121@example.com'],
+    });
+
+    assert.deepEqual(result.messageId, ['ticket-4821@example.com']);
+    assert.equal(result.sentAt, '2026-09-01T10:00:00Z');
+    assert.deepEqual(result.inReplyTo, ['122@example.com']);
+    assert.deepEqual(result.references, ['120@example.com', '121@example.com']);
+  });
+
+  it('keeps a non-zero fractional second in the date', () => {
+    const result = convert({ date: new Date('2026-09-01T10:00:00.250Z') });
+
+    assert.equal(result.sentAt, '2026-09-01T10:00:00.250Z');
+  });
+
+  it('omits the properties a message does not set', () => {
+    const result = convert();
+
+    assert.equal(result.messageId, undefined);
+    assert.equal(result.sentAt, undefined);
+    assert.equal(result.inReplyTo, undefined);
+    assert.equal(result.references, undefined);
+  });
+
+  it('never writes both a structured property and its raw header', () => {
+    const result = convert({
+      messageId: 'typed@example.com',
+      date: new Date('2026-09-01T10:00:00Z'),
+      inReplyTo: ['typed@example.com'],
+      references: [],
+      headers: new Headers({
+        'Message-ID': '<custom@example.com>',
+        Date: 'Thu, 01 Jan 1970 00:00:00 +0000',
+        'In-Reply-To': '<custom@example.com>',
+        References: '<custom@example.com>',
+      }),
+    });
+
+    assert.equal(result['header:message-id'], undefined);
+    assert.equal(result['header:date'], undefined);
+    assert.equal(result['header:in-reply-to'], undefined);
+    assert.equal(result['header:references'], undefined);
+    assert.equal(result.references, undefined);
+  });
+
+  it('lets a raw header through when the field is unset', () => {
+    const result = convert({
+      headers: new Headers({
+        'Message-ID': '<custom@example.com>',
+        'In-Reply-To': '<custom@example.com>',
+      }),
+    });
+
+    assert.equal(result['header:message-id'], '<custom@example.com>');
+    assert.equal(result['header:in-reply-to'], '<custom@example.com>');
+  });
+
+  it('drops a raw header a structured property already carries', () => {
+    const result = convert({
+      headers: new Headers({
+        From: 'spoofed@example.com',
+        Bcc: 'hidden@example.com',
+        Subject: 'Overridden',
+        'Content-Type': 'text/plain',
+        'MIME-Version': '1.0',
+        'X-Mailer': 'Test Mailer',
+      }),
+    });
+
+    for (const name of ['from', 'bcc', 'subject', 'content-type', 'mime-version']) {
+      assert.equal(result[`header:${name}`], undefined);
+    }
+    assert.equal(result['header:x-mailer'], 'Test Mailer');
+  });
+
+  it('keeps a custom priority header from shadowing the derived one', () => {
+    const result = convert({
+      priority: 'high',
+      headers: new Headers({ 'X-Priority': '3' }),
+    });
+
+    assert.equal(result['header:X-Priority'], '1');
+    assert.equal(result['header:x-priority'], undefined);
+  });
+
+  it('rejects an invalid identifier', () => {
+    assert.throws(() => convert({ messageId: 'not an identifier' }), {
+      name: 'TypeError',
+      message: /Invalid message ID/,
+    });
+    assert.throws(() => convert({ references: ['a@b>'] }), {
+      name: 'TypeError',
+      message: /Invalid message ID/,
+    });
+  });
+
+  it('rejects a date it cannot express', () => {
+    assert.throws(() => convert({ date: new Date('nonsense') }), {
+      name: 'TypeError',
+      message: /Invalid date/,
+    });
+
+    const farFuture = new Date(0);
+    farFuture.setUTCFullYear(10000, 0, 1);
+    assert.throws(() => convert({ date: farFuture }), {
+      name: 'RangeError',
+      message: /Year out of range/,
+    });
+  });
+
+  it('rejects a header value that would forge further fields', () => {
+    const headers = {
+      ...new Headers(),
+      entries: () => [['X-Evil', 'value\r\nX-Injected: yes']][Symbol.iterator](),
+    };
+
+    assert.throws(() => convert({ headers }), {
+      name: 'TypeError',
+      message: /carriage return or line feed/,
+    });
+  });
+});
diff --git a/tests/unit/jmap-raw-message.integration.test.js b/tests/unit/jmap-raw-message.integration.test.js
new file mode 100644
index 0000000..be9bfe0
--- /dev/null
+++ b/tests/unit/jmap-raw-message.integration.test.js
@@ -0,0 +1,714 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/raw-message.integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { Buffer } = require('node:buffer');
+const { createServer } = require('node:http');
+const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+const { isRawTransport } = require('../../src/core/transport.js');
+const { composeMessage } = require('../../src/mime/index.js');
+const { createMessage } = require('../../src/core/message.js');
+const { readAttachmentContent } = require('../../src/core/attachment.js');
+const { TEST_DKIM_PRIVATE_KEY } = require('../helpers/mime/dkim-test-keys.js');
+
+const core = 'urn:ietf:params:jmap:core';
+const mail = 'urn:ietf:params:jmap:mail';
+const submission = 'urn:ietf:params:jmap:submission';
+const content = Buffer.from(
+  'From: sender@example.com\r\nBcc: hidden@example.com\r\nMessage-ID: <preserved@example.com>\r\nDKIM-Signature: original\r\n folded\r\nContent-Type: application/pkcs7-mime\r\n\r\n.opaque\r\n',
+);
+const raw = {
+  envelope: { from: 'sender@example.com', to: ['recipient@example.com'] },
+  content,
+  encoding: '7bit',
+};
+
+const setup = async (options = {}) => {
+  const calls = [];
+  const uploads = [];
+  const uploadContentTypes = [];
+  const uploadsAtImport = [];
+  const sockets = new Set();
+  let base = '';
+  const server = createServer(async (req, res) => {
+    req.on('error', () => {});
+    const reply = (body, status = 200) => {
+      res.writeHead(status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(body));
+    };
+    const httpError = (stage) => {
+      if (options.httpError?.stage !== stage) return false;
+      res.writeHead(options.httpError.status, {
+        'Content-Type': 'text/plain',
+        'Retry-After': '7',
+      });
+      res.end(options.httpError.body);
+      return true;
+    };
+    if (req.url === '/session') {
+      reply({
+        capabilities: { [core]: {}, [mail]: {}, [submission]: {} },
+        accounts: {
+          a: { accountCapabilities: { [mail]: {}, [submission]: {} } },
+        },
+        primaryAccounts: { [mail]: 'a' },
+        apiUrl: base + '/api',
+        uploadUrl: base + '/upload/{accountId}',
+        downloadUrl: base + '/download/{blobId}',
+        state: 's',
+      });
+      return;
+    }
+    if (req.url?.startsWith('/upload/')) {
+      uploadContentTypes.push(req.headers['content-type']);
+      if (options.upload === 'early') {
+        if (httpError('upload')) return;
+        reply({ accountId: 'a', blobId: 'blob', size: 0 });
+        return;
+      }
+      if (options.slowUpload) {
+        req.pause();
+        await new Promise((resolve) => {
+          const timer = setTimeout(resolve, 300);
+          req.once('close', () => {
+            clearTimeout(timer);
+            resolve();
+          });
+        });
+        req.resume();
+      }
+      const chunks = [];
+      try {
+        for await (const chunk of req) chunks.push(Buffer.from(chunk));
+      } catch {
+        return;
+      }
+      const bytes = Buffer.concat(chunks);
+      uploads.push(bytes);
+      if (httpError('upload')) return;
+      if (options.upload === 'stall-response') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.flushHeaders();
+        res.write('{');
+        return;
+      }
+      reply({
+        accountId: 'a',
+        blobId: 'blob',
+        type: 'message/rfc822',
+        size: bytes.length + (options.upload === 'wrong-size' ? 1 : 0),
+      });
+      return;
+    }
+    const chunks = [];
+    try {
+      for await (const chunk of req) chunks.push(Buffer.from(chunk));
+    } catch {
+      return;
+    }
+    const request = JSON.parse(Buffer.concat(chunks).toString());
+    const [name, args, id] = request.methodCalls[0];
+    calls.push({ name, args });
+    const result = { accountId: 'a' };
+    if (name === 'Mailbox/get') {
+      result.list = [{ id: 'drafts', role: 'drafts' }];
+    } else if (name === 'Identity/get') {
+      result.list = [
+        { id: 'first', email: 'other@example.com' },
+        {
+          id: 'matching',
+          email: 'sender@example.com',
+        },
+      ];
+    } else if (name === 'Email/import') {
+      uploadsAtImport.push(uploads.length);
+      if (httpError('import')) return;
+      if (options.importing === 'partial') {
+        reply({
+          methodResponses: [['error', { type: 'serverPartialFail' }, id]],
+        });
+        return;
+      }
+      if (options.importing === 'lost') {
+        req.socket.destroy();
+        return;
+      }
+      if (options.importing === 'reject') {
+        result.notCreated = {
+          raw: { type: 'invalidEmail', description: 'invalid' },
+        };
+      } else if (options.importing === 'duplicate' || options.importing === 'different-blob') {
+        result.notCreated = {
+          raw: { type: 'alreadyExists', existingId: 'existing' },
+        };
+      } else result.created = { raw: { id: 'email', blobId: 'blob' } };
+    } else if (name === 'Email/get') {
+      result.list = [
+        {
+          id: 'existing',
+          blobId: options.importing === 'different-blob' ? 'old-blob' : 'blob',
+        },
+      ];
+    } else if (name === 'EmailSubmission/set') {
+      if (httpError('submission')) return;
+      if (options.submitting === 'partial' || options.submitting === 'method-error') {
+        reply({
+          methodResponses: [
+            [
+              'error',
+              {
+                type: options.submitting === 'partial' ? 'serverPartialFail' : 'forbidden',
+              },
+              id,
+            ],
+          ],
+        });
+        return;
+      }
+      if (options.submitting === 'lost') {
+        req.socket.destroy();
+        return;
+      }
+      if (options.submitting === 'stall-response') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.flushHeaders();
+        res.write('{');
+        return;
+      }
+      if (options.submitting === 'request-error') {
+        reply({ type: 'urn:ietf:params:jmap:error:notRequest', status: 400 }, 400);
+        return;
+      }
+      if (options.submitting === 'missing') {
+        reply({ methodResponses: [] });
+        return;
+      }
+      if (options.submitting !== 'reject') {
+        result.created = { raw: { id: 'submission' } };
+      }
+      if (options.submitting === 'reject' || options.submitting === 'contradictory') {
+        result.notCreated = { raw: { type: 'forbidden' } };
+      }
+    }
+    if (options.discovery?.method === name) {
+      if (options.discovery.fault === 'account') result.accountId = 'wrong';
+      if (options.discovery.fault === 'call') {
+        reply({ methodResponses: [[name, result, 'wrong']] });
+        return;
+      }
+      if (options.discovery.fault === 'duplicate') {
+        reply({
+          methodResponses: [
+            [name, result, id],
+            [name, result, id],
+          ],
+        });
+        return;
+      }
+      if (options.discovery.fault === 'identifier') {
+        result.list =
+          name === 'Mailbox/get'
+            ? [{ role: 'drafts', id: 42 }]
+            : [{ id: 42, email: 'sender@example.com' }];
+      }
+    }
+    reply({ methodResponses: [[name, result, id]] });
+  });
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address();
+  assert.ok(address && typeof address !== 'string');
+  base = `http://127.0.0.1:${address.port}`;
+  const transport = new JmapTransport({
+    sessionUrl: base + '/session',
+    bearerToken: 'local-test',
+    timeout: options.timeout ?? 2000,
+    retries: 3,
+  });
+  return {
+    transport,
+    calls,
+    uploads,
+    async close() {
+      for (const socket of sockets) socket.destroy();
+      await new Promise((resolve) => server.close(() => resolve()));
+      // close() is awaited by each test, so assertion failures reach its runner.
+      for (const contentType of uploadContentTypes) {
+        assert.equal(contentType, 'message/rfc822');
+      }
+      for (const count of uploadsAtImport) {
+        assert.equal(count, 1, 'must finish upload before importing');
+      }
+    },
+  };
+};
+
+for (const encoding of ['7bit', undefined]) {
+  test(`JMAP raw uses ${encoding ? 'one traversal' : 'analysis and transmission'}`, async () => {
+    const context = await setup();
+    let opens = 0;
+    try {
+      assert.ok(isRawTransport(context.transport));
+      const receipt = await context.transport.sendRaw({
+        ...raw,
+        encoding,
+        content: async function* () {
+          opens++;
+          for (let i = 0; i < content.length; i += 7) {
+            yield content.subarray(i, i + 7);
+          }
+        },
+      });
+      assert.ok(receipt.successful, JSON.stringify(receipt));
+      assert.equal(receipt.messageId, 'submission');
+      assert.equal(opens, encoding ? 1 : 2);
+      assert.deepEqual(context.uploads, [content]);
+      const imported = context.calls.find((c) => c.name === 'Email/import');
+      assert.deepEqual(imported.args.emails, {
+        raw: { blobId: 'blob', mailboxIds: { drafts: true } },
+      });
+      const sent = context.calls.find((c) => c.name === 'EmailSubmission/set');
+      assert.deepEqual(sent.args.create, {
+        raw: {
+          emailId: 'email',
+          identityId: 'matching',
+          envelope: {
+            mailFrom: { email: 'sender@example.com' },
+            rcptTo: [{ email: 'recipient@example.com' }],
+          },
+        },
+      });
+    } finally {
+      await context.close();
+    }
+  });
+}
+
+for (const mode of [
+  'lost',
+  'missing',
+  'reject',
+  'contradictory',
+  'request-error',
+  'stall-response',
+  'partial',
+  'method-error',
+]) {
+  test(`JMAP raw submission ${mode} has safe retry classification`, async () => {
+    const context = await setup({ submitting: mode, timeout: 200 });
+    try {
+      const receipt = await context.transport.sendRaw(raw);
+      assert.ok(!receipt.successful);
+      assert.equal(receipt.retryable, false);
+      assert.equal(
+        receipt.errors?.[0].code,
+        mode === 'reject' || mode === 'request-error' || mode === 'method-error'
+          ? 'jmap.raw_submission_failed'
+          : 'jmap.raw_submission_unknown',
+      );
+      assert.equal(context.calls.filter((c) => c.name === 'EmailSubmission/set').length, 1);
+    } finally {
+      await context.close();
+    }
+  });
+}
+
+for (const mode of ['lost', 'reject', 'duplicate', 'different-blob', 'partial']) {
+  test(`JMAP raw import ${mode} never reuses a different blob`, async () => {
+    const context = await setup({ importing: mode });
+    try {
+      const receipt = await context.transport.sendRaw(raw);
+      if (mode === 'duplicate') {
+        assert.ok(receipt.successful, JSON.stringify(receipt));
+      } else {
+        assert.ok(!receipt.successful);
+        assert.equal(receipt.errors?.[0].code, 'jmap.raw_import_failed');
+        assert.equal(receipt.retryable, mode === 'lost' || mode === 'partial');
+        assert.ok(!context.calls.some((c) => c.name === 'EmailSubmission/set'));
+      }
+      assert.equal(context.calls.filter((c) => c.name === 'Email/import').length, 1);
+    } finally {
+      await context.close();
+    }
+  });
+}
+
+for (const mode of ['early', 'wrong-size', 'stall-response']) {
+  test(`JMAP raw upload ${mode} cannot lead to import`, async () => {
+    const context = await setup({ upload: mode, timeout: 200 });
+    try {
+      const receipt = await context.transport.sendRaw({
+        ...raw,
+        content: async function* () {
+          yield content;
+          if (mode === 'early') await new Promise(() => {});
+        },
+      });
+      assert.ok(!receipt.successful);
+      assert.ok(!context.calls.some((c) => c.name === 'Email/import'));
+    } finally {
+      await context.close();
+    }
+  });
+}
+
+test('JMAP raw null sender uses a default identity without changing the envelope', async () => {
+  const context = await setup();
+  try {
+    assert.ok(
+      (
+        await context.transport.sendRaw({
+          ...raw,
+          envelope: { ...raw.envelope, from: null },
+        })
+      ).successful,
+    );
+    const sent = context.calls.find((c) => c.name === 'EmailSubmission/set').args.create;
+    assert.deepEqual(sent, {
+      raw: {
+        emailId: 'email',
+        identityId: 'first',
+        envelope: {
+          mailFrom: { email: '' },
+          rcptTo: [{ email: 'recipient@example.com' }],
+        },
+      },
+    });
+  } finally {
+    await context.close();
+  }
+});
+
+test('JMAP raw source failures retain their diagnostic instead of fetch wrapping', async () => {
+  const context = await setup();
+  try {
+    const receipt = await context.transport.sendRaw({
+      ...raw,
+      content: async function* () {
+        yield content;
+        throw new TypeError('original source failure');
+      },
+    });
+    assert.ok(!receipt.successful);
+    assert.ok(receipt.errorMessages.join().includes('original source failure'));
+    assert.ok(!context.calls.some((c) => c.name === 'Email/import'));
+  } finally {
+    await context.close();
+  }
+});
+
+test('JMAP raw abort stops a large source without buffering or draining it', async () => {
+  const context = await setup({ slowUpload: true });
+  const controller = new AbortController();
+  const reason = new TypeError('stop bounded upload');
+  const block = Buffer.from(('x'.repeat(998) + '\r\n').repeat(32));
+  let produced = 0;
+  let closed = 0;
+  let started;
+  const ready = new Promise((resolve) => (started = resolve));
+  try {
+    const pending = context.transport.sendRaw(
+      {
+        ...raw,
+        content: async function* () {
+          try {
+            yield Buffer.from('X: y\r\n\r\n');
+            started();
+            for (let i = 0; i < 2048; i++) {
+              produced += block.length;
+              yield block;
+            }
+          } finally {
+            closed++;
+          }
+        },
+      },
+      { signal: controller.signal },
+    );
+    const rejected = assert.rejects(pending, (error) => error === reason);
+    await ready;
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    assert.ok(produced > 0 && produced < 2048 * block.length, String(produced));
+    controller.abort(reason);
+    const atAbort = produced;
+    await rejected;
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    assert.equal(produced, atAbort);
+    assert.equal(closed, 1);
+    assert.ok(!context.calls.some((c) => c.name === 'Email/import'));
+  } finally {
+    await context.close();
+  }
+});
+
+for (const encoding of ['7bit', undefined]) {
+  test(`JMAP raw ${encoding ? 'upload' : 'analysis'} progress refreshes inactivity`, async () => {
+    const context = await setup({ timeout: 200 });
+    try {
+      const receipt = await context.transport.sendRaw({
+        ...raw,
+        encoding,
+        content: async function* () {
+          for (const line of ['X: y\r\n', '\r\n', 'one\r\n', 'two\r\n']) {
+            await new Promise((resolve) => setTimeout(resolve, 90));
+            yield Buffer.from(line);
+          }
+        },
+      });
+      assert.ok(receipt.successful, JSON.stringify(receipt));
+    } finally {
+      await context.close();
+    }
+  });
+  test(`JMAP raw ${encoding ? 'upload' : 'analysis'} timeout closes a stalled source`, async () => {
+    const context = await setup({ timeout: 100 });
+    let closed = 0;
+    try {
+      const receipt = await context.transport.sendRaw({
+        ...raw,
+        encoding,
+        content: () => ({
+          [Symbol.asyncIterator]() {
+            return {
+              next: () => new Promise(() => {}),
+              return() {
+                closed++;
+                return Promise.resolve({
+                  done: true,
+                  value: undefined,
+                });
+              },
+            };
+          },
+        }),
+      });
+      assert.ok(!receipt.successful);
+      assert.ok(receipt.errorMessages.join().includes('timed out'));
+      assert.equal(closed, 1);
+      assert.ok(!context.calls.some((c) => c.name === 'Email/import'));
+    } finally {
+      await context.close();
+    }
+  });
+}
+
+test('JMAP raw rejects invalid second-pass bytes before import', async () => {
+  const context = await setup();
+  let opens = 0;
+  try {
+    const receipt = await context.transport.sendRaw({
+      ...raw,
+      encoding: undefined,
+      content: async function* () {
+        yield opens++ === 0 ? content : Buffer.from('X: y\r\n\r\ninvalid\n');
+      },
+    });
+    assert.ok(!receipt.successful);
+    assert.equal(receipt.errors?.[0].code, 'jmap.raw_message_invalid');
+    assert.equal(opens, 2);
+    assert.ok(!context.calls.some((c) => c.name === 'Email/import'));
+  } finally {
+    await context.close();
+  }
+});
+
+for (const source of [new Blob([content]), Promise.resolve(new Uint8Array(content))]) {
+  test(`JMAP raw accepts ${source instanceof Blob ? 'Blob' : 'promised bytes'}`, async () => {
+    const context = await setup();
+    try {
+      assert.ok((await context.transport.sendRaw({ ...raw, content: source })).successful);
+      assert.deepEqual(context.uploads, [content]);
+    } finally {
+      await context.close();
+    }
+  });
+}
+
+for (const method of ['Mailbox/get', 'Identity/get']) {
+  for (const fault of ['account', 'call', 'duplicate', 'identifier']) {
+    test(`JMAP raw rejects ${method} discovery with invalid ${fault}`, async () => {
+      const context = await setup({ discovery: { method, fault } });
+      try {
+        const receipt = await context.transport.sendRaw(raw);
+        assert.ok(!receipt.successful);
+        assert.equal(context.uploads.length, 0);
+      } finally {
+        await context.close();
+      }
+    });
+  }
+}
+
+// The fetch of Node 24 (undici) answers a 401 to a streamed request body with
+// "expected non-null body source" instead of the response, so the transport
+// reports a retryable network error (CLAUDE.md, known upstream bug 14). The
+// fix commit lifts the todo.
+const streamed401 =
+  Number(process.versions.node.split('.')[0]) >= 24
+    ? 'Node 24 fetch turns a 401 to a streamed body into a network error'
+    : undefined;
+
+for (const stage of ['upload', 'import', 'submission']) {
+  for (const status of [401, 403, 429, 502]) {
+    for (const body of ['', 'plain response']) {
+      const todo = status === 401 ? streamed401 : undefined;
+      test(
+        `JMAP raw ${stage} HTTP ${status} retains ${body ? 'text' : 'empty'} error metadata`,
+        { todo },
+        async () => {
+          const context = await setup({ httpError: { stage, status, body } });
+          try {
+            const receipt = await context.transport.sendRaw(raw);
+            assert.ok(!receipt.successful);
+            const auth = status === 401 || status === 403;
+            const unknown = stage === 'submission' && !auth;
+            assert.equal(receipt.retryable, stage !== 'submission' && !auth);
+            assert.equal(receipt.attempts, 1);
+            const error = receipt.errors?.[0];
+            assert.ok(error);
+            assert.equal(error.code, `jmap.raw_${stage}_${unknown ? 'unknown' : 'failed'}`);
+            assert.equal(error.statusCode, status);
+            assert.equal(error.retryAfterMilliseconds, 7000);
+            assert.deepEqual(error.providerDetails, {
+              responseBody: body,
+              jmapErrorType: undefined,
+            });
+            assert.equal(
+              error.category,
+              unknown ? 'unknown' : auth ? 'auth' : status === 429 ? 'rate-limit' : 'server-error',
+            );
+            assert.equal(context.uploads.length, 1);
+            assert.equal(
+              context.calls.filter((c) => c.name === 'Email/import').length,
+              stage === 'upload' ? 0 : 1,
+            );
+            assert.equal(
+              context.calls.filter((c) => c.name === 'EmailSubmission/set').length,
+              stage === 'submission' ? 1 : 0,
+            );
+          } finally {
+            await context.close();
+          }
+        },
+      );
+    }
+  }
+}
+
+test(
+  'JMAP raw keeps an authentication rejection before upload EOF',
+  { todo: streamed401 },
+  async () => {
+    const context = await setup({
+      upload: 'early',
+      httpError: { stage: 'upload', status: 401, body: 'unauthorized' },
+    });
+    let closed = 0;
+    try {
+      const receipt = await context.transport.sendRaw({
+        ...raw,
+        content: () => ({
+          [Symbol.asyncIterator]() {
+            let first = true;
+            return {
+              next() {
+                if (first) {
+                  first = false;
+                  return Promise.resolve({
+                    done: false,
+                    value: content,
+                  });
+                }
+                return new Promise(() => {});
+              },
+              return() {
+                closed++;
+                return Promise.resolve({ done: true, value: undefined });
+              },
+            };
+          },
+        }),
+      });
+      assert.ok(!receipt.successful);
+      assert.ok(!receipt.retryable);
+      assert.equal(receipt.errors?.[0].statusCode, 401);
+      assert.equal(receipt.errors?.[0].category, 'auth');
+      assert.equal(closed, 1);
+      assert.ok(!context.calls.some((c) => c.name === 'Email/import'));
+    } finally {
+      await context.close();
+    }
+  },
+);
+
+test('JMAP uploads composed MIME unchanged', async () => {
+  const context = await setup();
+  try {
+    const composed = await composeMessage(
+      createMessage({
+        from: 'sender@example.com',
+        to: 'recipient@example.com',
+        bcc: 'blind@example.com',
+        subject: 'Composed',
+        content: { text: 'First\r\nSecond', html: '<b>Second</b>' },
+      }),
+    );
+    const bytes = await readAttachmentContent(composed.content);
+    assert.ok((await context.transport.sendRaw(composed)).successful);
+    assert.deepEqual(context.uploads, [Buffer.from(bytes)]);
+    // oxlint-disable-next-line no-shadow -- upstream
+    const submission = context.calls.find((call) => call.name === 'EmailSubmission/set');
+    assert.ok(JSON.stringify(submission).includes('blind@example.com'));
+    assert.ok(!Buffer.from(bytes).toString().includes('Bcc:'));
+  } finally {
+    await context.close();
+  }
+});
+
+test('JMAP classifies composed replay failures without retrying upload', async () => {
+  const context = await setup();
+  try {
+    let reads = 0;
+    const composed = await composeMessage(
+      createMessage({
+        from: 'sender@example.com',
+        to: 'recipient@example.com',
+        subject: 'Changed attachment',
+        content: { text: 'Hello' },
+        attachments: {
+          filename: 'a',
+          contentId: 'a',
+          contentType: 'text/plain',
+          inline: false,
+          content: async function* () {
+            yield new Uint8Array([reads++]);
+          },
+        },
+      }),
+      {
+        dkim: {
+          bodyMode: 'streaming',
+          signatures: [
+            {
+              signingDomain: 'example.com',
+              selector: 'test',
+              privateKey: TEST_DKIM_PRIVATE_KEY,
+            },
+          ],
+        },
+      },
+    );
+    const receipt = await context.transport.sendRaw(composed);
+    assert.ok(!receipt.successful);
+    assert.equal(receipt.errors?.[0].code, 'jmap.raw_message_invalid');
+    assert.ok(!receipt.errors?.[0].retryable);
+    assert.equal(reads, 2);
+    assert.ok(!context.calls.some((call) => call.name === 'Email/import'));
+  } finally {
+    await context.close();
+  }
+});
diff --git a/tests/unit/jmap-retry-attempts.test.js b/tests/unit/jmap-retry-attempts.test.js
new file mode 100644
index 0000000..727cbf6
--- /dev/null
+++ b/tests/unit/jmap-retry-attempts.test.js
@@ -0,0 +1,126 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/retry-attempts.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+
+const baseMessage = {
+  sender: { address: 'sender@example.com' },
+  recipients: [{ address: 'recipient@example.com' }],
+  ccRecipients: [],
+  bccRecipients: [],
+  replyRecipients: [],
+  attachments: [],
+  subject: 'Test Subject',
+  content: { text: 'Hello, World!' },
+  priority: 'normal',
+  tags: [],
+  headers: new Headers(),
+};
+
+describe('JmapTransport retry attempts', () => {
+  it('should preserve attempt counts from retried network failures', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      globalThis.fetch = (input, init) => {
+        const url =
+          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const body = init?.body == null ? undefined : JSON.parse(init.body);
+
+        if (url.includes('.well-known/jmap')) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                capabilities: {},
+                accounts: {
+                  'acc-1': {
+                    name: 'Test',
+                    isPersonal: true,
+                    isReadOnly: false,
+                    accountCapabilities: {
+                      'urn:ietf:params:jmap:mail': {},
+                    },
+                  },
+                },
+                primaryAccounts: {},
+                username: 'test@example.com',
+                apiUrl: 'https://jmap.example.com/api',
+                downloadUrl: 'https://jmap.example.com/download/{blobId}',
+                uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+                state: '123',
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        if (body?.methodCalls?.[0]?.[0] === 'Mailbox/get') {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Mailbox/get',
+                    {
+                      list: [
+                        {
+                          id: 'drafts-123',
+                          role: 'drafts',
+                          name: 'Drafts',
+                        },
+                      ],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        if (body?.methodCalls?.[0]?.[0] === 'Identity/get') {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Identity/get',
+                    {
+                      list: [
+                        {
+                          id: 'identity-123',
+                          email: 'sender@example.com',
+                          name: 'Sender',
+                        },
+                      ],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        return Promise.reject(new TypeError('fetch failed'));
+      };
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+        retries: 1,
+      });
+
+      const receipt = await transport.send(baseMessage);
+
+      assert.ok(!receipt.successful);
+      assert.equal(receipt.attempts, 2);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
diff --git a/tests/unit/jmap-send-error.test.js b/tests/unit/jmap-send-error.test.js
new file mode 100644
index 0000000..07488c3
--- /dev/null
+++ b/tests/unit/jmap-send-error.test.js
@@ -0,0 +1,169 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/send-error.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+
+const baseMessage = {
+  sender: { address: 'sender@example.com' },
+  recipients: [{ address: 'recipient@example.com' }],
+  ccRecipients: [],
+  bccRecipients: [],
+  replyRecipients: [],
+  attachments: [],
+  subject: 'Test Subject',
+  content: { text: 'Hello, World!' },
+  priority: 'normal',
+  tags: [],
+  headers: new Headers(),
+};
+
+describe('JmapTransport send error', () => {
+  it('should return failed receipt on error', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      globalThis.fetch = () => {
+        return Promise.resolve(new Response('Unauthorized', { status: 401 }));
+      };
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+        retries: 0,
+      });
+
+      const receipt = await transport.send(baseMessage);
+
+      assert.equal(receipt.successful, false);
+      if (!receipt.successful) {
+        assert.ok(receipt.errorMessages.length > 0);
+        assert.equal(receipt.provider, 'jmap');
+        assert.equal(receipt.retryable, false);
+        assert.equal(receipt.errors?.[0]?.category, 'auth');
+        assert.equal(receipt.errors?.[0]?.statusCode, 401);
+        assert.deepEqual(receipt.errors?.[0]?.providerDetails, {
+          responseBody: 'Unauthorized',
+          jmapErrorType: undefined,
+        });
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('should return retryable timeout receipts for request timeouts', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      let fetchCount = 0;
+      globalThis.fetch = (input, init) => {
+        fetchCount++;
+        const url =
+          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+
+        if (url.includes('.well-known/jmap')) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                capabilities: {},
+                accounts: {
+                  'acc-1': {
+                    name: 'Test',
+                    isPersonal: true,
+                    isReadOnly: false,
+                    accountCapabilities: { 'urn:ietf:params:jmap:mail': {} },
+                  },
+                },
+                primaryAccounts: { 'urn:ietf:params:jmap:mail': 'acc-1' },
+                username: 'test@example.com',
+                apiUrl: 'https://jmap.example.com/api',
+                downloadUrl: 'https://jmap.example.com/download/{blobId}',
+                uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+                state: '123',
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        if (fetchCount === 2) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Mailbox/get',
+                    {
+                      list: [{ id: 'drafts-123', role: 'drafts', name: 'Drafts' }],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        if (fetchCount === 3) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Identity/get',
+                    {
+                      list: [
+                        {
+                          id: 'id-1',
+                          email: 'sender@example.com',
+                          name: 'Sender',
+                        },
+                      ],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        return new Promise((_resolve, reject) => {
+          assert.ok(init?.signal instanceof AbortSignal);
+          init.signal.addEventListener(
+            'abort',
+            () => {
+              reject(init.signal?.reason);
+            },
+            { once: true },
+          );
+        });
+      };
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+        retries: 0,
+        timeout: 1,
+      });
+
+      const receipt = await transport.send(baseMessage);
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.provider, 'jmap');
+        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.errors?.[0]?.category, 'timeout');
+        assert.equal(receipt.errors?.[0]?.retryable, true);
+        assert.equal(receipt.errors?.[0]?.code, 'timeout');
+        assert.equal(receipt.errors?.[0]?.provider, 'jmap');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
diff --git a/tests/unit/jmap-send-success.test.js b/tests/unit/jmap-send-success.test.js
new file mode 100644
index 0000000..93bafe7
--- /dev/null
+++ b/tests/unit/jmap-send-success.test.js
@@ -0,0 +1,148 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/send-success.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+
+const baseMessage = {
+  sender: { address: 'sender@example.com' },
+  recipients: [{ address: 'recipient@example.com' }],
+  ccRecipients: [],
+  bccRecipients: [],
+  replyRecipients: [],
+  attachments: [],
+  subject: 'Test Subject',
+  content: { text: 'Hello, World!' },
+  priority: 'normal',
+  tags: [],
+  headers: new Headers(),
+};
+
+describe('JmapTransport send success', () => {
+  it('should return successful receipt on success', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      const fetchInfo = { count: 0 };
+      globalThis.fetch = (input, _init) => {
+        fetchInfo.count++;
+        const url =
+          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+
+        // First call: session fetch
+        if (url.includes('.well-known/jmap')) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                capabilities: {},
+                accounts: {
+                  'acc-1': {
+                    name: 'Test',
+                    isPersonal: true,
+                    isReadOnly: false,
+                    accountCapabilities: { 'urn:ietf:params:jmap:mail': {} },
+                  },
+                },
+                primaryAccounts: { 'urn:ietf:params:jmap:mail': 'acc-1' },
+                username: 'test@example.com',
+                apiUrl: 'https://jmap.example.com/api',
+                downloadUrl: 'https://jmap.example.com/download/{blobId}',
+                uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+                state: '123',
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        // Second call: Mailbox/get for drafts
+        if (fetchInfo.count === 2) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Mailbox/get',
+                    {
+                      list: [{ id: 'drafts-123', role: 'drafts', name: 'Drafts' }],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        // Third call: Identity/get
+        if (fetchInfo.count === 3) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Identity/get',
+                    {
+                      list: [
+                        {
+                          id: 'id-1',
+                          email: 'sender@example.com',
+                          name: 'Sender',
+                        },
+                      ],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        // Fourth call: Email/set + EmailSubmission/set
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({
+              methodResponses: [
+                [
+                  'Email/set',
+                  {
+                    created: { draft: { id: 'email-123' } },
+                  },
+                  'c0',
+                ],
+                [
+                  'EmailSubmission/set',
+                  {
+                    created: { submission: { id: 'sub-456' } },
+                  },
+                  'c1',
+                ],
+              ],
+            }),
+            { status: 200 },
+          ),
+        );
+      };
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+        retries: 0,
+        timeout: 1000,
+      });
+
+      const receipt = await transport.send(baseMessage);
+
+      assert.equal(receipt.successful, true);
+      if (receipt.successful) {
+        assert.ok(receipt.messageId);
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
diff --git a/tests/unit/jmap-sendmany.test.js b/tests/unit/jmap-sendmany.test.js
new file mode 100644
index 0000000..475660a
--- /dev/null
+++ b/tests/unit/jmap-sendmany.test.js
@@ -0,0 +1,516 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/sendmany.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+
+const baseMessage = {
+  sender: { address: 'sender@example.com' },
+  recipients: [{ address: 'recipient@example.com' }],
+  ccRecipients: [],
+  bccRecipients: [],
+  replyRecipients: [],
+  attachments: [],
+  subject: 'Test Subject',
+  content: { text: 'Hello, World!' },
+  priority: 'normal',
+  tags: [],
+  headers: new Headers(),
+};
+
+describe('sendMany batch - success', () => {
+  it('should batch multiple messages into a single JMAP request', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      const requests = [];
+      globalThis.fetch = (input, init) => {
+        const url =
+          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+
+        const body = init?.body ? JSON.parse(init.body) : null;
+        requests.push({ url, body });
+
+        // Session fetch
+        if (url.includes('.well-known/jmap')) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                capabilities: {},
+                accounts: {
+                  'acc-1': {
+                    name: 'Test',
+                    isPersonal: true,
+                    isReadOnly: false,
+                    accountCapabilities: { 'urn:ietf:params:jmap:mail': {} },
+                  },
+                },
+                primaryAccounts: {},
+                username: 'test@example.com',
+                apiUrl: 'https://jmap.example.com/api',
+                downloadUrl: 'https://jmap.example.com/download/{blobId}',
+                uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+                state: '123',
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        // Mailbox/get
+        if (body?.methodCalls?.[0]?.[0] === 'Mailbox/get') {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Mailbox/get',
+                    {
+                      list: [
+                        {
+                          id: 'drafts-123',
+                          role: 'drafts',
+                          name: 'Drafts',
+                        },
+                      ],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        // Identity/get
+        if (body?.methodCalls?.[0]?.[0] === 'Identity/get') {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Identity/get',
+                    {
+                      list: [
+                        {
+                          id: 'id-1',
+                          email: 'sender@example.com',
+                          name: 'Sender',
+                        },
+                      ],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        // Batch Email/set + EmailSubmission/set
+        if (body?.methodCalls?.[0]?.[0] === 'Email/set') {
+          const emailCreates = body.methodCalls[0][1].create;
+          const createdEmails = {};
+          for (const key of Object.keys(emailCreates)) {
+            createdEmails[key] = { id: `email-${key}` };
+          }
+
+          const submissionCreates = body.methodCalls[1][1].create;
+          const createdSubmissions = {};
+          for (const key of Object.keys(submissionCreates)) {
+            createdSubmissions[key] = { id: `submission-${key}` };
+          }
+
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  ['Email/set', { created: createdEmails }, 'c0'],
+                  ['EmailSubmission/set', { created: createdSubmissions }, 'c1'],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        return Promise.resolve(new Response('Not found', { status: 404 }));
+      };
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+        retries: 0,
+        timeout: 5000,
+      });
+
+      const messages = [
+        { ...baseMessage, subject: 'Test 1' },
+        { ...baseMessage, subject: 'Test 2' },
+        { ...baseMessage, subject: 'Test 3' },
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      // Verify all receipts are successful
+      assert.equal(receipts.length, 3);
+      assert.ok(receipts.every((r) => r.successful));
+
+      // Verify batch request structure:
+      // 1. Session fetch
+      // 2. Mailbox/get (once)
+      // 3. Identity/get (once)
+      // 4. Batch Email/set + EmailSubmission/set (once for all messages)
+      assert.equal(requests.length, 4, 'Should make exactly 4 requests');
+
+      // Verify the batch request has all 3 emails
+      const batchRequest = requests[3];
+      const batchBody = batchRequest.body;
+      const emailCreates = batchBody?.methodCalls?.[0]?.[1]?.create;
+      assert.equal(Object.keys(emailCreates).length, 3, 'Email/set should have 3 creates');
+      assert.ok('draft0' in emailCreates);
+      assert.ok('draft1' in emailCreates);
+      assert.ok('draft2' in emailCreates);
+
+      // Verify submission creates reference the correct email IDs
+      const submissionCreates = batchBody?.methodCalls?.[1]?.[1]?.create;
+      assert.equal(
+        Object.keys(submissionCreates).length,
+        3,
+        'EmailSubmission/set should have 3 creates',
+      );
+      assert.equal(submissionCreates.sub0.emailId, '#draft0');
+      assert.equal(submissionCreates.sub1.emailId, '#draft1');
+      assert.equal(submissionCreates.sub2.emailId, '#draft2');
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('sendMany batch - partial failure', () => {
+  it('should handle partial failures in batch', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      globalThis.fetch = (input, init) => {
+        const url =
+          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+
+        const body = init?.body ? JSON.parse(init.body) : null;
+
+        if (url.includes('.well-known/jmap')) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                capabilities: {},
+                accounts: {
+                  'acc-1': {
+                    name: 'Test',
+                    isPersonal: true,
+                    isReadOnly: false,
+                    accountCapabilities: { 'urn:ietf:params:jmap:mail': {} },
+                  },
+                },
+                primaryAccounts: {},
+                username: 'test@example.com',
+                apiUrl: 'https://jmap.example.com/api',
+                downloadUrl: 'https://jmap.example.com/download/{blobId}',
+                uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+                state: '123',
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        if (body?.methodCalls?.[0]?.[0] === 'Mailbox/get') {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Mailbox/get',
+                    {
+                      list: [
+                        {
+                          id: 'drafts-123',
+                          role: 'drafts',
+                          name: 'Drafts',
+                        },
+                      ],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        if (body?.methodCalls?.[0]?.[0] === 'Identity/get') {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Identity/get',
+                    {
+                      list: [{ id: 'id-1', email: 'sender@example.com' }],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        // Batch with partial failure: draft1 fails
+        if (body?.methodCalls?.[0]?.[0] === 'Email/set') {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Email/set',
+                    {
+                      created: {
+                        draft0: { id: 'email-0' },
+                        draft2: { id: 'email-2' },
+                      },
+                      notCreated: {
+                        draft1: {
+                          type: 'invalidProperties',
+                          description: 'Invalid recipient',
+                        },
+                      },
+                    },
+                    'c0',
+                  ],
+                  [
+                    'EmailSubmission/set',
+                    {
+                      created: {
+                        sub0: { id: 'submission-0' },
+                        sub2: { id: 'submission-2' },
+                      },
+                      notCreated: {
+                        sub1: {
+                          type: 'invalidEmail',
+                          description: 'Email not created',
+                        },
+                      },
+                    },
+                    'c1',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        return Promise.resolve(new Response('Not found', { status: 404 }));
+      };
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+        retries: 0,
+        timeout: 5000,
+      });
+
+      const messages = [
+        { ...baseMessage, subject: 'Test 1' },
+        { ...baseMessage, subject: 'Test 2' },
+        { ...baseMessage, subject: 'Test 3' },
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 3);
+
+      // First message: success
+      assert.ok(receipts[0].successful);
+      assert.equal(receipts[0].messageId, 'submission-0');
+
+      // Second message: failure
+      assert.ok(!receipts[1].successful);
+      const failedReceipt = receipts[1];
+      assert.ok(failedReceipt.errorMessages.some((e) => e.includes('invalidProperties')));
+
+      // Third message: success
+      assert.ok(receipts[2].successful);
+      assert.equal(receipts[2].messageId, 'submission-2');
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('sendMany batch - attachment upload timeout', () => {
+  it('should return retryable timeout receipts', async () => {
+    const originalFetch = globalThis.fetch;
+
+    try {
+      globalThis.fetch = (input, init) => {
+        const url =
+          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+
+        const body = init?.body && typeof init.body === 'string' ? JSON.parse(init.body) : null;
+
+        if (url.includes('.well-known/jmap')) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                capabilities: {},
+                accounts: {
+                  'acc-1': {
+                    name: 'Test',
+                    isPersonal: true,
+                    isReadOnly: false,
+                    accountCapabilities: { 'urn:ietf:params:jmap:mail': {} },
+                  },
+                },
+                primaryAccounts: {},
+                username: 'test@example.com',
+                apiUrl: 'https://jmap.example.com/api',
+                downloadUrl: 'https://jmap.example.com/download/{blobId}',
+                uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+                state: '123',
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        if (body?.methodCalls?.[0]?.[0] === 'Mailbox/get') {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Mailbox/get',
+                    {
+                      list: [
+                        {
+                          id: 'drafts-123',
+                          role: 'drafts',
+                          name: 'Drafts',
+                        },
+                      ],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        if (body?.methodCalls?.[0]?.[0] === 'Identity/get') {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                methodResponses: [
+                  [
+                    'Identity/get',
+                    {
+                      list: [{ id: 'id-1', email: 'sender@example.com' }],
+                    },
+                    'c0',
+                  ],
+                ],
+              }),
+              { status: 200 },
+            ),
+          );
+        }
+
+        if (url.includes('/upload/')) {
+          return new Promise((_resolve, reject) => {
+            assert.ok(init?.signal instanceof AbortSignal);
+            init.signal.addEventListener(
+              'abort',
+              () => {
+                reject(init.signal?.reason);
+              },
+              { once: true },
+            );
+          });
+        }
+
+        return Promise.resolve(new Response('Not found', { status: 404 }));
+      };
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+        retries: 0,
+        timeout: 1,
+      });
+
+      const messages = [
+        {
+          ...baseMessage,
+          attachments: [
+            {
+              filename: 'timeout.txt',
+              contentType: 'text/plain',
+              content: new Uint8Array([1, 2, 3]),
+              contentId: 'timeout-attachment',
+              inline: false,
+            },
+          ],
+        },
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 1);
+      const receipt = receipts[0];
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.provider, 'jmap');
+        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.errors?.[0]?.category, 'timeout');
+        assert.equal(receipt.errors?.[0]?.retryable, true);
+        assert.equal(receipt.errors?.[0]?.code, 'abort');
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});
+
+describe('sendMany batch - empty', () => {
+  it('should yield empty for no messages', async () => {
+    const transport = new JmapTransport({
+      sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+      bearerToken: 'test-token',
+    });
+
+    const receipts = [];
+    for await (const receipt of transport.sendMany([])) {
+      receipts.push(receipt);
+    }
+
+    assert.equal(receipts.length, 0);
+  });
+});
diff --git a/tests/unit/jmap-session.test.js b/tests/unit/jmap-session.test.js
new file mode 100644
index 0000000..70b4ac8
--- /dev/null
+++ b/tests/unit/jmap-session.test.js
@@ -0,0 +1,91 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/session.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { findMailAccount } = require('../../src/jmap/session.js');
+
+describe('findMailAccount', () => {
+  it('should find account with mail capability', () => {
+    const session = {
+      capabilities: {},
+      accounts: {
+        'account-1': {
+          name: 'Test Account',
+          isPersonal: true,
+          isReadOnly: false,
+          accountCapabilities: {
+            'urn:ietf:params:jmap:mail': {},
+          },
+        },
+      },
+      primaryAccounts: {},
+      username: 'test@example.com',
+      apiUrl: 'https://jmap.example.com/api',
+      downloadUrl: 'https://jmap.example.com/download/{blobId}',
+      uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+      state: '123',
+    };
+
+    const accountId = findMailAccount(session);
+    assert.equal(accountId, 'account-1');
+  });
+
+  it('should return null when no mail account exists', () => {
+    const session = {
+      capabilities: {},
+      accounts: {
+        'account-1': {
+          name: 'Contacts Account',
+          isPersonal: true,
+          isReadOnly: false,
+          accountCapabilities: {
+            'urn:ietf:params:jmap:contacts': {},
+          },
+        },
+      },
+      primaryAccounts: {},
+      username: 'test@example.com',
+      apiUrl: 'https://jmap.example.com/api',
+      downloadUrl: 'https://jmap.example.com/download/{blobId}',
+      uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+      state: '123',
+    };
+
+    const accountId = findMailAccount(session);
+    assert.equal(accountId, null);
+  });
+
+  it('should find first mail account when multiple exist', () => {
+    const session = {
+      capabilities: {},
+      accounts: {
+        'contacts-only': {
+          name: 'Contacts Only',
+          isPersonal: true,
+          isReadOnly: false,
+          accountCapabilities: {
+            'urn:ietf:params:jmap:contacts': {},
+          },
+        },
+        'mail-account': {
+          name: 'Mail Account',
+          isPersonal: true,
+          isReadOnly: false,
+          accountCapabilities: {
+            'urn:ietf:params:jmap:mail': {},
+          },
+        },
+      },
+      primaryAccounts: {},
+      username: 'test@example.com',
+      apiUrl: 'https://jmap.example.com/api',
+      downloadUrl: 'https://jmap.example.com/download/{blobId}',
+      uploadUrl: 'https://jmap.example.com/upload/{accountId}',
+      state: '123',
+    };
+
+    const accountId = findMailAccount(session);
+    assert.equal(accountId, 'mail-account');
+  });
+});
diff --git a/tests/unit/jmap-transport.test.js b/tests/unit/jmap-transport.test.js
new file mode 100644
index 0000000..1f9226f
--- /dev/null
+++ b/tests/unit/jmap-transport.test.js
@@ -0,0 +1,202 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/jmap-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+
+const baseMessage = {
+  sender: { address: 'sender@example.com' },
+  recipients: [{ address: 'recipient@example.com' }],
+  ccRecipients: [],
+  bccRecipients: [],
+  replyRecipients: [],
+  attachments: [],
+  subject: 'Test Subject',
+  content: { text: 'Hello, World!' },
+  priority: 'normal',
+  tags: [],
+  headers: new Headers(),
+};
+
+describe('JmapTransport', () => {
+  describe('constructor', () => {
+    it('should create transport with config', () => {
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+      });
+
+      assert.ok(transport);
+      assert.equal(transport.config.sessionUrl, 'https://jmap.example.com/.well-known/jmap');
+    });
+  });
+
+  describe('send', () => {
+    it('should reject already-aborted signals', async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+      });
+
+      await assert.rejects(
+        () => transport.send(baseMessage, { signal: controller.signal }),
+        (error) => error instanceof Error && error.name === 'AbortError',
+      );
+    });
+
+    it('should reject already-aborted signals with custom reasons', async () => {
+      const controller = new AbortController();
+      controller.abort('stop');
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+      });
+
+      await assert.rejects(
+        () => transport.send(baseMessage, { signal: controller.signal }),
+        (error) => error === 'stop',
+      );
+    });
+
+    it('should reject caller aborts during fetch', async () => {
+      const originalFetch = globalThis.fetch;
+      const controller = new AbortController();
+
+      try {
+        globalThis.fetch = (_input, init) =>
+          new Promise((_resolve, reject) => {
+            init?.signal?.addEventListener(
+              'abort',
+              () => {
+                reject(new DOMException('The operation was aborted.', 'AbortError'));
+              },
+              { once: true },
+            );
+            setTimeout(() => controller.abort(), 0);
+          });
+
+        const transport = new JmapTransport({
+          sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+          bearerToken: 'test-token',
+          retries: 0,
+        });
+
+        await assert.rejects(
+          () => transport.send(baseMessage, { signal: controller.signal }),
+          (error) => error instanceof Error && error.name === 'AbortError',
+        );
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+
+    it('should reject caller aborts with AbortError without a reason', async () => {
+      const originalFetch = globalThis.fetch;
+      const controller = new AbortController();
+      Object.defineProperty(controller.signal, 'reason', {
+        value: undefined,
+      });
+
+      try {
+        globalThis.fetch = (_input, init) =>
+          new Promise((_resolve, reject) => {
+            init?.signal?.addEventListener(
+              'abort',
+              () => {
+                // oxlint-disable-next-line prefer-promise-reject-errors -- upstream
+                reject(undefined);
+              },
+              { once: true },
+            );
+            setTimeout(() => controller.abort(), 0);
+          });
+
+        const transport = new JmapTransport({
+          sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+          bearerToken: 'test-token',
+          retries: 0,
+        });
+
+        await assert.rejects(
+          () => transport.send(baseMessage, { signal: controller.signal }),
+          (error) => error instanceof Error && error.name === 'AbortError',
+        );
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+
+    it('should not expose network errors as reasonless caller aborts', async () => {
+      const originalFetch = globalThis.fetch;
+      const controller = new AbortController();
+      Object.defineProperty(controller.signal, 'reason', {
+        value: undefined,
+      });
+
+      try {
+        globalThis.fetch = (_input, init) =>
+          new Promise((_resolve, reject) => {
+            init?.signal?.addEventListener(
+              'abort',
+              () => {
+                reject(new TypeError('fetch failed'));
+              },
+              { once: true },
+            );
+            setTimeout(() => controller.abort(), 0);
+          });
+
+        const transport = new JmapTransport({
+          sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+          bearerToken: 'test-token',
+          retries: 0,
+        });
+
+        await assert.rejects(
+          () => transport.send(baseMessage, { signal: controller.signal }),
+          (error) =>
+            error instanceof Error &&
+            error.name === 'AbortError' &&
+            error.message !== 'fetch failed',
+        );
+      } finally {
+        globalThis.fetch = originalFetch;
+      }
+    });
+  });
+
+  describe('sendMany', () => {
+    it('should reject already-aborted signals with custom reasons', async () => {
+      const controller = new AbortController();
+      controller.abort('stop');
+
+      const transport = new JmapTransport({
+        sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+        bearerToken: 'test-token',
+      });
+
+      await assert.rejects(
+        async () => {
+          // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+          for await (const _receipt of transport.sendMany([baseMessage], {
+            signal: controller.signal,
+          })) {
+            // Consume the async iterable to trigger sendMany().
+          }
+        },
+        (error) => error === 'stop',
+      );
+    });
+  });
+});
+
+// Note: Complex tests with fetch mocking are in separate files:
+// - send-success.test.ts (successful send test)
+// - send-error.test.ts (error handling test)
+// - sendmany.test.ts (sendMany tests)
+// This avoids test interference issues with globalThis.fetch mocking
diff --git a/tests/unit/jmap-verify.test.js b/tests/unit/jmap-verify.test.js
new file mode 100644
index 0000000..7a06e6b
--- /dev/null
+++ b/tests/unit/jmap-verify.test.js
@@ -0,0 +1,334 @@
+// Ported from upyo v0.7.0 (packages/jmap/src/verify.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const { createServer } = require('node:http');
+const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+const { JmapApiError } = require('../../src/jmap/errors.js');
+const { createMessage } = require('../../src/core/message.js');
+
+const core = 'urn:ietf:params:jmap:core';
+const mail = 'urn:ietf:params:jmap:mail';
+const submission = 'urn:ietf:params:jmap:submission';
+
+const setup = async () => {
+  const calls = [];
+  const authorizations = [];
+  let base = '';
+  const state = {
+    status: 200,
+    stall: '',
+    identity: 'identity',
+    drafts: true,
+    methodError: false,
+    duplicate: false,
+    wrongAccount: false,
+    contradiction: false,
+    session: {},
+  };
+  let resolveStalled;
+  const stalledPromise = new Promise((resolve) => {
+    resolveStalled = resolve;
+  });
+  const stalled = { promise: stalledPromise, resolve: resolveStalled };
+  const server = createServer(async (req, res) => {
+    req.on('error', () => {});
+    authorizations.push(req.headers.authorization);
+    const reply = (data) => {
+      res.writeHead(state.status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(data));
+    };
+    if (req.url === '/session') {
+      calls.push('session');
+      if (state.stall === 'session') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.flushHeaders();
+        res.write('{');
+        stalled.resolve();
+        return;
+      }
+      reply(state.session);
+      return;
+    }
+    const chunks = [];
+    try {
+      for await (const chunk of req) chunks.push(chunk);
+    } catch {
+      return;
+    }
+    const request = JSON.parse(Buffer.concat(chunks).toString());
+    const [name, args, id] = request.methodCalls[0];
+    calls.push(name);
+    if (name === 'Email/set') {
+      calls.push('EmailSubmission/set');
+      reply({
+        methodResponses: [
+          ['Email/set', { created: { draft: { id: 'email' } } }, 'c0'],
+          ['EmailSubmission/set', { created: { submission: { id: 'sent' } } }, 'c1'],
+        ],
+      });
+      return;
+    }
+    if (state.stall === name) {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.flushHeaders();
+      res.write('{');
+      stalled.resolve();
+      return;
+    }
+    const list =
+      name === 'Mailbox/get'
+        ? state.drafts
+          ? [{ id: 'drafts', role: 'drafts' }]
+          : []
+        : [{ id: state.identity, email: '*@example.com' }];
+    const response = state.methodError
+      ? ['error', { type: 'forbidden', description: 'Not allowed.' }, id]
+      : [
+          name,
+          {
+            accountId: state.wrongAccount ? 'other' : args.accountId,
+            list,
+            notFound: state.contradiction ? [state.identity] : [],
+          },
+          id,
+        ];
+    reply({
+      methodResponses: state.duplicate ? [response, response] : [response],
+    });
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address();
+  assert.ok(address && typeof address !== 'string');
+  base = `http://127.0.0.1:${address.port}`;
+  state.session = {
+    capabilities: { [core]: {}, [mail]: {}, [submission]: {} },
+    accounts: {
+      a: {
+        isReadOnly: false,
+        accountCapabilities: { [mail]: {}, [submission]: {} },
+      },
+    },
+    apiUrl: base + '/api',
+  };
+  return {
+    state,
+    calls,
+    authorizations,
+    stalled,
+    base,
+    async close() {
+      server.closeAllConnections();
+      await new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+};
+
+test('JMAP verification always performs fresh read-only discovery', async () => {
+  const fixture = await setup();
+  try {
+    const transport = new JmapTransport({
+      sessionUrl: fixture.base + '/session',
+      bearerToken: 'token',
+      identityId: 'identity',
+      baseUrl: fixture.base,
+      retries: 0,
+    });
+    assert.equal(await transport.verify(), undefined);
+    await transport.verify();
+    assert.deepEqual(fixture.calls, [
+      'session',
+      'Mailbox/get',
+      'Identity/get',
+      'session',
+      'Mailbox/get',
+      'Identity/get',
+    ]);
+    assert.ok(fixture.authorizations.every((value) => value === 'Bearer token'));
+    fixture.state.status = 401;
+    await assert.rejects(
+      transport.verify(),
+      (e) => e instanceof JmapApiError && e.statusCode === 401,
+    );
+  } finally {
+    await fixture.close();
+  }
+});
+
+for (const failure of [
+  'capabilities',
+  'accounts',
+  'apiUrl',
+  'readonly',
+  'mailOnly',
+  'unknownAccount',
+  'identity',
+  'drafts',
+  'methodError',
+  'duplicate',
+  'wrongAccount',
+  'contradiction',
+]) {
+  test(`JMAP verification rejects ${failure}`, async () => {
+    const f = await setup();
+    try {
+      if (failure === 'capabilities' || failure === 'accounts' || failure === 'apiUrl') {
+        f.state.session[failure] = null;
+      } else if (failure === 'readonly') {
+        f.state.session.accounts = {
+          a: {
+            isReadOnly: true,
+            accountCapabilities: { [mail]: {}, [submission]: {} },
+          },
+        };
+      } else if (failure === 'mailOnly') {
+        f.state.session.accounts = {
+          a: { isReadOnly: false, accountCapabilities: { [mail]: {} } },
+        };
+      } else if (failure === 'identity') f.state.identity = 'wrong';
+      else if (failure === 'drafts') f.state.drafts = false;
+      else if (failure !== 'unknownAccount') f.state[failure] = true;
+      const transport = new JmapTransport({
+        sessionUrl: f.base + '/session',
+        basicAuth: { username: 'u', password: 'p' },
+        accountId: failure === 'unknownAccount' ? 'missing' : undefined,
+        identityId: 'identity',
+        retries: 0,
+      });
+      await assert.rejects(
+        transport.verify(),
+        (e) =>
+          e instanceof JmapApiError &&
+          (failure !== 'methodError' || e.jmapErrorType === 'forbidden'),
+      );
+      assert.ok(f.calls.every((name) => ['session', 'Mailbox/get', 'Identity/get'].includes(name)));
+    } finally {
+      await f.close();
+    }
+  });
+}
+
+for (const stage of ['session', 'Mailbox/get', 'Identity/get']) {
+  for (const cancel of [false, true]) {
+    test(`JMAP ${stage} body ${cancel ? 'cancellation' : 'timeout'} settles`, async () => {
+      const f = await setup();
+      f.state.stall = stage;
+      const controller = new AbortController();
+      const reason = new TypeError('Stopped.');
+      try {
+        const transport = new JmapTransport({
+          sessionUrl: f.base + '/session',
+          bearerToken: 'token',
+          timeout: cancel ? 5000 : 100,
+          retries: 0,
+        });
+        const pending = transport.verify({ signal: controller.signal });
+        const checked = assert.rejects(pending, (e) =>
+          cancel ? e === reason : e instanceof JmapApiError,
+        );
+        await f.stalled.promise;
+        if (cancel) controller.abort(reason);
+        await checked;
+      } finally {
+        controller.abort(reason);
+        await f.close();
+      }
+    });
+  }
+}
+
+test('JMAP pre-abort preserves arbitrary reasons without I/O', async () => {
+  const f = await setup();
+  try {
+    const transport = new JmapTransport({
+      sessionUrl: f.base + '/session',
+      bearerToken: 'token',
+    });
+    const controller = new AbortController();
+    controller.abort(null);
+    await assert.rejects(transport.verify({ signal: controller.signal }), (e) => e === null);
+    assert.deepEqual(f.calls, []);
+  } finally {
+    await f.close();
+  }
+});
+
+for (const accountId of [undefined, 'a']) {
+  test(`all Session accounts are validated, configured=${accountId != null}`, async () => {
+    const f = await setup();
+    try {
+      f.state.session.accounts = {
+        broken: null,
+        ...Object(f.state.session.accounts),
+      };
+      const transport = new JmapTransport({
+        sessionUrl: f.base + '/session',
+        bearerToken: 'token',
+        accountId,
+      });
+      await assert.rejects(
+        transport.verify(),
+        (e) => e instanceof JmapApiError && e.message.includes('broken'),
+      );
+      assert.deepEqual(f.calls, ['session']);
+    } finally {
+      await f.close();
+    }
+  });
+}
+
+test('verification bypasses and preserves a populated delivery Session cache', async () => {
+  const f = await setup();
+  try {
+    const transport = new JmapTransport({
+      sessionUrl: f.base + '/session',
+      bearerToken: 'token',
+      identityId: 'identity',
+      retries: 0,
+    });
+    const message = createMessage({
+      from: 'a@example.com',
+      to: 'b@example.com',
+      subject: 'Test',
+      content: { text: 'Test' },
+    });
+    assert.ok((await transport.send(message)).successful);
+    assert.equal(f.calls.filter((c) => c === 'session').length, 1);
+    f.state.status = 401;
+    await assert.rejects(transport.verify(), JmapApiError);
+    assert.equal(f.calls.filter((c) => c === 'session').length, 2);
+    f.state.status = 200;
+    await transport.verify();
+    assert.equal(f.calls.filter((c) => c === 'session').length, 3);
+    assert.ok((await transport.send(message)).successful);
+    assert.equal(f.calls.filter((c) => c === 'session').length, 3);
+  } finally {
+    await f.close();
+  }
+});
+
+test('verification follows the structured-send account and honors explicit account selection', async () => {
+  const f = await setup();
+  try {
+    f.state.session.accounts = {
+      first: { isReadOnly: false, accountCapabilities: { [mail]: {} } },
+      second: {
+        isReadOnly: false,
+        accountCapabilities: { [mail]: {}, [submission]: {} },
+      },
+    };
+    const config = {
+      sessionUrl: f.base + '/session',
+      bearerToken: 'token',
+      retries: 0,
+    };
+    await assert.rejects(
+      new JmapTransport(config).verify(),
+      (e) => e instanceof JmapApiError && e.message.includes('first'),
+    );
+    await new JmapTransport({ ...config, accountId: 'second' }).verify();
+  } finally {
+    await f.close();
+  }
+});
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
new file mode 100644
index 0000000..5a7a374
--- /dev/null
+++ b/tests/unit/jmap.test.js
@@ -0,0 +1,167 @@
+// Paths of the ported JMAP transport (src/jmap/) that upstream reaches only
+// through its e2e suite against Stalwart: account, mailbox and identity
+// discovery failures, rejected creations and submissions, against a fake
+// JMAP server on a stubbed fetch.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { JmapTransport } = require('../../src/jmap/index.js');
+
+const CORE = 'urn:ietf:params:jmap:core';
+const MAIL = 'urn:ietf:params:jmap:mail';
+const SUBMISSION = 'urn:ietf:params:jmap:submission';
+
+const message = () =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+const session = (overrides = {}) => ({
+  capabilities: { [CORE]: {}, [MAIL]: {}, [SUBMISSION]: {} },
+  accounts: {
+    a1: {
+      name: 'Alex',
+      isPersonal: true,
+      isReadOnly: false,
+      accountCapabilities: { [MAIL]: {}, [SUBMISSION]: {} },
+    },
+  },
+  primaryAccounts: { [MAIL]: 'a1' },
+  username: 'alex@example.com',
+  apiUrl: 'https://jmap.example.com/api',
+  downloadUrl: 'https://jmap.example.com/download/{accountId}/{blobId}/{name}',
+  uploadUrl: 'https://jmap.example.com/upload/{accountId}/',
+  eventSourceUrl: 'https://jmap.example.com/events',
+  state: '1',
+  ...overrides,
+});
+const defaults = {
+  'Mailbox/get': () => ({ list: [{ id: 'drafts', role: 'drafts', name: 'Drafts' }] }),
+  'Identity/get': () => ({ list: [{ id: 'i1', email: 'alex@example.com', name: 'Alex' }] }),
+  'Email/set': () => ({ created: { draft: { id: 'e1', blobId: 'b1', threadId: 't1' } } }),
+  'EmailSubmission/set': () => ({ created: { submission: { id: 's1' } } }),
+};
+
+// A fake JMAP server: the session document, then one response per method
+// call; a handler that returns null leaves its method out of the reply.
+const serve = (t, handlers = {}) => {
+  const calls = [];
+  t.mock.method(globalThis, 'fetch', async (input, init) => {
+    const url = String(input);
+    calls.push(url);
+    if (url.endsWith('/.well-known/jmap')) return Response.json(handlers.session ?? session());
+    const { methodCalls } = JSON.parse(init.body);
+    const methodResponses = [];
+    for (const [name, args, id] of methodCalls) {
+      calls.push(name);
+      const result = (handlers[name] ?? defaults[name])(args);
+      if (result !== null) methodResponses.push([name, result, id]);
+    }
+    return Response.json({ methodResponses });
+  });
+  return calls;
+};
+const transport = (config = {}) =>
+  new JmapTransport({
+    sessionUrl: 'https://jmap.example.com/.well-known/jmap',
+    bearerToken: 'token',
+    retries: 0,
+    ...config,
+  });
+const errorOf = async (receiptPromise) => {
+  const receipt = await receiptPromise;
+  assert.strictEqual(receipt.successful, false);
+  return receipt.errorMessages.join(' | ');
+};
+
+test('JMAP: a message goes out, through the base URL when one is set', async (t) => {
+  const calls = serve(t);
+  const receipt = await transport({ baseUrl: 'http://localhost:8080' }).send(message());
+  assert.strictEqual(receipt.successful, true);
+  assert.ok(calls.includes('http://localhost:8080/api'), calls.join(', '));
+});
+
+test('JMAP: a session without a mail account fails every message', async (t) => {
+  const accounts = {
+    a1: { name: 'A', isPersonal: true, isReadOnly: false, accountCapabilities: {} },
+  };
+  serve(t, { session: session({ accounts, primaryAccounts: {} }) });
+  assert.match(await errorOf(transport().send(message())), /No mail-capable account found/);
+  const receipts = [];
+  for await (const receipt of transport().sendMany([message(), message()])) receipts.push(receipt);
+  assert.deepStrictEqual(
+    receipts.map((receipt) => receipt.errors[0].code),
+    ['jmap.no_mail_account', 'jmap.no_mail_account'],
+  );
+});
+
+test('JMAP: mailbox discovery fails without a reply, mailboxes or drafts', async (t) => {
+  const cases = [
+    [() => null, /No Mailbox\/get response received/],
+    [() => ({}), /No mailboxes found/],
+    [() => ({ list: [{ id: 'inbox', role: 'inbox', name: 'Inbox' }] }), /No drafts mailbox found/],
+  ];
+  for (const [mailboxes, expected] of cases) {
+    t.mock.restoreAll();
+    serve(t, { 'Mailbox/get': mailboxes });
+    assert.match(await errorOf(transport().send(message())), expected);
+  }
+});
+
+test('JMAP: identity discovery fails without a reply or identities; a set id skips it', async (t) => {
+  for (const [identities, expected] of [
+    [() => null, /No Identity\/get response received/],
+    [() => ({ list: [] }), /No identities found/],
+  ]) {
+    t.mock.restoreAll();
+    serve(t, { 'Identity/get': identities });
+    assert.match(await errorOf(transport().send(message())), expected);
+  }
+  t.mock.restoreAll();
+  const calls = serve(t);
+  assert.strictEqual((await transport({ identityId: 'i9' }).send(message())).successful, true);
+  assert.ok(!calls.includes('Identity/get'));
+});
+
+test('JMAP: rejected creations and submissions fail the send', async (t) => {
+  const cases = [
+    [
+      {
+        'EmailSubmission/set': () => ({}),
+        'Email/set': () => ({
+          notCreated: { draft: { type: 'invalidProperties', description: 'bad' } },
+        }),
+      },
+      /Email creation failed \(draft\): invalidProperties - bad/,
+    ],
+    [
+      { 'EmailSubmission/set': () => ({ notCreated: { submission: { type: 'forbiddenFrom' } } }) },
+      /Email submission failed \(submission\): forbiddenFrom/,
+    ],
+    [
+      { 'Email/set': () => ({}), 'EmailSubmission/set': () => ({}) },
+      /Unknown error: No submission result received/,
+    ],
+  ];
+  for (const [handlers, expected] of cases) {
+    t.mock.restoreAll();
+    serve(t, handlers);
+    assert.match(await errorOf(transport().send(message())), expected);
+  }
+});
+
+test('JMAP: an abort that is not the caller fails the send as retryable', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => {
+    throw new DOMException('The operation was aborted.', 'AbortError');
+  });
+  const receipt = await transport().send(message());
+  assert.strictEqual(receipt.successful, false);
+  assert.strictEqual(receipt.retryable, true);
+});
+
+test('JMAP: verification refuses a session without the submission capability', async (t) => {
+  serve(t, { session: session({ capabilities: { [CORE]: {}, [MAIL]: {} } }) });
+  await assert.rejects(transport().verify(), /lacks core, mail, or submission capability/);
+});

From ee484e85a01cf599a1d7773c31142569f732b308 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:32:39 +0300
Subject: [PATCH 015/158] feat(retry): port the retry decorator from upyo 0.7.0

./retry exports RetryTransport and createRetryTransport: a transport that
wraps another one and retries a failed send with exponential backoff, full
or no jitter and Retry-After, under an attempt limit; a custom shouldRetry
and wait can be passed, a caller's abort is never retried, and sendMany
keeps the input order under a concurrency limit and a launch interval.

Upstream's suite is ported; its iterator accesses split over lines are
rewritten through a variable (no-unexpected-multiline), the behavior is the
same. tests/unit/retry.test.js covers the default wait, the validation of
the options and receipts without a retryable flag.

Every d.ts that uses AsyncDisposable now references esnext.disposable on its
own, and the subpath d.ts files import types only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml           |    2 +-
 package.json                       |    4 +
 src/lettermint/index.d.ts          |    2 +-
 src/maileroo/index.d.ts            |    2 +-
 src/mailgun/index.d.ts             |    2 +-
 src/mailtrap/index.d.ts            |    2 +-
 src/mock/index.d.ts                |    2 +-
 src/plunk/index.d.ts               |    2 +-
 src/resend/index.d.ts              |    2 +-
 src/retry/config.js                |   85 ++
 src/retry/index.d.ts               |  245 ++++++
 src/retry/index.js                 |    6 +
 src/retry/retry-transport.js       |  486 +++++++++++
 src/sendgrid/index.d.ts            |    2 +-
 src/ses/index.d.ts                 |    2 +-
 tests/e2e/jmap/docker-compose.yml  |    2 +-
 tests/types/retry.test-d.ts        |   25 +
 tests/unit/retry-transport.test.js | 1225 ++++++++++++++++++++++++++++
 tests/unit/retry.test.js           |   99 +++
 19 files changed, 2186 insertions(+), 11 deletions(-)
 create mode 100644 src/retry/config.js
 create mode 100644 src/retry/index.d.ts
 create mode 100644 src/retry/index.js
 create mode 100644 src/retry/retry-transport.js
 create mode 100644 tests/types/retry.test-d.ts
 create mode 100644 tests/unit/retry-transport.test.js
 create mode 100644 tests/unit/retry.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bc9d744..c351412 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-retry 3 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 33effeb..313657b 100644
--- a/package.json
+++ b/package.json
@@ -68,6 +68,10 @@
       "types": "./src/plunk/index.d.ts",
       "default": "./src/plunk/index.js"
     },
+    "./retry": {
+      "types": "./src/retry/index.d.ts",
+      "default": "./src/retry/index.js"
+    },
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
diff --git a/src/lettermint/index.d.ts b/src/lettermint/index.d.ts
index f9be7ba..5b7ea3a 100644
--- a/src/lettermint/index.d.ts
+++ b/src/lettermint/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/lettermint/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Per-email Lettermint tracking settings.
diff --git a/src/maileroo/index.d.ts b/src/maileroo/index.d.ts
index ddfa482..668a43f 100644
--- a/src/maileroo/index.d.ts
+++ b/src/maileroo/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/maileroo/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Configuration interface for Maileroo transport connection settings.
diff --git a/src/mailgun/index.d.ts b/src/mailgun/index.d.ts
index b876619..7534647 100644
--- a/src/mailgun/index.d.ts
+++ b/src/mailgun/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/mailgun/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Configuration interface for Mailgun transport connection settings.
diff --git a/src/mailtrap/index.d.ts b/src/mailtrap/index.d.ts
index a771624..fd7cf37 100644
--- a/src/mailtrap/index.d.ts
+++ b/src/mailtrap/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/mailtrap/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Configuration interface for Mailtrap transport connection settings.
diff --git a/src/mock/index.d.ts b/src/mock/index.d.ts
index 3c17a26..0c74e1b 100644
--- a/src/mock/index.d.ts
+++ b/src/mock/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/mock/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Configuration interface for Mock transport.
diff --git a/src/plunk/index.d.ts b/src/plunk/index.d.ts
index b0eef69..a861a0a 100644
--- a/src/plunk/index.d.ts
+++ b/src/plunk/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/plunk/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Configuration interface for Plunk transport connection settings.
diff --git a/src/resend/index.d.ts b/src/resend/index.d.ts
index f02c65b..87767ef 100644
--- a/src/resend/index.d.ts
+++ b/src/resend/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/resend/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Configuration interface for Resend transport connection settings.
diff --git a/src/retry/config.js b/src/retry/config.js
new file mode 100644
index 0000000..ff76cc1
--- /dev/null
+++ b/src/retry/config.js
@@ -0,0 +1,85 @@
+// Ported from upyo v0.7.0 (packages/retry/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved retry configuration.
+ *
+ * @param config Retry configuration.
+ * @returns The resolved configuration.
+ * @throws {RangeError} If a numeric option is out of range.
+ */
+const createRetryConfig = (config = {}) => {
+  const maxAttempts = config.maxAttempts ?? 3;
+  const baseDelayMilliseconds = config.backoff?.baseDelayMilliseconds ?? 1000;
+  const maxDelayMilliseconds = config.backoff?.maxDelayMilliseconds ?? 30000;
+  const factor = config.backoff?.factor ?? 2;
+  const maxConcurrent = config.sendMany?.maxConcurrent ?? 1;
+  const intervalMilliseconds = config.sendMany?.intervalMilliseconds ?? 0;
+
+  assertIntegerAtLeast(maxAttempts, 1, 'maxAttempts');
+  assertFiniteAtLeast(baseDelayMilliseconds, 0, 'backoff.baseDelayMilliseconds');
+  assertFiniteAtLeast(maxDelayMilliseconds, 0, 'backoff.maxDelayMilliseconds');
+  assertFiniteAtLeast(factor, 1, 'backoff.factor');
+  assertIntegerAtLeast(maxConcurrent, 1, 'sendMany.maxConcurrent');
+  assertFiniteAtLeast(intervalMilliseconds, 0, 'sendMany.intervalMilliseconds');
+
+  return {
+    maxAttempts,
+    backoff: {
+      baseDelayMilliseconds,
+      maxDelayMilliseconds,
+      factor,
+    },
+    jitter: config.jitter ?? 'full',
+    random: config.random ?? Math.random,
+    shouldRetry: config.shouldRetry,
+    wait: config.wait ?? defaultWait,
+    sendMany: {
+      maxConcurrent,
+      intervalMilliseconds,
+    },
+  };
+};
+
+const defaultWait = async (context, signal) => {
+  signal?.throwIfAborted();
+  if (context.delayMilliseconds <= 0) return;
+
+  await new Promise((resolve, reject) => {
+    const cleanup = () => signal?.removeEventListener('abort', abort);
+    const timeout = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, context.delayMilliseconds);
+    const abort = () => {
+      clearTimeout(timeout);
+      cleanup();
+      reject(signal?.reason ?? createAbortError());
+    };
+
+    if (signal?.aborted) {
+      abort();
+      return;
+    }
+
+    signal?.addEventListener('abort', abort, { once: true });
+  });
+};
+
+const assertIntegerAtLeast = (value, minimum, name) => {
+  if (!Number.isInteger(value) || value < minimum) {
+    throw new RangeError(`${name} must be an integer greater than or equal to ${minimum}.`);
+  }
+};
+
+const assertFiniteAtLeast = (value, minimum, name) => {
+  if (!Number.isFinite(value) || value < minimum) {
+    throw new RangeError(`${name} must be greater than or equal to ${minimum}.`);
+  }
+};
+
+const createAbortError = () => {
+  return new DOMException('The operation was aborted.', 'AbortError');
+};
+
+module.exports = { createRetryConfig };
diff --git a/src/retry/index.d.ts b/src/retry/index.d.ts
new file mode 100644
index 0000000..2ac248a
--- /dev/null
+++ b/src/retry/index.d.ts
@@ -0,0 +1,245 @@
+// Types ported from upyo v0.7.0 (packages/retry/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/// <reference lib="esnext.disposable" />
+
+import type { Message, Receipt, ReceiptError, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Jitter mode for computed retry delays.
+ */
+export type JitterConfig = false | 'none' | 'full';
+/**
+ * Exponential backoff settings for retry delays.
+ */
+export interface BackoffConfig {
+  /**
+   * Delay before the first retry, in milliseconds.
+   *
+   * @default 1000
+   */
+  readonly baseDelayMilliseconds?: number;
+  /**
+   * Maximum computed delay, in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly maxDelayMilliseconds?: number;
+  /**
+   * Multiplier applied after each failed attempt.
+   *
+   * @default 2
+   */
+  readonly factor?: number;
+}
+/**
+ * Context passed to custom retry wait functions.
+ */
+export interface DelayContext<TProviderId extends string = string> {
+  /**
+   * Attempt that just failed.
+   */
+  readonly attempt: number;
+  /**
+   * Attempt that will run after this delay.
+   */
+  readonly nextAttempt: number;
+  /**
+   * Maximum configured attempts.
+   */
+  readonly maxAttempts: number;
+  /**
+   * Delay to wait before retrying, in milliseconds.
+   */
+  readonly delayMilliseconds: number;
+  /**
+   * Failed receipt that caused the retry, when the transport returned one.
+   */
+  readonly receipt?: Receipt<TProviderId> & {
+    readonly successful: false;
+  };
+  /**
+   * Thrown error that caused the retry, when the transport rejected.
+   */
+  readonly error?: unknown;
+  /**
+   * Why the delay is being applied.
+   */
+  readonly reason: 'retry' | 'sendMany-throttle';
+}
+/**
+ * Function used to wait between attempts or throttled sends.
+ *
+ * @param context Information about the delay being applied.
+ * @param signal Abort signal that should cancel the wait.
+ * @returns A promise that resolves when the delay is complete.
+ * @throws {DOMException} If the wait is aborted.
+ */
+export type WaitFunction<TProviderId extends string = string> = (
+  context: DelayContext<TProviderId>,
+  signal?: AbortSignal,
+) => Promise<void>;
+/**
+ * Failure passed to a custom retry classifier.
+ */
+export type RetryFailure<TProviderId extends string = string> =
+  | {
+      readonly kind: 'receipt';
+      readonly receipt: Receipt<TProviderId> & {
+        readonly successful: false;
+      };
+    }
+  | {
+      readonly kind: 'error';
+      readonly error: unknown;
+      readonly receiptError?: ReceiptError<TProviderId>;
+    };
+/**
+ * Function that decides whether a failure should be retried.
+ *
+ * @param failure Failed receipt or thrown error metadata.
+ * @returns Whether another attempt should be made.
+ */
+export type RetryClassifier<TProviderId extends string = string> = (
+  failure: RetryFailure<TProviderId>,
+) => boolean;
+/**
+ * Retry behavior for `sendMany()`.
+ */
+export interface SendManyRetryConfig {
+  /**
+   * Maximum number of messages to send at the same time.
+   *
+   * @default 1
+   */
+  readonly maxConcurrent?: number;
+  /**
+   * Minimum delay between launching message sends, in milliseconds.
+   *
+   * @default 0
+   */
+  readonly intervalMilliseconds?: number;
+}
+/**
+ * Configuration for the retry transport decorator.
+ */
+export interface RetryConfig<TProviderId extends string = string> {
+  /**
+   * Total number of send attempts, including the first one.
+   *
+   * @default 3
+   */
+  readonly maxAttempts?: number;
+  /**
+   * Exponential backoff settings.
+   */
+  readonly backoff?: BackoffConfig;
+  /**
+   * Jitter mode applied to computed backoff delays.
+   *
+   * `Retry-After` delays are not jittered.
+   *
+   * @default "full"
+   */
+  readonly jitter?: JitterConfig;
+  /**
+   * Random number source for jitter.
+   *
+   * @default Math.random
+   */
+  readonly random?: () => number;
+  /**
+   * Custom retry classifier.
+   */
+  readonly shouldRetry?: RetryClassifier<TProviderId>;
+  /**
+   * Custom wait function for tests or host-controlled scheduling.
+   */
+  readonly wait?: WaitFunction<TProviderId>;
+  /**
+   * Retry and throttling behavior for `sendMany()`.
+   */
+  readonly sendMany?: SendManyRetryConfig;
+}
+/**
+ * Resolved retry configuration with defaults applied.
+ */
+interface ResolvedRetryConfig<TProviderId extends string = string> {
+  readonly maxAttempts: number;
+  readonly backoff: Required<BackoffConfig>;
+  readonly jitter: JitterConfig;
+  readonly random: () => number;
+  readonly shouldRetry?: RetryClassifier<TProviderId>;
+  readonly wait: WaitFunction<TProviderId>;
+  readonly sendMany: Required<SendManyRetryConfig>;
+}
+/**
+ * Creates a resolved retry configuration.
+ *
+ * @param config Retry configuration.
+ * @returns The resolved configuration.
+ * @throws {RangeError} If a numeric option is out of range.
+ */
+
+/**
+ * Transport decorator that retries transient delivery failures.
+ */
+export declare class RetryTransport<TProviderId extends string = string>
+  implements Transport<TProviderId>, AsyncDisposable
+{
+  readonly id: TProviderId;
+  /**
+   * Resolved retry configuration.
+   */
+  readonly config: ResolvedRetryConfig<TProviderId>;
+  /**
+   * Creates a retrying transport around another transport.
+   *
+   * @param transport The transport to wrap.
+   * @param config Retry configuration.
+   * @throws {RangeError} If retry configuration is invalid.
+   */
+  constructor(transport: Transport<TProviderId>, config?: RetryConfig<TProviderId>);
+  /**
+   * Sends one message, retrying retryable failures.
+   *
+   * @param message The message to send.
+   * @param options Optional transport options.
+   * @returns The final delivery receipt.
+   * @throws {DOMException} If the operation is aborted.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
+  /**
+   * Sends messages with per-message retry behavior.
+   *
+   * Receipts are yielded in the same order as input messages.
+   *
+   * @param messages Messages to send.
+   * @param options Optional transport options.
+   * @returns An async iterable of receipts.
+   * @throws {DOMException} If the operation is aborted.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<TProviderId>>;
+  /**
+   * Disposes the wrapped transport when it supports disposal.
+   *
+   * @throws {unknown} If the wrapped transport's async or sync disposal hook
+   *   throws or rejects.
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Creates a retrying transport around another transport.
+ *
+ * @param baseTransport The transport to wrap.
+ * @param config Retry configuration.
+ * @returns A retrying transport decorator.
+ * @throws {RangeError} If retry configuration is invalid.
+ */
+export declare function createRetryTransport<TProviderId extends string = string>(
+  baseTransport: Transport<TProviderId>,
+  config?: RetryConfig<TProviderId>,
+): RetryTransport<TProviderId>;
diff --git a/src/retry/index.js b/src/retry/index.js
new file mode 100644
index 0000000..3abccea
--- /dev/null
+++ b/src/retry/index.js
@@ -0,0 +1,6 @@
+// Ported from upyo v0.7.0 (packages/retry/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createRetryTransport, RetryTransport } = require('./retry-transport.js');
+
+module.exports = { createRetryTransport, RetryTransport };
diff --git a/src/retry/retry-transport.js b/src/retry/retry-transport.js
new file mode 100644
index 0000000..b6a3cdb
--- /dev/null
+++ b/src/retry/retry-transport.js
@@ -0,0 +1,486 @@
+// Ported from upyo v0.7.0 (packages/retry/src/retry-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const {
+  classifyReceiptError,
+  createFailedReceipt,
+  createReceiptError,
+} = require('../core/receipt.js');
+const { combineSignals } = require('../core/abort-signal.js');
+const { createRetryConfig } = require('./config.js');
+
+/**
+ * Transport decorator that retries transient delivery failures.
+ */
+class RetryTransport {
+  id;
+
+  /**
+   * Resolved retry configuration.
+   */
+  config;
+
+  wrappedTransport;
+
+  /**
+   * Creates a retrying transport around another transport.
+   *
+   * @param transport The transport to wrap.
+   * @param config Retry configuration.
+   * @throws {RangeError} If retry configuration is invalid.
+   */
+  constructor(transport, config = {}) {
+    this.wrappedTransport = transport;
+    this.id = transport.id;
+    this.config = createRetryConfig(config);
+  }
+
+  /**
+   * Sends one message, retrying retryable failures.
+   *
+   * @param message The message to send.
+   * @param options Optional transport options.
+   * @returns The final delivery receipt.
+   * @throws {DOMException} If the operation is aborted.
+   */
+  async send(message, options) {
+    options?.signal?.throwIfAborted();
+
+    let lastThrownError;
+    for (let attempt = 1; attempt <= this.config.maxAttempts; attempt++) {
+      options?.signal?.throwIfAborted();
+
+      let receipt;
+      try {
+        receipt = await this.wrappedTransport.send(message, options);
+      } catch (error) {
+        options?.signal?.throwIfAborted();
+
+        lastThrownError = error;
+        if (attempt >= this.config.maxAttempts || !this.shouldRetryError(error)) {
+          return this.createThrownFailure(error, attempt);
+        }
+
+        await this.waitBeforeRetry(
+          {
+            attempt,
+            nextAttempt: attempt + 1,
+            maxAttempts: this.config.maxAttempts,
+            delayMilliseconds: this.calculateDelay(attempt, toReceiptError(error)),
+            error,
+            reason: 'retry',
+          },
+          options?.signal,
+        );
+        continue;
+      }
+
+      options?.signal?.throwIfAborted();
+
+      if (receipt.successful) {
+        return this.withSuccessMetadata(receipt, attempt);
+      }
+
+      const failedReceipt = this.withFailureMetadata(receipt, attempt);
+      if (attempt >= this.config.maxAttempts || !this.shouldRetryReceipt(failedReceipt)) {
+        return failedReceipt;
+      }
+
+      await this.waitBeforeRetry(
+        {
+          attempt,
+          nextAttempt: attempt + 1,
+          maxAttempts: this.config.maxAttempts,
+          delayMilliseconds: this.calculateDelay(attempt, failedReceipt),
+          receipt: failedReceipt,
+          reason: 'retry',
+        },
+        options?.signal,
+      );
+    }
+
+    return this.createThrownFailure(lastThrownError, this.config.maxAttempts);
+  }
+
+  /**
+   * Sends messages with per-message retry behavior.
+   *
+   * Receipts are yielded in the same order as input messages.
+   *
+   * @param messages Messages to send.
+   * @param options Optional transport options.
+   * @returns An async iterable of receipts.
+   * @throws {DOMException} If the operation is aborted.
+   */
+  async *sendMany(messages, options) {
+    const iterator = toAsyncIterator(messages);
+    const inFlight = new Map();
+    const completed = new Map();
+    let inputDone = false;
+    let nextLaunchIndex = 0;
+    let nextYieldIndex = 0;
+    let launchPromise;
+    let launchError;
+    let hasLaunchError = false;
+    let hasQueuedFailure = false;
+    let pullingInput = false;
+    let closed = false;
+    const controller = new AbortController();
+    const combinedSignal = combineSignals(controller.signal, options?.signal);
+    const sendOptions = {
+      ...options,
+      signal: combinedSignal.signal,
+    };
+
+    const launchNext = async () => {
+      if (inputDone) return;
+      combinedSignal.signal.throwIfAborted();
+
+      pullingInput = true;
+      let inputPull;
+      try {
+        inputPull = Promise.resolve(iterator.next());
+      } catch (error) {
+        inputPull = Promise.reject(error);
+      }
+      inputPull = inputPull.finally(() => {
+        pullingInput = false;
+      });
+      const next = await raceWithAbort(inputPull, combinedSignal.signal);
+      if (closed) return;
+      if (next.done) {
+        inputDone = true;
+        return;
+      }
+
+      const index = nextLaunchIndex++;
+      if (index > 0) await this.waitBetweenSendMany(combinedSignal.signal);
+      if (closed) return;
+      const promise = this.send(next.value, sendOptions).then(
+        (receipt) => ({
+          index,
+          successful: true,
+          receipt,
+        }),
+        (error) => ({
+          index,
+          successful: false,
+          error,
+        }),
+      );
+      inFlight.set(index, promise);
+    };
+
+    const startLaunch = () => {
+      if (
+        launchPromise != null ||
+        inputDone ||
+        hasLaunchError ||
+        hasQueuedFailure ||
+        inFlight.size >= this.config.sendMany.maxConcurrent
+      ) {
+        return;
+      }
+
+      launchPromise = launchNext()
+        .catch((error) => {
+          launchError = error;
+          hasLaunchError = true;
+        })
+        .finally(() => {
+          launchPromise = undefined;
+        });
+    };
+
+    try {
+      startLaunch();
+
+      while (
+        inFlight.size > 0 ||
+        completed.has(nextYieldIndex) ||
+        // oxlint-disable-next-line no-unmodified-loop-condition -- upstream
+        launchPromise != null ||
+        // oxlint-disable-next-line no-unmodified-loop-condition -- upstream
+        !inputDone
+      ) {
+        combinedSignal.signal.throwIfAborted();
+
+        while (completed.has(nextYieldIndex)) {
+          const result = completed.get(nextYieldIndex);
+          completed.delete(nextYieldIndex);
+          if (result == null) break;
+          if (!result.successful) throw result.error;
+          yield result.receipt;
+          nextYieldIndex++;
+          startLaunch();
+        }
+
+        if (hasLaunchError && inFlight.size <= 0) throw launchError;
+
+        startLaunch();
+        if (inFlight.size <= 0 && launchPromise == null) break;
+
+        const launch = launchPromise?.then(() => ({
+          launched: true,
+        }));
+        const result = await raceWithAbort(
+          Promise.race([...inFlight.values(), ...(launch == null ? [] : [launch])]),
+          combinedSignal.signal,
+        );
+        if ('launched' in result) continue;
+        inFlight.delete(result.index);
+        completed.set(result.index, result);
+        if (!result.successful) hasQueuedFailure = true;
+        startLaunch();
+      }
+      if (hasLaunchError) throw launchError;
+    } finally {
+      closed = true;
+      controller.abort(new DOMException('The operation was aborted.', 'AbortError'));
+      launchPromise?.catch(() => {});
+      try {
+        const closeIterator = () => (inputDone ? undefined : iterator.return?.());
+        const closePromise = closeIterator();
+        if (pullingInput) {
+          closePromise?.catch(() => {});
+        } else {
+          await closePromise;
+        }
+      } finally {
+        combinedSignal.cleanup();
+      }
+    }
+  }
+
+  /**
+   * Disposes the wrapped transport when it supports disposal.
+   *
+   * @throws {unknown} If the wrapped transport's async or sync disposal hook
+   *   throws or rejects.
+   */
+  async [Symbol.asyncDispose]() {
+    const wrappedTransport = Object(this.wrappedTransport);
+    const asyncDisposeSymbol = Symbol.asyncDispose;
+    if (typeof asyncDisposeSymbol === 'symbol') {
+      const asyncDispose = wrappedTransport[asyncDisposeSymbol];
+      if (typeof asyncDispose === 'function') {
+        await asyncDispose.call(wrappedTransport);
+        return;
+      }
+    }
+
+    const disposeSymbol = Symbol.dispose;
+    if (typeof disposeSymbol === 'symbol') {
+      const dispose = wrappedTransport[disposeSymbol];
+      if (typeof dispose === 'function') dispose.call(wrappedTransport);
+    }
+  }
+
+  withSuccessMetadata(receipt, attempts) {
+    return {
+      ...receipt,
+      provider: receipt.provider ?? this.id,
+      attempts,
+    };
+  }
+
+  withFailureMetadata(receipt, attempts) {
+    return {
+      ...receipt,
+      provider: receipt.provider ?? this.id,
+      retryable: receipt.retryable ?? this.hasRetryableError(receipt.errors),
+      attempts,
+    };
+  }
+
+  shouldRetryReceipt(receipt) {
+    const shouldRetry = this.config.shouldRetry;
+    if (shouldRetry != null) {
+      return shouldRetry({ kind: 'receipt', receipt });
+    }
+    if (receipt.retryable != null) return receipt.retryable;
+    return this.hasRetryableError(receipt.errors);
+  }
+
+  shouldRetryError(error) {
+    const receiptError = toReceiptError(error);
+    const shouldRetry = this.config.shouldRetry;
+    if (shouldRetry != null) {
+      return shouldRetry({
+        kind: 'error',
+        error,
+        receiptError,
+      });
+    }
+    if (receiptError != null) return receiptError.retryable;
+    if (error instanceof Error && error.name === 'AbortError') return true;
+    return classifyReceiptError(error).retryable;
+  }
+
+  hasRetryableError(errors) {
+    return errors?.some((error) => error.retryable) ?? false;
+  }
+
+  calculateDelay(attempt, failure) {
+    const retryAfterMilliseconds = getRetryAfterMilliseconds(failure);
+    const cappedRetryAfter =
+      retryAfterMilliseconds == null ||
+      !Number.isFinite(retryAfterMilliseconds) ||
+      retryAfterMilliseconds < 0
+        ? undefined
+        : Math.min(retryAfterMilliseconds, this.config.backoff.maxDelayMilliseconds);
+
+    if (cappedRetryAfter != null) return cappedRetryAfter;
+
+    const computedDelay = Math.min(
+      this.config.backoff.baseDelayMilliseconds * Math.pow(this.config.backoff.factor, attempt - 1),
+      this.config.backoff.maxDelayMilliseconds,
+    );
+
+    if (this.config.jitter === false || this.config.jitter === 'none') {
+      return computedDelay;
+    }
+
+    const random = this.config.random;
+    return Math.floor(random() * computedDelay);
+  }
+
+  waitBeforeRetry(context, signal) {
+    const wait = this.config.wait;
+    return wait(context, signal);
+  }
+
+  waitBetweenSendMany(signal) {
+    const delayMilliseconds = this.config.sendMany.intervalMilliseconds;
+    if (delayMilliseconds <= 0) return Promise.resolve();
+    const wait = this.config.wait;
+    return wait(
+      {
+        attempt: 0,
+        nextAttempt: 0,
+        maxAttempts: this.config.maxAttempts,
+        delayMilliseconds,
+        reason: 'sendMany-throttle',
+      },
+      signal,
+    );
+  }
+
+  createThrownFailure(error, attempts) {
+    const receiptError = toReceiptError(error);
+    if (receiptError != null) {
+      return createFailedReceipt(receiptError, {
+        provider: receiptError.provider ?? this.id,
+        attempts,
+      });
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    const classification =
+      error instanceof Error && error.name === 'AbortError'
+        ? {
+            category: 'timeout',
+            code: 'timeout',
+            retryable: true,
+          }
+        : classifyReceiptError(error);
+    return createFailedReceipt(
+      createReceiptError(message, {
+        provider: this.id,
+        category: classification.category,
+        code: classification.code,
+        retryable: classification.retryable,
+      }),
+      {
+        provider: this.id,
+        attempts,
+      },
+    );
+  }
+}
+
+/**
+ * Creates a retrying transport around another transport.
+ *
+ * @param baseTransport The transport to wrap.
+ * @param config Retry configuration.
+ * @returns A retrying transport decorator.
+ * @throws {RangeError} If retry configuration is invalid.
+ */
+const createRetryTransport = (baseTransport, config = {}) => {
+  return new RetryTransport(baseTransport, config);
+};
+
+const getRetryAfterMilliseconds = (failure) => {
+  if (failure == null) return undefined;
+  if (isReceiptError(failure)) return failure.retryAfterMilliseconds;
+  return failure.errors?.find((error) => error.retryAfterMilliseconds != null)
+    ?.retryAfterMilliseconds;
+};
+
+const toAsyncIterator = (values) => {
+  const asyncIterator = values[Symbol.asyncIterator];
+  if (typeof asyncIterator === 'function') return asyncIterator.call(values);
+
+  const iterator = values[Symbol.iterator]();
+  return {
+    async next() {
+      return await Promise.resolve(iterator.next());
+    },
+    async return(value) {
+      return await Promise.resolve(
+        iterator.return?.(value) ?? {
+          done: true,
+          value,
+        },
+      );
+    },
+  };
+};
+
+const raceWithAbort = (promise, signal) => {
+  if (signal.aborted) return Promise.reject(getAbortReason(signal));
+
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      cleanup();
+      reject(getAbortReason(signal));
+    };
+    const cleanup = () => {
+      signal.removeEventListener('abort', abort);
+    };
+    signal.addEventListener('abort', abort, { once: true });
+    promise.then(
+      // oxlint-disable-next-line promise/always-return -- upstream
+      (value) => {
+        cleanup();
+        resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+};
+
+const getAbortReason = (signal) => {
+  return signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+};
+
+const toReceiptError = (value) => {
+  return isReceiptError(value) ? value : undefined;
+};
+
+const isReceiptError = (value) => {
+  return (
+    typeof value === 'object' &&
+    value != null &&
+    typeof value.message === 'string' &&
+    typeof value.code === 'string' &&
+    typeof value.category === 'string' &&
+    typeof value.retryable === 'boolean'
+  );
+};
+
+module.exports = { RetryTransport, createRetryTransport };
diff --git a/src/sendgrid/index.d.ts b/src/sendgrid/index.d.ts
index f1e5e44..8c7b074 100644
--- a/src/sendgrid/index.d.ts
+++ b/src/sendgrid/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/sendgrid/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Configuration interface for SendGrid transport connection settings.
diff --git a/src/ses/index.d.ts b/src/ses/index.d.ts
index e71fc7a..4fefc8b 100644
--- a/src/ses/index.d.ts
+++ b/src/ses/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/ses/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Authentication configuration for AWS SES.
diff --git a/tests/e2e/jmap/docker-compose.yml b/tests/e2e/jmap/docker-compose.yml
index 7fec748..45f8250 100644
--- a/tests/e2e/jmap/docker-compose.yml
+++ b/tests/e2e/jmap/docker-compose.yml
@@ -7,7 +7,7 @@ services:
     image: docker.io/stalwartlabs/stalwart:v0.15.5
     container_name: mailer-stalwart
     ports:
-      - "8080:8080"   # HTTP/JMAP port
+      - '8080:8080' # HTTP/JMAP port
     volumes:
       - stalwart-data:/opt/stalwart
     environment:
diff --git a/tests/types/retry.test-d.ts b/tests/types/retry.test-d.ts
new file mode 100644
index 0000000..176a14b
--- /dev/null
+++ b/tests/types/retry.test-d.ts
@@ -0,0 +1,25 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import { MockTransport } from '../../src/mock/index.js';
+import { RetryTransport, createRetryTransport, type RetryConfig } from '../../src/retry/index.js';
+
+const base = new MockTransport();
+const transport = createRetryTransport(base, {
+  maxAttempts: 5,
+  backoff: { baseDelayMilliseconds: 500, maxDelayMilliseconds: 10_000, factor: 2 },
+  jitter: 'full',
+  shouldRetry: (failure) => failure.kind === 'receipt',
+});
+expectType<RetryTransport<'mock'>>(transport);
+expectAssignable<Transport<'mock'>>(transport);
+expectAssignable<AsyncDisposable>(transport);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'mock'>>>(transport.send(message));
+expectAssignable<RetryConfig>({ sendMany: { maxConcurrent: 4, intervalMilliseconds: 100 } });
+expectError(createRetryTransport(base, { maxAttempts: '3' }));
diff --git a/tests/unit/retry-transport.test.js b/tests/unit/retry-transport.test.js
new file mode 100644
index 0000000..287edd6
--- /dev/null
+++ b/tests/unit/retry-transport.test.js
@@ -0,0 +1,1225 @@
+// Ported from upyo v0.7.0 (packages/retry/src/retry-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { createFailedReceipt, createReceiptError } = require('../../src/core/receipt.js');
+const { createMessage } = require('../../src/core/message.js');
+const { createRetryTransport, RetryTransport } = require('../../src/retry/index.js');
+
+describe('RetryTransport', () => {
+  it('retries retryable failed receipts and returns the later success', async () => {
+    const delays = [];
+    const base = new SequenceTransport([
+      createFailedReceipt('Too many requests', {
+        provider: 'base',
+        statusCode: 429,
+      }),
+      { successful: true, messageId: 'delivered' },
+    ]);
+    const transport = new RetryTransport(base, {
+      maxAttempts: 3,
+      backoff: { baseDelayMilliseconds: 100 },
+      jitter: false,
+      wait: (context) => {
+        delays.push(context);
+        return Promise.resolve();
+      },
+    });
+
+    const receipt = await transport.send(message());
+
+    assert.equal(base.calls, 2);
+    assert.ok(receipt.successful);
+    assert.equal(receipt.messageId, 'delivered');
+    assert.equal(receipt.provider, 'base');
+    assert.equal(receipt.attempts, 2);
+    assert.deepEqual(
+      delays.map((delay) => delay.delayMilliseconds),
+      [100],
+    );
+  });
+
+  it('does not retry permanent failed receipts', async () => {
+    const waits = [];
+    const base = new SequenceTransport([
+      createFailedReceipt('Invalid recipient', {
+        provider: 'base',
+        category: 'validation',
+        retryable: false,
+      }),
+      { successful: true, messageId: 'should-not-send' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 3,
+      wait: (context) => {
+        waits.push(context);
+        return Promise.resolve();
+      },
+    });
+
+    const receipt = await transport.send(message());
+
+    assert.equal(base.calls, 1);
+    assert.ok(!receipt.successful);
+    assert.deepEqual(receipt.errorMessages, ['Invalid recipient']);
+    assert.equal(receipt.provider, 'base');
+    assert.equal(receipt.attempts, 1);
+    assert.equal(waits.length, 0);
+  });
+
+  it('uses capped Retry-After metadata before computed backoff', async () => {
+    const delays = [];
+    const base = new SequenceTransport([
+      createFailedReceipt(
+        createReceiptError('Rate limited', {
+          provider: 'base',
+          statusCode: 429,
+          retryAfterMilliseconds: 5_000,
+        }),
+      ),
+      { successful: true, messageId: 'delivered' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      backoff: {
+        baseDelayMilliseconds: 100,
+        maxDelayMilliseconds: 2_000,
+      },
+      jitter: false,
+      wait: (context) => {
+        delays.push(context.delayMilliseconds);
+        return Promise.resolve();
+      },
+    });
+
+    await transport.send(message());
+
+    assert.deepEqual(delays, [2_000]);
+  });
+
+  it('preserves zero Retry-After metadata', async () => {
+    const delays = [];
+    const base = new SequenceTransport([
+      createFailedReceipt(
+        createReceiptError('Rate limited', {
+          provider: 'base',
+          statusCode: 429,
+          retryAfterMilliseconds: 0,
+        }),
+      ),
+      { successful: true, messageId: 'delivered' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      backoff: { baseDelayMilliseconds: 100 },
+      jitter: false,
+      wait: (context) => {
+        delays.push(context.delayMilliseconds);
+        return Promise.resolve();
+      },
+    });
+
+    await transport.send(message());
+
+    assert.deepEqual(delays, [0]);
+  });
+
+  it('ignores invalid Retry-After metadata', async () => {
+    const invalidRetryAfterValues = [NaN, -1, Infinity];
+
+    for (const retryAfterMilliseconds of invalidRetryAfterValues) {
+      const delays = [];
+      const base = new SequenceTransport([
+        createFailedReceipt(
+          createReceiptError('Rate limited', {
+            provider: 'base',
+            statusCode: 429,
+            retryAfterMilliseconds,
+          }),
+        ),
+        { successful: true, messageId: 'delivered' },
+      ]);
+      const transport = createRetryTransport(base, {
+        maxAttempts: 2,
+        backoff: {
+          baseDelayMilliseconds: 100,
+          maxDelayMilliseconds: 2_000,
+        },
+        jitter: false,
+        wait: (context) => {
+          delays.push(context.delayMilliseconds);
+          return Promise.resolve();
+        },
+      });
+
+      await transport.send(message());
+
+      assert.deepEqual(delays, [100]);
+    }
+  });
+
+  it('retries transient thrown errors and converts exhaustion to a receipt', async () => {
+    const base = new SequenceTransport([
+      new Error('Connection reset by peer'),
+      new Error('Connection reset by peer'),
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      jitter: false,
+      wait: () => Promise.resolve(),
+    });
+
+    const receipt = await transport.send(message());
+
+    assert.equal(base.calls, 2);
+    assert.ok(!receipt.successful);
+    assert.deepEqual(receipt.errorMessages, ['Connection reset by peer']);
+    assert.ok(receipt.retryable);
+    assert.equal(receipt.provider, 'base');
+    assert.equal(receipt.attempts, 2);
+    assert.equal(receipt.errors?.[0]?.category, 'network');
+  });
+
+  it('retries provider AbortError timeouts', async () => {
+    const base = new SequenceTransport([
+      createAbortError('Request timed out.'),
+      { successful: true, messageId: 'delivered' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      jitter: false,
+      wait: () => Promise.resolve(),
+    });
+
+    const receipt = await transport.send(message());
+
+    assert.equal(base.calls, 2);
+    assert.ok(receipt.successful);
+    assert.equal(receipt.messageId, 'delivered');
+    assert.equal(receipt.attempts, 2);
+  });
+
+  it('retries provider AbortErrors without timeout messages', async () => {
+    const base = new SequenceTransport([
+      createAbortError(),
+      { successful: true, messageId: 'delivered' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      jitter: false,
+      wait: () => Promise.resolve(),
+    });
+
+    const receipt = await transport.send(message());
+
+    assert.equal(base.calls, 2);
+    assert.ok(receipt.successful);
+    assert.equal(receipt.messageId, 'delivered');
+    assert.equal(receipt.attempts, 2);
+  });
+
+  it('preserves retryable metadata for exhausted provider AbortErrors', async () => {
+    const base = new SequenceTransport([createAbortError(), createAbortError()]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      jitter: false,
+      wait: () => Promise.resolve(),
+    });
+
+    const receipt = await transport.send(message());
+
+    assert.equal(base.calls, 2);
+    assert.ok(!receipt.successful);
+    assert.ok(receipt.retryable);
+    assert.equal(receipt.errors?.[0]?.category, 'timeout');
+    assert.equal(receipt.errors?.[0]?.code, 'timeout');
+    assert.equal(receipt.attempts, 2);
+  });
+
+  it('lets custom retry policy classify provider AbortErrors', async () => {
+    const errors = [];
+    const base = new SequenceTransport([
+      createAbortError(),
+      { successful: true, messageId: 'delivered' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      wait: () => Promise.resolve(),
+      shouldRetry: (failure) => {
+        if (failure.kind === 'error' && failure.error instanceof Error) {
+          errors.push(failure.error);
+          return failure.error.name === 'AbortError';
+        }
+        return false;
+      },
+    });
+
+    const receipt = await transport.send(message());
+
+    assert.equal(base.calls, 2);
+    assert.ok(receipt.successful);
+    assert.equal(errors.length, 1);
+    assert.equal(errors[0], base.results[0]);
+  });
+
+  it('does not retry caller cancellation', async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const base = new SequenceTransport([{ successful: true, messageId: 'should-not-send' }]);
+    const transport = createRetryTransport(base);
+
+    await assert.rejects(() => transport.send(message(), { signal: controller.signal }), {
+      name: 'AbortError',
+    });
+    assert.equal(base.calls, 0);
+  });
+
+  it('rejects caller aborts after wrapped sends', async () => {
+    const controller = new AbortController();
+    const reason = new TypeError('Stop after send.');
+    const releaseSend = createDeferred();
+    const base = new TrackingTransport(async () => {
+      await releaseSend.promise;
+      return { successful: true, messageId: 'should-not-deliver' };
+    });
+    const transport = createRetryTransport(base);
+
+    const sending = transport.send(message(), { signal: controller.signal });
+    controller.abort(reason);
+    releaseSend.resolve();
+
+    await assert.rejects(sending, (error) => error === reason);
+  });
+
+  it('stops retrying when aborted during the retry wait', async () => {
+    const controller = new AbortController();
+    const base = new SequenceTransport([
+      createFailedReceipt('Service unavailable', {
+        provider: 'base',
+        statusCode: 503,
+      }),
+      { successful: true, messageId: 'should-not-send' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      jitter: false,
+      wait: (_context, signal) => {
+        controller.abort();
+        signal?.throwIfAborted();
+        return Promise.resolve();
+      },
+    });
+
+    await assert.rejects(() => transport.send(message(), { signal: controller.signal }), {
+      name: 'AbortError',
+    });
+    assert.equal(base.calls, 1);
+  });
+
+  it('propagates custom retry wait rejections', async () => {
+    const waitError = new TypeError('Retry scheduler failed.');
+    const base = new SequenceTransport([
+      createFailedReceipt('Service unavailable', {
+        provider: 'base',
+        statusCode: 503,
+      }),
+      { successful: true, messageId: 'should-not-send' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      jitter: false,
+      wait: () => Promise.reject(waitError),
+    });
+
+    await assert.rejects(() => transport.send(message()), waitError);
+    assert.equal(base.calls, 1);
+  });
+
+  it('preserves custom abort reasons during the default retry wait', async () => {
+    const controller = new AbortController();
+    const reason = new TypeError('Stop retrying.');
+    const base = new SequenceTransport([
+      createFailedReceipt('Service unavailable', {
+        provider: 'base',
+        statusCode: 503,
+      }),
+      { successful: true, messageId: 'should-not-send' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      backoff: { baseDelayMilliseconds: 1_000 },
+      jitter: false,
+    });
+
+    const sending = transport.send(message(), { signal: controller.signal });
+    controller.abort(reason);
+
+    await assert.rejects(sending, reason);
+    assert.equal(base.calls, 1);
+  });
+
+  it('preserves structured thrown receipt errors', async () => {
+    const error = createReceiptError('Rate limited.', {
+      provider: 'base',
+      statusCode: 429,
+      retryAfterMilliseconds: 5_000,
+      providerDetails: { requestId: 'req-1' },
+    });
+    const delays = [];
+    const base = new SequenceTransport([error, error]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      backoff: { maxDelayMilliseconds: 10_000 },
+      jitter: false,
+      wait: (context) => {
+        delays.push(context.delayMilliseconds);
+        return Promise.resolve();
+      },
+    });
+
+    const receipt = await transport.send(message());
+
+    assert.equal(base.calls, 2);
+    assert.deepEqual(delays, [5_000]);
+    assert.ok(!receipt.successful);
+    assert.deepEqual(receipt.errorMessages, ['Rate limited.']);
+    assert.ok(receipt.retryable);
+    assert.equal(receipt.provider, 'base');
+    assert.equal(receipt.attempts, 2);
+    assert.deepEqual(receipt.errors, [error]);
+  });
+
+  it('retries sendMany messages in input order', async () => {
+    const base = new SequenceTransport([
+      createFailedReceipt('Temporarily unavailable', {
+        provider: 'base',
+        statusCode: 503,
+      }),
+      { successful: true, messageId: 'first' },
+      { successful: true, messageId: 'second' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      jitter: false,
+      wait: () => Promise.resolve(),
+    });
+
+    const receipts = await collect(transport.sendMany([message('First'), message('Second')]));
+
+    assert.equal(base.calls, 3);
+    assert.deepEqual(
+      receipts.map((receipt) => receipt.successful && receipt.messageId),
+      ['first', 'second'],
+    );
+  });
+
+  it('limits sendMany concurrency and spaces launches', async () => {
+    const events = [];
+    let active = 0;
+    let maxActive = 0;
+    const releaseFirst = createDeferred();
+    const releaseSecond = createDeferred();
+    const releases = [releaseFirst.promise, releaseSecond.promise];
+    const base = new TrackingTransport(async (_message, index) => {
+      active++;
+      maxActive = Math.max(maxActive, active);
+      events.push(`start:${index}`);
+      await releases[index];
+      active--;
+      events.push(`finish:${index}`);
+      return { successful: true, messageId: `message-${index}` };
+    });
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: {
+        maxConcurrent: 2,
+        intervalMilliseconds: 25,
+      },
+      wait: (context) => {
+        events.push(`wait:${context.delayMilliseconds}`);
+        return Promise.resolve();
+      },
+    });
+
+    const receiptsPromise = collect(transport.sendMany([message('First'), message('Second')]));
+
+    releaseSecond.resolve();
+    await waitFor(() => events.includes('finish:1'));
+    assert.deepEqual(events, ['start:0', 'wait:25', 'start:1', 'finish:1']);
+
+    releaseFirst.resolve();
+
+    const receipts = await receiptsPromise;
+
+    assert.deepEqual(events, ['start:0', 'wait:25', 'start:1', 'finish:1', 'finish:0']);
+    assert.equal(maxActive, 2);
+    assert.deepEqual(
+      receipts.map((receipt) => receipt.successful && receipt.messageId),
+      ['message-0', 'message-1'],
+    );
+  });
+
+  it('yields completed sendMany receipts before slow async input', async () => {
+    const releaseSecond = createDeferred();
+    const messages = async function* () {
+      yield message('First');
+      await releaseSecond.promise;
+      yield message('Second');
+    };
+    const base = new TrackingTransport((_message, index) =>
+      Promise.resolve({
+        successful: true,
+        messageId: `message-${index}`,
+      }),
+    );
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2 },
+    });
+
+    const iterator = transport.sendMany(messages())[Symbol.asyncIterator]();
+    const firstResult = iterator.next();
+    const firstSettled = await settlesWithin(firstResult);
+
+    assert.ok(firstSettled);
+    const first = await firstResult;
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+    if (first.value.successful) {
+      assert.equal(first.value.messageId, 'message-0');
+    }
+
+    releaseSecond.resolve();
+    const second = await iterator.next();
+    assert.ok(!second.done);
+    assert.ok(second.value.successful);
+    if (second.value.successful) {
+      assert.equal(second.value.messageId, 'message-1');
+    }
+    const done = await iterator.next();
+    assert.ok(done.done);
+  });
+
+  it('surfaces sendMany input errors after yielding ready receipts', async () => {
+    const inputError = new TypeError('Input failed.');
+    const releaseFailure = createDeferred();
+    const messages = async function* () {
+      yield message('First');
+      await releaseFailure.promise;
+      throw inputError;
+    };
+    const base = new TrackingTransport((_message, index) =>
+      Promise.resolve({
+        successful: true,
+        messageId: `message-${index}`,
+      }),
+    );
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2 },
+    });
+
+    const iterator = transport.sendMany(messages())[Symbol.asyncIterator]();
+    const first = await iterator.next();
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+    if (first.value.successful) {
+      assert.equal(first.value.messageId, 'message-0');
+    }
+
+    releaseFailure.resolve();
+
+    await assert.rejects(() => iterator.next(), inputError);
+  });
+
+  it('rejects pending sendMany input pulls when aborted', async () => {
+    const controller = new AbortController();
+    const reason = new TypeError('Stop reading input.');
+    const releaseSecond = createDeferred();
+    const messages = async function* () {
+      yield message('First');
+      await releaseSecond.promise;
+      yield message('Second');
+    };
+    const base = new TrackingTransport((_message, index) =>
+      Promise.resolve({
+        successful: true,
+        messageId: `message-${index}`,
+      }),
+    );
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2 },
+    });
+
+    const batch = transport.sendMany(messages(), {
+      signal: controller.signal,
+    });
+    const iterator = batch[Symbol.asyncIterator]();
+    const first = await iterator.next();
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+
+    const next = iterator.next();
+    controller.abort(reason);
+
+    await assert.rejects(
+      () => Promise.race([next, rejectAfter(50)]),
+      (error) => error === reason,
+    );
+  });
+
+  it('rejects pending sendMany sends when aborted', async () => {
+    const controller = new AbortController();
+    const reason = new TypeError('Stop pending sends.');
+    const releaseSend = createDeferred();
+    const events = [];
+    const base = new TrackingTransport(async (_message, index) => {
+      events.push(`start:${index}`);
+      await releaseSend.promise;
+      return { successful: true, messageId: `message-${index}` };
+    });
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 1 },
+    });
+
+    const batch = transport.sendMany([message('First')], {
+      signal: controller.signal,
+    });
+    const iterator = batch[Symbol.asyncIterator]();
+    const next = iterator.next();
+
+    await waitFor(() => events.includes('start:0'));
+    controller.abort(reason);
+
+    try {
+      await assert.rejects(
+        () => Promise.race([next, rejectAfter(50)]),
+        (error) => error === reason,
+      );
+    } finally {
+      releaseSend.resolve();
+      await next.catch(() => undefined);
+    }
+  });
+
+  it('yields queued sendMany receipts before launch errors', async () => {
+    const inputError = new TypeError('Input failed.');
+    const messages = {
+      [Symbol.iterator]() {
+        let index = 0;
+        return {
+          next() {
+            if (index++ === 0) {
+              return { done: false, value: message('First') };
+            }
+            throw inputError;
+          },
+        };
+      },
+    };
+    const base = new TrackingTransport((_message, index) =>
+      Promise.resolve({
+        successful: true,
+        messageId: `message-${index}`,
+      }),
+    );
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2 },
+    });
+
+    const iterator = transport.sendMany(messages)[Symbol.asyncIterator]();
+    const first = await iterator.next();
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+    if (first.value.successful) {
+      assert.equal(first.value.messageId, 'message-0');
+    }
+
+    await assert.rejects(() => iterator.next(), inputError);
+  });
+
+  it('accepts primitive sync iterables in sendMany', async () => {
+    let calls = 0;
+    const base = new TrackingTransport((_message, index) => {
+      calls++;
+      return Promise.resolve({
+        successful: true,
+        messageId: `message-${index}`,
+      });
+    });
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 1 },
+    });
+
+    const receipts = await collect(transport.sendMany('ab'));
+
+    assert.equal(calls, 2);
+    assert.deepEqual(
+      receipts.map((receipt) => receipt.successful && receipt.messageId),
+      ['message-0', 'message-1'],
+    );
+  });
+
+  it('drains already-launched sendMany receipts before launch errors', async () => {
+    const inputError = new TypeError('Input failed.');
+    const events = [];
+    const releaseFirst = createDeferred();
+    const messages = {
+      [Symbol.iterator]() {
+        let index = 0;
+        return {
+          next() {
+            if (index < 2) {
+              return { done: false, value: message(`Message ${index++}`) };
+            }
+            events.push('input-error');
+            throw inputError;
+          },
+        };
+      },
+    };
+    const base = new TrackingTransport(async (_message, index) => {
+      events.push(`start:${index}`);
+      if (index === 0) await releaseFirst.promise;
+      events.push(`finish:${index}`);
+      return { successful: true, messageId: `message-${index}` };
+    });
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2 },
+    });
+
+    const iterator = transport.sendMany(messages)[Symbol.asyncIterator]();
+    const firstResult = iterator.next();
+
+    await waitFor(() => events.includes('input-error'));
+    assert.ok(!(await settlesWithin(firstResult)));
+
+    releaseFirst.resolve();
+
+    const first = await firstResult;
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+    if (first.value.successful) {
+      assert.equal(first.value.messageId, 'message-0');
+    }
+
+    const second = await iterator.next();
+    assert.ok(!second.done);
+    assert.ok(second.value.successful);
+    if (second.value.successful) {
+      assert.equal(second.value.messageId, 'message-1');
+    }
+
+    await assert.rejects(
+      () => iterator.next(),
+      (error) => error === inputError,
+    );
+  });
+
+  it('does not hang when closed with a pending sendMany input pull', async () => {
+    const never = createDeferred();
+    const messages = async function* () {
+      yield message('First');
+      await never.promise;
+      yield message('Second');
+    };
+    const base = new TrackingTransport((_message, index) =>
+      Promise.resolve({
+        successful: true,
+        messageId: `message-${index}`,
+      }),
+    );
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2 },
+    });
+
+    const iterator = transport.sendMany(messages())[Symbol.asyncIterator]();
+    const first = await iterator.next();
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+
+    const returned = iterator.return?.();
+    assert.ok(returned != null);
+    assert.ok(await settlesWithin(returned, 50));
+  });
+
+  it('closes pending sendMany input pulls when consumers stop early', async () => {
+    const pendingPullStarted = createDeferred();
+    let closed = false;
+    const messages = {
+      [Symbol.asyncIterator]() {
+        let index = 0;
+        return {
+          next() {
+            if (index++ === 0) {
+              return Promise.resolve({
+                done: false,
+                value: message('First'),
+              });
+            }
+            pendingPullStarted.resolve();
+            return new Promise(() => {});
+          },
+          return() {
+            closed = true;
+            return Promise.resolve({ done: true, value: undefined });
+          },
+        };
+      },
+    };
+    const base = new TrackingTransport((_message, index) =>
+      Promise.resolve({
+        successful: true,
+        messageId: `message-${index}`,
+      }),
+    );
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2 },
+    });
+
+    const iterator = transport.sendMany(messages)[Symbol.asyncIterator]();
+    const first = await iterator.next();
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+    await pendingPullStarted.promise;
+
+    const returned = iterator.return?.();
+    assert.ok(returned != null);
+    assert.ok(await settlesWithin(returned, 50));
+    await returned;
+    await waitFor(() => closed);
+
+    assert.ok(closed);
+  });
+
+  it('yields completed sendMany receipts while throttling launches', async () => {
+    const releaseThrottle = createDeferred();
+    const base = new TrackingTransport((_message, index) =>
+      Promise.resolve({
+        successful: true,
+        messageId: `message-${index}`,
+      }),
+    );
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2, intervalMilliseconds: 1_000 },
+      wait: (context) => {
+        if (context.reason === 'sendMany-throttle') {
+          return releaseThrottle.promise;
+        }
+        return Promise.resolve();
+      },
+    });
+
+    const batch = transport.sendMany([message('First'), message('Second')]);
+    const iterator = batch[Symbol.asyncIterator]();
+    const firstResult = iterator.next();
+    const firstSettled = await settlesWithin(firstResult);
+
+    assert.ok(firstSettled);
+    const first = await firstResult;
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+    if (first.value.successful) {
+      assert.equal(first.value.messageId, 'message-0');
+    }
+
+    releaseThrottle.resolve();
+    const second = await iterator.next();
+    assert.ok(!second.done);
+    assert.ok(second.value.successful);
+    if (second.value.successful) {
+      assert.equal(second.value.messageId, 'message-1');
+    }
+    const done = await iterator.next();
+    assert.ok(done.done);
+  });
+
+  it('refills sendMany concurrency when later messages finish first', async () => {
+    const events = [];
+    const releaseFirst = createDeferred();
+    const base = new TrackingTransport(async (_message, index) => {
+      events.push(`start:${index}`);
+      if (index === 0) await releaseFirst.promise;
+      events.push(`finish:${index}`);
+      return { successful: true, messageId: `message-${index}` };
+    });
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2 },
+    });
+
+    const receiptsPromise = collect(
+      transport.sendMany([message('First'), message('Second'), message('Third')]),
+    );
+
+    await waitFor(() => events.includes('finish:1'));
+    await waitFor(() => events.includes('start:2'));
+    assert.deepEqual(events, ['start:0', 'start:1', 'finish:1', 'start:2', 'finish:2']);
+
+    releaseFirst.resolve();
+
+    const receipts = await receiptsPromise;
+
+    assert.deepEqual(
+      receipts.map((receipt) => receipt.successful && receipt.messageId),
+      ['message-0', 'message-1', 'message-2'],
+    );
+  });
+
+  it('stops launching sendMany messages after queued send failures', async () => {
+    const sendError = new TypeError('Retry policy failed.');
+    const releaseFirst = createDeferred();
+    const events = [];
+    const base = new TrackingTransport(async (_message, index) => {
+      events.push(`start:${index}`);
+      if (index === 0) {
+        await releaseFirst.promise;
+        return { successful: true, messageId: 'first' };
+      }
+      return createFailedReceipt('Service unavailable.', {
+        provider: 'base',
+        retryable: true,
+      });
+    });
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      sendMany: { maxConcurrent: 2 },
+      wait: () => Promise.reject(sendError),
+    });
+
+    const batch = transport.sendMany([message('First'), message('Second'), message('Third')]);
+    const iterator = batch[Symbol.asyncIterator]();
+    const firstResult = iterator.next();
+
+    await waitFor(() => events.includes('start:1'));
+    await Promise.resolve();
+    assert.deepEqual(events, ['start:0', 'start:1']);
+
+    releaseFirst.resolve();
+    const first = await firstResult;
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+    await assert.rejects(
+      () => iterator.next(),
+      (error) => error === sendError,
+    );
+    assert.deepEqual(events, ['start:0', 'start:1']);
+  });
+
+  it('keeps later sendMany thrown failures ordered', async () => {
+    const releaseFirst = createDeferred();
+    const base = new TrackingTransport(async (_message, index) => {
+      if (index === 1) throw createAbortError();
+      await releaseFirst.promise;
+      return { successful: true, messageId: 'first' };
+    });
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2 },
+    });
+
+    const receipts = transport.sendMany([message('First'), message('Second')]);
+    const iterator = receipts[Symbol.asyncIterator]();
+
+    await Promise.resolve();
+    releaseFirst.resolve();
+
+    const first = await iterator.next();
+    assert.ok(!first.done);
+    assert.ok(first.value.successful);
+    if (first.value.successful) {
+      assert.equal(first.value.messageId, 'first');
+    }
+
+    const second = await iterator.next();
+    assert.ok(!second.done);
+    assert.ok(!second.value.successful);
+    if (!second.value.successful) {
+      assert.deepEqual(second.value.errorMessages, ['The operation was aborted.']);
+      assert.equal(second.value.attempts, 1);
+    }
+  });
+
+  it('closes sendMany input iterators when consumers stop early', async () => {
+    let closed = false;
+    const messages = async function* () {
+      try {
+        yield message('First');
+        yield message('Second');
+      } finally {
+        closed = true;
+      }
+    };
+    const base = new SequenceTransport([
+      { successful: true, messageId: 'first' },
+      { successful: true, messageId: 'second' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 1 },
+    });
+
+    for await (const receipt of transport.sendMany(messages())) {
+      assert.ok(receipt.successful);
+      break;
+    }
+
+    await waitFor(() => closed);
+    assert.ok(closed);
+  });
+
+  it('cancels pending sendMany launch waits when consumers stop early', async () => {
+    const events = [];
+    const releaseFirst = createDeferred();
+    let waitStarted = false;
+    let waitAborted = false;
+    const base = new TrackingTransport(async (_message, index) => {
+      events.push(`start:${index}`);
+      if (index === 0) await releaseFirst.promise;
+      return {
+        successful: true,
+        messageId: `message-${index}`,
+      };
+    });
+    const transport = createRetryTransport(base, {
+      maxAttempts: 1,
+      sendMany: { maxConcurrent: 2, intervalMilliseconds: 1_000 },
+      wait: (_context, signal) => {
+        waitStarted = true;
+        return new Promise((_resolve, reject) => {
+          signal?.addEventListener(
+            'abort',
+            () => {
+              waitAborted = true;
+              reject(signal.reason);
+            },
+            { once: true },
+          );
+        });
+      },
+    });
+
+    const batch = transport.sendMany([message('First'), message('Second')]);
+    const iterator = batch[Symbol.asyncIterator]();
+    const firstResult = iterator.next();
+    await waitFor(() => waitStarted);
+    releaseFirst.resolve();
+
+    const first = await firstResult;
+    assert.ok(!first.done);
+    assert.ok(waitStarted);
+
+    await iterator.return?.();
+
+    await waitFor(() => waitAborted);
+    assert.deepEqual(events, ['start:0']);
+  });
+
+  it('disposes wrapped async disposable transports', async () => {
+    const base = new DisposableTransport({ asyncDisposable: true });
+    const transport = createRetryTransport(base);
+
+    await transport[Symbol.asyncDispose]();
+
+    assert.ok(base.asyncDisposed);
+    assert.ok(!base.disposed);
+  });
+
+  it('disposes wrapped sync disposable transports', async () => {
+    const base = new DisposableTransport({ disposable: true });
+    const transport = createRetryTransport(base);
+
+    await transport[Symbol.asyncDispose]();
+
+    assert.ok(!base.asyncDisposed);
+    assert.ok(base.disposed);
+  });
+
+  it('prefers wrapped async disposal when both forms are available', async () => {
+    const base = new DisposableTransport({
+      asyncDisposable: true,
+      disposable: true,
+    });
+    const transport = createRetryTransport(base);
+
+    await transport[Symbol.asyncDispose]();
+
+    assert.ok(base.asyncDisposed);
+    assert.ok(!base.disposed);
+  });
+});
+
+function message(subject = 'Hello') {
+  return createMessage({
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject,
+    content: { text: 'Hello' },
+  });
+}
+
+async function collect(values) {
+  const result = [];
+  for await (const value of values) result.push(value);
+  return result;
+}
+
+function createDeferred() {
+  let resolve;
+  let reject;
+  // oxlint-disable-next-line promise/param-names -- upstream
+  const promise = new Promise((promiseResolve, promiseReject) => {
+    resolve = promiseResolve;
+    reject = promiseReject;
+  });
+  assert.ok(resolve != null);
+  assert.ok(reject != null);
+  return { promise, resolve, reject };
+}
+
+async function waitFor(predicate) {
+  const deadline = Date.now() + 1_000;
+  while (!predicate()) {
+    if (Date.now() >= deadline) {
+      assert.fail('Timed out waiting for condition.');
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+}
+
+async function settlesWithin(promise, milliseconds = 10) {
+  let timeout;
+  try {
+    return await Promise.race([
+      promise.then(
+        () => true,
+        () => true,
+      ),
+      new Promise((resolve) => {
+        timeout = setTimeout(() => resolve(false), milliseconds);
+      }),
+    ]);
+  } finally {
+    if (timeout != null) clearTimeout(timeout);
+  }
+}
+
+function rejectAfter(milliseconds) {
+  return new Promise((_resolve, reject) => {
+    setTimeout(() => reject(new Error('Timed out waiting for rejection.')), milliseconds);
+  });
+}
+
+// oxlint-disable-next-line no-shadow -- upstream
+function createAbortError(message = 'The operation was aborted.') {
+  return new DOMException(message, 'AbortError');
+}
+
+class SequenceTransport {
+  id = 'base';
+  calls = 0;
+
+  results;
+
+  constructor(results) {
+    this.results = results;
+  }
+
+  // oxlint-disable-next-line no-shadow -- upstream
+  send(message, options) {
+    options?.signal?.throwIfAborted();
+    const result = this.results[this.calls++];
+    if (result instanceof Error) return Promise.reject(result);
+    if (isReceiptError(result)) return Promise.reject(result);
+    if (typeof result === 'function') return Promise.resolve(result(message));
+    if (result == null) {
+      return Promise.resolve({ successful: true, messageId: 'fallback' });
+    }
+    return Promise.resolve(result);
+  }
+
+  async *sendMany(messages, options) {
+    for await (const item of messages) {
+      yield await this.send(item, options);
+    }
+  }
+}
+
+function isReceiptError(value) {
+  return (
+    typeof value === 'object' &&
+    value != null &&
+    'category' in value &&
+    'retryable' in value &&
+    'message' in value
+  );
+}
+
+class TrackingTransport {
+  id = 'base';
+  calls = 0;
+
+  handler;
+
+  constructor(handler) {
+    this.handler = handler;
+  }
+
+  // oxlint-disable-next-line no-shadow -- upstream
+  send(message, options) {
+    const index = this.calls++;
+    return this.handler(message, index, options);
+  }
+
+  async *sendMany(messages, options) {
+    for await (const item of messages) {
+      yield await this.send(item, options);
+    }
+  }
+}
+
+class DisposableTransport {
+  id = 'base';
+  asyncDisposed = false;
+  disposed = false;
+
+  options;
+
+  constructor(options) {
+    this.options = options;
+    if (options.asyncDisposable) {
+      Object.defineProperty(this, Symbol.asyncDispose, {
+        value: () => {
+          this.asyncDisposed = true;
+          return Promise.resolve();
+        },
+      });
+    }
+    if (options.disposable) {
+      Object.defineProperty(this, Symbol.dispose, {
+        value: () => {
+          this.disposed = true;
+        },
+      });
+    }
+  }
+
+  send(_message, _options) {
+    return Promise.resolve({ successful: true, messageId: 'disposed' });
+  }
+
+  async *sendMany(messages, options) {
+    for await (const item of messages) {
+      yield await this.send(item, options);
+    }
+  }
+}
diff --git a/tests/unit/retry.test.js b/tests/unit/retry.test.js
new file mode 100644
index 0000000..ac84e0b
--- /dev/null
+++ b/tests/unit/retry.test.js
@@ -0,0 +1,99 @@
+// Paths of the ported RetryTransport (src/retry/) that upstream's suites
+// leave out: the default wait, the validation of the options, and receipts
+// without a retryable flag.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { RetryTransport, createRetryTransport } = require('../../src/retry/index.js');
+
+const message = () =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+const sequence = (...results) => {
+  let calls = 0;
+  return {
+    id: 'base',
+    get calls() {
+      return calls;
+    },
+    send: async () => results[Math.min(calls++, results.length - 1)],
+    async *sendMany() {},
+  };
+};
+const failure = (retryable) => ({
+  successful: false,
+  errorMessages: ['Busy'],
+  errors: [{ message: 'Busy', category: 'server-error', code: 'busy', retryable }],
+});
+const success = { successful: true, messageId: 'ok' };
+
+test('Retry: the options are validated', () => {
+  const base = sequence(success);
+  assert.throws(() => createRetryTransport(base, { maxAttempts: 0 }), {
+    name: 'RangeError',
+    message: 'maxAttempts must be an integer greater than or equal to 1.',
+  });
+  assert.throws(() => createRetryTransport(base, { backoff: { factor: 0.5 } }), {
+    name: 'RangeError',
+    message: 'backoff.factor must be greater than or equal to 1.',
+  });
+  assert.ok(new RetryTransport(base) instanceof RetryTransport);
+});
+
+test('Retry: the default wait sleeps between attempts and stops on an abort', async () => {
+  const base = sequence(failure(true), success);
+  const options = { maxAttempts: 2, backoff: { baseDelayMilliseconds: 10 }, jitter: 'none' };
+  const receipt = await createRetryTransport(base, options).send(message());
+  assert.strictEqual(receipt.successful, true);
+  assert.strictEqual(base.calls, 2);
+
+  const controller = new AbortController();
+  const slow = { ...options, backoff: { baseDelayMilliseconds: 5000 } };
+  const sending = createRetryTransport(sequence(failure(true)), slow).send(message(), {
+    signal: controller.signal,
+  });
+  setTimeout(() => controller.abort(), 20);
+  await assert.rejects(sending, { name: 'AbortError' });
+});
+
+test('Retry: a receipt without a retryable flag is retried by its errors', async () => {
+  const unflagged = failure(true);
+  const base = sequence(unflagged, success);
+  const receipt = await createRetryTransport(base, {
+    maxAttempts: 2,
+    wait: async () => {},
+  }).send(message());
+  assert.strictEqual(receipt.successful, true);
+
+  const custom = sequence(failure(false), success);
+  const forced = await createRetryTransport(custom, {
+    maxAttempts: 2,
+    wait: async () => {},
+    shouldRetry: ({ kind }) => kind === 'receipt',
+  }).send(message());
+  assert.strictEqual(forced.successful, true);
+  assert.strictEqual(custom.calls, 2);
+
+  const final = await createRetryTransport(sequence(failure(true)), {
+    maxAttempts: 1,
+  }).send(message());
+  assert.strictEqual(final.retryable, true);
+  assert.strictEqual(final.attempts, 1);
+});
+
+test('Retry: the default wait rejects with an AbortError for a signal without a reason', async () => {
+  const { createRetryConfig } = require('../../src/retry/config.js');
+  const { wait } = createRetryConfig();
+  const signal = {
+    aborted: true,
+    reason: undefined,
+    throwIfAborted() {},
+    addEventListener() {},
+    removeEventListener() {},
+  };
+  await assert.rejects(wait({ delayMilliseconds: 10 }, signal), { name: 'AbortError' });
+});

From 0a61baafeeb7acb2ab214540071222f19dbe941f Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:35:27 +0300
Subject: [PATCH 016/158] feat(pool): port the pool decorator from upyo 0.7.0

./pool exports PoolTransport and the RoundRobinStrategy, WeightedStrategy,
PriorityStrategy and SelectorStrategy classes: a transport over several
others that picks one per message by the strategy (or a strategy object of
the application), fails over to another on a failed send up to maxRetries,
and applies an optional per-attempt timeout.

Upstream's suites are ported; they use ./mock. tests/unit/pool.test.js
covers weights that leave nothing to pick, aborts before a send, a timeout
without a caller signal and a dispose that throws. The unused
continueOnSuccess of upstream is kept and listed in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   2 +-
 package.json                                  |   4 +
 src/pool/config.js                            |  49 ++
 src/pool/index.d.ts                           | 366 ++++++++
 src/pool/index.js                             |  26 +
 src/pool/pool-transport.js                    | 401 +++++++++
 src/pool/strategies/priority-strategy.js      |  60 ++
 src/pool/strategies/round-robin-strategy.js   |  58 ++
 src/pool/strategies/selector-strategy.js      |  68 ++
 src/pool/strategies/weighted-strategy.js      |  62 ++
 tests/helpers/pool/test-config.js             | 103 +++
 tests/types/pool.test-d.ts                    |  45 +
 .../pool-strategies-priority-strategy.test.js | 171 ++++
 ...ol-strategies-round-robin-strategy.test.js | 140 +++
 .../pool-strategies-selector-strategy.test.js | 229 +++++
 .../pool-strategies-weighted-strategy.test.js | 176 ++++
 tests/unit/pool-transport.test.js             | 797 ++++++++++++++++++
 tests/unit/pool.test.js                       |  69 ++
 18 files changed, 2825 insertions(+), 1 deletion(-)
 create mode 100644 src/pool/config.js
 create mode 100644 src/pool/index.d.ts
 create mode 100644 src/pool/index.js
 create mode 100644 src/pool/pool-transport.js
 create mode 100644 src/pool/strategies/priority-strategy.js
 create mode 100644 src/pool/strategies/round-robin-strategy.js
 create mode 100644 src/pool/strategies/selector-strategy.js
 create mode 100644 src/pool/strategies/weighted-strategy.js
 create mode 100644 tests/helpers/pool/test-config.js
 create mode 100644 tests/types/pool.test-d.ts
 create mode 100644 tests/unit/pool-strategies-priority-strategy.test.js
 create mode 100644 tests/unit/pool-strategies-round-robin-strategy.test.js
 create mode 100644 tests/unit/pool-strategies-selector-strategy.test.js
 create mode 100644 tests/unit/pool-strategies-weighted-strategy.test.js
 create mode 100644 tests/unit/pool-transport.test.js
 create mode 100644 tests/unit/pool.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c351412..9388619 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-retry 3 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 313657b..e89cf4c 100644
--- a/package.json
+++ b/package.json
@@ -68,6 +68,10 @@
       "types": "./src/plunk/index.d.ts",
       "default": "./src/plunk/index.js"
     },
+    "./pool": {
+      "types": "./src/pool/index.d.ts",
+      "default": "./src/pool/index.js"
+    },
     "./retry": {
       "types": "./src/retry/index.d.ts",
       "default": "./src/retry/index.js"
diff --git a/src/pool/config.js b/src/pool/config.js
new file mode 100644
index 0000000..e471e60
--- /dev/null
+++ b/src/pool/config.js
@@ -0,0 +1,49 @@
+// Ported from upyo v0.7.0 (packages/pool/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Creates a resolved pool configuration with defaults applied.
+ *
+ * @param config The pool configuration.
+ * @returns The resolved configuration with defaults.
+ * @throws {Error} If the configuration is invalid.
+ */
+const createPoolConfig = (config) => {
+  if (!config.transports || config.transports.length === 0) {
+    throw new Error('Pool must have at least one transport');
+  }
+
+  const enabledTransports = config.transports.filter((entry) => entry.enabled !== false);
+
+  if (enabledTransports.length === 0) {
+    throw new Error('Pool must have at least one enabled transport');
+  }
+
+  const resolvedTransports = config.transports.map((entry) => ({
+    transport: entry.transport,
+    weight: entry.weight ?? 1,
+    priority: entry.priority ?? 0,
+    selector: entry.selector,
+    enabled: entry.enabled ?? true,
+  }));
+
+  // Validate weights for weighted strategy
+  if (config.strategy === 'weighted') {
+    const hasValidWeights = resolvedTransports.some((entry) => entry.enabled && entry.weight > 0);
+    if (!hasValidWeights) {
+      throw new Error(
+        'Weighted strategy requires at least one enabled transport with positive weight',
+      );
+    }
+  }
+
+  return {
+    strategy: config.strategy,
+    transports: resolvedTransports,
+    maxRetries: config.maxRetries ?? enabledTransports.length - 1,
+    timeout: config.timeout,
+    continueOnSuccess: config.continueOnSuccess ?? false,
+  };
+};
+
+module.exports = { createPoolConfig };
diff --git a/src/pool/index.d.ts b/src/pool/index.d.ts
new file mode 100644
index 0000000..4e40ca1
--- /dev/null
+++ b/src/pool/index.d.ts
@@ -0,0 +1,366 @@
+// Types ported from upyo v0.7.0 (packages/pool/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * Result of transport selection by a strategy.
+ */
+export interface TransportSelection<TProviderId extends string = string> {
+  /**
+   * The selected transport entry.
+   */
+  readonly entry: ResolvedTransportEntry<TProviderId>;
+  /**
+   * Index of the selected transport in the original list.
+   */
+  readonly index: number;
+}
+/**
+ * Base interface for transport selection strategies.
+ */
+export interface Strategy<TProviderId extends string = string> {
+  /**
+   * Selects a transport for sending a message.
+   *
+   * @param message The message to send.
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if no suitable transport is
+   *          available.
+   */
+  select(
+    message: Message,
+    transports: readonly ResolvedTransportEntry<TProviderId>[],
+    attemptedIndices: ReadonlySet<number>,
+  ): TransportSelection<TProviderId> | undefined;
+  /**
+   * Resets any internal state of the strategy.
+   */
+  reset(): void;
+}
+
+/**
+ * Strategy for selecting transports in a pool.
+ */
+export type PoolStrategy = 'round-robin' | 'weighted' | 'priority' | 'selector-based';
+/**
+ * Function that determines if a transport should handle a specific message.
+ */
+export type TransportSelector = (message: Message) => boolean;
+/**
+ * Configuration for a transport entry in the pool.
+ */
+export interface TransportEntry<TProviderId extends string = string> {
+  /**
+   * The transport instance to use.
+   */
+  readonly transport: Transport<TProviderId>;
+  /**
+   * Weight for weighted distribution strategy.
+   * Higher values mean more traffic. Defaults to 1.
+   */
+  readonly weight?: number;
+  /**
+   * Priority for priority-based failover strategy.
+   * Higher values are tried first. Defaults to 0.
+   */
+  readonly priority?: number;
+  /**
+   * Selector function for selector-based routing.
+   * If provided, this transport will only be used for messages
+   * where the selector returns true.
+   */
+  readonly selector?: TransportSelector;
+  /**
+   * Whether this transport is enabled.
+   * Disabled transports are skipped. Defaults to true.
+   */
+  readonly enabled?: boolean;
+}
+/**
+ * Configuration options for the pool transport.
+ */
+export interface PoolConfig<TProviderId extends string = string> {
+  /**
+   * The strategy to use for selecting transports.
+   * Can be a built-in strategy name or a custom Strategy instance.
+   */
+  readonly strategy: PoolStrategy | Strategy<TProviderId>;
+  /**
+   * The transports in the pool.
+   */
+  readonly transports: readonly TransportEntry<TProviderId>[];
+  /**
+   * Maximum number of retry attempts after the initial send attempt fails.
+   * Set to 0 to disable retries. Defaults to enough retries to try every
+   * enabled transport once.
+   */
+  readonly maxRetries?: number;
+  /**
+   * Timeout in milliseconds for each send attempt.
+   * If not specified, no timeout is applied.
+   */
+  readonly timeout?: number;
+  /**
+   * Whether to continue trying other transports after a successful send
+   * when using selector-based strategy. Defaults to false.
+   */
+  readonly continueOnSuccess?: boolean;
+}
+/**
+ * Resolved pool configuration with defaults applied.
+ */
+export interface ResolvedPoolConfig<TProviderId extends string = string> {
+  readonly strategy: PoolStrategy | Strategy<TProviderId>;
+  readonly transports: readonly ResolvedTransportEntry<TProviderId>[];
+  readonly maxRetries: number;
+  readonly timeout?: number;
+  readonly continueOnSuccess: boolean;
+}
+/**
+ * Resolved transport entry with defaults applied.
+ */
+export interface ResolvedTransportEntry<TProviderId extends string = string> {
+  readonly transport: Transport<TProviderId>;
+  readonly weight: number;
+  readonly priority: number;
+  readonly selector?: TransportSelector;
+  readonly enabled: boolean;
+}
+/**
+ * Creates a resolved pool configuration with defaults applied.
+ *
+ * @param config The pool configuration.
+ * @returns The resolved configuration with defaults.
+ * @throws {Error} If the configuration is invalid.
+ */
+
+/**
+ * Pool transport that combines multiple transports with various load balancing
+ * and failover strategies.
+ *
+ * This transport implements the same `Transport` interface, making it a drop-in
+ * replacement for any single transport. It distributes messages across multiple
+ * underlying transports based on the configured strategy.
+ *
+ * @example Round-robin load balancing
+ * ```typescript
+ * import { PoolTransport } from "@alexify/mailer/pool";
+ *
+ * const transport = new PoolTransport({
+ *   strategy: "round-robin",
+ *   transports: [
+ *     { transport: mailgunTransport },
+ *     { transport: sendgridTransport },
+ *     { transport: sesTransport },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Priority-based failover
+ * ```typescript
+ * const transport = new PoolTransport({
+ *   strategy: "priority",
+ *   transports: [
+ *     { transport: primaryTransport, priority: 100 },
+ *     { transport: backupTransport, priority: 50 },
+ *     { transport: lastResortTransport, priority: 10 },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Custom routing with selectors
+ * ```typescript
+ * const transport = new PoolTransport({
+ *   strategy: "selector-based",
+ *   transports: [
+ *     {
+ *       transport: bulkEmailTransport,
+ *       selector: (msg) => msg.tags?.includes("newsletter"),
+ *     },
+ *     {
+ *       transport: transactionalTransport,
+ *       selector: (msg) => msg.priority === "high",
+ *     },
+ *     { transport: defaultTransport }, // Catches everything else
+ *   ],
+ * });
+ * ```
+ */
+export declare class PoolTransport<TProviderId extends string = string>
+  implements Transport<TProviderId | 'pool'>, AsyncDisposable
+{
+  readonly id = 'pool';
+  /**
+   * The resolved configuration used by this pool transport.
+   */
+  readonly config: ResolvedPoolConfig<TProviderId>;
+  /**
+   * Creates a new PoolTransport instance.
+   *
+   * @param config Configuration options for the pool transport.
+   * @throws {Error} If the configuration is invalid.
+   */
+  constructor(config: PoolConfig<TProviderId>);
+  /**
+   * Sends a single email message using the pool strategy.
+   *
+   * The transport is selected based on the configured strategy. If the
+   * selected transport fails, the pool will retry with other transports
+   * up to the configured retry limit.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including abort signal.
+   * @returns A promise that resolves to a receipt indicating success or failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId | 'pool'>>;
+  /**
+   * Sends multiple email messages using the pool strategy.
+   *
+   * Each message is sent individually using the `send` method, respecting
+   * the configured strategy and retry logic.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including abort signal.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<TProviderId | 'pool'>>;
+  /**
+   * Disposes of all underlying transports that support disposal.
+   *
+   * This method is called automatically when using the `await using` syntax.
+   * It ensures proper cleanup of resources held by the underlying transports.
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Round-robin strategy that cycles through transports in order.
+ *
+ * This strategy maintains an internal counter and selects transports
+ * in a circular fashion, ensuring even distribution of messages across
+ * all enabled transports.
+ */
+export declare class RoundRobinStrategy<
+  TProviderId extends string = string,
+> implements Strategy<TProviderId> {
+  /**
+   * Selects the next transport in round-robin order.
+   *
+   * @param _message The message to send (unused in this strategy).
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if all transports have been
+   *          attempted.
+   */
+  select(
+    _message: Message,
+    transports: readonly ResolvedTransportEntry<TProviderId>[],
+    attemptedIndices: ReadonlySet<number>,
+  ): TransportSelection<TProviderId> | undefined;
+  /**
+   * Resets the round-robin counter to start from the beginning.
+   */
+  reset(): void;
+}
+
+/**
+ * Weighted strategy that distributes traffic based on configured weights.
+ *
+ * This strategy uses weighted random selection to distribute messages
+ * across transports proportionally to their configured weights.
+ * A transport with weight 2 will receive approximately twice as many
+ * messages as a transport with weight 1.
+ */
+export declare class WeightedStrategy<
+  TProviderId extends string = string,
+> implements Strategy<TProviderId> {
+  /**
+   * Selects a transport based on weighted random distribution.
+   *
+   * @param _message The message to send (unused in this strategy).
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if all transports have been
+   *          attempted.
+   */
+  select(
+    _message: Message,
+    transports: readonly ResolvedTransportEntry<TProviderId>[],
+    attemptedIndices: ReadonlySet<number>,
+  ): TransportSelection<TProviderId> | undefined;
+  /**
+   * Resets the strategy (no-op for weighted strategy as it's stateless).
+   */
+  reset(): void;
+}
+
+/**
+ * Priority strategy that selects transports based on priority values.
+ *
+ * This strategy always attempts to use the highest priority transport
+ * first, falling back to lower priority transports only when higher
+ * priority ones fail. Transports with the same priority are considered
+ * equivalent and one is selected randomly.
+ */
+export declare class PriorityStrategy<
+  TProviderId extends string = string,
+> implements Strategy<TProviderId> {
+  /**
+   * Selects the highest priority transport that hasn't been attempted.
+   *
+   * @param _message The message to send (unused in this strategy).
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if all transports have been
+   *          attempted.
+   */
+  select(
+    _message: Message,
+    transports: readonly ResolvedTransportEntry<TProviderId>[],
+    attemptedIndices: ReadonlySet<number>,
+  ): TransportSelection<TProviderId> | undefined;
+  /**
+   * Resets the strategy (no-op for priority strategy as it's stateless).
+   */
+  reset(): void;
+}
+
+/**
+ * Selector strategy that routes messages based on custom selector functions.
+ *
+ * This strategy evaluates each transport's selector function (if provided)
+ * to determine if it should handle a specific message. Transports without
+ * selectors are considered as catch-all fallbacks. Among matching transports,
+ * one is selected randomly.
+ */
+export declare class SelectorStrategy<
+  TProviderId extends string = string,
+> implements Strategy<TProviderId> {
+  /**
+   * Selects a transport based on selector function matching.
+   *
+   * @param message The message to send.
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if no transport matches.
+   */
+  select(
+    message: Message,
+    transports: readonly ResolvedTransportEntry<TProviderId>[],
+    attemptedIndices: ReadonlySet<number>,
+  ): TransportSelection<TProviderId> | undefined;
+  /**
+   * Resets the strategy (no-op for selector strategy as it's stateless).
+   */
+  reset(): void;
+}
diff --git a/src/pool/index.js b/src/pool/index.js
new file mode 100644
index 0000000..d05ada1
--- /dev/null
+++ b/src/pool/index.js
@@ -0,0 +1,26 @@
+// Ported from upyo v0.7.0 (packages/pool/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * @alexify/mailer/pool - Pool transport for Upyo email library
+ *
+ * Provides load balancing and failover capabilities for combining
+ * multiple email transports with various strategies.
+ *
+ * @packageDocumentation
+ */
+
+const { PoolTransport } = require('./pool-transport.js');
+
+const { RoundRobinStrategy } = require('./strategies/round-robin-strategy.js');
+const { WeightedStrategy } = require('./strategies/weighted-strategy.js');
+const { PriorityStrategy } = require('./strategies/priority-strategy.js');
+const { SelectorStrategy } = require('./strategies/selector-strategy.js');
+
+module.exports = {
+  PoolTransport,
+  RoundRobinStrategy,
+  WeightedStrategy,
+  PriorityStrategy,
+  SelectorStrategy,
+};
diff --git a/src/pool/pool-transport.js b/src/pool/pool-transport.js
new file mode 100644
index 0000000..fba7027
--- /dev/null
+++ b/src/pool/pool-transport.js
@@ -0,0 +1,401 @@
+// Ported from upyo v0.7.0 (packages/pool/src/pool-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { createFailedReceipt, createReceiptError } = require('../core/receipt.js');
+const { createPoolConfig } = require('./config.js');
+const { RoundRobinStrategy } = require('./strategies/round-robin-strategy.js');
+const { WeightedStrategy } = require('./strategies/weighted-strategy.js');
+const { PriorityStrategy } = require('./strategies/priority-strategy.js');
+const { SelectorStrategy } = require('./strategies/selector-strategy.js');
+
+/**
+ * Pool transport that combines multiple transports with various load balancing
+ * and failover strategies.
+ *
+ * This transport implements the same `Transport` interface, making it a drop-in
+ * replacement for any single transport. It distributes messages across multiple
+ * underlying transports based on the configured strategy.
+ *
+ * @example Round-robin load balancing
+ * ```typescript
+ * import { PoolTransport } from "@alexify/mailer/pool";
+ *
+ * const transport = new PoolTransport({
+ *   strategy: "round-robin",
+ *   transports: [
+ *     { transport: mailgunTransport },
+ *     { transport: sendgridTransport },
+ *     { transport: sesTransport },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Priority-based failover
+ * ```typescript
+ * const transport = new PoolTransport({
+ *   strategy: "priority",
+ *   transports: [
+ *     { transport: primaryTransport, priority: 100 },
+ *     { transport: backupTransport, priority: 50 },
+ *     { transport: lastResortTransport, priority: 10 },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Custom routing with selectors
+ * ```typescript
+ * const transport = new PoolTransport({
+ *   strategy: "selector-based",
+ *   transports: [
+ *     {
+ *       transport: bulkEmailTransport,
+ *       selector: (msg) => msg.tags?.includes("newsletter"),
+ *     },
+ *     {
+ *       transport: transactionalTransport,
+ *       selector: (msg) => msg.priority === "high",
+ *     },
+ *     { transport: defaultTransport }, // Catches everything else
+ *   ],
+ * });
+ * ```
+ */
+class PoolTransport {
+  id = 'pool';
+
+  /**
+   * The resolved configuration used by this pool transport.
+   */
+  config;
+
+  strategy;
+
+  /**
+   * Creates a new PoolTransport instance.
+   *
+   * @param config Configuration options for the pool transport.
+   * @throws {Error} If the configuration is invalid.
+   */
+  constructor(config) {
+    this.config = createPoolConfig(config);
+    this.strategy = this.createStrategy(this.config.strategy);
+  }
+
+  /**
+   * Sends a single email message using the pool strategy.
+   *
+   * The transport is selected based on the configured strategy. If the
+   * selected transport fails, the pool will retry with other transports
+   * up to the configured retry limit.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including abort signal.
+   * @returns A promise that resolves to a receipt indicating success or failure.
+   */
+  async send(message, options) {
+    const attemptedIndices = new Set();
+    const errorMessages = [];
+    const errors = [];
+    let checkCallerAbortBeforeFailure = false;
+
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      // Check for cancellation
+      if (options?.signal?.aborted) {
+        throw new DOMException('The operation was aborted.', 'AbortError');
+      }
+
+      // Select a transport
+      const selection = this.strategy.select(message, this.config.transports, attemptedIndices);
+
+      if (!selection) {
+        // No more transports available
+        break;
+      }
+
+      attemptedIndices.add(selection.index);
+
+      let abortedByCaller = false;
+      try {
+        // Apply timeout if configured
+        const sendOptions = this.createSendOptions(options);
+
+        let receipt;
+        try {
+          receipt = await selection.entry.transport.send(message, sendOptions.options);
+        } catch (error) {
+          if (sendOptions.abortedByCaller() && isCallerAbort(error, options?.signal)) {
+            abortedByCaller = true;
+          }
+          throw error;
+        } finally {
+          sendOptions.cleanup();
+        }
+
+        if (receipt.successful) {
+          return receipt;
+        }
+
+        // Collect error messages for failed attempts
+        errorMessages.push(...receipt.errorMessages);
+        errors.push(...getReceiptErrors(receipt, selection.entry.transport.id));
+        checkCallerAbortBeforeFailure = true;
+      } catch (error) {
+        // Handle transport errors
+        if (abortedByCaller && isCallerAbort(error, options?.signal)) {
+          throw error;
+        }
+
+        const thrownErrors = getThrownReceiptErrors(error, selection.entry.transport.id);
+        if (thrownErrors.length > 0) {
+          errorMessages.push(...thrownErrors.map((item) => item.message));
+          errors.push(...thrownErrors);
+          checkCallerAbortBeforeFailure = true;
+          continue;
+        }
+
+        const timeoutMessage = 'Transport send timed out.';
+        const abortError = isAbortError(error);
+        const errorMessage = abortError
+          ? timeoutMessage
+          : error instanceof Error
+            ? error.message
+            : String(error);
+        errorMessages.push(errorMessage);
+        errors.push(
+          createReceiptError(errorMessage, {
+            provider: selection.entry.transport.id,
+            category: abortError ? 'timeout' : undefined,
+            retryable: abortError ? true : undefined,
+          }),
+        );
+        checkCallerAbortBeforeFailure ||= !abortError;
+      }
+    }
+
+    // All attempts failed
+    if (checkCallerAbortBeforeFailure) {
+      options?.signal?.throwIfAborted();
+    }
+
+    return createFailedReceipt(
+      errorMessages.length > 0 ? errorMessages : ['All transports failed to send the message.'],
+      {
+        provider: 'pool',
+        errors: errors.length > 0 ? errors : undefined,
+        attempts: attemptedIndices.size,
+      },
+    );
+  }
+
+  /**
+   * Sends multiple email messages using the pool strategy.
+   *
+   * Each message is sent individually using the `send` method, respecting
+   * the configured strategy and retry logic.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including abort signal.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  async *sendMany(messages, options) {
+    // Reset strategy state for batch operations
+    this.strategy.reset();
+
+    for await (const message of messages) {
+      if (options?.signal?.aborted) {
+        throw new DOMException('The operation was aborted.', 'AbortError');
+      }
+
+      yield await this.send(message, options);
+    }
+  }
+
+  /**
+   * Disposes of all underlying transports that support disposal.
+   *
+   * This method is called automatically when using the `await using` syntax.
+   * It ensures proper cleanup of resources held by the underlying transports.
+   */
+  async [Symbol.asyncDispose]() {
+    const disposalPromises = [];
+
+    for (const entry of this.config.transports) {
+      const transport = entry.transport;
+
+      // Check for AsyncDisposable
+      if (typeof transport[Symbol.asyncDispose] === 'function') {
+        const asyncDispose = transport[Symbol.asyncDispose]();
+        disposalPromises.push(Promise.resolve(asyncDispose));
+      } // Check for Disposable
+      else if (typeof transport[Symbol.dispose] === 'function') {
+        try {
+          transport[Symbol.dispose]();
+        } catch {
+          // Ignore disposal errors
+        }
+      }
+    }
+
+    // Wait for all async disposals to complete
+    await Promise.allSettled(disposalPromises);
+  }
+
+  /**
+   * Creates a strategy instance based on the strategy type or returns the provided strategy.
+   */
+  createStrategy(strategy) {
+    // If it's already a Strategy instance, return it directly
+    if (typeof strategy === 'object' && strategy !== null) {
+      return strategy;
+    }
+
+    // Handle built-in strategy names
+    switch (strategy) {
+      case 'round-robin':
+        return new RoundRobinStrategy();
+      case 'weighted':
+        return new WeightedStrategy();
+      case 'priority':
+        return new PriorityStrategy();
+      case 'selector-based':
+        return new SelectorStrategy();
+      default:
+        throw new Error(`Unknown strategy: ${strategy}`);
+    }
+  }
+
+  /**
+   * Creates send options with timeout if configured.
+   */
+  createSendOptions(options) {
+    if (!this.config.timeout) {
+      return {
+        options,
+        abortedByCaller: () => options?.signal?.aborted ?? false,
+        cleanup: () => {},
+      };
+    }
+
+    // Create AbortController for timeout
+    const timeoutController = new AbortController();
+    let abortSource;
+    const timeoutId = setTimeout(() => {
+      abortSource ??= 'timeout';
+      timeoutController.abort(createAbortError());
+    }, this.config.timeout);
+    let cleanupAbortSource = () => {};
+    let signal = timeoutController.signal;
+    let cleanupCombinedSignal = () => {};
+
+    // Combine with existing signal if present
+    if (options?.signal) {
+      const markCallerAbort = () => {
+        abortSource ??= 'caller';
+        clearTimeout(timeoutId);
+      };
+      if (options.signal.aborted) {
+        markCallerAbort();
+      } else {
+        options.signal.addEventListener('abort', markCallerAbort, {
+          once: true,
+        });
+      }
+      cleanupAbortSource = () => options.signal?.removeEventListener('abort', markCallerAbort);
+
+      const combinedSignal = combineSignals(timeoutController.signal, options.signal);
+      signal = combinedSignal.signal;
+      cleanupCombinedSignal = combinedSignal.cleanup;
+    }
+
+    // Clean up timeout when done
+    timeoutController.signal.addEventListener('abort', () => {
+      clearTimeout(timeoutId);
+    });
+
+    return {
+      options: {
+        ...options,
+        signal,
+      },
+      abortedByCaller: () => abortSource === 'caller',
+      cleanup: () => {
+        clearTimeout(timeoutId);
+        cleanupAbortSource();
+        cleanupCombinedSignal();
+      },
+    };
+  }
+}
+
+const createAbortError = () => {
+  return new DOMException('The operation was aborted.', 'AbortError');
+};
+
+const isCallerAbort = (error, signal) => {
+  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+};
+
+const getReceiptErrors = (receipt, provider) => {
+  if (receipt.errors != null && receipt.errors.length > 0) {
+    return receipt.errors.map((error) => withReceiptErrorProvider(error, provider));
+  }
+
+  return receipt.errorMessages.map((message) =>
+    createReceiptError(message, {
+      provider: receipt.provider ?? provider,
+      retryable: receipt.retryable,
+    }),
+  );
+};
+
+const getThrownReceiptErrors = (error, provider) => {
+  if (isReceiptError(error)) {
+    return [withReceiptErrorProvider(error, provider)];
+  }
+
+  if (isFailedReceipt(error)) {
+    return getReceiptErrors(error, provider);
+  }
+
+  return [];
+};
+
+const withReceiptErrorProvider = (error, provider) => {
+  return {
+    message: error.message,
+    code: error.code,
+    category: error.category,
+    retryable: error.retryable,
+    provider: error.provider ?? provider,
+    statusCode: error.statusCode,
+    retryAfterMilliseconds: error.retryAfterMilliseconds,
+    providerDetails: error.providerDetails,
+  };
+};
+
+const isReceiptError = (value) => {
+  return (
+    typeof value === 'object' &&
+    value != null &&
+    typeof value.message === 'string' &&
+    typeof value.code === 'string' &&
+    typeof value.retryable === 'boolean' &&
+    typeof value.category === 'string'
+  );
+};
+
+const isFailedReceipt = (value) => {
+  return (
+    typeof value === 'object' &&
+    value != null &&
+    value.successful === false &&
+    Array.isArray(value.errorMessages)
+  );
+};
+
+const isAbortError = (error) => {
+  return error instanceof Error && error.name === 'AbortError';
+};
+
+module.exports = { PoolTransport };
diff --git a/src/pool/strategies/priority-strategy.js b/src/pool/strategies/priority-strategy.js
new file mode 100644
index 0000000..d144805
--- /dev/null
+++ b/src/pool/strategies/priority-strategy.js
@@ -0,0 +1,60 @@
+// Ported from upyo v0.7.0 (packages/pool/src/strategies/priority-strategy.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Priority strategy that selects transports based on priority values.
+ *
+ * This strategy always attempts to use the highest priority transport
+ * first, falling back to lower priority transports only when higher
+ * priority ones fail. Transports with the same priority are considered
+ * equivalent and one is selected randomly.
+ */
+class PriorityStrategy {
+  /**
+   * Selects the highest priority transport that hasn't been attempted.
+   *
+   * @param _message The message to send (unused in this strategy).
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if all transports have been
+   *          attempted.
+   */
+  select(_message, transports, attemptedIndices) {
+    // Filter to enabled transports that haven't been attempted
+    const availableTransports = transports
+      .map((entry, index) => ({ entry, index }))
+      .filter(({ entry, index }) => entry.enabled && !attemptedIndices.has(index));
+
+    if (availableTransports.length < 1) return undefined;
+
+    // Sort by priority (highest first)
+    availableTransports.sort((a, b) => b.entry.priority - a.entry.priority);
+
+    // Get the highest priority value
+    const highestPriority = availableTransports[0].entry.priority;
+
+    // Filter to only transports with the highest priority
+    const topPriorityTransports = availableTransports.filter(
+      ({ entry }) => entry.priority === highestPriority,
+    );
+
+    // If multiple transports have the same priority, select randomly
+    if (topPriorityTransports.length > 1) {
+      const randomIndex = Math.floor(Math.random() * topPriorityTransports.length);
+      return topPriorityTransports[randomIndex];
+    }
+
+    // Return the single highest priority transport
+    return topPriorityTransports[0];
+  }
+
+  /**
+   * Resets the strategy (no-op for priority strategy as it's stateless).
+   */
+  reset() {
+    // Priority strategy is stateless, nothing to reset
+  }
+}
+
+module.exports = { PriorityStrategy };
diff --git a/src/pool/strategies/round-robin-strategy.js b/src/pool/strategies/round-robin-strategy.js
new file mode 100644
index 0000000..ee21b35
--- /dev/null
+++ b/src/pool/strategies/round-robin-strategy.js
@@ -0,0 +1,58 @@
+// Ported from upyo v0.7.0 (packages/pool/src/strategies/round-robin-strategy.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Round-robin strategy that cycles through transports in order.
+ *
+ * This strategy maintains an internal counter and selects transports
+ * in a circular fashion, ensuring even distribution of messages across
+ * all enabled transports.
+ */
+class RoundRobinStrategy {
+  currentIndex = 0;
+
+  /**
+   * Selects the next transport in round-robin order.
+   *
+   * @param _message The message to send (unused in this strategy).
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if all transports have been
+   *          attempted.
+   */
+  select(_message, transports, attemptedIndices) {
+    const enabledCount = transports.filter((t) => t.enabled).length;
+    if (enabledCount < 1) return undefined;
+
+    // Try up to the number of enabled transports
+    for (let attempts = 0; attempts < enabledCount; attempts++) {
+      // Find the next enabled transport
+      while (!transports[this.currentIndex].enabled) {
+        this.currentIndex = (this.currentIndex + 1) % transports.length;
+      }
+
+      const index = this.currentIndex;
+      const entry = transports[index];
+
+      // Move to next for the next call
+      this.currentIndex = (this.currentIndex + 1) % transports.length;
+
+      // Skip if already attempted
+      if (attemptedIndices.has(index)) continue;
+
+      return { entry, index };
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Resets the round-robin counter to start from the beginning.
+   */
+  reset() {
+    this.currentIndex = 0;
+  }
+}
+
+module.exports = { RoundRobinStrategy };
diff --git a/src/pool/strategies/selector-strategy.js b/src/pool/strategies/selector-strategy.js
new file mode 100644
index 0000000..4ae2812
--- /dev/null
+++ b/src/pool/strategies/selector-strategy.js
@@ -0,0 +1,68 @@
+// Ported from upyo v0.7.0 (packages/pool/src/strategies/selector-strategy.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Selector strategy that routes messages based on custom selector functions.
+ *
+ * This strategy evaluates each transport's selector function (if provided)
+ * to determine if it should handle a specific message. Transports without
+ * selectors are considered as catch-all fallbacks. Among matching transports,
+ * one is selected randomly.
+ */
+class SelectorStrategy {
+  /**
+   * Selects a transport based on selector function matching.
+   *
+   * @param message The message to send.
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if no transport matches.
+   */
+  select(message, transports, attemptedIndices) {
+    // Filter to enabled transports that haven't been attempted
+    const availableTransports = transports
+      .map((entry, index) => ({ entry, index }))
+      .filter(({ entry, index }) => entry.enabled && !attemptedIndices.has(index));
+
+    if (availableTransports.length < 1) return undefined;
+
+    // Separate transports with selectors from those without
+    const withSelectors = [];
+    const withoutSelectors = [];
+
+    for (const transport of availableTransports) {
+      if (transport.entry.selector) {
+        // Evaluate selector function
+        try {
+          if (transport.entry.selector(message)) {
+            withSelectors.push(transport);
+          }
+        } catch {
+          // If selector throws, skip this transport
+        }
+      } else {
+        // No selector means it accepts all messages
+        withoutSelectors.push(transport);
+      }
+    }
+
+    // Prefer transports with matching selectors
+    const candidates = withSelectors.length > 0 ? withSelectors : withoutSelectors;
+
+    if (candidates.length < 1) return undefined;
+
+    // Select randomly from candidates
+    const randomIndex = Math.floor(Math.random() * candidates.length);
+    return candidates[randomIndex];
+  }
+
+  /**
+   * Resets the strategy (no-op for selector strategy as it's stateless).
+   */
+  reset() {
+    // Selector strategy is stateless, nothing to reset
+  }
+}
+
+module.exports = { SelectorStrategy };
diff --git a/src/pool/strategies/weighted-strategy.js b/src/pool/strategies/weighted-strategy.js
new file mode 100644
index 0000000..aafd72e
--- /dev/null
+++ b/src/pool/strategies/weighted-strategy.js
@@ -0,0 +1,62 @@
+// Ported from upyo v0.7.0 (packages/pool/src/strategies/weighted-strategy.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Weighted strategy that distributes traffic based on configured weights.
+ *
+ * This strategy uses weighted random selection to distribute messages
+ * across transports proportionally to their configured weights.
+ * A transport with weight 2 will receive approximately twice as many
+ * messages as a transport with weight 1.
+ */
+class WeightedStrategy {
+  /**
+   * Selects a transport based on weighted random distribution.
+   *
+   * @param _message The message to send (unused in this strategy).
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if all transports have been
+   *          attempted.
+   */
+  select(_message, transports, attemptedIndices) {
+    // Filter to enabled transports that haven't been attempted
+    const availableTransports = transports
+      .map((entry, index) => ({ entry, index }))
+      .filter(
+        ({ entry, index }) => entry.enabled && entry.weight > 0 && !attemptedIndices.has(index),
+      );
+
+    if (availableTransports.length < 1) return undefined;
+
+    // Calculate total weight of available transports
+    const totalWeight = availableTransports.reduce((sum, { entry }) => sum + entry.weight, 0);
+
+    if (totalWeight <= 0) return undefined;
+
+    // Random selection based on weights
+    const random = Math.random() * totalWeight;
+    let cumulativeWeight = 0;
+
+    for (const { entry, index } of availableTransports) {
+      cumulativeWeight += entry.weight;
+      if (random < cumulativeWeight) {
+        return { entry, index };
+      }
+    }
+
+    // Fallback to last available transport (shouldn't normally reach here)
+    const last = availableTransports[availableTransports.length - 1];
+    return { entry: last.entry, index: last.index };
+  }
+
+  /**
+   * Resets the strategy (no-op for weighted strategy as it's stateless).
+   */
+  reset() {
+    // Weighted strategy is stateless, nothing to reset
+  }
+}
+
+module.exports = { WeightedStrategy };
diff --git a/tests/helpers/pool/test-config.js b/tests/helpers/pool/test-config.js
new file mode 100644
index 0000000..05cef7e
--- /dev/null
+++ b/tests/helpers/pool/test-config.js
@@ -0,0 +1,103 @@
+// Ported from upyo v0.7.0 (packages/pool/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { MockTransport } = require('../../../src/mock/index.js');
+const { PoolTransport } = require('../../../src/pool/pool-transport.js');
+
+/**
+ * Creates a test message with default values.
+ */
+const createTestMessage = (overrides) => {
+  return {
+    sender: { address: 'sender@example.com', name: 'Sender' },
+    recipients: [{ address: 'recipient@example.com', name: 'Recipient' }],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    attachments: [],
+    subject: 'Test Subject',
+    content: { text: 'Test content' },
+    tags: [],
+    priority: 'normal',
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+/**
+ * Creates a mock transport that always succeeds.
+ */
+const createSuccessTransport = (messageId = 'success-id') => {
+  const transport = new MockTransport();
+  transport.setNextResponse({
+    successful: true,
+    messageId,
+    provider: 'mock',
+  });
+  return transport;
+};
+
+/**
+ * Creates a mock transport that always fails.
+ */
+const createFailureTransport = (errorMessage = 'Transport failed') => {
+  const transport = new MockTransport();
+  transport.setNextResponse({
+    successful: false,
+    errorMessages: [errorMessage],
+    provider: 'mock',
+  });
+  return transport;
+};
+
+/**
+ * Creates a mock transport that fails N times then succeeds.
+ */
+const createFlakeyTransport = (
+  failureCount,
+  successId = 'flaky-success',
+  errorMessage = 'Temporary failure',
+) => {
+  const transport = new MockTransport();
+  let attempts = 0;
+
+  // Override send method to implement flaky behavior
+  const originalSend = transport.send.bind(transport);
+  transport.send = (message, options) => {
+    attempts++;
+    if (attempts <= failureCount) {
+      transport.setNextResponse({
+        successful: false,
+        errorMessages: [errorMessage],
+        provider: 'mock',
+      });
+    } else {
+      transport.setNextResponse({
+        successful: true,
+        messageId: successId,
+        provider: 'mock',
+      });
+    }
+    return originalSend(message, options);
+  };
+
+  return transport;
+};
+
+/**
+ * Creates a pool transport with the given configuration.
+ */
+const createTestPoolTransport = (config) => {
+  return new PoolTransport({
+    strategy: 'round-robin',
+    ...config,
+  });
+};
+
+module.exports = {
+  createTestMessage,
+  createSuccessTransport,
+  createFailureTransport,
+  createFlakeyTransport,
+  createTestPoolTransport,
+};
diff --git a/tests/types/pool.test-d.ts b/tests/types/pool.test-d.ts
new file mode 100644
index 0000000..4d4c9d8
--- /dev/null
+++ b/tests/types/pool.test-d.ts
@@ -0,0 +1,45 @@
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt } from '../../index.js';
+import { MockTransport } from '../../src/mock/index.js';
+import {
+  PoolTransport,
+  PriorityStrategy,
+  RoundRobinStrategy,
+  SelectorStrategy,
+  WeightedStrategy,
+  type PoolConfig,
+  type Strategy,
+} from '../../src/pool/index.js';
+
+const primary = new MockTransport();
+const backup = new MockTransport();
+const pool = new PoolTransport({
+  strategy: 'priority',
+  transports: [
+    { transport: primary, priority: 10 },
+    { transport: backup, priority: 1, selector: (message) => message.priority === 'high' },
+  ],
+  maxRetries: 1,
+  timeout: 5000,
+});
+expectType<'pool'>(pool.id);
+expectAssignable<AsyncDisposable>(pool);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'mock' | 'pool'>>>(pool.send(message));
+
+for (const strategy of [
+  new RoundRobinStrategy(),
+  new WeightedStrategy(),
+  new PriorityStrategy(),
+  new SelectorStrategy(),
+]) {
+  expectAssignable<Strategy>(strategy);
+}
+expectAssignable<PoolConfig>({ strategy: new RoundRobinStrategy(), transports: [] });
+expectError(new PoolTransport({ strategy: 'random', transports: [] }));
diff --git a/tests/unit/pool-strategies-priority-strategy.test.js b/tests/unit/pool-strategies-priority-strategy.test.js
new file mode 100644
index 0000000..da9d52d
--- /dev/null
+++ b/tests/unit/pool-strategies-priority-strategy.test.js
@@ -0,0 +1,171 @@
+// Ported from upyo v0.7.0 (packages/pool/src/strategies/priority-strategy.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { PriorityStrategy } = require('../../src/pool/strategies/priority-strategy.js');
+const { createTestMessage } = require('../helpers/pool/test-config.js');
+const { MockTransport } = require('../../src/mock/index.js');
+
+describe('PriorityStrategy', () => {
+  const createTestEntries = () => {
+    return [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 10, // Low priority
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 100, // High priority
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 50, // Medium priority
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 100, // Also high priority
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 200, // Highest but disabled
+        enabled: false,
+      },
+    ];
+  };
+
+  test('should select highest priority transport first', () => {
+    const strategy = new PriorityStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Should select one of the transports with priority 100 (indices 1 or 3)
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.ok(selection.index === 1 || selection.index === 3);
+    assert.equal(selection.entry.priority, 100);
+  });
+
+  test('should randomly select among same priority transports', () => {
+    const strategy = new PriorityStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Count selections over many iterations
+    const selectionCounts = new Map();
+    const iterations = 100;
+
+    for (let i = 0; i < iterations; i++) {
+      const selection = strategy.select(message, transports, attemptedIndices);
+      if (selection) {
+        selectionCounts.set(selection.index, (selectionCounts.get(selection.index) || 0) + 1);
+      }
+    }
+
+    // Both indices 1 and 3 (priority 100) should be selected
+    const count1 = selectionCounts.get(1) || 0;
+    const count3 = selectionCounts.get(3) || 0;
+
+    assert.ok(count1 > 0);
+    assert.ok(count3 > 0);
+    assert.equal(count1 + count3, iterations);
+
+    // Other priorities should not be selected
+    assert.equal(selectionCounts.get(0) || 0, 0);
+    assert.equal(selectionCounts.get(2) || 0, 0);
+    assert.equal(selectionCounts.get(4) || 0, 0);
+  });
+
+  test('should fall back to lower priority when higher ones attempted', () => {
+    const strategy = new PriorityStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set([1, 3]); // Already tried priority 100
+
+    // Should select priority 50 (index 2)
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.equal(selection.index, 2);
+    assert.equal(selection.entry.priority, 50);
+  });
+
+  test('should skip disabled transports', () => {
+    const strategy = new PriorityStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Transport at index 4 has priority 200 but is disabled
+    // Should select priority 100 instead
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.ok(selection.index === 1 || selection.index === 3);
+    assert.equal(selection.entry.priority, 100);
+  });
+
+  test('should return undefined when all transports attempted', () => {
+    const strategy = new PriorityStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set([0, 1, 2, 3, 4]);
+
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection, undefined);
+  });
+
+  test('should handle negative priorities', () => {
+    const strategy = new PriorityStrategy();
+    const transports = [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: -10,
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: -5,
+        enabled: true,
+      },
+    ];
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Should select -5 (higher than -10)
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.equal(selection.index, 1);
+    assert.equal(selection.entry.priority, -5);
+  });
+
+  test('reset() should be a no-op', () => {
+    const strategy = new PriorityStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Select before reset
+    const selection1 = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection1);
+
+    // Reset should not affect stateless strategy
+    strategy.reset();
+
+    // Should still select highest priority
+    const selection2 = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection2);
+    assert.equal(selection2.entry.priority, 100);
+  });
+});
diff --git a/tests/unit/pool-strategies-round-robin-strategy.test.js b/tests/unit/pool-strategies-round-robin-strategy.test.js
new file mode 100644
index 0000000..004005f
--- /dev/null
+++ b/tests/unit/pool-strategies-round-robin-strategy.test.js
@@ -0,0 +1,140 @@
+// Ported from upyo v0.7.0 (packages/pool/src/strategies/round-robin-strategy.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { RoundRobinStrategy } = require('../../src/pool/strategies/round-robin-strategy.js');
+const { createTestMessage } = require('../helpers/pool/test-config.js');
+const { MockTransport } = require('../../src/mock/index.js');
+
+describe('RoundRobinStrategy', () => {
+  const createTestEntries = () => {
+    return [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: false, // Disabled
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+      },
+    ];
+  };
+
+  test('should cycle through enabled transports in order', () => {
+    const strategy = new RoundRobinStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // First selection should be index 0
+    const selection1 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection1?.index, 0);
+
+    // Second selection should be index 1
+    const selection2 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection2?.index, 1);
+
+    // Third selection should skip index 2 (disabled) and select index 3
+    const selection3 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection3?.index, 3);
+
+    // Fourth selection should wrap around to index 0
+    const selection4 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection4?.index, 0);
+  });
+
+  test('should skip already attempted transports', () => {
+    const strategy = new RoundRobinStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set([0, 1]); // Already tried 0 and 1
+
+    // Should skip 0, 1, and disabled 2, select 3
+    const selection1 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection1?.index, 3);
+
+    attemptedIndices.add(3);
+
+    // All enabled transports attempted, should return undefined
+    const selection2 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection2, undefined);
+  });
+
+  test('should return undefined when no enabled transports', () => {
+    const strategy = new RoundRobinStrategy();
+    const transports = [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: false,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: false,
+      },
+    ];
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection, undefined);
+  });
+
+  test('should reset counter on reset()', () => {
+    const strategy = new RoundRobinStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Advance to second transport
+    strategy.select(message, transports, attemptedIndices);
+    const selection1 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection1?.index, 1);
+
+    // Reset and verify it starts from beginning
+    strategy.reset();
+    const selection2 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection2?.index, 0);
+  });
+
+  test('should handle single enabled transport', () => {
+    const strategy = new RoundRobinStrategy();
+    const transports = [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+      },
+    ];
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Should always select the only transport
+    const selection1 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection1?.index, 0);
+
+    const selection2 = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection2?.index, 0);
+  });
+});
diff --git a/tests/unit/pool-strategies-selector-strategy.test.js b/tests/unit/pool-strategies-selector-strategy.test.js
new file mode 100644
index 0000000..3323330
--- /dev/null
+++ b/tests/unit/pool-strategies-selector-strategy.test.js
@@ -0,0 +1,229 @@
+// Ported from upyo v0.7.0 (packages/pool/src/strategies/selector-strategy.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { SelectorStrategy } = require('../../src/pool/strategies/selector-strategy.js');
+const { createTestMessage } = require('../helpers/pool/test-config.js');
+const { MockTransport } = require('../../src/mock/index.js');
+
+describe('SelectorStrategy', () => {
+  const createTestEntries = () => {
+    return [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        selector: (msg) => msg.tags?.includes('newsletter'),
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        selector: (msg) => msg.priority === 'high',
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        // No selector - accepts all
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: false,
+        selector: (msg) => msg.tags?.includes('promo'),
+      },
+    ];
+  };
+
+  test('should select transport with matching selector', () => {
+    const strategy = new SelectorStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage({ tags: ['newsletter', 'marketing'] });
+    const attemptedIndices = new Set();
+
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.equal(selection.index, 0);
+  });
+
+  test('should select transport without selector as fallback', () => {
+    const strategy = new SelectorStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage({ tags: ['transactional'] });
+    const attemptedIndices = new Set();
+
+    // No selector matches, should select transport without selector (index 2)
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.equal(selection.index, 2);
+  });
+
+  test('should randomly select among multiple matching transports', () => {
+    const strategy = new SelectorStrategy();
+    const transports = [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        selector: (msg) => msg.tags?.includes('test'),
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        selector: (msg) => msg.tags?.includes('test'),
+      },
+    ];
+    const message = createTestMessage({ tags: ['test'] });
+    const attemptedIndices = new Set();
+
+    // Count selections over many iterations
+    const selectionCounts = new Map();
+    const iterations = 100;
+
+    for (let i = 0; i < iterations; i++) {
+      const selection = strategy.select(message, transports, attemptedIndices);
+      if (selection) {
+        selectionCounts.set(selection.index, (selectionCounts.get(selection.index) || 0) + 1);
+      }
+    }
+
+    // Both should be selected at least once
+    assert.ok((selectionCounts.get(0) || 0) > 0);
+    assert.ok((selectionCounts.get(1) || 0) > 0);
+  });
+
+  test('should skip disabled transports even if selector matches', () => {
+    const strategy = new SelectorStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage({ tags: ['promo'] });
+    const attemptedIndices = new Set();
+
+    // Index 3 has matching selector but is disabled
+    // Should fall back to transport without selector (index 2)
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.equal(selection.index, 2);
+  });
+
+  test('should skip already attempted transports', () => {
+    const strategy = new SelectorStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage({ tags: ['newsletter'] });
+    const attemptedIndices = new Set([0]); // Already tried matching transport
+
+    // Should fall back to transport without selector
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.equal(selection.index, 2);
+  });
+
+  test('should handle selector that throws error', () => {
+    const strategy = new SelectorStrategy();
+    const transports = [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        selector: (_msg) => {
+          throw new Error('Selector error');
+        },
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        // No selector
+      },
+    ];
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Should skip transport with throwing selector and select fallback
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.equal(selection.index, 1);
+  });
+
+  test('should return undefined when no transport matches or available', () => {
+    const strategy = new SelectorStrategy();
+    const transports = [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        selector: (msg) => msg.tags?.includes('newsletter'),
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        selector: (msg) => msg.priority === 'high',
+      },
+    ];
+    const message = createTestMessage({ tags: ['other'] });
+    const attemptedIndices = new Set();
+
+    // No selector matches and no fallback available
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection, undefined);
+  });
+
+  test('should prioritize selector matches over fallbacks', () => {
+    const strategy = new SelectorStrategy();
+    const transports = [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        // No selector - fallback
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+        selector: (msg) => msg.priority === 'high',
+      },
+    ];
+    const message = createTestMessage({ priority: 'high' });
+    const attemptedIndices = new Set();
+
+    // Should select transport with matching selector (index 1) over fallback
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection);
+    assert.equal(selection.index, 1);
+  });
+
+  test('reset() should be a no-op', () => {
+    const strategy = new SelectorStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage({ tags: ['newsletter'] });
+    const attemptedIndices = new Set();
+
+    // Select before reset
+    const selection1 = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection1);
+
+    // Reset should not affect stateless strategy
+    strategy.reset();
+
+    // Should still select matching transport
+    const selection2 = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection2);
+    assert.equal(selection2.index, 0);
+  });
+});
diff --git a/tests/unit/pool-strategies-weighted-strategy.test.js b/tests/unit/pool-strategies-weighted-strategy.test.js
new file mode 100644
index 0000000..df8c8ff
--- /dev/null
+++ b/tests/unit/pool-strategies-weighted-strategy.test.js
@@ -0,0 +1,176 @@
+// Ported from upyo v0.7.0 (packages/pool/src/strategies/weighted-strategy.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { WeightedStrategy } = require('../../src/pool/strategies/weighted-strategy.js');
+const { createTestMessage } = require('../helpers/pool/test-config.js');
+const { MockTransport } = require('../../src/mock/index.js');
+
+describe('WeightedStrategy', () => {
+  const createTestEntries = () => {
+    return [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 2,
+        priority: 0,
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 3,
+        priority: 0,
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: false, // Disabled
+      },
+    ];
+  };
+
+  test('should select transports based on weight distribution', () => {
+    const strategy = new WeightedStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Count selections over many iterations
+    const selectionCounts = new Map();
+    const iterations = 1000;
+
+    for (let i = 0; i < iterations; i++) {
+      const selection = strategy.select(message, transports, attemptedIndices);
+      if (selection) {
+        selectionCounts.set(selection.index, (selectionCounts.get(selection.index) || 0) + 1);
+      }
+    }
+
+    // Verify distribution roughly matches weights
+    // Transport 0: weight 1 (1/6 ≈ 16.7%)
+    // Transport 1: weight 2 (2/6 ≈ 33.3%)
+    // Transport 2: weight 3 (3/6 = 50%)
+    // Transport 3: disabled (0%)
+
+    const count0 = selectionCounts.get(0) || 0;
+    const count1 = selectionCounts.get(1) || 0;
+    const count2 = selectionCounts.get(2) || 0;
+    const count3 = selectionCounts.get(3) || 0;
+
+    // Allow 10% variance
+    assert.ok(count0 > iterations * 0.07 && count0 < iterations * 0.27);
+    assert.ok(count1 > iterations * 0.23 && count1 < iterations * 0.43);
+    assert.ok(count2 > iterations * 0.4 && count2 < iterations * 0.6);
+    assert.equal(count3, 0); // Disabled transport should never be selected
+  });
+
+  test('should skip already attempted transports', () => {
+    const strategy = new WeightedStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set([0, 1]); // Already tried 0 and 1
+
+    // Should only select from index 2 (weight 3)
+    const selections = new Set();
+    for (let i = 0; i < 10; i++) {
+      const selection = strategy.select(message, transports, attemptedIndices);
+      if (selection) {
+        selections.add(selection.index);
+      }
+    }
+
+    assert.equal(selections.size, 1);
+    assert.ok(selections.has(2));
+  });
+
+  test('should return undefined when all transports attempted', () => {
+    const strategy = new WeightedStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set([0, 1, 2, 3]);
+
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection, undefined);
+  });
+
+  test('should return undefined when no enabled transports', () => {
+    const strategy = new WeightedStrategy();
+    const transports = [
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: false,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 2,
+        priority: 0,
+        enabled: false,
+      },
+    ];
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    const selection = strategy.select(message, transports, attemptedIndices);
+    assert.equal(selection, undefined);
+  });
+
+  test('should handle zero weight transports', () => {
+    const strategy = new WeightedStrategy();
+    const transports = [
+      {
+        transport: new MockTransport(),
+        weight: 0, // Zero weight
+        priority: 0,
+        enabled: true,
+      },
+      {
+        transport: new MockTransport(),
+        weight: 1,
+        priority: 0,
+        enabled: true,
+      },
+    ];
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Should only select transport with positive weight
+    const selections = new Set();
+    for (let i = 0; i < 10; i++) {
+      const selection = strategy.select(message, transports, attemptedIndices);
+      if (selection) {
+        selections.add(selection.index);
+      }
+    }
+
+    assert.equal(selections.size, 1);
+    assert.ok(selections.has(1));
+  });
+
+  test('reset() should be a no-op', () => {
+    const strategy = new WeightedStrategy();
+    const transports = createTestEntries();
+    const message = createTestMessage();
+    const attemptedIndices = new Set();
+
+    // Select before reset
+    const selection1 = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection1);
+
+    // Reset should not affect stateless strategy
+    strategy.reset();
+
+    // Should still be able to select
+    const selection2 = strategy.select(message, transports, attemptedIndices);
+    assert.ok(selection2);
+  });
+});
diff --git a/tests/unit/pool-transport.test.js b/tests/unit/pool-transport.test.js
new file mode 100644
index 0000000..4d7c994
--- /dev/null
+++ b/tests/unit/pool-transport.test.js
@@ -0,0 +1,797 @@
+// Ported from upyo v0.7.0 (packages/pool/src/pool-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const assert = require('node:assert/strict');
+const { describe, test } = require('node:test');
+const { PoolTransport } = require('../../src/pool/pool-transport.js');
+const { MockTransport } = require('../../src/mock/index.js');
+const { createFailedReceipt, createReceiptError } = require('../../src/core/receipt.js');
+const {
+  createFailureTransport,
+  createSuccessTransport,
+  createTestMessage,
+} = require('../helpers/pool/test-config.js');
+
+describe('PoolTransport', () => {
+  class FixedFailureTransport {
+    id;
+    receipt;
+
+    constructor(id, receipt) {
+      this.id = id;
+      this.receipt = receipt;
+    }
+
+    send(_message, _options) {
+      return Promise.resolve(this.receipt);
+    }
+
+    async *sendMany(messages, _options) {
+      // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+      for await (const _message of messages) {
+        yield this.receipt;
+      }
+    }
+  }
+
+  class ThrowingTransport {
+    id;
+    error;
+
+    constructor(id, error) {
+      this.id = id;
+      this.error = error;
+    }
+
+    send(_message, _options) {
+      return Promise.reject(this.error);
+    }
+
+    async *sendMany(messages, options) {
+      for await (const message of messages) {
+        yield await this.send(message, options);
+      }
+    }
+  }
+
+  describe('round-robin strategy', () => {
+    test('should distribute messages across transports', async () => {
+      const transport1 = new MockTransport();
+      const transport2 = new MockTransport();
+      const transport3 = new MockTransport();
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [
+          { transport: transport1 },
+          { transport: transport2 },
+          { transport: transport3 },
+        ],
+      });
+
+      // Send three messages
+      await pool.send(createTestMessage({ subject: 'Message 1' }));
+      await pool.send(createTestMessage({ subject: 'Message 2' }));
+      await pool.send(createTestMessage({ subject: 'Message 3' }));
+
+      // Each transport should have received exactly one message
+      assert.equal(transport1.getSentMessagesCount(), 1);
+      assert.equal(transport2.getSentMessagesCount(), 1);
+      assert.equal(transport3.getSentMessagesCount(), 1);
+
+      // Verify the messages
+      assert.equal(transport1.getSentMessages()[0].subject, 'Message 1');
+      assert.equal(transport2.getSentMessages()[0].subject, 'Message 2');
+      assert.equal(transport3.getSentMessages()[0].subject, 'Message 3');
+    });
+
+    test('should skip disabled transports', async () => {
+      const transport1 = new MockTransport();
+      const transport2 = new MockTransport();
+      const transport3 = new MockTransport();
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [
+          { transport: transport1, enabled: true },
+          { transport: transport2, enabled: false },
+          { transport: transport3, enabled: true },
+        ],
+      });
+
+      await pool.send(createTestMessage({ subject: 'Message 1' }));
+      await pool.send(createTestMessage({ subject: 'Message 2' }));
+
+      assert.equal(transport1.getSentMessagesCount(), 1);
+      assert.equal(transport2.getSentMessagesCount(), 0); // Disabled
+      assert.equal(transport3.getSentMessagesCount(), 1);
+    });
+  });
+
+  describe('weighted strategy', () => {
+    test('should distribute based on weights', async () => {
+      const transport1 = new MockTransport();
+      const transport2 = new MockTransport();
+
+      const pool = new PoolTransport({
+        strategy: 'weighted',
+        transports: [
+          { transport: transport1, weight: 1 },
+          { transport: transport2, weight: 3 },
+        ],
+      });
+
+      const originalRandom = Math.random;
+      const randomValues = [0.125, 0.375, 0.625, 0.875];
+      try {
+        Math.random = () => randomValues.shift() ?? 0.875;
+
+        for (let i = 0; i < 4; i++) {
+          await pool.send(createTestMessage({ subject: `Message ${i}` }));
+        }
+      } finally {
+        Math.random = originalRandom;
+      }
+
+      const count1 = transport1.getSentMessagesCount();
+      const count2 = transport2.getSentMessagesCount();
+
+      assert.equal(count1, 1);
+      assert.equal(count2, 3);
+    });
+  });
+
+  describe('priority strategy', () => {
+    test('should use highest priority transport first', async () => {
+      const highPriority = createSuccessTransport('high-id');
+      const mediumPriority = createSuccessTransport('medium-id');
+      const lowPriority = createSuccessTransport('low-id');
+
+      const pool = new PoolTransport({
+        strategy: 'priority',
+        transports: [
+          { transport: lowPriority, priority: 10 },
+          { transport: highPriority, priority: 100 },
+          { transport: mediumPriority, priority: 50 },
+        ],
+      });
+
+      const receipt = await pool.send(createTestMessage());
+      assert.ok(receipt.successful);
+      assert.equal(receipt.messageId, 'high-id');
+
+      // Only high priority should have been used
+      assert.equal(highPriority.getSentMessagesCount(), 1);
+      assert.equal(mediumPriority.getSentMessagesCount(), 0);
+      assert.equal(lowPriority.getSentMessagesCount(), 0);
+    });
+
+    test('should failover to lower priority on failure', async () => {
+      const highPriority = createFailureTransport('High priority failed');
+      const mediumPriority = createSuccessTransport('medium-id');
+      const lowPriority = createSuccessTransport('low-id');
+
+      const pool = new PoolTransport({
+        strategy: 'priority',
+        transports: [
+          { transport: highPriority, priority: 100 },
+          { transport: mediumPriority, priority: 50 },
+          { transport: lowPriority, priority: 10 },
+        ],
+      });
+
+      const receipt = await pool.send(createTestMessage());
+      assert.ok(receipt.successful);
+      assert.equal(receipt.messageId, 'medium-id');
+
+      // High priority was tried but failed
+      assert.equal(highPriority.getSentMessagesCount(), 1);
+      // Medium priority succeeded
+      assert.equal(mediumPriority.getSentMessagesCount(), 1);
+      // Low priority was not needed
+      assert.equal(lowPriority.getSentMessagesCount(), 0);
+    });
+  });
+
+  describe('selector-based strategy', () => {
+    test('should route messages based on selectors', async () => {
+      const newsletterTransport = new MockTransport();
+      const transactionalTransport = new MockTransport();
+      const defaultTransport = new MockTransport();
+
+      const pool = new PoolTransport({
+        strategy: 'selector-based',
+        transports: [
+          {
+            transport: newsletterTransport,
+            selector: (msg) => msg.tags?.includes('newsletter'),
+          },
+          {
+            transport: transactionalTransport,
+            selector: (msg) => msg.priority === 'high',
+          },
+          {
+            transport: defaultTransport,
+            // No selector - catches everything else
+          },
+        ],
+      });
+
+      // Send newsletter
+      await pool.send(
+        createTestMessage({
+          subject: 'Newsletter',
+          tags: ['newsletter', 'marketing'],
+        }),
+      );
+
+      // Send transactional
+      await pool.send(
+        createTestMessage({
+          subject: 'Password Reset',
+          priority: 'high',
+        }),
+      );
+
+      // Send default
+      await pool.send(
+        createTestMessage({
+          subject: 'Regular Email',
+        }),
+      );
+
+      // Verify routing
+      assert.equal(newsletterTransport.getSentMessagesCount(), 1);
+      assert.equal(newsletterTransport.getSentMessages()[0].subject, 'Newsletter');
+
+      assert.equal(transactionalTransport.getSentMessagesCount(), 1);
+      assert.equal(transactionalTransport.getSentMessages()[0].subject, 'Password Reset');
+
+      assert.equal(defaultTransport.getSentMessagesCount(), 1);
+      assert.equal(defaultTransport.getSentMessages()[0].subject, 'Regular Email');
+    });
+  });
+
+  describe('retry and failover', () => {
+    test('should retry with different transports on failure', async () => {
+      const transport1 = createFailureTransport('Failed 1');
+      const transport2 = createFailureTransport('Failed 2');
+      const transport3 = createSuccessTransport('success-id');
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [
+          { transport: transport1 },
+          { transport: transport2 },
+          { transport: transport3 },
+        ],
+        maxRetries: 3,
+      });
+
+      const receipt = await pool.send(createTestMessage());
+      assert.ok(receipt.successful);
+      assert.equal(receipt.messageId, 'success-id');
+
+      // All transports should have been tried
+      assert.equal(transport1.getSentMessagesCount(), 1);
+      assert.equal(transport2.getSentMessagesCount(), 1);
+      assert.equal(transport3.getSentMessagesCount(), 1);
+    });
+
+    test('should return failure when all transports fail', async () => {
+      const transport1 = createFailureTransport('Failed 1');
+      const transport2 = createFailureTransport('Failed 2');
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport: transport1 }, { transport: transport2 }],
+      });
+
+      const receipt = await pool.send(createTestMessage());
+      assert.ok(!receipt.successful);
+      assert.ok(receipt.errorMessages.includes('Failed 1'));
+      assert.ok(receipt.errorMessages.includes('Failed 2'));
+    });
+
+    test('should preserve transport ids in structured failures', async () => {
+      const primary = new FixedFailureTransport(
+        'mailgun',
+        createFailedReceipt('Too many requests', {
+          provider: 'mailgun',
+          statusCode: 429,
+        }),
+      );
+      const secondary = new FixedFailureTransport('sendgrid', {
+        successful: false,
+        errorMessages: ['Invalid API key'],
+      });
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport: primary }, { transport: secondary }],
+      });
+
+      const receipt = await pool.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.provider, 'pool');
+        assert.equal(receipt.attempts, 2);
+        assert.deepEqual(
+          receipt.errors?.map((error) => error.provider),
+          ['mailgun', 'sendgrid'],
+        );
+        assert.equal(receipt.errors?.[0]?.category, 'rate-limit');
+        assert.equal(receipt.errors?.[1]?.category, 'auth');
+      }
+    });
+
+    test('should preserve retryable legacy child failures', async () => {
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [
+          {
+            transport: new FixedFailureTransport('legacy', {
+              successful: false,
+              errorMessages: ['Try again later'],
+              retryable: true,
+              provider: 'legacy',
+            }),
+          },
+        ],
+      });
+
+      const receipt = await pool.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.errors?.[0]?.retryable, true);
+        assert.equal(receipt.errors?.[0]?.provider, 'legacy');
+      }
+    });
+
+    test('should preserve structured errors thrown by transports', async () => {
+      const thrownError = createReceiptError('Too many requests', {
+        provider: 'mailgun',
+        statusCode: 429,
+      });
+      const thrownReceipt = createFailedReceipt('Invalid API key', {
+        provider: 'sendgrid',
+        category: 'auth',
+      });
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [
+          { transport: new ThrowingTransport('mailgun', thrownError) },
+          { transport: new ThrowingTransport('sendgrid', thrownReceipt) },
+        ],
+      });
+
+      const receipt = await pool.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.deepEqual(receipt.errorMessages, ['Too many requests', 'Invalid API key']);
+        assert.deepEqual(
+          receipt.errors?.map((error) => error.category),
+          ['rate-limit', 'auth'],
+        );
+        assert.deepEqual(
+          receipt.errors?.map((error) => error.provider),
+          ['mailgun', 'sendgrid'],
+        );
+      }
+    });
+
+    test('should preserve thrown Error receipt messages', async () => {
+      class ThrownReceiptError extends Error {
+        code = 'http.429';
+        category = 'rate-limit';
+        retryable = true;
+      }
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [
+          {
+            transport: new ThrowingTransport(
+              'mailgun',
+              new ThrownReceiptError('Too many requests'),
+            ),
+          },
+        ],
+      });
+
+      const receipt = await pool.send(createTestMessage());
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errorMessages[0], 'Too many requests');
+        assert.equal(receipt.errors?.[0]?.message, 'Too many requests');
+        assert.equal(receipt.errors?.[0]?.provider, 'mailgun');
+      }
+    });
+
+    test('should respect maxRetries limit', async () => {
+      const transport1 = createFailureTransport('Failed');
+      const transport2 = createFailureTransport('Failed');
+      const transport3 = createSuccessTransport('success');
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [
+          { transport: transport1 },
+          { transport: transport2 },
+          { transport: transport3 },
+        ],
+        maxRetries: 1,
+      });
+
+      const receipt = await pool.send(createTestMessage());
+      assert.ok(!receipt.successful);
+
+      // Only first two should have been tried
+      assert.equal(transport1.getSentMessagesCount(), 1);
+      assert.equal(transport2.getSentMessagesCount(), 1);
+      assert.equal(transport3.getSentMessagesCount(), 0);
+    });
+
+    test('should make an initial attempt when retries are disabled', async () => {
+      const transport1 = createFailureTransport('Failed');
+      const transport2 = createSuccessTransport('success');
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport: transport1 }, { transport: transport2 }],
+        maxRetries: 0,
+      });
+
+      const receipt = await pool.send(createTestMessage());
+      assert.ok(!receipt.successful);
+
+      assert.equal(transport1.getSentMessagesCount(), 1);
+      assert.equal(transport2.getSentMessagesCount(), 0);
+    });
+  });
+
+  describe('sendMany', () => {
+    test('should send multiple messages', async () => {
+      const transport = new MockTransport();
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport }],
+      });
+
+      const messages = [
+        createTestMessage({ subject: 'Message 1' }),
+        createTestMessage({ subject: 'Message 2' }),
+        createTestMessage({ subject: 'Message 3' }),
+      ];
+
+      const receipts = [];
+      for await (const receipt of pool.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 3);
+      assert.ok(receipts.every((r) => r.successful));
+      assert.equal(transport.getSentMessagesCount(), 3);
+    });
+
+    test('should handle async iterable', async () => {
+      const transport = new MockTransport();
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport }],
+      });
+
+      const generateMessages = async function* () {
+        yield createTestMessage({ subject: 'Async 1' });
+        yield createTestMessage({ subject: 'Async 2' });
+      };
+
+      const receipts = [];
+      for await (const receipt of pool.sendMany(generateMessages())) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.ok(receipts.every((r) => r.successful));
+    });
+  });
+
+  describe('abort signal', () => {
+    test('should respect abort signal', async () => {
+      const transport = new MockTransport({ delay: 100 });
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport }],
+      });
+
+      const controller = new AbortController();
+      setTimeout(() => controller.abort(), 10); // Abort after 10ms
+
+      await assert.rejects(pool.send(createTestMessage(), { signal: controller.signal }), {
+        name: 'AbortError',
+      });
+    });
+
+    test('should abort sendMany on signal', async () => {
+      const transport = new MockTransport({ delay: 100 });
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport }],
+      });
+
+      const messages = [
+        createTestMessage({ subject: 'Message 1' }),
+        createTestMessage({ subject: 'Message 2' }),
+      ];
+
+      const controller = new AbortController();
+      setTimeout(() => controller.abort(), 50);
+
+      await assert.rejects(
+        async () => {
+          const receipts = [];
+          for await (const receipt of pool.sendMany(messages, {
+            signal: controller.signal,
+          })) {
+            receipts.push(receipt);
+          }
+        },
+        {
+          name: 'AbortError',
+        },
+      );
+    });
+
+    test('should pass through aborts that happen during selection', async () => {
+      const controller = new AbortController();
+      const transport = {
+        id: 'delayed',
+        send(_message, options) {
+          assert.ok(options?.signal?.aborted);
+          return Promise.reject(new DOMException('The operation was aborted.', 'AbortError'));
+        },
+        async *sendMany(messages) {
+          for await (const message of messages) {
+            yield await this.send(message);
+          }
+        },
+      };
+      const pool = new PoolTransport({
+        strategy: {
+          select(_message, transports) {
+            controller.abort();
+            return { entry: transports[0], index: 0 };
+          },
+          reset() {},
+        },
+        transports: [{ transport }],
+        timeout: 1000,
+      });
+
+      await assert.rejects(() => pool.send(createTestMessage(), { signal: controller.signal }), {
+        name: 'AbortError',
+      });
+    });
+
+    test('should preserve caller abort reasons with timeout', async () => {
+      const abortReason = new Error('Stop pooled send.');
+      const controller = new AbortController();
+      const transport = {
+        id: 'delayed',
+        send(_message, options) {
+          return new Promise((_resolve, reject) => {
+            options?.signal?.addEventListener(
+              'abort',
+              () => {
+                reject(options.signal?.reason);
+              },
+              { once: true },
+            );
+            setTimeout(() => controller.abort(abortReason), 0);
+          });
+        },
+        async *sendMany(messages, options) {
+          for await (const message of messages) {
+            yield await this.send(message, options);
+          }
+        },
+      };
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport }],
+        timeout: 1000,
+      });
+
+      await assert.rejects(
+        () => pool.send(createTestMessage(), { signal: controller.signal }),
+        (error) => error === abortReason,
+      );
+    });
+
+    test('should keep timeout receipts when callers abort later', async () => {
+      const controller = new AbortController();
+      const transport = {
+        id: 'slow',
+        send(_message, options) {
+          // oxlint-disable-next-line promise/param-names -- upstream
+          return new Promise((_, reject) => {
+            options?.signal?.addEventListener(
+              'abort',
+              () => {
+                setTimeout(() => {
+                  reject(new DOMException('The operation was aborted.', 'AbortError'));
+                }, 20);
+              },
+              { once: true },
+            );
+          });
+        },
+        async *sendMany(messages, options) {
+          for await (const message of messages) {
+            yield await this.send(message, options);
+          }
+        },
+      };
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport }],
+        timeout: 5,
+      });
+
+      setTimeout(() => controller.abort(), 10);
+      const receipt = await pool.send(createTestMessage(), {
+        signal: controller.signal,
+      });
+
+      assert.ok(!receipt.successful);
+      if (!receipt.successful) {
+        assert.equal(receipt.errors?.[0]?.category, 'timeout');
+        assert.ok(receipt.retryable);
+      }
+    });
+
+    test('should rethrow caller aborts before returning final failures', async () => {
+      const abortReason = new Error('Stop final failure.');
+      const controller = new AbortController();
+      const transport = {
+        id: 'failing',
+        send() {
+          controller.abort(abortReason);
+          return Promise.reject(new Error('Network failure.'));
+        },
+        async *sendMany(messages, options) {
+          for await (const message of messages) {
+            yield await this.send(message, options);
+          }
+        },
+      };
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport }],
+      });
+
+      await assert.rejects(
+        () => pool.send(createTestMessage(), { signal: controller.signal }),
+        (error) => error === abortReason,
+      );
+    });
+  });
+
+  describe('AsyncDisposable', () => {
+    test('should dispose underlying transports', async () => {
+      let disposed1 = false;
+      let disposed2 = false;
+
+      const transport1 = new MockTransport();
+      const transport2 = new MockTransport();
+
+      // Add disposal tracking
+      transport1[Symbol.asyncDispose] = () => {
+        disposed1 = true;
+        return Promise.resolve();
+      };
+      transport2[Symbol.dispose] = () => {
+        disposed2 = true;
+      };
+
+      const pool = new PoolTransport({
+        strategy: 'round-robin',
+        transports: [{ transport: transport1 }, { transport: transport2 }],
+      });
+
+      await pool[Symbol.asyncDispose]();
+
+      assert.ok(disposed1);
+      assert.ok(disposed2);
+    });
+  });
+
+  describe('custom strategy', () => {
+    test('should accept custom strategy instance', async () => {
+      const transport1 = new MockTransport();
+      const transport2 = new MockTransport();
+
+      // Custom strategy that always selects the second transport
+      const customStrategy = {
+        select: () => ({
+          entry: {
+            transport: transport2,
+            weight: 1,
+            priority: 0,
+            enabled: true,
+          },
+          index: 1,
+        }),
+        reset: () => {},
+      };
+
+      const pool = new PoolTransport({
+        strategy: customStrategy,
+        transports: [{ transport: transport1 }, { transport: transport2 }],
+      });
+
+      await pool.send(createTestMessage());
+      await pool.send(createTestMessage());
+
+      // Custom strategy should always use transport2
+      assert.equal(transport1.getSentMessagesCount(), 0);
+      assert.equal(transport2.getSentMessagesCount(), 2);
+    });
+  });
+
+  describe('configuration validation', () => {
+    test('should throw on empty transports', () => {
+      assert.throws(
+        () => {
+          // oxlint-disable-next-line no-new -- upstream
+          new PoolTransport({
+            strategy: 'round-robin',
+            transports: [],
+          });
+        },
+        {
+          message: /at least one transport/,
+        },
+      );
+    });
+
+    test('should throw on all disabled transports', () => {
+      assert.throws(
+        () => {
+          // oxlint-disable-next-line no-new -- upstream
+          new PoolTransport({
+            strategy: 'round-robin',
+            transports: [
+              { transport: new MockTransport(), enabled: false },
+              { transport: new MockTransport(), enabled: false },
+            ],
+          });
+        },
+        {
+          message: /at least one enabled transport/,
+        },
+      );
+    });
+
+    test('should throw on invalid strategy', () => {
+      assert.throws(
+        () => {
+          // oxlint-disable-next-line no-new -- upstream
+          new PoolTransport({
+            strategy: 'invalid',
+            transports: [{ transport: new MockTransport() }],
+          });
+        },
+        {
+          message: /Unknown strategy/,
+        },
+      );
+    });
+  });
+});
diff --git a/tests/unit/pool.test.js b/tests/unit/pool.test.js
new file mode 100644
index 0000000..6b8fb41
--- /dev/null
+++ b/tests/unit/pool.test.js
@@ -0,0 +1,69 @@
+// Paths of the ported PoolTransport (src/pool/) that upstream's suites leave
+// out: weights that leave nothing to pick, aborts before a send, a timeout
+// without a caller signal, and a transport whose dispose throws.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { MockTransport } = require('../../src/mock/index.js');
+const { PoolTransport } = require('../../src/pool/index.js');
+
+const message = () =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+
+test('Pool: a weighted pool needs an enabled transport with a positive weight', () => {
+  assert.throws(
+    () =>
+      new PoolTransport({
+        strategy: 'weighted',
+        transports: [{ transport: new MockTransport(), weight: 0 }],
+      }),
+    { message: 'Weighted strategy requires at least one enabled transport with positive weight' },
+  );
+});
+
+test('Pool: an aborted signal rejects a send and a batch before any transport', async () => {
+  const mock = new MockTransport();
+  const pool = new PoolTransport({ strategy: 'round-robin', transports: [{ transport: mock }] });
+  const signal = AbortSignal.abort();
+  await assert.rejects(pool.send(message(), { signal }), { name: 'AbortError' });
+  await assert.rejects(pool.sendMany([message()], { signal })[Symbol.asyncIterator]().next(), {
+    name: 'AbortError',
+  });
+  assert.strictEqual(mock.getSentMessagesCount(), 0);
+});
+
+test('Pool: a timeout applies without a caller signal, and retries stop at the last transport', async () => {
+  const failing = new MockTransport({
+    defaultResponse: { successful: false, errorMessages: ['Down'] },
+  });
+  const pool = new PoolTransport({
+    strategy: 'priority',
+    transports: [{ transport: failing }],
+    timeout: 1000,
+    maxRetries: 3,
+  });
+  const receipt = await pool.send(message());
+  assert.strictEqual(receipt.successful, false);
+  assert.strictEqual(failing.getSentMessagesCount(), 1);
+});
+
+test('Pool: a transport whose dispose throws does not fail the disposal', async () => {
+  const throwing = {
+    id: 'sync',
+    send: async () => ({ successful: true, messageId: 'x' }),
+    async *sendMany() {},
+    [Symbol.dispose]() {
+      throw new Error('dispose failed');
+    },
+  };
+  const pool = new PoolTransport({
+    strategy: 'round-robin',
+    transports: [{ transport: throwing }],
+  });
+  await pool[Symbol.asyncDispose]();
+});

From 64ad458c581ec928df74c220fc824ac43d2f345d Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:41:45 +0300
Subject: [PATCH 017/158] feat(otel): port the OpenTelemetry decorator from
 upyo 0.7.0

./otel exports OpenTelemetryTransport, createOpenTelemetryTransport,
createEmailAttributeExtractor, createErrorClassifier and
defaultErrorClassifier: a transport that wraps another one with a client
span per send or batch, events and statuses, and counters and histograms of
attempts, messages, durations, sizes and active sends, under sampling rates.

The OpenTelemetry API is passed in, never required: tracerProvider and
meterProvider come from the application (required while tracing or metrics
are on), the fallback to the global providers of @opentelemetry/api is
gone, SpanKind and SpanStatusCode become their numeric values, and the
tracer and meter are named from src/version.js. The d.ts declares the
providers as structural types; a type test checks that the real ones fit.
The upyo.* span attributes become mailer.*, and the metric prefix mailer.

Upstream's suites are ported; the integration suite runs on the real
OpenTelemetry SDK 1.x (devDependencies). tests/unit/otel.test.js covers
sampled-out sends, the transport name and network attributes guessed from
a config, custom batch attributes and failed batches; the dead
recordRetry and extractNetworkAttributes of upstream are excluded from the
coverage.

Also: pool's d.ts now references esnext.disposable itself, and a test keeps
every d.ts that uses AsyncDisposable doing so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |   2 +-
 package.json                                  |  10 +
 pnpm-lock.yaml                                |  94 +++
 src/otel/attributes.js                        | 213 ++++++
 src/otel/config.js                            | 154 +++++
 src/otel/index.d.ts                           | 610 ++++++++++++++++++
 src/otel/index.js                             | 286 ++++++++
 src/otel/message-size.js                      |  63 ++
 src/otel/metrics.js                           | 206 ++++++
 src/otel/opentelemetry-transport.js           | 386 +++++++++++
 src/otel/tracing.js                           | 188 ++++++
 src/pool/index.d.ts                           |   2 +
 tests/helpers/otel/mock-otel-providers.js     | 329 ++++++++++
 tests/helpers/otel/test-config.js             | 235 +++++++
 tests/types/otel.test-d.ts                    |  41 ++
 tests/unit/export-parity.test.js              |  12 +
 tests/unit/otel-config.test.js                | 224 +++++++
 tests/unit/otel-content-type.test.js          |  74 +++
 tests/unit/otel-index.test.js                 | 240 +++++++
 tests/unit/otel-integration.test.js           | 340 ++++++++++
 tests/unit/otel-message-size.test.js          |  68 ++
 .../unit/otel-opentelemetry-transport.test.js | 501 ++++++++++++++
 tests/unit/otel.test.js                       | 112 ++++
 23 files changed, 4389 insertions(+), 1 deletion(-)
 create mode 100644 src/otel/attributes.js
 create mode 100644 src/otel/config.js
 create mode 100644 src/otel/index.d.ts
 create mode 100644 src/otel/index.js
 create mode 100644 src/otel/message-size.js
 create mode 100644 src/otel/metrics.js
 create mode 100644 src/otel/opentelemetry-transport.js
 create mode 100644 src/otel/tracing.js
 create mode 100644 tests/helpers/otel/mock-otel-providers.js
 create mode 100644 tests/helpers/otel/test-config.js
 create mode 100644 tests/types/otel.test-d.ts
 create mode 100644 tests/unit/otel-config.test.js
 create mode 100644 tests/unit/otel-content-type.test.js
 create mode 100644 tests/unit/otel-index.test.js
 create mode 100644 tests/unit/otel-integration.test.js
 create mode 100644 tests/unit/otel-message-size.test.js
 create mode 100644 tests/unit/otel-opentelemetry-transport.test.js
 create mode 100644 tests/unit/otel.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9388619..375e219 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 4
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index e89cf4c..2b6a048 100644
--- a/package.json
+++ b/package.json
@@ -79,6 +79,10 @@
     "./mock": {
       "types": "./src/mock/index.d.ts",
       "default": "./src/mock/index.js"
+    },
+    "./otel": {
+      "types": "./src/otel/index.d.ts",
+      "default": "./src/otel/index.js"
     }
   },
   "directories": {
@@ -141,6 +145,12 @@
     "zero-dependency"
   ],
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^1.30.1",
+    "@opentelemetry/resources": "^1.30.1",
+    "@opentelemetry/sdk-metrics": "^1.30.1",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
     "@vercel/analytics": "^2.0.1",
     "@vercel/speed-insights": "^2.0.0",
     "c8": "^12.0.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a7a4235..060898b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -8,6 +8,24 @@ importers:
 
   .:
     devDependencies:
+      '@opentelemetry/api':
+        specifier: ^1.9.1
+        version: 1.9.1
+      '@opentelemetry/context-async-hooks':
+        specifier: ^1.30.1
+        version: 1.30.1(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources':
+        specifier: ^1.30.1
+        version: 1.30.1(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-metrics':
+        specifier: ^1.30.1
+        version: 1.30.1(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace-base':
+        specifier: ^1.30.1
+        version: 1.30.1(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions':
+        specifier: ^1.43.0
+        version: 1.43.0
       '@vercel/analytics':
         specifier: ^2.0.1
         version: 2.0.1(vue@3.5.44(typescript@7.0.2))
@@ -502,6 +520,48 @@ packages:
     resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
     engines: {node: '>= 8'}
 
+  '@opentelemetry/api@1.9.1':
+    resolution: {integrity: sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==}
+    engines: {node: '>=8.0.0'}
+
+  '@opentelemetry/context-async-hooks@1.30.1':
+    resolution: {integrity: sha512-s5vvxXPVdjqS3kTLKMeBMvop9hbWkwzBpu+mUO2M7sZtlkyDJGwFe33wRKnbaYDo8ExRVBIIdwIGrqpxHuKttA==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/core@1.30.1':
+    resolution: {integrity: sha512-OOCM2C/QIURhJMuKaekP3TRBxBKxG/TWWA0TL2J6nXUtDnuCtccy49LUJF8xPFXMX+0LMcxFpCo8M9cGY1W6rQ==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/resources@1.30.1':
+    resolution: {integrity: sha512-5UxZqiAgLYGFjS4s9qm5mBVo433u+dSPUFWVWXmLAD4wB65oMCoXaJP1KJa9DIYYMeHu3z4BZcStG3LC593cWA==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/sdk-metrics@1.30.1':
+    resolution: {integrity: sha512-q9zcZ0Okl8jRgmy7eNW3Ku1XSgg3sDLa5evHZpCwjspw7E8Is4K/haRPDJrBcX3YSn/Y7gUvFnByNYEKQNbNog==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.3.0 <1.10.0'
+
+  '@opentelemetry/sdk-trace-base@1.30.1':
+    resolution: {integrity: sha512-jVPgBbH1gCy2Lb7X0AVQ8XAfgg0pJ4nvl8/IiQA6nxOsPvS+0zMJaFSs2ltXe0J6C8dqjcnpyqINDJmU30+uOg==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/semantic-conventions@1.28.0':
+    resolution: {integrity: sha512-lp4qAiMTD4sNWW4DbKLBkfiMZ4jbAboJIGOQr5DvciMRI494OapieI9qiODpOt0XBr1LjIDy1xAGAnVs5supTA==}
+    engines: {node: '>=14'}
+
+  '@opentelemetry/semantic-conventions@1.43.0':
+    resolution: {integrity: sha512-eSYWTm620tTk45EKSedaUL8MFYI8hW164hIXsgIHyxu3VobUB3fFCu5t0hQby6OoWRPsG1KkKUG2M5UadiLiVg==}
+    engines: {node: '>=14'}
+
   '@oxfmt/binding-android-arm-eabi@0.72.0':
     resolution: {integrity: sha512-u4U1uaDOVBuorGNC/07NLm48nECHOiJJka002YGML16Md2DRvf38RGBt01lH60EOGvNlFVmbLoksQedNBoZHKw==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -2436,6 +2496,40 @@ snapshots:
       '@nodelib/fs.scandir': 2.1.5
       fastq: 1.20.3
 
+  '@opentelemetry/api@1.9.1': {}
+
+  '@opentelemetry/context-async-hooks@1.30.1(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+
+  '@opentelemetry/core@1.30.1(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/semantic-conventions': 1.28.0
+
+  '@opentelemetry/resources@1.30.1(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 1.30.1(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.28.0
+
+  '@opentelemetry/sdk-metrics@1.30.1(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 1.30.1(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 1.30.1(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/sdk-trace-base@1.30.1(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 1.30.1(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 1.30.1(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.28.0
+
+  '@opentelemetry/semantic-conventions@1.28.0': {}
+
+  '@opentelemetry/semantic-conventions@1.43.0': {}
+
   '@oxfmt/binding-android-arm-eabi@0.72.0':
     optional: true
 
diff --git a/src/otel/attributes.js b/src/otel/attributes.js
new file mode 100644
index 0000000..56cf293
--- /dev/null
+++ b/src/otel/attributes.js
@@ -0,0 +1,213 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/attributes.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { estimateMessageSize } = require('./message-size.js');
+
+/**
+ * Email attribute extractor class for generating OpenTelemetry attributes.
+ * Handles extraction of message metadata, error information, and transport details
+ * while respecting privacy settings for sensitive data.
+ *
+ * This class provides methods for extracting attributes from email messages,
+ * batch operations, and errors, making them suitable for use in OpenTelemetry
+ * spans and metrics.
+ *
+ * @example
+ * ```typescript
+ * import { EmailAttributeExtractor } from "@alexify/mailer/otel";
+ *
+ * const extractor = new EmailAttributeExtractor(
+ *   "smtp",           // transport name
+ *   false,            // don't record sensitive data
+ *   "2.1.0"          // transport version
+ * );
+ *
+ * // Extract attributes from a message
+ * const messageAttrs = extractor.extractMessageAttributes(message);
+ *
+ * // Extract attributes from batch operations
+ * const batchAttrs = extractor.extractBatchAttributes(messages, batchSize);
+ *
+ * // Extract attributes from errors
+ * const errorAttrs = extractor.extractErrorAttributes(error, "network");
+ * ```
+ */
+class EmailAttributeExtractor {
+  recordSensitiveData;
+  transportName;
+  transportVersion;
+
+  constructor(transportName, recordSensitiveData = false, transportVersion) {
+    this.transportName = transportName;
+    this.recordSensitiveData = recordSensitiveData;
+    this.transportVersion = transportVersion;
+  }
+
+  /**
+   * Extracts attributes for a single message send operation.
+   */
+  extractMessageAttributes(message) {
+    const attributes = {
+      // General operation attributes (following OTel patterns)
+      'operation.name': 'email.send',
+      'operation.type': 'email',
+
+      // Email-specific attributes (new namespace)
+      'email.to.count': message.recipients.length,
+      'email.cc.count': message.ccRecipients.length,
+      'email.bcc.count': message.bccRecipients.length,
+      'email.attachments.count': message.attachments.length,
+      'email.priority': message.priority,
+      'email.tags': JSON.stringify(message.tags),
+
+      // Upyo-specific attributes (vendor namespace)
+      'mailer.transport.name': this.transportName,
+      'mailer.retry.count': 0, // Will be updated by transport if retries occur
+      'mailer.batch.size': 1,
+    };
+
+    // Add transport version if available
+    if (this.transportVersion) {
+      attributes['mailer.transport.version'] = this.transportVersion;
+    }
+
+    // Conditionally add sensitive data
+    if (this.recordSensitiveData) {
+      attributes['email.from.address'] = message.sender.address;
+      attributes['email.subject.length'] = message.subject.length;
+    } else {
+      // Redacted versions
+      attributes['email.from.domain'] = this.extractDomain(message.sender.address);
+      attributes['email.subject.length'] = message.subject.length;
+    }
+
+    // Content type detection
+    attributes['email.content.type'] = this.detectContentType(message);
+
+    // Calculate message size estimate
+    attributes['email.message.size'] = estimateMessageSize(message);
+
+    return attributes;
+  }
+
+  /**
+   * Extracts attributes for batch send operations.
+   */
+  extractBatchAttributes(messages, batchSize) {
+    const totalAttachments = messages.reduce((sum, msg) => sum + msg.attachments.length, 0);
+    const totalSize = messages.reduce((sum, msg) => sum + estimateMessageSize(msg), 0);
+
+    const attributes = {
+      // General operation attributes
+      'operation.name': 'email.send_batch',
+      'operation.type': 'email',
+
+      // Batch-specific attributes
+      'email.batch.size': batchSize,
+      'email.batch.total_recipients': messages.reduce(
+        (sum, msg) =>
+          sum + msg.recipients.length + msg.ccRecipients.length + msg.bccRecipients.length,
+        0,
+      ),
+      'email.batch.total_attachments': totalAttachments,
+      'email.batch.total_size': totalSize,
+
+      // Upyo-specific attributes
+      'mailer.transport.name': this.transportName,
+      'mailer.batch.size': batchSize,
+    };
+
+    // Add transport version if available
+    if (this.transportVersion) {
+      attributes['mailer.transport.version'] = this.transportVersion;
+    }
+
+    return attributes;
+  }
+
+  // Dead upstream: the transport extracts its own network attributes.
+  /* c8 ignore start */
+  /**
+   * Extracts network-related attributes from transport configuration.
+   */
+  extractNetworkAttributes(protocol, serverAddress, serverPort) {
+    const attributes = {
+      'network.protocol.name': protocol,
+    };
+
+    if (serverAddress) {
+      attributes['server.address'] = serverAddress;
+    }
+
+    if (serverPort) {
+      attributes['server.port'] = serverPort;
+    }
+
+    return attributes;
+  }
+  /* c8 ignore stop */
+
+  /**
+   * Extracts error-related attributes.
+   */
+  extractErrorAttributes(error, errorCategory) {
+    const attributes = {
+      'error.type': errorCategory,
+    };
+
+    if (error instanceof Error) {
+      attributes['error.name'] = error.name;
+
+      // Only record error message if not sensitive data mode or if it's a safe error
+      if (this.recordSensitiveData || this.isSafeErrorMessage(error.message)) {
+        attributes['error.message'] = error.message;
+      }
+    }
+
+    return attributes;
+  }
+
+  detectContentType(message) {
+    // If there are attachments, it's always multipart
+    if (message.attachments.length > 0) {
+      return 'multipart';
+    }
+
+    // A calendar is a second body part wherever it goes: an alternative beside
+    // the text and HTML on the transports that compose one, and a synthesized
+    // invite.ics attachment on the rest.
+    if (message.calendar != null) {
+      return 'multipart';
+    }
+
+    // For content without attachments
+    if ('html' in message.content) {
+      return 'html';
+    }
+    return 'text';
+  }
+
+  extractDomain(email) {
+    const atIndex = email.lastIndexOf('@');
+    return atIndex > 0 ? email.substring(atIndex + 1) : 'unknown';
+  }
+
+  isSafeErrorMessage(message) {
+    const safePatterns = [
+      /^timeout/i,
+      /^connection/i,
+      /^network/i,
+      /^dns/i,
+      /^rate limit/i,
+      /^quota exceeded/i,
+      /^service unavailable/i,
+      /^internal server error/i,
+      /^bad gateway/i,
+      /^gateway timeout/i,
+    ];
+
+    return safePatterns.some((pattern) => pattern.test(message));
+  }
+}
+
+module.exports = { EmailAttributeExtractor };
diff --git a/src/otel/config.js b/src/otel/config.js
new file mode 100644
index 0000000..dccc946
--- /dev/null
+++ b/src/otel/config.js
@@ -0,0 +1,154 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Default configuration values.
+ */
+const DEFAULT_CONFIG = {
+  metrics: {
+    enabled: true,
+    samplingRate: 1.0,
+    prefix: 'mailer',
+    durationBuckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0],
+  },
+  tracing: {
+    enabled: true,
+    samplingRate: 1.0,
+    recordSensitiveData: false,
+    spanPrefix: 'email',
+  },
+};
+
+/**
+ * Creates a resolved OpenTelemetry configuration with defaults applied.
+ *
+ * @param config The input configuration options.
+ * @returns A resolved configuration with all defaults applied.
+ * @throws {Error} When tracing is enabled but no TracerProvider is provided.
+ * @throws {Error} When metrics are enabled but no MeterProvider is provided.
+ */
+const createOpenTelemetryConfig = (config = {}) => {
+  const resolvedConfig = {
+    tracerProvider: config.tracerProvider,
+    meterProvider: config.meterProvider,
+    metrics: {
+      ...DEFAULT_CONFIG.metrics,
+      ...config.metrics,
+    },
+    tracing: {
+      ...DEFAULT_CONFIG.tracing,
+      ...config.tracing,
+    },
+    attributeExtractor: config.attributeExtractor,
+    errorClassifier: config.errorClassifier,
+  };
+
+  // Validate required providers
+  if (resolvedConfig.tracing.enabled && !resolvedConfig.tracerProvider) {
+    throw new Error(
+      'TracerProvider is required when tracing is enabled. ' +
+        'Provide tracerProvider in config or use auto-configuration.',
+    );
+  }
+
+  if (resolvedConfig.metrics.enabled && !resolvedConfig.meterProvider) {
+    throw new Error(
+      'MeterProvider is required when metrics are enabled. ' +
+        'Provide meterProvider in config or use auto-configuration.',
+    );
+  }
+
+  return resolvedConfig;
+};
+
+/**
+ * Default error classifier that categorizes errors into standard types.
+ *
+ * @example
+ * ```typescript
+ * import { defaultErrorClassifier } from "@alexify/mailer/otel";
+ *
+ * console.log(defaultErrorClassifier(new Error("401 Unauthorized"))); // "auth"
+ * console.log(defaultErrorClassifier(new Error("Rate limit exceeded"))); // "rate-limit"
+ * console.log(defaultErrorClassifier(new Error("Connection timeout"))); // "network"
+ * console.log(defaultErrorClassifier(new Error("Invalid email format"))); // "validation"
+ * console.log(defaultErrorClassifier(new Error("500 Internal Server Error"))); // "server-error"
+ * console.log(defaultErrorClassifier(new Error("Something else"))); // "unknown"
+ * ```
+ *
+ * @param error The error to classify.
+ * @returns A string category such as `"auth"`, `"rate-limit"`, `"network"`,
+ *          `"validation"`, `"service-unavailable"`, `"server-error"`, or
+ *          `"unknown"`.
+ */
+const defaultErrorClassifier = (error) => {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    const name = error.name.toLowerCase();
+
+    // Authentication errors
+    if (
+      message.includes('auth') ||
+      message.includes('unauthorized') ||
+      message.includes('invalid api key') ||
+      message.includes('403')
+    ) {
+      return 'auth';
+    }
+
+    // Rate limiting
+    if (
+      message.includes('rate limit') ||
+      message.includes('429') ||
+      message.includes('quota exceeded') ||
+      message.includes('throttle')
+    ) {
+      return 'rate-limit';
+    }
+
+    // Server errors (check before network errors to catch "504 Gateway Timeout")
+    if (
+      message.includes('500') ||
+      message.includes('502') ||
+      message.includes('504') ||
+      message.includes('internal server error')
+    ) {
+      return 'server-error';
+    }
+
+    // Network errors
+    if (
+      name.includes('network') ||
+      message.includes('connect') ||
+      message.includes('timeout') ||
+      message.includes('dns') ||
+      name === 'aborterror'
+    ) {
+      return 'network';
+    }
+
+    // Validation errors
+    if (
+      message.includes('invalid') ||
+      message.includes('malformed') ||
+      message.includes('validation') ||
+      message.includes('400')
+    ) {
+      return 'validation';
+    }
+
+    // Service unavailable
+    if (
+      message.includes('503') ||
+      message.includes('service unavailable') ||
+      message.includes('temporarily unavailable')
+    ) {
+      return 'service-unavailable';
+    }
+  }
+
+  // Fallback category
+  return 'unknown';
+};
+
+module.exports = { createOpenTelemetryConfig, defaultErrorClassifier };
diff --git a/src/otel/index.d.ts b/src/otel/index.d.ts
new file mode 100644
index 0000000..1cd5d89
--- /dev/null
+++ b/src/otel/index.d.ts
@@ -0,0 +1,610 @@
+// Types ported from upyo v0.7.0 (packages/opentelemetry/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/// <reference lib="esnext.disposable" />
+
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+// The parts of the OpenTelemetry API this subpath calls, as structural types:
+// the providers come from the application's own setup, and nothing here
+// imports @opentelemetry/api. Its TracerProvider and MeterProvider fit them.
+
+/** An attribute value of a span, an event or a metric. */
+export type AttributeValue =
+  | string
+  | number
+  | boolean
+  | Array<null | undefined | string>
+  | Array<null | undefined | number>
+  | Array<null | undefined | boolean>;
+
+/** Attributes of a span, an event or a metric. */
+export type Attributes = Record<string, AttributeValue | undefined>;
+
+/** A span, as `Tracer.startSpan()` of the OpenTelemetry API returns it. */
+export interface Span {
+  setAttributes(attributes: Attributes): unknown;
+  addEvent(name: string, attributes?: Attributes): unknown;
+  setStatus(status: { code: number; message?: string }): unknown;
+  end(): void;
+}
+
+/** A tracer of the OpenTelemetry API. */
+export interface Tracer {
+  startSpan(name: string, options?: { kind?: number; attributes?: Attributes }): Span;
+}
+
+/** A tracer provider of the OpenTelemetry API, such as `trace.getTracerProvider()`. */
+export interface TracerProvider {
+  getTracer(name: string, version?: string): Tracer;
+}
+
+/** The options of a metric instrument. */
+export interface MetricOptions {
+  description?: string;
+  unit?: string;
+}
+
+/** A counter, or an up-down counter, of the OpenTelemetry API. */
+export interface Counter {
+  add(value: number, attributes?: Attributes): void;
+}
+
+/** A histogram of the OpenTelemetry API. */
+export interface Histogram {
+  record(value: number, attributes?: Attributes): void;
+}
+
+/** A meter of the OpenTelemetry API. */
+export interface Meter {
+  createCounter(name: string, options?: MetricOptions): Counter;
+  createHistogram(name: string, options?: MetricOptions): Histogram;
+  createUpDownCounter(name: string, options?: MetricOptions): Counter;
+}
+
+/** A meter provider of the OpenTelemetry API, such as `metrics.getMeterProvider()`. */
+export interface MeterProvider {
+  getMeter(name: string, version?: string): Meter;
+}
+
+/**
+ * Configuration options for OpenTelemetry observability features.
+ */
+export interface ObservabilityConfig {
+  /**
+   * Whether tracing is enabled.
+   * @default true
+   */
+  readonly enabled?: boolean;
+  /**
+   * Custom sampling rate for this feature (0.0 to 1.0).
+   * @default 1.0 (sample all)
+   */
+  readonly samplingRate?: number;
+}
+/**
+ * Configuration options for metrics collection.
+ */
+export interface MetricsConfig extends ObservabilityConfig {
+  /**
+   * Custom prefix for metric names.
+   * @default "mailer"
+   */
+  readonly prefix?: string;
+  /**
+   * Custom histogram buckets for duration metrics (in seconds).
+   * @default [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0]
+   */
+  readonly durationBuckets?: readonly number[];
+}
+/**
+ * Configuration options for tracing.
+ */
+export interface TracingConfig extends ObservabilityConfig {
+  /**
+   * Whether to record sensitive information in spans.
+   * When false, email addresses and subjects are redacted.
+   * @default false
+   */
+  readonly recordSensitiveData?: boolean;
+  /**
+   * Custom span name prefix.
+   * @default "email"
+   */
+  readonly spanPrefix?: string;
+}
+/**
+ * Custom attribute extractor function type.
+ */
+export type AttributeExtractor = (
+  operation: 'send' | 'send_batch',
+  transportName: string,
+  messageCount: number,
+  totalSize?: number,
+) => Record<string, string | number | boolean>;
+/**
+ * Custom error classifier function type.
+ */
+export type ErrorClassifier = (error: unknown) => string;
+/**
+ * Configuration options for auto-setup scenarios.
+ */
+export interface AutoConfig {
+  /**
+   * Service name for OpenTelemetry resource attributes.
+   * @default "email-service"
+   */
+  readonly serviceName?: string;
+  /**
+   * Service version for OpenTelemetry resource attributes.
+   */
+  readonly serviceVersion?: string;
+  /**
+   * Tracing endpoint configuration.
+   */
+  readonly tracing?: {
+    readonly endpoint?: string;
+    readonly headers?: Record<string, string>;
+  };
+  /**
+   * Metrics endpoint configuration.
+   */
+  readonly metrics?: {
+    readonly endpoint?: string;
+    readonly headers?: Record<string, string>;
+  };
+}
+/**
+ * Configuration for the OpenTelemetry transport.
+ */
+export interface OpenTelemetryConfig {
+  /**
+   * OpenTelemetry tracer provider.
+   * Required if tracing is enabled.
+   */
+  readonly tracerProvider?: TracerProvider;
+  /**
+   * OpenTelemetry meter provider.
+   * Required if metrics are enabled.
+   */
+  readonly meterProvider?: MeterProvider;
+  /**
+   * Metrics collection configuration.
+   * @default { enabled: true }
+   */
+  readonly metrics?: MetricsConfig;
+  /**
+   * Tracing configuration.
+   * @default { enabled: true }
+   */
+  readonly tracing?: TracingConfig;
+  /**
+   * Custom attribute extractor function.
+   * Called for each operation to add custom attributes.
+   */
+  readonly attributeExtractor?: AttributeExtractor;
+  /**
+   * Custom error classifier function.
+   * Called to classify errors into categories for metrics.
+   */
+  readonly errorClassifier?: ErrorClassifier;
+  /**
+   * Auto-configuration options for simplified setup.
+   * When provided, missing providers will be auto-configured.
+   */
+  readonly auto?: AutoConfig;
+}
+/**
+ * Resolved configuration with all defaults applied.
+ */
+interface ResolvedOpenTelemetryConfig {
+  readonly tracerProvider?: TracerProvider;
+  readonly meterProvider?: MeterProvider;
+  readonly metrics: Required<MetricsConfig>;
+  readonly tracing: Required<TracingConfig>;
+  readonly attributeExtractor?: AttributeExtractor;
+  readonly errorClassifier?: ErrorClassifier;
+}
+/**
+ * Creates a resolved OpenTelemetry configuration with defaults applied.
+ *
+ * @param config The input configuration options.
+ * @returns A resolved configuration with all defaults applied.
+ * @throws {Error} When tracing is enabled but no TracerProvider is provided.
+ * @throws {Error} When metrics are enabled but no MeterProvider is provided.
+ */
+
+/**
+ * Default error classifier that categorizes errors into standard types.
+ *
+ * @example
+ * ```typescript
+ * import { defaultErrorClassifier } from "@alexify/mailer/otel";
+ *
+ * console.log(defaultErrorClassifier(new Error("401 Unauthorized"))); // "auth"
+ * console.log(defaultErrorClassifier(new Error("Rate limit exceeded"))); // "rate-limit"
+ * console.log(defaultErrorClassifier(new Error("Connection timeout"))); // "network"
+ * console.log(defaultErrorClassifier(new Error("Invalid email format"))); // "validation"
+ * console.log(defaultErrorClassifier(new Error("500 Internal Server Error"))); // "server-error"
+ * console.log(defaultErrorClassifier(new Error("Something else"))); // "unknown"
+ * ```
+ *
+ * @param error The error to classify.
+ * @returns A string category such as `"auth"`, `"rate-limit"`, `"network"`,
+ *          `"validation"`, `"service-unavailable"`, `"server-error"`, or
+ *          `"unknown"`.
+ */
+export declare function defaultErrorClassifier(error: unknown): string;
+
+/**
+ * OpenTelemetry decorator transport that adds observability to any existing transport.
+ *
+ * This transport wraps another transport implementation to provide automatic
+ * OpenTelemetry metrics and tracing without requiring changes to existing code.
+ * It follows the decorator pattern, accepting any transport and adding standardized
+ * observability features including email delivery metrics, latency histograms,
+ * error classification, and distributed tracing support.
+ *
+ * The transport also supports automatic resource cleanup by implementing
+ * AsyncDisposable and properly disposing wrapped transports that support
+ * either Disposable or AsyncDisposable interfaces.
+ *
+ * @example Basic usage with explicit providers
+ * ```typescript
+ * import { OpenTelemetryTransport } from "@alexify/mailer/otel";
+ * import { createSmtpTransport } from "@alexify/mailer/smtp";
+ * import { trace, metrics } from "@opentelemetry/api";
+ *
+ * const baseTransport = createSmtpTransport({
+ *   host: "smtp.example.com",
+ *   port: 587,
+ * });
+ *
+ * const transport = new OpenTelemetryTransport(baseTransport, {
+ *   tracerProvider: trace.getTracerProvider(),
+ *   meterProvider: metrics.getMeterProvider(),
+ *   tracing: {
+ *     enabled: true,
+ *     samplingRate: 1.0,
+ *     recordSensitiveData: false,
+ *   },
+ *   metrics: {
+ *     enabled: true,
+ *   },
+ * });
+ *
+ * // Use the transport normally - it will automatically create spans and metrics
+ * await transport.send(message);
+ * ```
+ *
+ * @example With custom error classification and attribute extraction
+ * ```typescript
+ * const transport = new OpenTelemetryTransport(baseTransport, {
+ *   tracerProvider: trace.getTracerProvider(),
+ *   meterProvider: metrics.getMeterProvider(),
+ *   errorClassifier: (error) => {
+ *     if (error.message.includes("spam")) return "spam";
+ *     if (error.message.includes("bounce")) return "bounce";
+ *     return "unknown";
+ *   },
+ *   attributeExtractor: (operation, transportName) => ({
+ *     "service.environment": process.env.NODE_ENV,
+ *     "transport.type": transportName,
+ *   }),
+ * });
+ * ```
+ */
+export declare class OpenTelemetryTransport<TProviderId extends string = string>
+  implements Transport<TProviderId>, AsyncDisposable
+{
+  readonly id: TProviderId;
+  /**
+   * The resolved OpenTelemetry configuration.
+   */
+  readonly config: ResolvedOpenTelemetryConfig;
+  /**
+   * Creates a new OpenTelemetry transport that wraps an existing transport.
+   *
+   * @param transport The base transport to wrap with observability.
+   * @param config OpenTelemetry configuration options.
+   */
+  constructor(transport: Transport<TProviderId>, config?: OpenTelemetryConfig);
+  /**
+   * Sends a single email message with OpenTelemetry observability.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including abort signal.
+   * @returns A promise that resolves to a receipt indicating success or failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
+  /**
+   * Sends multiple email messages with OpenTelemetry observability.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including abort signal.
+   * @returns An async iterable that yields receipts for each sent message.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<TProviderId>>;
+  /**
+   * Cleanup resources if the wrapped transport supports Disposable or AsyncDisposable.
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Configuration options for the createOpenTelemetryTransport factory function.
+ *
+ * This interface extends the base OpenTelemetryConfig with additional options
+ * for service identification and auto-configuration. It provides a simplified
+ * way to configure OpenTelemetry observability without manually setting up
+ * providers and exporters.
+ *
+ * @example
+ * ```typescript
+ * const config: CreateOpenTelemetryTransportConfig = {
+ *   serviceName: "email-service",
+ *   serviceVersion: "1.2.0",
+ *   tracing: {
+ *     enabled: true,
+ *     samplingRate: 0.1,
+ *     recordSensitiveData: false,
+ *   },
+ *   metrics: {
+ *     enabled: true,
+ *     histogramBoundaries: [10, 50, 100, 500, 1000],
+ *   },
+ *   auto: {
+ *     tracing: {
+ *       endpoint: "http://jaeger:14268/api/traces",
+ *     },
+ *     metrics: {
+ *       endpoint: "http://prometheus:9090/api/v1/write",
+ *     },
+ *   },
+ * };
+ * ```
+ */
+export interface CreateOpenTelemetryTransportConfig extends Omit<OpenTelemetryConfig, 'auto'> {
+  /**
+   * Service name for OpenTelemetry resource attributes.
+   * This identifies your service in distributed traces and metrics.
+   * @default "email-service"
+   */
+  readonly serviceName?: string;
+  /**
+   * Service version for OpenTelemetry resource attributes.
+   * Useful for tracking performance across different deployment versions.
+   */
+  readonly serviceVersion?: string;
+  /**
+   * Auto-configuration options for setting up OpenTelemetry exporters and processors.
+   * When provided, the factory function will automatically configure the necessary
+   * infrastructure for sending telemetry data to observability backends.
+   */
+  readonly auto?: AutoConfig;
+}
+/**
+ * Creates an OpenTelemetry transport for email operations with comprehensive
+ * observability features.
+ *
+ * This function wraps an existing email transport with OpenTelemetry tracing
+ * and metrics collection, providing automatic instrumentation for email sending
+ * operations. It supports both single message and batch operations with
+ * configurable sampling, error classification, and attribute extraction.
+ * The `tracerProvider` and `meterProvider` are passed in, from the
+ * application's OpenTelemetry setup: this package does not require
+ * `@opentelemetry/api`, so there is no fallback to its global providers.
+ *
+ * @param baseTransport The underlying email transport to wrap with
+ *                      OpenTelemetry instrumentation.
+ * @param config Configuration options for OpenTelemetry setup including
+ *               providers, sampling rates, and custom extractors.
+ * @param config.serviceName Service name for OpenTelemetry resource attributes.
+ *                           Defaults to "email-service".
+ * @param config.serviceVersion Service version for OpenTelemetry resource
+ *                              attributes.
+ * @param config.tracerProvider The TracerProvider of the application, required
+ *                              while tracing is enabled.
+ * @param config.meterProvider The MeterProvider of the application, required
+ *                             while metrics are enabled.
+ * @param config.auto Auto-configuration options for setting up exporters and
+ *                    processors.
+ * @param config.tracing Tracing configuration including sampling rates and
+ *                       span settings.
+ * @param config.metrics Metrics configuration including histogram boundaries
+ *                       and collection settings.
+ * @param config.attributeExtractor Custom function for extracting attributes
+ *                                  from operations.
+ * @param config.errorClassifier Custom function for categorizing errors into
+ *                               types.
+ * @returns An OpenTelemetry-enabled transport that instruments all email
+ *          operations with traces and metrics.
+ *
+ * @example With minimal configuration
+ * ```typescript
+ * import { createOpenTelemetryTransport } from "@alexify/mailer/otel";
+ * import { createSmtpTransport } from "@alexify/mailer/smtp";
+ *
+ * const smtpTransport = createSmtpTransport({
+ *   host: "smtp.example.com",
+ *   port: 587,
+ * });
+ *
+ * const transport = createOpenTelemetryTransport(smtpTransport, {
+ *   serviceName: "email-service",
+ *   serviceVersion: "1.0.0",
+ * });
+ * ```
+ *
+ * @example With explicit providers
+ * ```typescript
+ * import { createOpenTelemetryTransport } from "@alexify/mailer/otel";
+ * import { trace, metrics } from "@opentelemetry/api";
+ *
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   tracerProvider: trace.getTracerProvider(),
+ *   meterProvider: metrics.getMeterProvider(),
+ *   serviceName: "my-email-service",
+ *   tracing: {
+ *     enabled: true,
+ *     samplingRate: 0.1,
+ *     recordSensitiveData: false,
+ *   },
+ *   metrics: {
+ *     enabled: true,
+ *     histogramBoundaries: [10, 50, 100, 500, 1000, 5000],
+ *   },
+ * });
+ * ```
+ *
+ * @example With auto-configuration
+ * ```typescript
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   serviceName: "email-service",
+ *   auto: {
+ *     tracing: { endpoint: "http://jaeger:14268/api/traces" },
+ *     metrics: { endpoint: "http://prometheus:9090/api/v1/write" }
+ *   }
+ * });
+ * ```
+ */
+export declare function createOpenTelemetryTransport<TProviderId extends string = string>(
+  baseTransport: Transport<TProviderId>,
+  config?: CreateOpenTelemetryTransportConfig,
+): OpenTelemetryTransport<TProviderId>;
+/**
+ * Creates a custom email attribute extractor function for OpenTelemetry
+ * spans and metrics.
+ *
+ * This function creates a reusable attribute extractor that can be used to
+ * generate consistent attributes for OpenTelemetry traces and metrics across
+ * different email operations.  It supports both basic transport information
+ * and custom attribute generation based on operation context.
+ *
+ * @param transportName The name of the email transport
+ *                      (e.g., `"smtp"`, `"mailgun"`, `"sendgrid"`).
+ * @param options Configuration options for customizing attribute extraction
+ *                behavior.
+ * @param options.recordSensitiveData Whether to include sensitive data like
+ *                                    email addresses in attributes.
+ *                                    Defaults to false for security.
+ * @param options.transportVersion The version of the transport implementation
+ *                                 for better observability.
+ * @param options.customAttributes A function to generate custom attributes
+ *                                 based on operation context.
+ * @returns A function that extracts attributes from email operations,
+ *          suitable for use with OpenTelemetry spans and metrics.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createEmailAttributeExtractor } from "@alexify/mailer/otel";
+ *
+ * const extractor = createEmailAttributeExtractor("smtp", {
+ *   transportVersion: "2.1.0",
+ * });
+ *
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   attributeExtractor: extractor,
+ * });
+ * ```
+ *
+ * @example With custom attributes
+ * ```typescript
+ * import { createEmailAttributeExtractor } from "@alexify/mailer/otel";
+ *
+ * const extractor = createEmailAttributeExtractor("smtp", {
+ *   recordSensitiveData: false,
+ *   transportVersion: "2.1.0",
+ *   customAttributes: (operation, transportName, messageCount, totalSize) => ({
+ *     "service.environment": process.env.NODE_ENV || "development",
+ *     "email.batch.size": messageCount || 1,
+ *     "email.total.bytes": totalSize || 0,
+ *     "transport.type": transportName,
+ *   }),
+ * });
+ *
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   attributeExtractor: extractor,
+ * });
+ * ```
+ */
+export declare function createEmailAttributeExtractor(
+  _transportName: string,
+  options?: {
+    readonly recordSensitiveData?: boolean;
+    readonly transportVersion?: string;
+    readonly customAttributes?: (
+      operation: 'send' | 'send_batch',
+      transportName: string,
+      messageCount: number,
+      totalSize?: number,
+    ) => Record<string, string | number | boolean>;
+  },
+): AttributeExtractor;
+/**
+ * Creates a custom error classifier function for categorizing email sending
+ * errors.
+ *
+ * This function creates an error classifier that categorizes errors into
+ * meaningful groups for better observability and alerting.  It supports custom
+ * regex patterns for domain-specific error classification while falling back
+ * to the default classifier for common error types.  The classifier is used to
+ * tag metrics and traces with error categories, enabling better
+ * monitoring and debugging of email delivery issues.
+ *
+ * @param options Configuration options for error classification behavior.
+ * @param options.patterns A record of category names mapped to regex patterns
+ *                         for custom error classification.
+ * @param options.fallback The fallback category to use when no patterns match
+ *                         and the default classifier returns "unknown".
+ *                         Defaults to "unknown".
+ * @returns A function that classifies errors into string categories for use
+ *          in OpenTelemetry attributes and metrics.
+ *
+ * @example Basic usage with common patterns
+ * ```typescript
+ * import { createErrorClassifier } from "@alexify/mailer/otel";
+ *
+ * const classifier = createErrorClassifier({
+ *   patterns: {
+ *     spam: /blocked.*spam|spam.*detected/i,
+ *     bounce: /bounce|undeliverable|invalid.*recipient/i,
+ *   },
+ *   fallback: "email_error",
+ * });
+ *
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   errorClassifier: classifier,
+ * });
+ * ```
+ *
+ * @example Advanced patterns for specific email providers
+ * ```typescript
+ * import { createErrorClassifier } from "@alexify/mailer/otel";
+ *
+ * const classifier = createErrorClassifier({
+ *   patterns: {
+ *     spam: /blocked.*spam|spam.*detected|reputation/i,
+ *     bounce: /bounce|undeliverable|invalid.*recipient/i,
+ *     quota: /quota.*exceeded|mailbox.*full/i,
+ *     reputation: /reputation|blacklist|blocked.*ip/i,
+ *     temporary: /temporary.*failure|try.*again.*later/i,
+ *     authentication: /authentication.*failed|invalid.*credentials/i,
+ *   },
+ *   fallback: "email_error",
+ * });
+ *
+ * // The classifier will categorize errors like:
+ * // new Error("Message blocked as spam") -> "spam"
+ * // new Error("Mailbox quota exceeded") -> "quota"
+ * // new Error("Authentication failed") -> "auth" (from default classifier)
+ * // new Error("Unknown error") -> "email_error" (fallback)
+ * ```
+ */
+export declare function createErrorClassifier(options?: {
+  readonly patterns?: Record<string, RegExp>;
+  readonly fallback?: string;
+}): ErrorClassifier;
diff --git a/src/otel/index.js b/src/otel/index.js
new file mode 100644
index 0000000..1ac1435
--- /dev/null
+++ b/src/otel/index.js
@@ -0,0 +1,286 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { OpenTelemetryTransport } = require('./opentelemetry-transport.js');
+const { defaultErrorClassifier } = require('./config.js');
+
+/**
+ * Creates an OpenTelemetry transport for email operations with comprehensive
+ * observability features.
+ *
+ * This function wraps an existing email transport with OpenTelemetry tracing
+ * and metrics collection, providing automatic instrumentation for email sending
+ * operations. It supports both single message and batch operations with
+ * configurable sampling, error classification, and attribute extraction.
+ * The `tracerProvider` and `meterProvider` are passed in, from the
+ * application's OpenTelemetry setup: this package does not require
+ * `@opentelemetry/api`, so there is no fallback to its global providers.
+ *
+ * @param baseTransport The underlying email transport to wrap with
+ *                      OpenTelemetry instrumentation.
+ * @param config Configuration options for OpenTelemetry setup including
+ *               providers, sampling rates, and custom extractors.
+ * @param config.serviceName Service name for OpenTelemetry resource attributes.
+ *                           Defaults to "email-service".
+ * @param config.serviceVersion Service version for OpenTelemetry resource
+ *                              attributes.
+ * @param config.tracerProvider The TracerProvider of the application, required
+ *                              while tracing is enabled.
+ * @param config.meterProvider The MeterProvider of the application, required
+ *                             while metrics are enabled.
+ * @param config.auto Auto-configuration options for setting up exporters and
+ *                    processors.
+ * @param config.tracing Tracing configuration including sampling rates and
+ *                       span settings.
+ * @param config.metrics Metrics configuration including histogram boundaries
+ *                       and collection settings.
+ * @param config.attributeExtractor Custom function for extracting attributes
+ *                                  from operations.
+ * @param config.errorClassifier Custom function for categorizing errors into
+ *                               types.
+ * @returns An OpenTelemetry-enabled transport that instruments all email
+ *          operations with traces and metrics.
+ *
+ * @example With minimal configuration
+ * ```typescript
+ * import { createOpenTelemetryTransport } from "@alexify/mailer/otel";
+ * import { createSmtpTransport } from "@alexify/mailer/smtp";
+ *
+ * const smtpTransport = createSmtpTransport({
+ *   host: "smtp.example.com",
+ *   port: 587,
+ * });
+ *
+ * const transport = createOpenTelemetryTransport(smtpTransport, {
+ *   serviceName: "email-service",
+ *   serviceVersion: "1.0.0",
+ * });
+ * ```
+ *
+ * @example With explicit providers
+ * ```typescript
+ * import { createOpenTelemetryTransport } from "@alexify/mailer/otel";
+ * import { trace, metrics } from "@opentelemetry/api";
+ *
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   tracerProvider: trace.getTracerProvider(),
+ *   meterProvider: metrics.getMeterProvider(),
+ *   serviceName: "my-email-service",
+ *   tracing: {
+ *     enabled: true,
+ *     samplingRate: 0.1,
+ *     recordSensitiveData: false,
+ *   },
+ *   metrics: {
+ *     enabled: true,
+ *     histogramBoundaries: [10, 50, 100, 500, 1000, 5000],
+ *   },
+ * });
+ * ```
+ *
+ * @example With auto-configuration
+ * ```typescript
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   serviceName: "email-service",
+ *   auto: {
+ *     tracing: { endpoint: "http://jaeger:14268/api/traces" },
+ *     metrics: { endpoint: "http://prometheus:9090/api/v1/write" }
+ *   }
+ * });
+ * ```
+ */
+const createOpenTelemetryTransport = (baseTransport, config = {}) => {
+  const { serviceName = 'email-service', serviceVersion, auto, ...otherConfig } = config;
+
+  // The providers come from the application, never from a global API.
+  const finalConfig = {
+    ...otherConfig,
+    // Add auto-configuration if specified
+    ...(auto && {
+      auto: {
+        serviceName,
+        serviceVersion,
+        ...auto,
+      },
+    }),
+  };
+
+  return new OpenTelemetryTransport(baseTransport, finalConfig);
+};
+
+/**
+ * Creates a custom email attribute extractor function for OpenTelemetry
+ * spans and metrics.
+ *
+ * This function creates a reusable attribute extractor that can be used to
+ * generate consistent attributes for OpenTelemetry traces and metrics across
+ * different email operations.  It supports both basic transport information
+ * and custom attribute generation based on operation context.
+ *
+ * @param transportName The name of the email transport
+ *                      (e.g., `"smtp"`, `"mailgun"`, `"sendgrid"`).
+ * @param options Configuration options for customizing attribute extraction
+ *                behavior.
+ * @param options.recordSensitiveData Whether to include sensitive data like
+ *                                    email addresses in attributes.
+ *                                    Defaults to false for security.
+ * @param options.transportVersion The version of the transport implementation
+ *                                 for better observability.
+ * @param options.customAttributes A function to generate custom attributes
+ *                                 based on operation context.
+ * @returns A function that extracts attributes from email operations,
+ *          suitable for use with OpenTelemetry spans and metrics.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createEmailAttributeExtractor } from "@alexify/mailer/otel";
+ *
+ * const extractor = createEmailAttributeExtractor("smtp", {
+ *   transportVersion: "2.1.0",
+ * });
+ *
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   attributeExtractor: extractor,
+ * });
+ * ```
+ *
+ * @example With custom attributes
+ * ```typescript
+ * import { createEmailAttributeExtractor } from "@alexify/mailer/otel";
+ *
+ * const extractor = createEmailAttributeExtractor("smtp", {
+ *   recordSensitiveData: false,
+ *   transportVersion: "2.1.0",
+ *   customAttributes: (operation, transportName, messageCount, totalSize) => ({
+ *     "service.environment": process.env.NODE_ENV || "development",
+ *     "email.batch.size": messageCount || 1,
+ *     "email.total.bytes": totalSize || 0,
+ *     "transport.type": transportName,
+ *   }),
+ * });
+ *
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   attributeExtractor: extractor,
+ * });
+ * ```
+ */
+const createEmailAttributeExtractor = (_transportName, options = {}) => {
+  return (operation, transport, messageCount, totalSize) => {
+    // Use the EmailAttributeExtractor for base attributes
+    const baseAttributes = {
+      'operation.name': operation === 'send' ? 'email.send' : 'email.send_batch',
+      'operation.type': 'email',
+      'mailer.transport.name': transport,
+    };
+
+    // Add transport version if available
+    if (options.transportVersion) {
+      baseAttributes['mailer.transport.version'] = options.transportVersion;
+    }
+
+    // Add batch-specific attributes for batch operations
+    if (operation === 'send_batch') {
+      baseAttributes['mailer.batch.size'] = messageCount;
+      if (totalSize !== undefined) {
+        baseAttributes['email.batch.total_size'] = totalSize;
+      }
+    }
+
+    const customAttributes =
+      options.customAttributes?.(operation, transport, messageCount, totalSize) || {};
+
+    return {
+      ...baseAttributes,
+      ...customAttributes,
+    };
+  };
+};
+
+/**
+ * Creates a custom error classifier function for categorizing email sending
+ * errors.
+ *
+ * This function creates an error classifier that categorizes errors into
+ * meaningful groups for better observability and alerting.  It supports custom
+ * regex patterns for domain-specific error classification while falling back
+ * to the default classifier for common error types.  The classifier is used to
+ * tag metrics and traces with error categories, enabling better
+ * monitoring and debugging of email delivery issues.
+ *
+ * @param options Configuration options for error classification behavior.
+ * @param options.patterns A record of category names mapped to regex patterns
+ *                         for custom error classification.
+ * @param options.fallback The fallback category to use when no patterns match
+ *                         and the default classifier returns "unknown".
+ *                         Defaults to "unknown".
+ * @returns A function that classifies errors into string categories for use
+ *          in OpenTelemetry attributes and metrics.
+ *
+ * @example Basic usage with common patterns
+ * ```typescript
+ * import { createErrorClassifier } from "@alexify/mailer/otel";
+ *
+ * const classifier = createErrorClassifier({
+ *   patterns: {
+ *     spam: /blocked.*spam|spam.*detected/i,
+ *     bounce: /bounce|undeliverable|invalid.*recipient/i,
+ *   },
+ *   fallback: "email_error",
+ * });
+ *
+ * const transport = createOpenTelemetryTransport(baseTransport, {
+ *   errorClassifier: classifier,
+ * });
+ * ```
+ *
+ * @example Advanced patterns for specific email providers
+ * ```typescript
+ * import { createErrorClassifier } from "@alexify/mailer/otel";
+ *
+ * const classifier = createErrorClassifier({
+ *   patterns: {
+ *     spam: /blocked.*spam|spam.*detected|reputation/i,
+ *     bounce: /bounce|undeliverable|invalid.*recipient/i,
+ *     quota: /quota.*exceeded|mailbox.*full/i,
+ *     reputation: /reputation|blacklist|blocked.*ip/i,
+ *     temporary: /temporary.*failure|try.*again.*later/i,
+ *     authentication: /authentication.*failed|invalid.*credentials/i,
+ *   },
+ *   fallback: "email_error",
+ * });
+ *
+ * // The classifier will categorize errors like:
+ * // new Error("Message blocked as spam") -> "spam"
+ * // new Error("Mailbox quota exceeded") -> "quota"
+ * // new Error("Authentication failed") -> "auth" (from default classifier)
+ * // new Error("Unknown error") -> "email_error" (fallback)
+ * ```
+ */
+const createErrorClassifier = (options = {}) => {
+  const { patterns = {}, fallback = 'unknown' } = options;
+
+  return (error) => {
+    if (error instanceof Error) {
+      const message = error.message.toLowerCase();
+
+      // Check custom patterns first
+      for (const [category, pattern] of Object.entries(patterns)) {
+        if (pattern.test(message)) {
+          return category;
+        }
+      }
+    }
+
+    // Fall back to default classifier
+    const defaultCategory = defaultErrorClassifier(error);
+    return defaultCategory === 'unknown' ? fallback : defaultCategory;
+  };
+};
+
+module.exports = {
+  OpenTelemetryTransport,
+  defaultErrorClassifier,
+  createOpenTelemetryTransport,
+  createEmailAttributeExtractor,
+  createErrorClassifier,
+};
diff --git a/src/otel/message-size.js b/src/otel/message-size.js
new file mode 100644
index 0000000..5fc6947
--- /dev/null
+++ b/src/otel/message-size.js
@@ -0,0 +1,63 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/message-size.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const encoder = new TextEncoder();
+
+/**
+ * Counts a string in UTF-8 bytes rather than UTF-16 code units.
+ *
+ * `String.prototype.length` counts code units, which undercounts every
+ * character outside the Basic Latin block: a Korean subject is a third of its
+ * real size, an emoji a half.  The size these estimates report is in bytes, so
+ * they have to be counted that way.
+ *
+ * @param text The string to measure.
+ * @returns The number of bytes the string occupies in UTF-8.
+ */
+const utf8Length = (text) => {
+  return encoder.encode(text).length;
+};
+
+/**
+ * Estimates the wire size of a message, in bytes.
+ *
+ * This is an estimate, not a measurement: the header block is a flat guess, and
+ * an attachment contributes only its framing rather than its content, which
+ * would mean reading every attachment to report a span attribute.  What it does
+ * count, it counts in the units it claims.
+ *
+ * @param message The message to measure.
+ * @returns The estimated size in bytes.
+ */
+const estimateMessageSize = (message) => {
+  let size = 0;
+
+  // Headers estimate (rough)
+  size += 500;
+
+  // Subject
+  size += utf8Length(message.subject);
+
+  // Content
+  if ('html' in message.content) {
+    size += utf8Length(message.content.html);
+    if (message.content.text) {
+      size += utf8Length(message.content.text);
+    }
+  } else {
+    size += utf8Length(message.content.text);
+  }
+
+  // Calendar payload, which travels in full whichever way a transport
+  // carries it
+  if (message.calendar != null) {
+    size += utf8Length(message.calendar.content);
+  }
+
+  // Attachments estimate (metadata only, not content)
+  size += message.attachments.length * 100;
+
+  return size;
+};
+
+module.exports = { estimateMessageSize };
diff --git a/src/otel/metrics.js b/src/otel/metrics.js
new file mode 100644
index 0000000..3f75ac7
--- /dev/null
+++ b/src/otel/metrics.js
@@ -0,0 +1,206 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/metrics.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const metadata = require('../version.js');
+const { estimateMessageSize } = require('./message-size.js');
+
+/**
+ * Manages OpenTelemetry metrics collection for email operations.
+ */
+class MetricsCollector {
+  meter;
+  config;
+
+  // Counters
+  attemptCounter;
+  messageCounter;
+
+  // Histograms
+  durationHistogram;
+  messageSizeHistogram;
+  attachmentCountHistogram;
+
+  // Gauges (using UpDownCounter)
+  activeSendsGauge;
+
+  constructor(meterProvider, config) {
+    this.config = config;
+    this.meter = meterProvider.getMeter(metadata.name, metadata.version);
+
+    // Initialize counters
+    this.attemptCounter = this.meter.createCounter(`${config.prefix}_email_attempts_total`, {
+      description: 'Total number of email send attempts',
+      unit: '1',
+    });
+
+    this.messageCounter = this.meter.createCounter(`${config.prefix}_email_messages_total`, {
+      description: 'Total number of email messages processed',
+      unit: '1',
+    });
+
+    // Initialize histograms
+    this.durationHistogram = this.meter.createHistogram(`${config.prefix}_email_duration_seconds`, {
+      description: 'Duration of email send operations',
+      unit: 's',
+    });
+
+    this.messageSizeHistogram = this.meter.createHistogram(
+      `${config.prefix}_email_message_size_bytes`,
+      {
+        description: 'Size of email messages in bytes',
+        unit: 'By',
+      },
+    );
+
+    this.attachmentCountHistogram = this.meter.createHistogram(
+      `${config.prefix}_email_attachments_count`,
+      {
+        description: 'Number of attachments per email',
+        unit: '1',
+      },
+    );
+
+    // Initialize gauge
+    this.activeSendsGauge = this.meter.createUpDownCounter(`${config.prefix}_email_active_sends`, {
+      description: 'Number of currently active email send operations',
+      unit: '1',
+    });
+  }
+
+  /**
+   * Records the start of an email send operation.
+   */
+  recordSendStart(transport, messageCount = 1) {
+    if (!this.shouldSample()) {
+      return;
+    }
+
+    const labels = {
+      transport,
+    };
+
+    this.activeSendsGauge.add(1, labels);
+    this.messageCounter.add(messageCount, {
+      ...labels,
+      priority: 'normal', // Default, will be overridden by recordMessage if available
+    });
+  }
+
+  /**
+   * Records the completion of an email send operation.
+   */
+  recordSendComplete(transport, duration, success, errorType) {
+    if (!this.shouldSample()) {
+      return;
+    }
+
+    const labels = {
+      transport,
+      status: success ? 'success' : 'failure',
+      ...(errorType && { error_type: errorType }),
+    };
+
+    this.activeSendsGauge.add(-1, { transport });
+    this.attemptCounter.add(1, labels);
+    this.durationHistogram.record(duration, labels);
+  }
+
+  /**
+   * Records metrics for individual messages.
+   */
+  recordMessage(message, transport) {
+    if (!this.shouldSample()) {
+      return;
+    }
+
+    const labels = {
+      transport,
+      priority: message.priority,
+      content_type: this.getContentType(message),
+    };
+
+    const messageSize = estimateMessageSize(message);
+    this.messageSizeHistogram.record(messageSize, labels);
+    this.attachmentCountHistogram.record(message.attachments.length, labels);
+  }
+
+  /**
+   * Records metrics for batch operations.
+   */
+  recordBatch(messages, transport, duration, successCount, failureCount) {
+    if (!this.shouldSample()) {
+      return;
+    }
+
+    // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+    const _totalMessages = messages.length;
+    const labels = { transport };
+
+    // Record batch-level metrics
+    this.attemptCounter.add(1, {
+      ...labels,
+      status: failureCount === 0 ? 'success' : 'partial_failure',
+      operation: 'batch',
+    });
+
+    this.durationHistogram.record(duration, {
+      ...labels,
+      operation: 'batch',
+    });
+
+    // Record individual message metrics
+    for (const message of messages) {
+      this.recordMessage(message, transport);
+    }
+
+    // Record success/failure breakdown
+    if (successCount > 0) {
+      this.messageCounter.add(successCount, {
+        ...labels,
+        status: 'success',
+      });
+    }
+
+    if (failureCount > 0) {
+      this.messageCounter.add(failureCount, {
+        ...labels,
+        status: 'failure',
+      });
+    }
+  }
+
+  /**
+   * Records an error for metrics classification.
+   */
+  recordError(transport, errorType, operation = 'send') {
+    if (!this.shouldSample()) {
+      return;
+    }
+
+    this.attemptCounter.add(1, {
+      transport,
+      status: 'failure',
+      error_type: errorType,
+      operation,
+    });
+  }
+
+  shouldSample() {
+    return Math.random() < this.config.samplingRate;
+  }
+
+  getContentType(message) {
+    // A calendar is a second body part wherever it goes: an alternative beside
+    // the text and HTML on the transports that compose one, and a synthesized
+    // invite.ics attachment on the rest.
+    if (message.calendar != null) {
+      return 'multipart';
+    }
+    if ('html' in message.content) {
+      return message.content.text ? 'multipart' : 'html';
+    }
+    return 'text';
+  }
+}
+
+module.exports = { MetricsCollector };
diff --git a/src/otel/opentelemetry-transport.js b/src/otel/opentelemetry-transport.js
new file mode 100644
index 0000000..ae6e604
--- /dev/null
+++ b/src/otel/opentelemetry-transport.js
@@ -0,0 +1,386 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/opentelemetry-transport.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createOpenTelemetryConfig, defaultErrorClassifier } = require('./config.js');
+const { MetricsCollector } = require('./metrics.js');
+const { TracingCollector } = require('./tracing.js');
+const { estimateMessageSize } = require('./message-size.js');
+
+/**
+ * OpenTelemetry decorator transport that adds observability to any existing transport.
+ *
+ * This transport wraps another transport implementation to provide automatic
+ * OpenTelemetry metrics and tracing without requiring changes to existing code.
+ * It follows the decorator pattern, accepting any transport and adding standardized
+ * observability features including email delivery metrics, latency histograms,
+ * error classification, and distributed tracing support.
+ *
+ * The transport also supports automatic resource cleanup by implementing
+ * AsyncDisposable and properly disposing wrapped transports that support
+ * either Disposable or AsyncDisposable interfaces.
+ *
+ * @example Basic usage with explicit providers
+ * ```typescript
+ * import { OpenTelemetryTransport } from "@alexify/mailer/otel";
+ * import { createSmtpTransport } from "@alexify/mailer/smtp";
+ * import { trace, metrics } from "@opentelemetry/api";
+ *
+ * const baseTransport = createSmtpTransport({
+ *   host: "smtp.example.com",
+ *   port: 587,
+ * });
+ *
+ * const transport = new OpenTelemetryTransport(baseTransport, {
+ *   tracerProvider: trace.getTracerProvider(),
+ *   meterProvider: metrics.getMeterProvider(),
+ *   tracing: {
+ *     enabled: true,
+ *     samplingRate: 1.0,
+ *     recordSensitiveData: false,
+ *   },
+ *   metrics: {
+ *     enabled: true,
+ *   },
+ * });
+ *
+ * // Use the transport normally - it will automatically create spans and metrics
+ * await transport.send(message);
+ * ```
+ *
+ * @example With custom error classification and attribute extraction
+ * ```typescript
+ * const transport = new OpenTelemetryTransport(baseTransport, {
+ *   tracerProvider: trace.getTracerProvider(),
+ *   meterProvider: metrics.getMeterProvider(),
+ *   errorClassifier: (error) => {
+ *     if (error.message.includes("spam")) return "spam";
+ *     if (error.message.includes("bounce")) return "bounce";
+ *     return "unknown";
+ *   },
+ *   attributeExtractor: (operation, transportName) => ({
+ *     "service.environment": process.env.NODE_ENV,
+ *     "transport.type": transportName,
+ *   }),
+ * });
+ * ```
+ */
+class OpenTelemetryTransport {
+  id;
+
+  /**
+   * The resolved OpenTelemetry configuration.
+   */
+  config;
+
+  wrappedTransport;
+  metricsCollector;
+  tracingCollector;
+  transportName;
+  transportVersion;
+
+  /**
+   * Creates a new OpenTelemetry transport that wraps an existing transport.
+   *
+   * @param transport The base transport to wrap with observability.
+   * @param config OpenTelemetry configuration options.
+   */
+  constructor(transport, config = {}) {
+    this.wrappedTransport = transport;
+    this.id = transport.id;
+    this.config = createOpenTelemetryConfig(config);
+
+    // Extract transport information
+    this.transportName = this.extractTransportName(transport);
+    this.transportVersion = this.extractTransportVersion(transport);
+
+    // Initialize collectors based on configuration
+    if (this.config.metrics.enabled && this.config.meterProvider) {
+      this.metricsCollector = new MetricsCollector(this.config.meterProvider, this.config.metrics);
+    }
+
+    if (this.config.tracing.enabled && this.config.tracerProvider) {
+      this.tracingCollector = new TracingCollector(
+        this.config.tracerProvider,
+        this.config.tracing,
+        this.transportName,
+        this.transportVersion,
+      );
+    }
+  }
+
+  /**
+   * Sends a single email message with OpenTelemetry observability.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including abort signal.
+   * @returns A promise that resolves to a receipt indicating success or failure.
+   */
+  async send(message, options) {
+    const startTime = performance.now();
+
+    // Create span if tracing is enabled
+    const span = this.tracingCollector?.createSendSpan(message, this.extractNetworkAttributes());
+
+    // Record metrics start
+    this.metricsCollector?.recordSendStart(this.transportName, 1);
+    this.metricsCollector?.recordMessage(message, this.transportName);
+
+    try {
+      // Apply custom attributes if configured
+      if (this.config.attributeExtractor && span) {
+        const customAttributes = this.config.attributeExtractor(
+          'send',
+          this.transportName,
+          1,
+          estimateMessageSize(message),
+        );
+        span.setAttributes(customAttributes);
+      }
+
+      // Delegate to wrapped transport
+      const receipt = await this.wrappedTransport.send(message, options);
+      const duration = (performance.now() - startTime) / 1000; // Convert to seconds
+
+      // Record success/failure
+      if (receipt.successful) {
+        span?.recordSuccess(receipt.messageId);
+        this.metricsCollector?.recordSendComplete(this.transportName, duration, true);
+      } else {
+        const errorCategory = this.classifyReceipt(receipt);
+        span?.recordFailure(receipt.errorMessages);
+        this.metricsCollector?.recordSendComplete(
+          this.transportName,
+          duration,
+          false,
+          errorCategory,
+        );
+      }
+
+      return receipt;
+    } catch (error) {
+      const duration = (performance.now() - startTime) / 1000;
+      const errorCategory = this.classifyError(error);
+
+      span?.recordError(error, errorCategory);
+      this.metricsCollector?.recordSendComplete(this.transportName, duration, false, errorCategory);
+
+      throw error;
+    } finally {
+      span?.end();
+    }
+  }
+
+  /**
+   * Sends multiple email messages with OpenTelemetry observability.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including abort signal.
+   * @returns An async iterable that yields receipts for each sent message.
+   */
+  async *sendMany(messages, options) {
+    const startTime = performance.now();
+    const messageArray = [];
+
+    // Collect messages for batch metrics
+    for await (const message of messages) {
+      messageArray.push(message);
+    }
+
+    const batchSize = messageArray.length;
+
+    // Create batch span if tracing is enabled
+    const span = this.tracingCollector?.createBatchSpan(
+      messageArray,
+      batchSize,
+      this.extractNetworkAttributes(),
+    );
+
+    // Record batch start
+    this.metricsCollector?.recordSendStart(this.transportName, batchSize);
+
+    let successCount = 0;
+    let failureCount = 0;
+    const receipts = [];
+
+    try {
+      // Apply custom attributes if configured
+      if (this.config.attributeExtractor && span) {
+        const totalSize = messageArray.reduce((sum, msg) => sum + estimateMessageSize(msg), 0);
+        const customAttributes = this.config.attributeExtractor(
+          'send_batch',
+          this.transportName,
+          batchSize,
+          totalSize,
+        );
+        span.setAttributes(customAttributes);
+      }
+
+      // Delegate to wrapped transport
+      for await (const receipt of this.wrappedTransport.sendMany(messageArray, options)) {
+        receipts.push(receipt);
+
+        if (receipt.successful) {
+          successCount++;
+        } else {
+          failureCount++;
+        }
+
+        yield receipt;
+      }
+
+      const duration = (performance.now() - startTime) / 1000;
+
+      // Record batch completion
+      this.metricsCollector?.recordBatch(
+        messageArray,
+        this.transportName,
+        duration,
+        successCount,
+        failureCount,
+      );
+
+      // Update span based on results
+      if (failureCount === 0) {
+        span?.recordSuccess();
+      } else if (successCount > 0) {
+        span?.addEvent('partial_success', {
+          success_count: successCount,
+          failure_count: failureCount,
+        });
+      } else {
+        const allErrorMessages = receipts
+          .filter((r) => !r.successful)
+          .flatMap((r) => r.errorMessages);
+        span?.recordFailure(allErrorMessages);
+      }
+    } catch (error) {
+      // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+      const _duration = (performance.now() - startTime) / 1000;
+      const errorCategory = this.classifyError(error);
+
+      span?.recordError(error, errorCategory);
+      this.metricsCollector?.recordError(this.transportName, errorCategory, 'send_batch');
+
+      throw error;
+    } finally {
+      span?.end();
+    }
+  }
+
+  /**
+   * Cleanup resources if the wrapped transport supports Disposable or AsyncDisposable.
+   */
+  async [Symbol.asyncDispose]() {
+    if (!this.wrappedTransport) {
+      return;
+    }
+
+    // Try AsyncDisposable first
+    if (typeof this.wrappedTransport[Symbol.asyncDispose] === 'function') {
+      await this.wrappedTransport[Symbol.asyncDispose]();
+      return;
+    }
+
+    // Fall back to synchronous Disposable
+    if (typeof this.wrappedTransport[Symbol.dispose] === 'function') {
+      this.wrappedTransport[Symbol.dispose]();
+    }
+  }
+
+  extractTransportName(transport) {
+    if (typeof transport.id === 'string' && transport.id !== '') {
+      return transport.id;
+    }
+
+    // Try to extract from constructor name
+    const constructorName = transport.constructor?.name;
+    if (constructorName && constructorName !== 'Object') {
+      return constructorName.toLowerCase().replace('transport', '');
+    }
+
+    // Try to extract from config if available
+    if ('config' in transport && transport.config && typeof transport.config === 'object') {
+      // Check for common config properties that might indicate transport type
+      if ('domain' in transport.config) return 'mailgun';
+      if ('apiKey' in transport.config && 'region' in transport.config) {
+        return 'sendgrid';
+      }
+      if ('accessKeyId' in transport.config) return 'ses';
+      if ('host' in transport.config) return 'smtp';
+    }
+
+    return 'unknown';
+  }
+
+  extractTransportVersion(transport) {
+    // Try to extract version from config or transport properties
+    if ('config' in transport && transport.config && typeof transport.config === 'object') {
+      if ('version' in transport.config) {
+        return String(transport.config.version);
+      }
+    }
+    return undefined;
+  }
+
+  extractNetworkAttributes() {
+    const transport = this.wrappedTransport;
+
+    if ('config' in transport && transport.config && typeof transport.config === 'object') {
+      const config = transport.config;
+
+      // SMTP transport
+      if ('host' in config && 'port' in config) {
+        return {
+          'network.protocol.name': 'smtp',
+          'server.address': String(config.host),
+          'server.port': Number(config.port),
+        };
+      }
+
+      // HTTP-based transports
+      if ('baseUrl' in config || 'endpoint' in config || 'domain' in config) {
+        const url =
+          config.baseUrl ||
+          config.endpoint ||
+          (config.domain && `https://api.${config.region === 'eu' ? 'eu.' : ''}mailgun.net`);
+
+        if (url && typeof url === 'string') {
+          try {
+            const parsedUrl = new URL(url);
+            return {
+              'network.protocol.name': parsedUrl.protocol.replace(':', ''),
+              'server.address': parsedUrl.hostname,
+              ...(parsedUrl.port && { 'server.port': parseInt(parsedUrl.port) }),
+            };
+          } catch {
+            // Invalid URL, skip network attributes
+          }
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  classifyError(error) {
+    const classifier = this.config.errorClassifier || defaultErrorClassifier;
+    return classifier(error);
+  }
+
+  classifyReceipt(receipt) {
+    const structuredCategory = receipt.errors?.[0]?.category;
+    if (structuredCategory != null) return structuredCategory;
+    return this.classifyErrors(receipt.errorMessages);
+  }
+
+  classifyErrors(errorMessages) {
+    // Use first error message to determine category
+    if (errorMessages.length === 0) return 'unknown';
+
+    // Create a synthetic error for classification
+    const syntheticError = new Error(errorMessages[0]);
+    return this.classifyError(syntheticError);
+  }
+}
+
+module.exports = { OpenTelemetryTransport };
diff --git a/src/otel/tracing.js b/src/otel/tracing.js
new file mode 100644
index 0000000..cb8713f
--- /dev/null
+++ b/src/otel/tracing.js
@@ -0,0 +1,188 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/tracing.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+// SpanKind.CLIENT and SpanStatusCode.OK and ERROR of the OpenTelemetry API:
+// the providers are passed in, and @opentelemetry/api is never required.
+const SPAN_KIND_CLIENT = 2;
+const SPAN_STATUS_OK = 1;
+const SPAN_STATUS_ERROR = 2;
+const { EmailAttributeExtractor } = require('./attributes.js');
+const metadata = require('../version.js');
+
+/**
+ * Manages OpenTelemetry tracing for email operations.
+ */
+class TracingCollector {
+  tracer;
+  config;
+  attributeExtractor;
+
+  constructor(tracerProvider, config, transportName, transportVersion) {
+    this.config = config;
+    this.tracer = tracerProvider.getTracer(metadata.name, metadata.version);
+    this.attributeExtractor = new EmailAttributeExtractor(
+      transportName,
+      config.recordSensitiveData,
+      transportVersion,
+    );
+  }
+
+  /**
+   * Creates a span for a single email send operation.
+   */
+  createSendSpan(message, networkAttributes) {
+    if (!this.shouldSample()) {
+      return new NoOpEmailSpan();
+    }
+
+    const spanName = `${this.config.spanPrefix} send`;
+    const span = this.tracer.startSpan(spanName, {
+      kind: SPAN_KIND_CLIENT,
+    });
+
+    // Set message attributes
+    const messageAttributes = this.attributeExtractor.extractMessageAttributes(message);
+    span.setAttributes(messageAttributes);
+
+    // Set network attributes if provided
+    if (networkAttributes) {
+      span.setAttributes(networkAttributes);
+    }
+
+    return new LiveEmailSpan(span, this.attributeExtractor);
+  }
+
+  /**
+   * Creates a span for a batch email send operation.
+   */
+  createBatchSpan(messages, batchSize, networkAttributes) {
+    if (!this.shouldSample()) {
+      return new NoOpEmailSpan();
+    }
+
+    const spanName = `${this.config.spanPrefix} send_batch`;
+    const span = this.tracer.startSpan(spanName, {
+      kind: SPAN_KIND_CLIENT,
+    });
+
+    // Set batch attributes
+    const batchAttributes = this.attributeExtractor.extractBatchAttributes(messages, batchSize);
+    span.setAttributes(batchAttributes);
+
+    // Set network attributes if provided
+    if (networkAttributes) {
+      span.setAttributes(networkAttributes);
+    }
+
+    return new LiveEmailSpan(span, this.attributeExtractor);
+  }
+
+  shouldSample() {
+    return Math.random() < this.config.samplingRate;
+  }
+}
+
+/**
+ * Live implementation of EmailSpan that delegates to OpenTelemetry Span.
+ */
+class LiveEmailSpan {
+  span;
+  attributeExtractor;
+
+  constructor(span, attributeExtractor) {
+    this.span = span;
+    this.attributeExtractor = attributeExtractor;
+  }
+
+  addEvent(name, attributes) {
+    this.span.addEvent(name, attributes);
+  }
+
+  setAttributes(attributes) {
+    this.span.setAttributes(attributes);
+  }
+
+  recordError(error, errorCategory) {
+    // Set span status to error
+    this.span.setStatus({
+      code: SPAN_STATUS_ERROR,
+      message: error instanceof Error ? error.message : 'Unknown error',
+    });
+
+    // Record error attributes
+    const errorAttributes = this.attributeExtractor.extractErrorAttributes(error, errorCategory);
+    this.span.setAttributes(errorAttributes);
+
+    // Add error event
+    this.span.addEvent('exception', {
+      'exception.type': error instanceof Error ? error.constructor.name : 'unknown',
+      'exception.message': error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  // Dead upstream: nothing calls recordRetry (CLAUDE.md, known upstream bugs).
+  /* c8 ignore start */
+  recordRetry(attempt, reason) {
+    this.span.setAttributes({
+      'mailer.retry.count': attempt,
+    });
+
+    this.span.addEvent('retry', {
+      'retry.attempt': attempt,
+      ...(reason && { 'retry.reason': reason }),
+    });
+  }
+  /* c8 ignore stop */
+
+  recordSuccess(messageId) {
+    this.span.setStatus({ code: SPAN_STATUS_OK });
+
+    if (messageId) {
+      this.span.setAttributes({
+        'mailer.message.id': messageId,
+      });
+    }
+
+    this.span.addEvent('email.sent', {
+      ...(messageId && { 'message.id': messageId }),
+    });
+  }
+
+  recordFailure(errorMessages) {
+    this.span.setStatus({
+      code: SPAN_STATUS_ERROR,
+      message: errorMessages[0] || 'Send failed',
+    });
+
+    this.span.setAttributes({
+      'email.error.count': errorMessages.length,
+    });
+
+    this.span.addEvent('email.send_failed', {
+      'error.count': errorMessages.length,
+      'error.messages': JSON.stringify(errorMessages),
+    });
+  }
+
+  end() {
+    this.span.end();
+  }
+}
+
+/**
+ * No-op implementation for when sampling is disabled.
+ */
+class NoOpEmailSpan {
+  addEvent() {}
+  setAttributes() {}
+  recordError() {}
+  // Dead upstream: nothing calls recordRetry.
+  /* c8 ignore start */
+  recordRetry() {}
+  /* c8 ignore stop */
+  recordSuccess() {}
+  recordFailure() {}
+  end() {}
+}
+
+module.exports = { TracingCollector };
diff --git a/src/pool/index.d.ts b/src/pool/index.d.ts
index 4e40ca1..4e162f1 100644
--- a/src/pool/index.d.ts
+++ b/src/pool/index.d.ts
@@ -1,6 +1,8 @@
 // Types ported from upyo v0.7.0 (packages/pool/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+/// <reference lib="esnext.disposable" />
+
 import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
diff --git a/tests/helpers/otel/mock-otel-providers.js b/tests/helpers/otel/mock-otel-providers.js
new file mode 100644
index 0000000..7783eff
--- /dev/null
+++ b/tests/helpers/otel/mock-otel-providers.js
@@ -0,0 +1,329 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/test-utils/mock-otel-providers.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Mock implementation of OpenTelemetry Span for testing.
+ */
+class MockSpan {
+  events = [];
+  attributes = {};
+  status;
+  ended = false;
+  name = '';
+
+  spanContext() {
+    return {
+      traceId: 'mock-trace-id',
+      spanId: 'mock-span-id',
+      traceFlags: 1,
+    };
+  }
+
+  setAttribute(key, value) {
+    this.attributes[key] = value;
+    return this;
+  }
+
+  setAttributes(attributes) {
+    Object.assign(this.attributes, attributes);
+    return this;
+  }
+
+  addEvent(name, attributesOrStartTime, startTime) {
+    this.events.push({
+      name,
+      attributes:
+        typeof attributesOrStartTime === 'object' && attributesOrStartTime !== null
+          ? attributesOrStartTime
+          : undefined,
+      timestamp: typeof attributesOrStartTime === 'number' ? attributesOrStartTime : startTime,
+    });
+    return this;
+  }
+
+  setStatus(status) {
+    this.status = status;
+    return this;
+  }
+
+  updateName(name) {
+    this.attributes['span.name'] = name;
+    return this;
+  }
+
+  end(endTime) {
+    this.ended = true;
+    if (endTime) {
+      this.attributes['span.end_time'] = endTime;
+    }
+  }
+
+  isRecording() {
+    return !this.ended;
+  }
+
+  recordException(exception, time) {
+    const errorLike = exception;
+    this.addEvent(
+      'exception',
+      {
+        'exception.type': errorLike?.constructor?.name || 'unknown',
+        'exception.message': errorLike?.message || String(exception),
+      },
+      time,
+    );
+  }
+
+  addLink() {
+    return this;
+  }
+
+  addLinks() {
+    return this;
+  }
+}
+
+/**
+ * Mock implementation of OpenTelemetry Tracer for testing.
+ */
+class MockTracer {
+  spans = [];
+
+  startSpan(name, options) {
+    const span = new MockSpan();
+    span.name = name;
+    span.attributes['span.name'] = name;
+    if (options?.kind !== undefined) {
+      span.attributes['span.kind'] = options.kind;
+    }
+    this.spans.push(span);
+    return span;
+  }
+
+  startActiveSpan(name, optionsOrFn, contextOrFn, fn) {
+    const actualFn =
+      typeof optionsOrFn === 'function'
+        ? optionsOrFn
+        : typeof contextOrFn === 'function'
+          ? contextOrFn
+          : fn;
+    const span = this.startSpan(name, typeof optionsOrFn === 'object' ? optionsOrFn : undefined);
+    return actualFn(span);
+  }
+
+  /**
+   * Test helper to get the last created span.
+   */
+  getLastSpan() {
+    return this.spans[this.spans.length - 1];
+  }
+
+  /**
+   * Test helper to clear all spans.
+   */
+  clearSpans() {
+    this.spans.length = 0;
+  }
+}
+
+/**
+ * Mock implementation of OpenTelemetry TracerProvider for testing.
+ */
+class MockTracerProvider {
+  tracers = [];
+
+  getTracer(_name, _version) {
+    const tracer = new MockTracer();
+    this.tracers.push(tracer);
+    return tracer;
+  }
+
+  /**
+   * Test helper to get all spans from all tracers.
+   */
+  getAllSpans() {
+    return this.tracers.flatMap((tracer) => tracer.spans);
+  }
+
+  /**
+   * Test helper to clear all tracers and spans.
+   */
+  clear() {
+    this.tracers.forEach((tracer) => tracer.clearSpans());
+    this.tracers.length = 0;
+  }
+}
+
+class MockMetricInstrument {
+  records = [];
+
+  record(value, attributes) {
+    this.records.push({ value, attributes });
+  }
+
+  /**
+   * Test helper to get total recorded value.
+   */
+  getTotalValue() {
+    return this.records.reduce((sum, record) => sum + record.value, 0);
+  }
+
+  /**
+   * Test helper to clear all records.
+   */
+  clear() {
+    this.records.length = 0;
+  }
+}
+
+/**
+ * Mock implementation of OpenTelemetry Counter for testing.
+ */
+class MockCounter extends MockMetricInstrument {
+  add(value, attributes) {
+    this.record(value, attributes);
+  }
+}
+
+/**
+ * Mock implementation of OpenTelemetry UpDownCounter for testing.
+ */
+class MockUpDownCounter extends MockMetricInstrument {
+  add(value, attributes) {
+    this.record(value, attributes);
+  }
+}
+
+/**
+ * Mock implementation of OpenTelemetry Histogram for testing.
+ */
+class MockHistogram extends MockMetricInstrument {
+  record(value, attributes) {
+    super.record(value, attributes);
+  }
+}
+
+/**
+ * Mock implementation of OpenTelemetry Meter for testing.
+ */
+class MockMeter {
+  counters = [];
+  upDownCounters = [];
+  histograms = [];
+
+  createCounter(_name, _options) {
+    const counter = new MockCounter();
+    this.counters.push(counter);
+    return counter;
+  }
+
+  createUpDownCounter(_name, _options) {
+    const upDownCounter = new MockUpDownCounter();
+    this.upDownCounters.push(upDownCounter);
+    return upDownCounter;
+  }
+
+  createHistogram(_name, _options) {
+    const histogram = new MockHistogram();
+    this.histograms.push(histogram);
+    return histogram;
+  }
+
+  createObservableCounter(_name, _options) {
+    throw new Error('Observable instruments not implemented in mock');
+  }
+
+  createObservableUpDownCounter(_name, _options) {
+    throw new Error('Observable instruments not implemented in mock');
+  }
+
+  createObservableGauge(_name, _options) {
+    throw new Error('Observable instruments not implemented in mock');
+  }
+
+  createGauge(_name, _options) {
+    throw new Error('Gauge not implemented in mock');
+  }
+
+  addBatchObservableCallback(_callback, _observables) {
+    throw new Error('Observable instruments not implemented in mock');
+  }
+
+  removeBatchObservableCallback(_callback) {
+    throw new Error('Observable instruments not implemented in mock');
+  }
+
+  /**
+   * Test helper to clear all metric instruments.
+   */
+  clear() {
+    this.counters.forEach((c) => c.clear());
+    this.upDownCounters.forEach((c) => c.clear());
+    this.histograms.forEach((c) => c.clear());
+    this.counters.length = 0;
+    this.upDownCounters.length = 0;
+    this.histograms.length = 0;
+  }
+}
+
+/**
+ * Mock implementation of OpenTelemetry MeterProvider for testing.
+ */
+class MockMeterProvider {
+  meters = [];
+
+  getMeter(_name, _version, _options) {
+    const meter = new MockMeter();
+    this.meters.push(meter);
+    return meter;
+  }
+
+  /**
+   * Test helper to get all metric records from all meters.
+   */
+  getAllRecords() {
+    const allRecords = [];
+
+    this.meters.forEach((meter) => {
+      meter.counters.forEach((counter) => {
+        allRecords.push({
+          instrument: 'counter',
+          records: [...counter.records],
+        });
+      });
+      meter.upDownCounters.forEach((upDownCounter) => {
+        allRecords.push({
+          instrument: 'upDownCounter',
+          records: [...upDownCounter.records],
+        });
+      });
+      meter.histograms.forEach((histogram) => {
+        allRecords.push({
+          instrument: 'histogram',
+          records: [...histogram.records],
+        });
+      });
+    });
+
+    return allRecords;
+  }
+
+  /**
+   * Test helper to clear all meters and their instruments.
+   */
+  clear() {
+    this.meters.forEach((meter) => meter.clear());
+    this.meters.length = 0;
+  }
+}
+
+module.exports = {
+  MockSpan,
+  MockTracer,
+  MockTracerProvider,
+  MockCounter,
+  MockUpDownCounter,
+  MockHistogram,
+  MockMeter,
+  MockMeterProvider,
+};
diff --git a/tests/helpers/otel/test-config.js b/tests/helpers/otel/test-config.js
new file mode 100644
index 0000000..f696d27
--- /dev/null
+++ b/tests/helpers/otel/test-config.js
@@ -0,0 +1,235 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/test-utils/test-config.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { MockMeterProvider, MockTracerProvider } = require('./mock-otel-providers.js');
+
+/**
+ * Mock transport implementation for testing OpenTelemetry integration.
+ */
+class MockTransport {
+  id = 'mock';
+
+  sentMessages = [];
+  nextReceipt = null;
+  shouldThrow = null;
+  delay = 0;
+  messageIdCounter = 1;
+
+  /**
+   * Configures the next receipt to be returned.
+   */
+  setNextReceipt(receipt) {
+    this.nextReceipt = receipt;
+  }
+
+  /**
+   * Configures the transport to throw an error on the next send.
+   */
+  setThrowError(error) {
+    this.shouldThrow = error;
+  }
+
+  /**
+   * Sets a delay for send operations (useful for testing timeouts).
+   */
+  setDelay(ms) {
+    this.delay = ms;
+  }
+
+  async send(message, options) {
+    // Check for abort signal
+    if (options?.signal?.aborted) {
+      throw new DOMException('The operation was aborted.', 'AbortError');
+    }
+
+    // Simulate delay
+    if (this.delay > 0) {
+      await new Promise((resolve) => setTimeout(resolve, this.delay));
+    }
+
+    // Check for abort signal after delay
+    if (options?.signal?.aborted) {
+      throw new DOMException('The operation was aborted.', 'AbortError');
+    }
+
+    // Throw configured error if set
+    if (this.shouldThrow) {
+      const error = this.shouldThrow;
+      this.shouldThrow = null; // Reset for next call
+      throw error;
+    }
+
+    this.sentMessages.push(message);
+
+    // Return configured receipt or default success
+    if (this.nextReceipt) {
+      const receipt = this.nextReceipt;
+      this.nextReceipt = null; // Reset for next call
+      return receipt;
+    }
+
+    return {
+      successful: true,
+      messageId: `test-msg-${this.messageIdCounter++}`,
+      provider: 'mock',
+    };
+  }
+
+  async *sendMany(messages, options) {
+    for await (const message of messages) {
+      yield await this.send(message, options);
+    }
+  }
+
+  /**
+   * Resets the transport state for the next test.
+   */
+  reset() {
+    this.sentMessages.length = 0;
+    this.nextReceipt = null;
+    this.shouldThrow = null;
+    this.delay = 0;
+    this.messageIdCounter = 1;
+  }
+}
+
+/**
+ * Creates a complete test setup with mock providers and transport.
+ */
+const createTestSetup = () => {
+  const tracerProvider = new MockTracerProvider();
+  const meterProvider = new MockMeterProvider();
+  const mockTransport = new MockTransport();
+
+  const config = {
+    tracerProvider,
+    meterProvider,
+    metrics: { enabled: true },
+    tracing: { enabled: true },
+  };
+
+  return {
+    mockTransport,
+    tracerProvider,
+    meterProvider,
+    config,
+  };
+};
+
+/**
+ * Creates a test message for testing purposes.
+ */
+const createTestMessage = (overrides = {}) => {
+  return {
+    sender: { address: 'sender@example.com' },
+    recipients: [
+      { address: 'recipient1@example.com' },
+      { address: 'recipient2@example.com' },
+      { address: 'recipient3@example.com' },
+    ],
+    ccRecipients: [],
+    bccRecipients: [],
+    replyRecipients: [],
+    subject: 'Test Subject',
+    content: { text: 'Test body content' },
+    priority: 'normal',
+    attachments: [
+      {
+        inline: false,
+        filename: 'test1.txt',
+        content: Promise.resolve(new Uint8Array([1, 2, 3])),
+        contentType: 'text/plain',
+        contentId: 'test1@example.com',
+      },
+      {
+        inline: false,
+        filename: 'test2.txt',
+        content: Promise.resolve(new Uint8Array([4, 5, 6])),
+        contentType: 'text/plain',
+        contentId: 'test2@example.com',
+      },
+    ],
+    tags: [],
+    headers: new Headers(),
+    ...overrides,
+  };
+};
+
+/**
+ * Utility functions for test assertions.
+ */
+const assertions = {
+  /**
+   * Asserts that a span with the given name exists and returns it.
+   */
+  hasSpan(spans, name, attributes) {
+    const span = spans.find((s) => s.name === name);
+    if (!span) {
+      throw new Error(`Expected span with name '${name}' not found`);
+    }
+
+    if (attributes) {
+      for (const [key, expectedValue] of Object.entries(attributes)) {
+        const actualValue = span.attributes[key];
+        if (actualValue !== expectedValue) {
+          throw new Error(
+            `Expected span attribute '${key}' to be '${expectedValue}', got '${actualValue}'`,
+          );
+        }
+      }
+    }
+
+    return span;
+  },
+
+  /**
+   * Asserts that a metric with the given name exists and optionally checks the count.
+   */
+  hasMetric(metrics, instrumentType, expectedCount) {
+    const matchingMetrics = metrics.filter((m) => m.instrument === instrumentType);
+    if (matchingMetrics.length === 0) {
+      throw new Error(
+        `Expected metric of type '${instrumentType}' not found. Available types: ${metrics
+          .map((m) => m.instrument)
+          .join(', ')}`,
+      );
+    }
+
+    if (expectedCount !== undefined) {
+      const totalCount = matchingMetrics.reduce((sum, metric) => {
+        return sum + metric.records.length;
+      }, 0);
+
+      if (totalCount !== expectedCount) {
+        throw new Error(
+          `Expected ${expectedCount} metric records for '${instrumentType}', but found ${totalCount}`,
+        );
+      }
+    }
+
+    return matchingMetrics[0];
+  },
+};
+
+/**
+ * Extracts all spans from a mock tracer provider.
+ */
+const extractSpans = (tracerProvider) => {
+  return tracerProvider.getAllSpans();
+};
+
+/**
+ * Extracts all metrics from a mock meter provider.
+ */
+const extractMetrics = (meterProvider) => {
+  return meterProvider.getAllRecords();
+};
+
+module.exports = {
+  MockTransport,
+  createTestSetup,
+  createTestMessage,
+  assertions,
+  extractSpans,
+  extractMetrics,
+};
diff --git a/tests/types/otel.test-d.ts b/tests/types/otel.test-d.ts
new file mode 100644
index 0000000..6090597
--- /dev/null
+++ b/tests/types/otel.test-d.ts
@@ -0,0 +1,41 @@
+import { metrics, trace } from '@opentelemetry/api';
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import { MockTransport } from '../../src/mock/index.js';
+import {
+  OpenTelemetryTransport,
+  createEmailAttributeExtractor,
+  createErrorClassifier,
+  createOpenTelemetryTransport,
+  defaultErrorClassifier,
+  type MeterProvider,
+  type OpenTelemetryConfig,
+  type TracerProvider,
+} from '../../src/otel/index.js';
+
+// The providers of the OpenTelemetry API fit the structural types.
+expectAssignable<TracerProvider>(trace.getTracerProvider());
+expectAssignable<MeterProvider>(metrics.getMeterProvider());
+
+const transport = createOpenTelemetryTransport(new MockTransport(), {
+  tracerProvider: trace.getTracerProvider(),
+  meterProvider: metrics.getMeterProvider(),
+  tracing: { samplingRate: 0.5, recordSensitiveData: false },
+  metrics: { prefix: 'billing' },
+});
+expectType<OpenTelemetryTransport<'mock'>>(transport);
+expectAssignable<Transport<'mock'>>(transport);
+expectAssignable<AsyncDisposable>(transport);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'mock'>>>(transport.send(message));
+expectType<string>(defaultErrorClassifier(new Error('Timed out')));
+expectAssignable<(error: unknown) => string>(createErrorClassifier({ patterns: {} }));
+expectAssignable<OpenTelemetryConfig>({ tracing: { enabled: false }, metrics: { enabled: false } });
+expectAssignable<Function>(createEmailAttributeExtractor);
+expectError(new OpenTelemetryTransport(new MockTransport(), { tracerProvider: 'global' }));
diff --git a/tests/unit/export-parity.test.js b/tests/unit/export-parity.test.js
index f298fde..e4bc645 100644
--- a/tests/unit/export-parity.test.js
+++ b/tests/unit/export-parity.test.js
@@ -59,3 +59,15 @@ for (const { specifier, runtimeFile, dtsFile } of entryPoints) {
     assert.deepStrictEqual(JSON.parse(output), []);
   });
 }
+
+// tsc compiles the d.ts files of check:dts together, so a lib referenced by
+// one of them hides a missing reference in another; a consumer may import a
+// single subpath.
+test('Exports: a d.ts that uses AsyncDisposable references esnext.disposable itself', () => {
+  for (const { dtsFile } of entryPoints) {
+    const source = fs.readFileSync(path.join(ROOT, dtsFile), 'utf8');
+    if (/AsyncDisposable|Symbol\.asyncDispose/.test(source)) {
+      assert.match(source, /^\/\/\/ <reference lib="esnext\.disposable" \/>$/m, dtsFile);
+    }
+  }
+});
diff --git a/tests/unit/otel-config.test.js b/tests/unit/otel-config.test.js
new file mode 100644
index 0000000..92bd11a
--- /dev/null
+++ b/tests/unit/otel-config.test.js
@@ -0,0 +1,224 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/config.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const { strict: assert } = require('node:assert');
+const { createOpenTelemetryConfig, defaultErrorClassifier } = require('../../src/otel/config.js');
+const { MockMeterProvider, MockTracerProvider } = require('../helpers/otel/mock-otel-providers.js');
+
+describe('config', () => {
+  describe('createOpenTelemetryConfig', () => {
+    it('should create config with defaults', () => {
+      const tracerProvider = new MockTracerProvider();
+      const meterProvider = new MockMeterProvider();
+
+      const config = createOpenTelemetryConfig({
+        tracerProvider,
+        meterProvider,
+      });
+
+      assert.equal(config.metrics.enabled, true);
+      assert.equal(config.metrics.samplingRate, 1.0);
+      assert.equal(config.metrics.prefix, 'mailer');
+      assert.deepEqual(
+        config.metrics.durationBuckets,
+        [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0],
+      );
+
+      assert.equal(config.tracing.enabled, true);
+      assert.equal(config.tracing.samplingRate, 1.0);
+      assert.equal(config.tracing.recordSensitiveData, false);
+      assert.equal(config.tracing.spanPrefix, 'email');
+    });
+
+    it('should merge custom configuration', () => {
+      const tracerProvider = new MockTracerProvider();
+      const meterProvider = new MockMeterProvider();
+
+      const config = createOpenTelemetryConfig({
+        tracerProvider,
+        meterProvider,
+        metrics: {
+          enabled: true,
+          prefix: 'custom',
+          samplingRate: 0.5,
+        },
+        tracing: {
+          enabled: true,
+          recordSensitiveData: true,
+          spanPrefix: 'custom_email',
+        },
+      });
+
+      assert.equal(config.metrics.prefix, 'custom');
+      assert.equal(config.metrics.samplingRate, 0.5);
+      assert.equal(config.tracing.recordSensitiveData, true);
+      assert.equal(config.tracing.spanPrefix, 'custom_email');
+    });
+
+    it('should throw when tracing enabled without TracerProvider', () => {
+      assert.throws(() => {
+        createOpenTelemetryConfig({
+          tracing: { enabled: true },
+          // No tracerProvider
+        });
+      }, /TracerProvider is required when tracing is enabled/);
+    });
+
+    it('should throw when metrics enabled without MeterProvider', () => {
+      assert.throws(() => {
+        createOpenTelemetryConfig({
+          tracing: { enabled: false },
+          metrics: { enabled: true },
+          // No meterProvider
+        });
+      }, /MeterProvider is required when metrics are enabled/);
+    });
+
+    it('should work with both disabled', () => {
+      const config = createOpenTelemetryConfig({
+        metrics: { enabled: false },
+        tracing: { enabled: false },
+      });
+
+      assert.equal(config.metrics.enabled, false);
+      assert.equal(config.tracing.enabled, false);
+    });
+
+    it('should preserve custom functions', () => {
+      const tracerProvider = new MockTracerProvider();
+      const meterProvider = new MockMeterProvider();
+      const customExtractor = () => ({ custom: 'value' });
+      const customClassifier = () => 'custom_error';
+
+      const config = createOpenTelemetryConfig({
+        tracerProvider,
+        meterProvider,
+        attributeExtractor: customExtractor,
+        errorClassifier: customClassifier,
+      });
+
+      assert.equal(config.attributeExtractor, customExtractor);
+      assert.equal(config.errorClassifier, customClassifier);
+    });
+  });
+
+  describe('defaultErrorClassifier', () => {
+    it('should classify authentication errors', () => {
+      const errors = [
+        new Error('Unauthorized access'),
+        new Error('Invalid API key provided'),
+        new Error('Authentication failed'),
+        new Error('HTTP 403 Forbidden'),
+      ];
+
+      for (const error of errors) {
+        const category = defaultErrorClassifier(error);
+        assert.equal(category, 'auth', `Failed to classify: ${error.message}`);
+      }
+    });
+
+    it('should classify rate limiting errors', () => {
+      const errors = [
+        new Error('Rate limit exceeded'),
+        new Error('HTTP 429 Too Many Requests'),
+        new Error('Quota exceeded for today'),
+        new Error('Request throttled'),
+      ];
+
+      for (const error of errors) {
+        const category = defaultErrorClassifier(error);
+        assert.equal(category, 'rate-limit', `Failed to classify: ${error}`);
+      }
+    });
+
+    it('should classify network errors', () => {
+      const errors = [
+        new Error('Connection timeout'),
+        new Error('DNS resolution failed'),
+        (() => {
+          const e = new Error('Network is unreachable');
+          e.name = 'NetworkError';
+          return e;
+        })(),
+        (() => {
+          const e = new Error('Operation was aborted');
+          e.name = 'AbortError';
+          return e;
+        })(),
+      ];
+
+      for (const error of errors) {
+        const category = defaultErrorClassifier(error);
+        assert.equal(category, 'network', `Failed to classify: ${error.message}`);
+      }
+    });
+
+    it('should classify validation errors', () => {
+      const errors = [
+        new Error('Invalid email address format'),
+        new Error('Malformed request body'),
+        new Error("Validation failed for field 'email'"),
+        new Error('HTTP 400 Bad Request'),
+      ];
+
+      for (const error of errors) {
+        const category = defaultErrorClassifier(error);
+        assert.equal(category, 'validation', `Failed to classify: ${error}`);
+      }
+    });
+
+    it('should classify service unavailable errors', () => {
+      const errors = [
+        new Error('HTTP 503 Service Unavailable'),
+        new Error('Service temporarily unavailable'),
+        new Error('Temporarily unavailable, try again later'),
+      ];
+
+      for (const error of errors) {
+        const category = defaultErrorClassifier(error);
+        assert.equal(category, 'service-unavailable', `Failed to classify: ${error}`);
+      }
+    });
+
+    it('should classify server errors', () => {
+      const errors = [
+        new Error('HTTP 500 Internal Server Error'),
+        new Error('HTTP 502 Bad Gateway'),
+        new Error('HTTP 504 Gateway Timeout'),
+        new Error('Internal server error occurred'),
+      ];
+
+      for (const error of errors) {
+        const category = defaultErrorClassifier(error);
+        assert.equal(category, 'server-error', `Failed to classify: ${error}`);
+      }
+    });
+
+    it('should classify unknown errors', () => {
+      const errors = [
+        new Error('Something unexpected happened'),
+        { message: 'Unknown error' },
+        'string error',
+        123,
+        null,
+        undefined,
+      ];
+
+      for (const error of errors) {
+        const category = defaultErrorClassifier(error);
+        assert.equal(category, 'unknown', `Failed to classify: ${error}`);
+      }
+    });
+
+    it('should be case insensitive', () => {
+      const error1 = new Error('RATE LIMIT EXCEEDED');
+      const error2 = new Error('Rate Limit Exceeded');
+      const error3 = new Error('rate limit exceeded');
+
+      assert.equal(defaultErrorClassifier(error1), 'rate-limit');
+      assert.equal(defaultErrorClassifier(error2), 'rate-limit');
+      assert.equal(defaultErrorClassifier(error3), 'rate-limit');
+    });
+  });
+});
diff --git a/tests/unit/otel-content-type.test.js b/tests/unit/otel-content-type.test.js
new file mode 100644
index 0000000..3da30a3
--- /dev/null
+++ b/tests/unit/otel-content-type.test.js
@@ -0,0 +1,74 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/content-type.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { EmailAttributeExtractor } = require('../../src/otel/attributes.js');
+const { MetricsCollector } = require('../../src/otel/metrics.js');
+const { createOpenTelemetryConfig } = require('../../src/otel/config.js');
+const { MockMeterProvider, MockTracerProvider } = require('../helpers/otel/mock-otel-providers.js');
+
+const CALENDAR_ICS =
+  [
+    'BEGIN:VCALENDAR',
+    'METHOD:REQUEST',
+    'BEGIN:VEVENT',
+    'UID:1@example.com',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ].join('\r\n') + '\r\n';
+
+const base = {
+  from: 'organizer@example.com',
+  to: 'attendee@example.net',
+  subject: 'Lunch',
+};
+
+const invitation = (content) =>
+  createMessage({
+    ...base,
+    content,
+    calendar: { method: 'REQUEST', content: CALENDAR_ICS },
+  });
+
+describe('content type detection', () => {
+  const extractor = new EmailAttributeExtractor('test');
+  const spanContentType = (message) =>
+    extractor.extractMessageAttributes(message)['email.content.type'];
+
+  it('should report a message with no calendar as before', () => {
+    assert.equal(spanContentType(createMessage({ ...base, content: { text: 'Lunch.' } })), 'text');
+    assert.equal(
+      spanContentType(createMessage({ ...base, content: { html: '<p>Lunch</p>' } })),
+      'html',
+    );
+  });
+
+  // A calendar is a second body part wherever it goes: an alternative on the
+  // transports that compose one, a synthesized invite.ics attachment elsewhere.
+  it('should report a calendar message as multipart on the span', () => {
+    assert.equal(spanContentType(invitation({ text: 'Lunch.' })), 'multipart');
+    assert.equal(spanContentType(invitation({ html: '<p>Lunch</p>' })), 'multipart');
+  });
+
+  it('should label the size metric multipart for the same message', () => {
+    const meterProvider = new MockMeterProvider();
+    const config = createOpenTelemetryConfig({
+      meterProvider,
+      tracerProvider: new MockTracerProvider(),
+      metrics: { enabled: true },
+    });
+    const collector = new MetricsCollector(meterProvider, config.metrics);
+
+    collector.recordMessage(invitation({ text: 'Lunch.' }), 'test');
+
+    const labelled = meterProvider.meters
+      .flatMap((meter) => meter.histograms)
+      .flatMap((histogram) => histogram.records)
+      .map((record) => record.attributes?.content_type)
+      .filter((value) => value !== undefined);
+    assert.ok(labelled.length > 0, 'no histogram recorded a content type');
+    for (const value of labelled) assert.equal(value, 'multipart');
+  });
+});
diff --git a/tests/unit/otel-index.test.js b/tests/unit/otel-index.test.js
new file mode 100644
index 0000000..cb960d3
--- /dev/null
+++ b/tests/unit/otel-index.test.js
@@ -0,0 +1,240 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/index.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const { strict: assert } = require('node:assert');
+const {
+  createEmailAttributeExtractor,
+  createErrorClassifier,
+  createOpenTelemetryTransport,
+  OpenTelemetryTransport,
+} = require('../../src/otel/index.js');
+const { createTestSetup } = require('../helpers/otel/test-config.js');
+
+describe('index', () => {
+  describe('createOpenTelemetryTransport', () => {
+    it('should create transport with default service name', () => {
+      const setup = createTestSetup();
+      const transport = createOpenTelemetryTransport(setup.mockTransport, {
+        tracerProvider: setup.tracerProvider,
+        meterProvider: setup.meterProvider,
+      });
+
+      assert.ok(transport instanceof OpenTelemetryTransport);
+    });
+
+    it('should use custom service name and version', () => {
+      const setup = createTestSetup();
+      const transport = createOpenTelemetryTransport(setup.mockTransport, {
+        tracerProvider: setup.tracerProvider,
+        meterProvider: setup.meterProvider,
+        serviceName: 'my-email-service',
+        serviceVersion: '1.2.3',
+      });
+
+      assert.ok(transport instanceof OpenTelemetryTransport);
+    });
+
+    it('should work with auto configuration', () => {
+      const setup = createTestSetup();
+      const transport = createOpenTelemetryTransport(setup.mockTransport, {
+        tracerProvider: setup.tracerProvider,
+        meterProvider: setup.meterProvider,
+        serviceName: 'email-service',
+        auto: {
+          tracing: { endpoint: 'http://jaeger:14268/api/traces' },
+          metrics: { endpoint: 'http://prometheus:9090/api/v1/write' },
+        },
+      });
+
+      assert.ok(transport instanceof OpenTelemetryTransport);
+    });
+
+    // Changed in the port: the providers are passed in, with no fallback to
+    // the global providers of @opentelemetry/api, so the minimal configuration
+    // names them, and none at all is refused while tracing is enabled.
+    it('should work with minimal configuration', () => {
+      const setup = createTestSetup();
+      const transport = createOpenTelemetryTransport(setup.mockTransport, {
+        tracerProvider: setup.tracerProvider,
+        meterProvider: setup.meterProvider,
+      });
+
+      assert.ok(transport instanceof OpenTelemetryTransport);
+      assert.throws(
+        () => createOpenTelemetryTransport(setup.mockTransport),
+        /TracerProvider is required when tracing is enabled/,
+      );
+    });
+
+    it('should merge configuration correctly', () => {
+      const setup = createTestSetup();
+      const transport = createOpenTelemetryTransport(setup.mockTransport, {
+        tracerProvider: setup.tracerProvider,
+        meterProvider: setup.meterProvider,
+        metrics: { prefix: 'custom' },
+        tracing: { recordSensitiveData: true },
+        serviceName: 'test-service',
+      });
+
+      assert.equal(transport.config.metrics.prefix, 'custom');
+      assert.equal(transport.config.tracing.recordSensitiveData, true);
+    });
+  });
+
+  describe('createEmailAttributeExtractor', () => {
+    it('should create basic attribute extractor', () => {
+      const extractor = createEmailAttributeExtractor('test-transport');
+
+      const attributes = extractor('send', 'test-transport', 1, 1000);
+
+      assert.equal(typeof attributes, 'object');
+    });
+
+    it('should include custom attributes', () => {
+      const extractor = createEmailAttributeExtractor('test-transport', {
+        recordSensitiveData: true,
+        transportVersion: '2.0.0',
+        customAttributes: (operation, transportName, messageCount, totalSize) => ({
+          'app.version': '1.0.0',
+          'app.environment': 'test',
+          'operation.custom': operation,
+          'transport.custom': transportName,
+          'batch.custom_size': messageCount,
+          'size.custom': totalSize || 0,
+        }),
+      });
+
+      const attributes = extractor('send_batch', 'test-transport', 5, 2500);
+
+      assert.equal(attributes['app.version'], '1.0.0');
+      assert.equal(attributes['app.environment'], 'test');
+      assert.equal(attributes['operation.custom'], 'send_batch');
+      assert.equal(attributes['transport.custom'], 'test-transport');
+      assert.equal(attributes['batch.custom_size'], 5);
+      assert.equal(attributes['size.custom'], 2500);
+    });
+
+    it('should work without custom attributes', () => {
+      const extractor = createEmailAttributeExtractor('test-transport', {
+        recordSensitiveData: false,
+      });
+
+      const attributes = extractor('send', 'test-transport', 1);
+
+      assert.equal(typeof attributes, 'object');
+      // Should not throw and should return an object
+    });
+
+    it('should handle different operations', () => {
+      const extractor = createEmailAttributeExtractor('test-transport', {
+        customAttributes: (operation) => ({ 'current.operation': operation }),
+      });
+
+      const sendAttributes = extractor('send', 'test-transport', 1);
+      const batchAttributes = extractor('send_batch', 'test-transport', 3);
+
+      assert.equal(sendAttributes['current.operation'], 'send');
+      assert.equal(batchAttributes['current.operation'], 'send_batch');
+    });
+  });
+
+  describe('createErrorClassifier', () => {
+    it('should create basic error classifier', () => {
+      const classifier = createErrorClassifier();
+
+      const category = classifier(new Error('Some error'));
+
+      assert.equal(typeof category, 'string');
+    });
+
+    it('should use custom patterns', () => {
+      const classifier = createErrorClassifier({
+        patterns: {
+          custom_spam: /spam|blocked|reputation/i,
+          custom_bounce: /bounce|undeliverable|invalid.*recipient/i,
+        },
+        fallback: 'custom_unknown',
+      });
+
+      assert.equal(classifier(new Error('Message blocked as spam')), 'custom_spam');
+      assert.equal(classifier(new Error('Email bounced back')), 'custom_bounce');
+      assert.equal(classifier(new Error('Invalid recipient address')), 'custom_bounce');
+    });
+
+    it('should fall back to default classifier', () => {
+      const classifier = createErrorClassifier({
+        patterns: {
+          custom_error: /very_specific_pattern/,
+        },
+      });
+
+      // Should fall back to default classifier for rate limit
+      assert.equal(classifier(new Error('Rate limit exceeded')), 'rate-limit');
+
+      // Should use default fallback for unmatched errors
+      assert.equal(classifier(new Error('Something else')), 'unknown');
+    });
+
+    it('should use custom fallback', () => {
+      const classifier = createErrorClassifier({
+        patterns: {
+          never_matches: /this_will_never_match_anything_specific_12345/,
+        },
+        fallback: 'my_custom_fallback',
+      });
+
+      const category = classifier(new Error('Random error'));
+      assert.equal(category, 'my_custom_fallback');
+    });
+
+    it('should be case insensitive for custom patterns', () => {
+      const classifier = createErrorClassifier({
+        patterns: {
+          spam_error: /spam/i,
+        },
+      });
+
+      assert.equal(classifier(new Error('SPAM detected')), 'spam_error');
+      assert.equal(classifier(new Error('Spam detected')), 'spam_error');
+      assert.equal(classifier(new Error('spam detected')), 'spam_error');
+    });
+
+    it('should handle non-Error objects', () => {
+      const classifier = createErrorClassifier({
+        patterns: {
+          string_error: /string/,
+        },
+        fallback: 'non_error',
+      });
+
+      assert.equal(classifier('string error'), 'non_error');
+      assert.equal(classifier(123), 'non_error');
+      assert.equal(classifier(null), 'non_error');
+    });
+
+    it('should prioritize custom patterns over default', () => {
+      const classifier = createErrorClassifier({
+        patterns: {
+          custom_auth: /auth/i, // This should override default auth classification
+        },
+      });
+
+      const category = classifier(new Error('Authentication failed'));
+      assert.equal(category, 'custom_auth');
+    });
+
+    it('should work with multiple overlapping patterns', () => {
+      const classifier = createErrorClassifier({
+        patterns: {
+          first_pattern: /error.*failed/i,
+          second_pattern: /failed.*error/i,
+        },
+      });
+
+      // Should match the first pattern that matches
+      const category = classifier(new Error('Error authentication failed'));
+      assert.equal(category, 'first_pattern');
+    });
+  });
+});
diff --git a/tests/unit/otel-integration.test.js b/tests/unit/otel-integration.test.js
new file mode 100644
index 0000000..0ed73f4
--- /dev/null
+++ b/tests/unit/otel-integration.test.js
@@ -0,0 +1,340 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/integration.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const { strict: assert } = require('node:assert');
+const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base');
+const { MeterProvider } = require('@opentelemetry/sdk-metrics');
+const { InMemorySpanExporter, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
+const { Resource } = require('@opentelemetry/resources');
+const {
+  SEMRESATTRS_SERVICE_NAME,
+  SEMRESATTRS_SERVICE_VERSION,
+} = require('@opentelemetry/semantic-conventions');
+const { AsyncHooksContextManager } = require('@opentelemetry/context-async-hooks');
+const { context } = require('@opentelemetry/api');
+const { OpenTelemetryTransport } = require('../../src/otel/opentelemetry-transport.js');
+const { createTestMessage, MockTransport } = require('../helpers/otel/test-config.js');
+
+// Import actual OpenTelemetry SDK components
+
+/**
+ * Helper function to create test setup with real OpenTelemetry providers
+ */
+const createRealTestSetup = () => {
+  const spanExporter = new InMemorySpanExporter();
+
+  // Set up context manager for proper context propagation
+  const contextManager = new AsyncHooksContextManager();
+  context.setGlobalContextManager(contextManager.enable());
+
+  const tracerProvider = new BasicTracerProvider({
+    resource: new Resource({
+      [SEMRESATTRS_SERVICE_NAME]: 'test-email-service',
+      [SEMRESATTRS_SERVICE_VERSION]: '1.0.0',
+    }),
+  });
+
+  // Add span processor to capture spans
+  tracerProvider.addSpanProcessor(new SimpleSpanProcessor(spanExporter));
+
+  const meterProvider = new MeterProvider({
+    resource: new Resource({
+      [SEMRESATTRS_SERVICE_NAME]: 'test-email-service',
+      [SEMRESATTRS_SERVICE_VERSION]: '1.0.0',
+    }),
+  });
+
+  const mockTransport = new MockTransport();
+  const transport = new OpenTelemetryTransport(mockTransport, {
+    tracerProvider,
+    meterProvider,
+    metrics: { enabled: true },
+    tracing: { enabled: true },
+  });
+
+  return {
+    tracerProvider,
+    meterProvider,
+    spanExporter,
+    mockTransport,
+    transport,
+    contextManager,
+    async cleanup() {
+      await transport[Symbol.asyncDispose]();
+      await tracerProvider.shutdown();
+      await meterProvider.shutdown();
+      mockTransport.reset();
+      contextManager.disable();
+    },
+  };
+};
+
+/**
+ * Integration tests using real OpenTelemetry SDK components.
+ * These tests verify that our implementation works correctly with actual
+ * OpenTelemetry providers, not just our mock implementations.
+ */
+describe('OpenTelemetryTransport Integration Tests', () => {
+  describe('Real SDK Integration', () => {
+    it('should create spans with real TracerProvider', async () => {
+      const setup = createRealTestSetup();
+      try {
+        const message = createTestMessage();
+        await setup.transport.send(message);
+
+        // Force span export
+        await setup.tracerProvider.forceFlush();
+
+        // Get exported spans
+        const spans = setup.spanExporter.getFinishedSpans();
+        assert.equal(spans.length, 1);
+
+        const span = spans[0];
+        assert.equal(span.name, 'email send');
+        assert.equal(span.attributes['operation.name'], 'email.send');
+        assert.equal(span.attributes['operation.type'], 'email');
+        assert.equal(span.attributes['mailer.transport.name'], 'mock');
+      } finally {
+        await setup.cleanup();
+      }
+    });
+
+    it('should handle span failures with real SDK', async () => {
+      const setup = createRealTestSetup();
+      try {
+        const message = createTestMessage();
+        const error = new Error('SMTP connection failed');
+        setup.mockTransport.setThrowError(error);
+
+        await assert.rejects(() => setup.transport.send(message), /SMTP connection failed/);
+        await setup.tracerProvider.forceFlush();
+
+        const spans = setup.spanExporter.getFinishedSpans();
+        assert.equal(spans.length, 1);
+
+        const span = spans[0];
+        assert.equal(span.status.code, 2); // ERROR status
+
+        // Check for exception event
+        const exceptionEvents = span.events.filter((e) => e.name === 'exception');
+        assert.equal(exceptionEvents.length, 1);
+        assert.equal(
+          exceptionEvents[0].attributes?.['exception.message'],
+          'SMTP connection failed',
+        );
+      } finally {
+        await setup.cleanup();
+      }
+    });
+
+    it('should create batch spans for sendMany', async () => {
+      const setup = createRealTestSetup();
+      try {
+        const messages = [
+          createTestMessage({ subject: 'Message 1' }),
+          createTestMessage({ subject: 'Message 2' }),
+          createTestMessage({ subject: 'Message 3' }),
+        ];
+
+        const receipts = [];
+        for await (const receipt of setup.transport.sendMany(messages)) {
+          receipts.push(receipt);
+        }
+
+        assert.equal(receipts.length, 3);
+        await setup.tracerProvider.forceFlush();
+
+        const spans = setup.spanExporter.getFinishedSpans();
+        assert.equal(spans.length, 1);
+
+        const span = spans[0];
+        assert.equal(span.name, 'email send_batch');
+        assert.equal(span.attributes['operation.name'], 'email.send_batch');
+        assert.equal(span.attributes['mailer.batch.size'], 3);
+      } finally {
+        await setup.cleanup();
+      }
+    });
+
+    it('should preserve span context and support distributed tracing', async () => {
+      const setup = createRealTestSetup();
+      try {
+        const message = createTestMessage();
+
+        // Create a root span to simulate incoming request context
+        const tracer = setup.tracerProvider.getTracer('test-tracer');
+        await tracer.startActiveSpan('incoming-request', async (rootSpan) => {
+          try {
+            await setup.transport.send(message);
+            rootSpan.setStatus({ code: 1 }); // OK
+          } finally {
+            rootSpan.end();
+          }
+        });
+
+        await setup.tracerProvider.forceFlush();
+
+        const spans = setup.spanExporter.getFinishedSpans();
+        assert.equal(spans.length, 2); // root span + email span
+
+        const emailSpan = spans.find((s) => s.name === 'email send');
+        const rootSpan = spans.find((s) => s.name === 'incoming-request');
+
+        assert.ok(emailSpan);
+        assert.ok(rootSpan);
+
+        // Email span should be child of root span
+        assert.equal(
+          emailSpan.parentSpanId,
+          rootSpan.spanContext().spanId,
+          `Email span parentSpanId (${emailSpan.parentSpanId}) should match root span ID (${rootSpan.spanContext().spanId})`,
+        );
+        assert.equal(emailSpan.spanContext().traceId, rootSpan.spanContext().traceId);
+      } finally {
+        await setup.cleanup();
+      }
+    });
+
+    it('should handle multiple spans correctly', async () => {
+      const setup = createRealTestSetup();
+      try {
+        // Send multiple messages to verify span isolation
+        const message1 = createTestMessage({ subject: 'Message 1' });
+        const message2 = createTestMessage({ subject: 'Message 2' });
+
+        await setup.transport.send(message1);
+        await setup.transport.send(message2);
+
+        await setup.tracerProvider.forceFlush();
+
+        const spans = setup.spanExporter.getFinishedSpans();
+        assert.equal(spans.length, 2);
+
+        // All spans should be for email send operations
+        assert.ok(spans.every((span) => span.name === 'email send'));
+        assert.ok(spans.every((span) => span.attributes['operation.name'] === 'email.send'));
+      } finally {
+        await setup.cleanup();
+      }
+    });
+
+    it('should work with metrics collection using real MeterProvider', async () => {
+      const setup = createRealTestSetup();
+      try {
+        // Note: Real metrics testing requires a metric reader, but we can verify
+        // that the transport doesn't crash when using real MeterProvider
+        const message = createTestMessage();
+
+        // This should not throw with real MeterProvider
+        await setup.transport.send(message);
+
+        // Send multiple messages to test batch metrics
+        const messages = [
+          createTestMessage({ subject: 'Batch 1' }),
+          createTestMessage({ subject: 'Batch 2' }),
+        ];
+
+        const receipts = [];
+        for await (const receipt of setup.transport.sendMany(messages)) {
+          receipts.push(receipt);
+        }
+
+        assert.equal(receipts.length, 2);
+
+        // Force metric collection (this verifies no exceptions are thrown)
+        await setup.meterProvider.forceFlush();
+      } finally {
+        await setup.cleanup();
+      }
+    });
+
+    it('should work with custom configuration using real SDK', async () => {
+      const setup = createRealTestSetup();
+      try {
+        // Create transport with custom configuration
+        const customTransport = new OpenTelemetryTransport(setup.mockTransport, {
+          tracerProvider: setup.tracerProvider,
+          meterProvider: setup.meterProvider,
+          metrics: { enabled: true },
+          tracing: {
+            enabled: true,
+            recordSensitiveData: true,
+          },
+          attributeExtractor: (operation, transportName) => ({
+            'custom.operation': operation,
+            'custom.transport': transportName,
+            'custom.timestamp': Date.now(),
+          }),
+        });
+
+        const message = createTestMessage();
+        await customTransport.send(message);
+        await setup.tracerProvider.forceFlush();
+
+        const spans = setup.spanExporter.getFinishedSpans();
+        const span = spans[0];
+
+        // Check custom attributes
+        assert.equal(span.attributes['custom.operation'], 'send');
+        assert.equal(span.attributes['custom.transport'], 'mock');
+        assert.ok(typeof span.attributes['custom.timestamp'] === 'number');
+
+        // Check sensitive data recording
+        assert.equal(span.attributes['email.from.address'], 'sender@example.com');
+
+        await customTransport[Symbol.asyncDispose]();
+      } finally {
+        await setup.cleanup();
+      }
+    });
+  });
+
+  describe('Error Classification with Real SDK', () => {
+    it('should classify and record errors correctly in real spans', async () => {
+      const setup = createRealTestSetup();
+      try {
+        const message = createTestMessage();
+
+        // Test different error types
+        const testCases = [
+          { error: new Error('401 Unauthorized'), expectedCategory: 'auth' },
+          {
+            error: new Error('Rate limit exceeded'),
+            expectedCategory: 'rate-limit',
+          },
+          {
+            error: new Error('DNS_PROBE_FINISHED_NXDOMAIN'),
+            expectedCategory: 'network',
+          },
+          {
+            error: new Error('500 Internal Server Error'),
+            expectedCategory: 'server-error',
+          },
+        ];
+
+        for (const { error } of testCases) {
+          // Reset exporter for each test
+          setup.spanExporter.reset();
+          setup.mockTransport.setThrowError(error);
+
+          await assert.rejects(() => setup.transport.send(message));
+          await setup.tracerProvider.forceFlush();
+
+          const spans = setup.spanExporter.getFinishedSpans();
+          assert.equal(spans.length, 1);
+
+          const span = spans[0];
+          assert.equal(span.status.code, 2); // ERROR
+
+          // Verify error classification is recorded in span attributes
+          const errorEvents = span.events.filter((e) => e.name === 'exception');
+          assert.equal(errorEvents.length, 1);
+          assert.equal(errorEvents[0].attributes?.['exception.message'], error.message);
+        }
+      } finally {
+        await setup.cleanup();
+      }
+    });
+  });
+});
diff --git a/tests/unit/otel-message-size.test.js b/tests/unit/otel-message-size.test.js
new file mode 100644
index 0000000..21bada7
--- /dev/null
+++ b/tests/unit/otel-message-size.test.js
@@ -0,0 +1,68 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/message-size.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { createMessage } = require('../../src/core/message.js');
+const assert = require('node:assert/strict');
+const { describe, it } = require('node:test');
+const { estimateMessageSize } = require('../../src/otel/message-size.js');
+
+describe('estimateMessageSize()', () => {
+  const base = {
+    from: 'sender@example.com',
+    to: 'recipient@example.net',
+  };
+
+  it('should count non-ASCII text in UTF-8 bytes', () => {
+    // "점심" is two code units but six bytes, so counting code units would
+    // report a size a third of the truth.
+    const ascii = estimateMessageSize(
+      createMessage({ ...base, subject: 'ab', content: { text: 'cd' } }),
+    );
+    const korean = estimateMessageSize(
+      createMessage({ ...base, subject: '점심', content: { text: '식사' } }),
+    );
+
+    assert.equal(korean - ascii, 8);
+  });
+
+  it('should count an astral character as four bytes', () => {
+    const empty = estimateMessageSize(
+      createMessage({ ...base, subject: '', content: { text: '' } }),
+    );
+    const emoji = estimateMessageSize(
+      createMessage({ ...base, subject: '', content: { text: '🍜' } }),
+    );
+
+    assert.equal(emoji - empty, 4);
+  });
+
+  it('should count the calendar payload', () => {
+    const ics = ['BEGIN:VCALENDAR', 'METHOD:REQUEST', 'END:VCALENDAR'].join('\r\n') + '\r\n';
+    const without = estimateMessageSize(
+      createMessage({ ...base, subject: 's', content: { text: 't' } }),
+    );
+    // oxlint-disable-next-line no-underscore-dangle -- upstream
+    const with_ = estimateMessageSize(
+      createMessage({
+        ...base,
+        subject: 's',
+        content: { text: 't' },
+        calendar: { method: 'REQUEST', content: ics },
+      }),
+    );
+
+    assert.equal(with_ - without, ics.length);
+  });
+
+  it('should count both bodies when the message carries text and HTML', () => {
+    const size = estimateMessageSize(
+      createMessage({
+        ...base,
+        subject: '',
+        content: { html: '<p>hi</p>', text: 'hi' },
+      }),
+    );
+
+    assert.equal(size, 500 + '<p>hi</p>'.length + 'hi'.length);
+  });
+});
diff --git a/tests/unit/otel-opentelemetry-transport.test.js b/tests/unit/otel-opentelemetry-transport.test.js
new file mode 100644
index 0000000..a7c2480
--- /dev/null
+++ b/tests/unit/otel-opentelemetry-transport.test.js
@@ -0,0 +1,501 @@
+// Ported from upyo v0.7.0 (packages/opentelemetry/src/opentelemetry-transport.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { describe, it } = require('node:test');
+const { strict: assert } = require('node:assert');
+const { createFailedReceipt } = require('../../src/core/receipt.js');
+const { OpenTelemetryTransport } = require('../../src/otel/opentelemetry-transport.js');
+const {
+  assertions,
+  createTestMessage,
+  createTestSetup,
+  extractMetrics,
+  extractSpans,
+} = require('../helpers/otel/test-config.js');
+
+describe('OpenTelemetryTransport', () => {
+  describe('constructor', () => {
+    it('should create transport with valid configuration', () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      assert.ok(transport instanceof OpenTelemetryTransport);
+      assert.ok(transport.config);
+    });
+
+    it('should throw when tracing enabled but no TracerProvider', () => {
+      const setup = createTestSetup();
+      assert.throws(() => {
+        // oxlint-disable-next-line no-new -- upstream
+        new OpenTelemetryTransport(setup.mockTransport, {
+          tracing: { enabled: true },
+          // No tracerProvider
+        });
+      }, /TracerProvider is required when tracing is enabled/);
+    });
+
+    it('should throw when metrics enabled but no MeterProvider', () => {
+      const setup = createTestSetup();
+      assert.throws(() => {
+        // oxlint-disable-next-line no-new -- upstream
+        new OpenTelemetryTransport(setup.mockTransport, {
+          tracerProvider: setup.tracerProvider, // Provide TracerProvider
+          metrics: { enabled: true },
+          // No meterProvider
+        });
+      }, /MeterProvider is required when metrics are enabled/);
+    });
+
+    it('should work with observability disabled', () => {
+      const setup = createTestSetup();
+      const disabledTransport = new OpenTelemetryTransport(setup.mockTransport, {
+        tracing: { enabled: false },
+        metrics: { enabled: false },
+      });
+      assert.ok(disabledTransport instanceof OpenTelemetryTransport);
+    });
+
+    it('should handle null-prototype transports', () => {
+      const setup = createTestSetup();
+      const nullPrototypeTransport = Object.assign(Object.create(null), {
+        id: '',
+        send: () => Promise.resolve(createFailedReceipt('Not implemented.', { provider: '' })),
+        sendMany: async function* (_messages, _options) {},
+      });
+
+      assert.doesNotThrow(() => {
+        // oxlint-disable-next-line no-new -- upstream
+        new OpenTelemetryTransport(nullPrototypeTransport, setup.config);
+      });
+    });
+  });
+
+  describe('send', () => {
+    it('should successfully send a message and record observability data', async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      const message = createTestMessage();
+      const receipt = await transport.send(message);
+
+      // Verify the message was sent
+      assert.equal(receipt.successful, true);
+      assert.ok(setup.mockTransport.sentMessages.includes(message));
+
+      // Verify spans were created
+      const spans = extractSpans(setup.tracerProvider);
+      assert.equal(spans.length, 1);
+      assertions.hasSpan(spans, 'email send', {
+        'operation.name': 'email.send',
+        'operation.type': 'email',
+        'mailer.transport.name': 'mock',
+      });
+
+      // Verify metrics were recorded
+      const metrics = extractMetrics(setup.meterProvider);
+      assertions.hasMetric(metrics, 'counter', 2); // attempts + messages
+      assertions.hasMetric(metrics, 'histogram', 3); // duration + size + attachments
+      assertions.hasMetric(metrics, 'upDownCounter', 2); // start + end
+    });
+
+    it('should handle send failures properly', async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      const message = createTestMessage();
+      const error = new Error('Network timeout');
+      setup.mockTransport.setThrowError(error);
+
+      await assert.rejects(() => transport.send(message), /Network timeout/);
+
+      // Verify error was recorded in span
+      const spans = extractSpans(setup.tracerProvider);
+      const span = assertions.hasSpan(spans, 'email send');
+      assert.equal(span.status?.code, 2); // ERROR
+      assert.ok(span.events.some((e) => e.name === 'exception'));
+
+      // Verify error metrics
+      const metrics = extractMetrics(setup.meterProvider);
+      const attemptRecords =
+        metrics.find((m) => m.records.some((r) => r.attributes?.status === 'failure'))?.records ||
+        [];
+      assert.ok(attemptRecords.length > 0);
+    });
+
+    it('should handle receipt failures', async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      const message = createTestMessage();
+      setup.mockTransport.setNextReceipt({
+        successful: false,
+        errorMessages: ['Invalid API key', 'Rate limit exceeded'],
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, false);
+      assert.deepEqual(receipt.errorMessages, ['Invalid API key', 'Rate limit exceeded']);
+
+      // Verify span recorded failure
+      const spans = extractSpans(setup.tracerProvider);
+      const span = assertions.hasSpan(spans, 'email send');
+      assert.equal(span.status?.code, 2); // ERROR
+    });
+
+    it('should prefer structured receipt categories for metrics', async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, {
+        ...setup.config,
+        errorClassifier: () => 'validation',
+      });
+      const message = createTestMessage();
+      setup.mockTransport.setNextReceipt(
+        createFailedReceipt('Provider throttled the request', {
+          provider: 'mock',
+          statusCode: 429,
+        }),
+      );
+
+      const receipt = await transport.send(message);
+
+      assert.equal(receipt.successful, false);
+
+      const metrics = extractMetrics(setup.meterProvider);
+      const failureRecord = metrics
+        .flatMap((metric) => metric.records)
+        .find((record) => record.attributes?.status === 'failure');
+
+      assert.equal(failureRecord?.attributes?.error_type, 'rate-limit');
+    });
+
+    it('should respect abort signals', async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      const message = createTestMessage();
+      const controller = new AbortController();
+
+      // Abort immediately
+      controller.abort();
+
+      await assert.rejects(
+        () => transport.send(message, { signal: controller.signal }),
+        /AbortError/,
+      );
+    });
+
+    it('should infer transport names when wrapped transports have no id', async () => {
+      class LegacyTransport {
+        send(_message, _options) {
+          return Promise.resolve({
+            successful: true,
+            messageId: 'legacy-message-id',
+          });
+        }
+
+        async *sendMany(messages, options) {
+          for await (const message of messages) {
+            yield await this.send(message, options);
+          }
+        }
+      }
+
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(
+        // @ts-expect-error Simulates an older JavaScript transport without id.
+        new LegacyTransport(),
+        setup.config,
+      );
+
+      await transport.send(createTestMessage());
+
+      const spans = extractSpans(setup.tracerProvider);
+      assertions.hasSpan(spans, 'email send', {
+        'mailer.transport.name': 'legacy',
+      });
+    });
+
+    it('should work with tracing disabled', async () => {
+      const setup = createTestSetup();
+      const tracingDisabledTransport = new OpenTelemetryTransport(setup.mockTransport, {
+        meterProvider: setup.meterProvider,
+        tracing: { enabled: false },
+        metrics: { enabled: true },
+      });
+
+      const message = createTestMessage();
+      await tracingDisabledTransport.send(message);
+
+      // No spans should be created
+      const spans = extractSpans(setup.tracerProvider);
+      assert.equal(spans.length, 0);
+
+      // Metrics should still be recorded
+      const metrics = extractMetrics(setup.meterProvider);
+      assertions.hasMetric(metrics, 'counter', 2);
+    });
+
+    it('should work with metrics disabled', async () => {
+      const setup = createTestSetup();
+      const metricsDisabledTransport = new OpenTelemetryTransport(setup.mockTransport, {
+        tracerProvider: setup.tracerProvider,
+        tracing: { enabled: true },
+        metrics: { enabled: false },
+      });
+
+      const message = createTestMessage();
+      await metricsDisabledTransport.send(message);
+
+      // Spans should be created
+      const spans = extractSpans(setup.tracerProvider);
+      assert.equal(spans.length, 1);
+
+      // No metrics should be recorded
+      const metrics = extractMetrics(setup.meterProvider);
+      assert.equal(Object.keys(metrics).length, 0);
+    });
+
+    it('should extract message attributes correctly', async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      const message = createTestMessage({
+        subject: 'Important Email',
+        content: { html: '<p>Test HTML</p>', text: 'Test text' },
+        priority: 'high',
+        tags: ['urgent', 'notification'],
+        attachments: [], // No attachments so it's HTML content type
+      });
+
+      await transport.send(message);
+
+      const spans = extractSpans(setup.tracerProvider);
+      const span = assertions.hasSpan(spans, 'email send', {
+        'email.to.count': 3,
+        'email.attachments.count': 0,
+        'email.priority': 'high',
+        'email.content.type': 'html',
+        'email.subject.length': 15, // "Important Email".length
+      });
+
+      // Tags should be JSON stringified
+      assert.equal(span.attributes['email.tags'], JSON.stringify(['urgent', 'notification']));
+    });
+  });
+
+  describe('sendMany', () => {
+    it('should send multiple messages and record batch metrics', async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      const messages = [
+        createTestMessage({ subject: 'Message 1' }),
+        createTestMessage({ subject: 'Message 2' }),
+        createTestMessage({ subject: 'Message 3' }),
+      ];
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 3);
+      assert.ok(receipts.every((r) => r.successful));
+
+      // Verify batch span
+      const spans = extractSpans(setup.tracerProvider);
+      assertions.hasSpan(spans, 'email send_batch', {
+        'operation.name': 'email.send_batch',
+        'email.batch.size': 3,
+        'mailer.batch.size': 3,
+      });
+
+      // Verify all messages were sent
+      assert.equal(setup.mockTransport.sentMessages.length, 3);
+    });
+
+    it('should handle partial failures in batch', async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      const messages = [
+        createTestMessage({ subject: 'Message 1' }),
+        createTestMessage({ subject: 'Message 2' }),
+      ];
+
+      // Make second message fail
+      let callCount = 0;
+      const originalSend = setup.mockTransport.send.bind(setup.mockTransport);
+      setup.mockTransport.send = (msg, opts) => {
+        callCount++;
+        if (callCount === 2) {
+          return Promise.resolve({
+            successful: false,
+            errorMessages: ['Recipient not found'],
+          });
+        }
+        return originalSend(msg, opts);
+      };
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages)) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.equal(receipts[0].successful, true);
+      assert.equal(receipts[1].successful, false);
+
+      // Verify batch span recorded partial success
+      const spans = extractSpans(setup.tracerProvider);
+      const span = assertions.hasSpan(spans, 'email send_batch');
+      assert.ok(span.events.some((e) => e.name === 'partial_success'));
+    });
+
+    it('should handle batch failures', async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      const messages = [createTestMessage()];
+      const error = new Error('Batch API error');
+      setup.mockTransport.setThrowError(error);
+
+      await assert.rejects(async () => {
+        // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+        for await (const _receipt of transport.sendMany(messages)) {
+          // This should throw before yielding any receipts
+        }
+      }, /Batch API error/);
+
+      // Verify error was recorded
+      const spans = extractSpans(setup.tracerProvider);
+      const span = assertions.hasSpan(spans, 'email send_batch');
+      assert.equal(span.status?.code, 2); // ERROR
+    });
+  });
+
+  describe('Resource Disposal', () => {
+    it('should dispose wrapped transport if it supports AsyncDisposable', async () => {
+      const setup = createTestSetup();
+      let disposed = false;
+      const disposableTransport = {
+        ...setup.mockTransport,
+        [Symbol.asyncDispose]: () => {
+          disposed = true;
+          return Promise.resolve();
+        },
+      };
+
+      const otelTransport = new OpenTelemetryTransport(disposableTransport, setup.config);
+      await otelTransport[Symbol.asyncDispose]();
+
+      assert.equal(disposed, true);
+    });
+
+    it('should dispose wrapped transport if it supports Disposable', async () => {
+      const setup = createTestSetup();
+      let disposed = false;
+      const disposableTransport = {
+        ...setup.mockTransport,
+        [Symbol.dispose]: () => {
+          disposed = true;
+        },
+      };
+
+      const otelTransport = new OpenTelemetryTransport(disposableTransport, setup.config);
+      await otelTransport[Symbol.asyncDispose]();
+
+      assert.equal(disposed, true);
+    });
+
+    it('should prefer AsyncDisposable over Disposable when both are available', async () => {
+      const setup = createTestSetup();
+      let asyncDisposed = false;
+      let syncDisposed = false;
+
+      const disposableTransport = {
+        ...setup.mockTransport,
+        [Symbol.asyncDispose]: () => {
+          asyncDisposed = true;
+          return Promise.resolve();
+        },
+        [Symbol.dispose]: () => {
+          syncDisposed = true;
+        },
+      };
+
+      const otelTransport = new OpenTelemetryTransport(disposableTransport, setup.config);
+      await otelTransport[Symbol.asyncDispose]();
+
+      assert.equal(asyncDisposed, true);
+      assert.equal(syncDisposed, false);
+    });
+
+    it("should not throw if wrapped transport doesn't support disposal", async () => {
+      const setup = createTestSetup();
+      const transport = new OpenTelemetryTransport(setup.mockTransport, setup.config);
+      await assert.doesNotReject(() => transport[Symbol.asyncDispose]());
+    });
+  });
+
+  describe('custom configuration', () => {
+    it('should use custom attribute extractor', async () => {
+      const setup = createTestSetup();
+      const customTransport = new OpenTelemetryTransport(setup.mockTransport, {
+        ...setup.config,
+        attributeExtractor: () => ({
+          'custom.attribute': 'test-value',
+          'custom.number': 42,
+        }),
+      });
+
+      const message = createTestMessage();
+      await customTransport.send(message);
+
+      const spans = extractSpans(setup.tracerProvider);
+      assertions.hasSpan(spans, 'email send', {
+        'custom.attribute': 'test-value',
+        'custom.number': 42,
+      });
+    });
+
+    it('should use custom error classifier', async () => {
+      const setup = createTestSetup();
+      const customTransport = new OpenTelemetryTransport(setup.mockTransport, {
+        ...setup.config,
+        errorClassifier: (error) => {
+          if (error instanceof Error && error.message.includes('custom')) {
+            return 'custom_error';
+          }
+          return 'other_error';
+        },
+      });
+
+      const message = createTestMessage();
+      setup.mockTransport.setThrowError(new Error('custom error occurred'));
+
+      await assert.rejects(() => customTransport.send(message));
+
+      const metrics = extractMetrics(setup.meterProvider);
+      const failureRecords = metrics
+        .flatMap((m) => m.records)
+        .filter((r) => r.attributes?.error_type === 'custom_error');
+
+      assert.ok(failureRecords.length > 0);
+    });
+
+    it('should respect sensitive data configuration', async () => {
+      const setup = createTestSetup();
+      const sensitiveTransport = new OpenTelemetryTransport(setup.mockTransport, {
+        ...setup.config,
+        tracing: {
+          enabled: true,
+          recordSensitiveData: true,
+          samplingRate: 1.0,
+          spanPrefix: 'email',
+        },
+      });
+
+      const message = createTestMessage();
+      await sensitiveTransport.send(message);
+
+      const spans = extractSpans(setup.tracerProvider);
+      const span = assertions.hasSpan(spans, 'email send');
+
+      // Should include sensitive data
+      assert.equal(span.attributes['email.from.address'], 'sender@example.com');
+    });
+  });
+});
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
new file mode 100644
index 0000000..bbf753d
--- /dev/null
+++ b/tests/unit/otel.test.js
@@ -0,0 +1,112 @@
+// Paths of the ported OpenTelemetry decorator (src/otel/) that upstream's
+// suites leave out: sampled-out spans and metrics, the transport name,
+// version and network attributes guessed from a transport's config, custom
+// batch attributes and failed batches.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { OpenTelemetryTransport } = require('../../src/otel/index.js');
+const { MockMeterProvider, MockTracerProvider } = require('../helpers/otel/mock-otel-providers.js');
+const { createTestMessage } = require('../helpers/otel/test-config.js');
+
+const providers = () => ({
+  tracerProvider: new MockTracerProvider(),
+  meterProvider: new MockMeterProvider(),
+});
+const plain = (config, receipt = { successful: true, messageId: 'm1' }) => ({
+  config,
+  send: async () => receipt,
+  async *sendMany(messages) {
+    for await (const message of messages) {
+      yield typeof receipt === 'function' ? receipt(message) : receipt;
+    }
+  },
+});
+const collect = async (iterable) => {
+  const items = [];
+  for await (const item of iterable) items.push(item);
+  return items;
+};
+
+test('OTel: nothing is recorded when sampled out', async () => {
+  const { tracerProvider, meterProvider } = providers();
+  const options = {
+    tracerProvider,
+    meterProvider,
+    tracing: { samplingRate: 0 },
+    metrics: { samplingRate: 0 },
+    attributeExtractor: () => ({ 'app.custom': true }),
+  };
+  const ok = new OpenTelemetryTransport(plain({}), options);
+  assert.strictEqual((await ok.send(createTestMessage())).successful, true);
+  await collect(ok.sendMany([createTestMessage()]));
+
+  const failure = { successful: false, errorMessages: ['Rejected'], errors: [] };
+  let index = 0;
+  const partial = new OpenTelemetryTransport(
+    plain({}, () => (index++ === 0 ? { successful: true, messageId: 'm1' } : failure)),
+    options,
+  );
+  await collect(partial.sendMany([createTestMessage(), createTestMessage()]));
+  await collect(
+    new OpenTelemetryTransport(plain({}, failure), options).sendMany([createTestMessage()]),
+  );
+
+  const throwing = plain({});
+  throwing.send = async () => {
+    throw new Error('Connection refused');
+  };
+  await assert.rejects(new OpenTelemetryTransport(throwing, options).send(createTestMessage()));
+  assert.deepStrictEqual(tracerProvider.getAllSpans(), []);
+});
+
+test('OTel: the transport name and the network attributes come from its config', async () => {
+  const cases = [
+    [
+      { host: 'smtp.example.com', port: 587 },
+      'smtp',
+      { 'server.address': 'smtp.example.com', 'server.port': 587 },
+    ],
+    [
+      { domain: 'mg.example.com', region: 'eu' },
+      'mailgun',
+      { 'server.address': 'api.eu.mailgun.net' },
+    ],
+    [
+      { apiKey: 'k', region: 'us', baseUrl: 'https://api.example.com:8443' },
+      'sendgrid',
+      { 'server.port': 8443 },
+    ],
+    [{ accessKeyId: 'a', endpoint: 'not a url' }, 'ses', {}],
+    [{ version: 3 }, 'unknown', {}],
+  ];
+  for (const [config, name, network] of cases) {
+    const { tracerProvider, meterProvider } = providers();
+    const transport = new OpenTelemetryTransport(plain(config), { tracerProvider, meterProvider });
+    await transport.send(createTestMessage());
+    const [span] = tracerProvider.getAllSpans();
+    assert.strictEqual(span.attributes['mailer.transport.name'], name, name);
+    for (const [key, value] of Object.entries(network)) {
+      assert.strictEqual(span.attributes[key], value, `${name}: ${key}`);
+    }
+    if ('version' in config) assert.strictEqual(span.attributes['mailer.transport.version'], '3');
+  }
+});
+
+test('OTel: a batch gets the custom attributes and records its failures', async () => {
+  const { tracerProvider, meterProvider } = providers();
+  const failure = { successful: false, errorMessages: ['Rejected'], errors: [] };
+  const transport = new OpenTelemetryTransport(plain({}, failure), {
+    tracerProvider,
+    meterProvider,
+    attributeExtractor: (operation, transportName, count) => ({
+      'app.operation': operation,
+      'app.count': count,
+    }),
+  });
+  const receipts = await collect(transport.sendMany([createTestMessage(), createTestMessage()]));
+  assert.strictEqual(receipts.length, 2);
+  const [span] = tracerProvider.getAllSpans();
+  assert.strictEqual(span.attributes['app.operation'], 'send_batch');
+  assert.strictEqual(span.attributes['app.count'], 2);
+  assert.strictEqual(span.status.code, 2);
+});

From 1561948b7de9381afcbadddf2df29a77fc14529f Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:47:05 +0300
Subject: [PATCH 018/158] feat(logger): port the LogTape decorator of upyo
 0.7.0 as ./logger

./logger exports LoggerTransport: the delivery lifecycle of each message
(email.sending, email.sent, email.failed, with counts, duration, receipt and
errors) logged through a logger the application passes in, around a
wrapped transport or alone (log-only, with synthetic receipts). It is
@upyo/logtape's transport with the logger injected instead of LogTape's
getLogger(category):

- any pino-like logger fits, called as logger[level](properties, message);
  pino's level names (warn, not warning), checked when the transport is made;
- a thrown error goes under err, the key pino serializes;
- the inline mode builds its text itself, as pino interpolates no template;
- the category option is gone (pass logger.child() instead), and the
  log-only receipts are logger-<uuid>.

The pending queue and the sendMany logic are upstream's. Upstream's suite is
ported onto a recording pino-like logger in place of LogTape's recorder;
tests/unit/logger.test.js checks the validation and a real pino logger
(a devDependency), and the type tests check that pino fits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                |   2 +-
 package.json                            |   5 +
 pnpm-lock.yaml                          |  92 +++
 src/logger/config.js                    |  46 ++
 src/logger/index.d.ts                   | 187 ++++++
 src/logger/index.js                     |  13 +
 src/logger/logger-transport.js          | 302 ++++++++++
 src/logger/pending-queue.js             |  64 ++
 tests/types/logger.test-d.ts            |  42 ++
 tests/unit/logger-pending-queue.test.js |  33 ++
 tests/unit/logger-transport.test.js     | 752 ++++++++++++++++++++++++
 tests/unit/logger.test.js               |  66 +++
 12 files changed, 1603 insertions(+), 1 deletion(-)
 create mode 100644 src/logger/config.js
 create mode 100644 src/logger/index.d.ts
 create mode 100644 src/logger/index.js
 create mode 100644 src/logger/logger-transport.js
 create mode 100644 src/logger/pending-queue.js
 create mode 100644 tests/types/logger.test-d.ts
 create mode 100644 tests/unit/logger-pending-queue.test.js
 create mode 100644 tests/unit/logger-transport.test.js
 create mode 100644 tests/unit/logger.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 375e219..ab0a5bf 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 4
+      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 4 --max-gzip-logger 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/package.json b/package.json
index 2b6a048..c522c77 100644
--- a/package.json
+++ b/package.json
@@ -83,6 +83,10 @@
     "./otel": {
       "types": "./src/otel/index.d.ts",
       "default": "./src/otel/index.js"
+    },
+    "./logger": {
+      "types": "./src/logger/index.d.ts",
+      "default": "./src/logger/index.js"
     }
   },
   "directories": {
@@ -157,6 +161,7 @@
     "esbuild": "^0.28.2",
     "oxfmt": "^0.72.0",
     "oxlint": "^1.75.0",
+    "pino": "^10.4.0",
     "postal-mime": "^3.0.1",
     "tsd": "^0.33.0",
     "typescript": "^7.0.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 060898b..f521b7c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -44,6 +44,9 @@ importers:
       oxlint:
         specifier: ^1.75.0
         version: 1.88.0
+      pino:
+        specifier: ^10.4.0
+        version: 10.4.0
       postal-mime:
         specifier: ^3.0.1
         version: 3.0.1
@@ -806,6 +809,9 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@pinojs/redact@0.4.0':
+    resolution: {integrity: sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==}
+
   '@rollup/rollup-android-arm-eabi@4.64.6':
     resolution: {integrity: sha512-FkO19Fowv/OQeJZPVfdetJaI3/VpbZmBsnmAlR/rQ+b3QwfiGQiOpVegpSRH331kelvHTVw9hXYG3DwjAaRzyQ==}
     cpu: [arm]
@@ -1321,6 +1327,10 @@ packages:
     resolution: {integrity: sha512-3CYzex9M9FGQjCGMGyi6/31c8GJbgb0qGyrx5HWxPd0aCwh4cB2YjMb2Xf9UuoogrMrlO9cTqnB5rI5GHZTcUA==}
     engines: {node: '>=0.10.0'}
 
+  atomic-sleep@1.0.0:
+    resolution: {integrity: sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==}
+    engines: {node: '>=8.0.0'}
+
   balanced-match@4.0.4:
     resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
     engines: {node: 18 || 20 || >=22}
@@ -1731,6 +1741,10 @@ packages:
     resolution: {integrity: sha512-p2W1sgqij3zMMyRC067Dg16bfzVH+w7hyegmpIvZ4JNjqtGOVAIvLmjBx3yP7YTe9vKJgkoNOPjwQGogDoMXFA==}
     engines: {node: '>=10'}
 
+  on-exit-leak-free@2.1.2:
+    resolution: {integrity: sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==}
+    engines: {node: '>=14.0.0'}
+
   oniguruma-to-es@3.1.1:
     resolution: {integrity: sha512-bUH8SDvPkH3ho3dvwJwfonjlQ4R80vjyvrU8YpxuROddv55vAEJrTuCuCVUhhsHbtlD9tGGbaNApGQckXhS8iQ==}
 
@@ -1813,6 +1827,16 @@ packages:
     resolution: {integrity: sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==}
     engines: {node: '>=8.6'}
 
+  pino-abstract-transport@3.0.0:
+    resolution: {integrity: sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg==}
+
+  pino-std-serializers@7.1.0:
+    resolution: {integrity: sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw==}
+
+  pino@10.4.0:
+    resolution: {integrity: sha512-bk1ZMTwG/Vymx+zPoa28MhNzucFvXJWp3csrSuxuHPSMeUettaCoQ5Jvg07mtC4JGNpcfTwz41oVCnNgBK9+vA==}
+    hasBin: true
+
   plur@4.0.0:
     resolution: {integrity: sha512-4UGewrYgqDFw9vV6zNV+ADmPAUAfJPKtGvb/VdpQAx25X5f3xXdGdyOEVFwkl8Hl/tl7+xbeHqSEM+D5/TirUg==}
     engines: {node: '>=10'}
@@ -1836,12 +1860,18 @@ packages:
     resolution: {integrity: sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==}
     engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
 
+  process-warning@5.1.1:
+    resolution: {integrity: sha512-oCkNVj4OKnKEcocVBcDfiIugN1/cE6rgfT3nCtzeqZPA8+rIxMaQ0xXzIkGP8Gj2qUaP1UR7uhJ1VD8lUCpzCg==}
+
   property-information@7.2.0:
     resolution: {integrity: sha512-IAtzIB6sUiWaJYrX9smp3V46pBGbBeLFRGdh25kg1334VcBlD8HzhPeNIWQH9zhGmo2itIe25EHt9dQP7G5hmg==}
 
   queue-microtask@1.2.3:
     resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
 
+  quick-format-unescaped@4.0.4:
+    resolution: {integrity: sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==}
+
   quick-lru@4.0.1:
     resolution: {integrity: sha512-ARhCpm70fzdcvNQfPoy49IaanKkTlRWF2JMzqhcJbhSFRZv7nPTvZJdcY7301IPmvW+/p0RgIWnQDLJxifsQ7g==}
     engines: {node: '>=8'}
@@ -1857,6 +1887,9 @@ packages:
     resolution: {integrity: sha512-Ug69mNOpfvKDAc2Q8DRpMjjzdtrnv9HcSMX+4VsZxD1aZ6ZzrIE7rlzXBtWTyhULSMKg076AW6WR5iZpD0JiOg==}
     engines: {node: '>=8'}
 
+  real-require@1.0.0:
+    resolution: {integrity: sha512-P4nbQYQfePJxRSmY+v/KINxVucm4NF3p3s7pJveMTtom52FR4YGltUQLB8idDXwDDWW+eYrWDFbuzUnjoWHF7g==}
+
   redent@3.0.0:
     resolution: {integrity: sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==}
     engines: {node: '>=8'}
@@ -1890,6 +1923,10 @@ packages:
   run-parallel@1.2.0:
     resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
 
+  safe-stable-stringify@2.5.0:
+    resolution: {integrity: sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA==}
+    engines: {node: '>=10'}
+
   search-insights@2.17.3:
     resolution: {integrity: sha512-RQPdCYTa8A68uM2jwxoY842xDhvx3E5LFL1LxvxCNMev4o5mLuokczhzjAgGwUZBAmOKZknArSxLKmXtIi2AxQ==}
 
@@ -1921,6 +1958,9 @@ packages:
     resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==}
     engines: {node: '>=8'}
 
+  sonic-boom@4.2.1:
+    resolution: {integrity: sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==}
+
   source-map-js@1.2.2:
     resolution: {integrity: sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==}
     engines: {node: '>=0.10.0'}
@@ -1944,6 +1984,10 @@ packages:
     resolution: {integrity: sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ==}
     engines: {node: '>=0.10.0'}
 
+  split2@4.2.0:
+    resolution: {integrity: sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==}
+    engines: {node: '>= 10.x'}
+
   string-width@4.2.3:
     resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
     engines: {node: '>=8'}
@@ -1994,6 +2038,10 @@ packages:
     resolution: {integrity: sha512-ZOffsNrXYggvU1mDGHk54I96r26P8SyMjO5slMKSc7+IWmtB/MQKnEC2fP51imB3/pT6YK5cT5E8f+Dd9KdyOQ==}
     engines: {node: 20 || >=22}
 
+  thread-stream@4.2.0:
+    resolution: {integrity: sha512-e2zZ96wSChazBsbENf/Pcm/4swHt2cEKQ92rhUjkL9GCKiTDJIaTBenjE/m9DXi0QBmTMDkFDdOomUy20A1tDQ==}
+    engines: {node: '>=20'}
+
   tinypool@2.2.0:
     resolution: {integrity: sha512-jBrmx4lYmaC9k/mgPbylxs7kBUxHtD8256up+HjLaDFfXScKJQyil+SWXSvhAtT7XHo+yTVlpB81PGmHP8oLSQ==}
     engines: {node: ^20.0.0 || >=22.0.0}
@@ -2644,6 +2692,8 @@ snapshots:
   '@oxlint/binding-win32-x64-msvc@1.88.0':
     optional: true
 
+  '@pinojs/redact@0.4.0': {}
+
   '@rollup/rollup-android-arm-eabi@4.64.6':
     optional: true
 
@@ -3010,6 +3060,8 @@ snapshots:
 
   arrify@1.0.1: {}
 
+  atomic-sleep@1.0.0: {}
+
   balanced-match@4.0.4: {}
 
   birpc@2.9.0: {}
@@ -3463,6 +3515,8 @@ snapshots:
       semver: 7.8.5
       validate-npm-package-license: 3.0.4
 
+  on-exit-leak-free@2.1.2: {}
+
   oniguruma-to-es@3.1.1:
     dependencies:
       emoji-regex-xs: 1.0.0
@@ -3559,6 +3613,26 @@ snapshots:
 
   picomatch@2.3.2: {}
 
+  pino-abstract-transport@3.0.0:
+    dependencies:
+      split2: 4.2.0
+
+  pino-std-serializers@7.1.0: {}
+
+  pino@10.4.0:
+    dependencies:
+      '@pinojs/redact': 0.4.0
+      atomic-sleep: 1.0.0
+      on-exit-leak-free: 2.1.2
+      pino-abstract-transport: 3.0.0
+      pino-std-serializers: 7.1.0
+      process-warning: 5.1.1
+      quick-format-unescaped: 4.0.4
+      real-require: 1.0.0
+      safe-stable-stringify: 2.5.0
+      sonic-boom: 4.2.1
+      thread-stream: 4.2.0
+
   plur@4.0.0:
     dependencies:
       irregular-plurals: 3.5.0
@@ -3579,10 +3653,14 @@ snapshots:
       ansi-styles: 5.2.0
       react-is: 18.3.1
 
+  process-warning@5.1.1: {}
+
   property-information@7.2.0: {}
 
   queue-microtask@1.2.3: {}
 
+  quick-format-unescaped@4.0.4: {}
+
   quick-lru@4.0.1: {}
 
   react-is@18.3.1: {}
@@ -3600,6 +3678,8 @@ snapshots:
       parse-json: 5.2.0
       type-fest: 0.6.0
 
+  real-require@1.0.0: {}
+
   redent@3.0.0:
     dependencies:
       indent-string: 4.0.0
@@ -3662,6 +3742,8 @@ snapshots:
     dependencies:
       queue-microtask: 1.2.3
 
+  safe-stable-stringify@2.5.0: {}
+
   search-insights@2.17.3: {}
 
   semver@5.7.2: {}
@@ -3689,6 +3771,10 @@ snapshots:
 
   slash@3.0.0: {}
 
+  sonic-boom@4.2.1:
+    dependencies:
+      atomic-sleep: 1.0.0
+
   source-map-js@1.2.2: {}
 
   space-separated-tokens@2.0.2: {}
@@ -3709,6 +3795,8 @@ snapshots:
 
   speakingurl@14.0.1: {}
 
+  split2@4.2.0: {}
+
   string-width@4.2.3:
     dependencies:
       emoji-regex: 8.0.0
@@ -3766,6 +3854,10 @@ snapshots:
       glob: 13.0.6
       minimatch: 10.2.6
 
+  thread-stream@4.2.0:
+    dependencies:
+      real-require: 1.0.0
+
   tinypool@2.2.0: {}
 
   to-regex-range@5.0.1:
diff --git a/src/logger/config.js b/src/logger/config.js
new file mode 100644
index 0000000..c48f03d
--- /dev/null
+++ b/src/logger/config.js
@@ -0,0 +1,46 @@
+// Ported from upyo v0.7.0 (packages/logtape/src/config.ts), adapted to a
+// pino-like logger passed in: pino's level names, and no LogTape category.
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/** The level names of pino (LogTape's `warning` is pino's `warn`). */
+const LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+
+/**
+ * Resolves logger transport options with their defaults.
+ *
+ * @param options User-provided transport options.
+ * @returns Fully resolved transport options.
+ * @throws {TypeError} If the logger is missing, a level is not one of pino's,
+ *                     or the logger has no method for a configured level.
+ */
+const resolveLoggerTransportOptions = (options) => {
+  const { logger } = options;
+  if (logger == null || (typeof logger !== 'object' && typeof logger !== 'function')) {
+    throw new TypeError(
+      'Expected a logger: an object with a method per level, such as a pino logger.',
+    );
+  }
+  const levels = {
+    sending: options.levels?.sending ?? 'debug',
+    sent: options.levels?.sent ?? 'info',
+    failed: options.levels?.failed ?? 'error',
+  };
+  for (const [event, level] of Object.entries(levels)) {
+    if (!LEVELS.includes(level)) {
+      throw new TypeError(
+        `Expected levels.${event} to be one of ${LEVELS.join(', ')}: ${JSON.stringify(level)}`,
+      );
+    }
+    if (typeof logger[level] !== 'function') {
+      throw new TypeError(`Expected the logger to have a ${level}() method for levels.${event}.`);
+    }
+  }
+  return {
+    transport: options.transport,
+    logger,
+    recordMessage: options.recordMessage ?? false,
+    levels,
+  };
+};
+
+module.exports = { resolveLoggerTransportOptions };
diff --git a/src/logger/index.d.ts b/src/logger/index.d.ts
new file mode 100644
index 0000000..e89ac91
--- /dev/null
+++ b/src/logger/index.d.ts
@@ -0,0 +1,187 @@
+// Types ported from upyo v0.7.0 (packages/logtape/src), adapted to a pino-like
+// logger passed in instead of LogTape.
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/// <reference lib="esnext.disposable" />
+
+import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+
+/**
+ * A log level, by pino's names (LogTape's `warning` is `warn`).
+ */
+export type LoggerLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+/**
+ * A log method that takes the structured properties first and the message
+ * second, as pino's do.
+ */
+export type LogMethod = (properties: object, message: string) => unknown;
+
+/**
+ * The logger the transport writes to: a pino logger, a child of one
+ * (`logger.child({ component: 'mail' })`), or anything with the methods of the
+ * levels in use. `debug`, `info` and `error` are the default levels.
+ */
+export interface Logger {
+  readonly trace?: LogMethod;
+  readonly debug?: LogMethod;
+  readonly info?: LogMethod;
+  readonly warn?: LogMethod;
+  readonly error?: LogMethod;
+  readonly fatal?: LogMethod;
+}
+
+/**
+ * Log levels used for email delivery lifecycle events.
+ */
+export interface LoggerTransportLevels {
+  /**
+   * Level used before an email is handed to the transport.
+   *
+   * @default "debug"
+   */
+  readonly sending?: LoggerLevel;
+  /**
+   * Level used after an email is sent successfully.
+   *
+   * @default "info"
+   */
+  readonly sent?: LoggerLevel;
+  /**
+   * Level used when a transport returns a failed receipt or throws.
+   *
+   * @default "error"
+   */
+  readonly failed?: LoggerLevel;
+}
+
+/**
+ * Options for {@link LoggerTransport}.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport.
+ */
+export interface LoggerTransportOptions<TProviderId extends string = 'logger'> {
+  /**
+   * The logger to write to. It must have a method for each configured level;
+   * the transport checks that when it is made.
+   */
+  readonly logger: Logger;
+  /**
+   * Transport that performs the actual delivery.
+   *
+   * When omitted, the logger transport only logs the delivery and returns a
+   * synthetic successful receipt.
+   */
+  readonly transport?: Transport<TProviderId>;
+  /**
+   * How to include the complete email message in logs.
+   *
+   * `"properties"` adds the message to the structured properties while
+   * keeping the lifecycle message on one line.  `"inline"` also renders the
+   * subject and body beneath the lifecycle message.  Plain text is preferred
+   * when it is defined; otherwise, the HTML body is rendered.
+   *
+   * Messages may contain sensitive or large values, including email bodies,
+   * headers, and attachment data.
+   *
+   * @default undefined
+   */
+  readonly recordMessage?: 'properties' | 'inline';
+  /**
+   * Levels used for delivery lifecycle events.
+   */
+  readonly levels?: LoggerTransportLevels;
+}
+
+/**
+ * Fully resolved options used by {@link LoggerTransport}.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport.
+ */
+export interface ResolvedLoggerTransportOptions<TProviderId extends string = 'logger'> {
+  /** The logger written to. */
+  readonly logger: Logger;
+  /** Transport that performs the actual delivery, if configured. */
+  readonly transport?: Transport<TProviderId>;
+  /** Resolved complete-message recording mode, or `false` when disabled. */
+  readonly recordMessage: 'properties' | 'inline' | false;
+  /** Resolved delivery lifecycle log levels. */
+  readonly levels: Required<LoggerTransportLevels>;
+}
+
+type LoggerTransportConstructorArguments<TProviderId extends string> = [TProviderId] extends [
+  'logger',
+]
+  ? [options: LoggerTransportOptions<TProviderId>]
+  : [
+      options: LoggerTransportOptions<TProviderId> & {
+        readonly transport: Transport<TProviderId>;
+      },
+    ];
+
+/**
+ * Transport that records email delivery lifecycle events through a logger the
+ * application passes in: any pino-like logger whose methods take the
+ * properties first and the message second (`logger.info(properties, message)`).
+ * The events are `email.sending`, `email.sent` and `email.failed`; a thrown
+ * error is logged under `err`, the key pino serializes.
+ *
+ * With no wrapped transport, this class acts as a log-only transport and
+ * returns synthetic successful receipts.  When a transport is supplied, it
+ * decorates that transport without changing its receipts or thrown errors.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport, or
+ *                        `"logger"` in log-only mode.
+ */
+export declare class LoggerTransport<TProviderId extends string = 'logger'>
+  implements Transport<TProviderId>, AsyncDisposable
+{
+  /** Provider id used by receipts from this transport. */
+  readonly id: TProviderId;
+  /** Fully resolved transport options. */
+  readonly config: ResolvedLoggerTransportOptions<TProviderId>;
+  /**
+   * Creates a logger transport.
+   *
+   * @param options The logger, and optional wrapped transport and logging
+   *                configuration.
+   * @throws {TypeError} If the logger is missing, or has no method for a
+   *                     configured level.
+   */
+  constructor(...[options]: LoggerTransportConstructorArguments<TProviderId>);
+  /**
+   * Sends one email while recording its delivery lifecycle.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options, including cancellation.
+   * @returns The wrapped transport receipt, or a synthetic successful receipt
+   *          in log-only mode.
+   * @throws {DOMException} If the operation is aborted.
+   * @throws {Error} If the wrapped transport throws an error.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
+  /**
+   * Sends multiple emails while recording each delivery lifecycle.
+   *
+   * A wrapped transport's `sendMany()` implementation is used directly so
+   * provider-specific batching and streaming behavior are preserved.
+   * Completion logs are emitted as receipts are consumed.  Stopping iteration
+   * early closes the wrapped iterator without draining it, preserving its
+   * cancellation behavior.
+   *
+   * @param messages Email messages to send.
+   * @param options Optional transport options, including cancellation.
+   * @returns An async iterable of unmodified delivery receipts.
+   * @throws {DOMException} If the operation is aborted.
+   * @throws {Error} If the wrapped transport throws an error.
+   */
+  sendMany(
+    messages: Iterable<Message> | AsyncIterable<Message>,
+    options?: TransportOptions,
+  ): AsyncIterable<Receipt<TProviderId>>;
+  /**
+   * Disposes the wrapped transport when it supports explicit resource
+   * management.
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+}
diff --git a/src/logger/index.js b/src/logger/index.js
new file mode 100644
index 0000000..b0b53ce
--- /dev/null
+++ b/src/logger/index.js
@@ -0,0 +1,13 @@
+// Ported from upyo v0.7.0 (packages/logtape/src/index.ts), as ./logger.
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * @alexify/mailer/logger - the delivery lifecycle of email, logged through a
+ * pino-like logger the application passes in.
+ *
+ * @module
+ */
+
+const { LoggerTransport } = require('./logger-transport.js');
+
+module.exports = { LoggerTransport };
diff --git a/src/logger/logger-transport.js b/src/logger/logger-transport.js
new file mode 100644
index 0000000..e3a3a73
--- /dev/null
+++ b/src/logger/logger-transport.js
@@ -0,0 +1,302 @@
+// Ported from upyo v0.7.0 (packages/logtape/src/logtape-transport.ts), adapted to
+// a pino-like logger passed in instead of LogTape's getLogger(category).
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { inspect } = require('node:util');
+const { resolveLoggerTransportOptions } = require('./config.js');
+const { PendingQueue } = require('./pending-queue.js');
+
+/**
+ * Transport that records email delivery lifecycle events through a logger the
+ * application passes in: any pino-like logger whose methods take the
+ * properties first and the message second (`logger.info(properties, message)`).
+ *
+ * With no wrapped transport, this class acts as a log-only transport and
+ * returns synthetic successful receipts.  When a transport is supplied, it
+ * decorates that transport without changing its receipts or thrown errors.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport, or
+ *                        `"logger"` in log-only mode.
+ */
+class LoggerTransport {
+  /** Provider id used by receipts from this transport. */
+  id;
+
+  /** Fully resolved transport options. */
+  config;
+
+  logger;
+  wrappedTransport;
+
+  /**
+   * Creates a logger transport.
+   *
+   * @param options The logger, and optional wrapped transport and logging
+   *                configuration.
+   * @throws {TypeError} If the logger is missing, or has no method for a
+   *                     configured level.
+   */
+  constructor(options) {
+    this.config = resolveLoggerTransportOptions(options ?? {});
+    this.wrappedTransport = this.config.transport;
+    this.id = this.wrappedTransport?.id ?? 'logger';
+    this.logger = this.config.logger;
+  }
+
+  /**
+   * Sends one email while recording its delivery lifecycle.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options, including cancellation.
+   * @returns The wrapped transport receipt, or a synthetic successful receipt
+   *          in log-only mode.
+   * @throws {DOMException} If the operation is aborted.
+   * @throws {Error} If the wrapped transport throws an error.
+   */
+  send(message, options) {
+    return this.sendOne(message, options, 'send');
+  }
+
+  /**
+   * Sends multiple emails while recording each delivery lifecycle.
+   *
+   * A wrapped transport's `sendMany()` implementation is used directly so
+   * provider-specific batching and streaming behavior are preserved.
+   * Completion logs are emitted as receipts are consumed.  Stopping iteration
+   * early closes the wrapped iterator without draining it, preserving its
+   * cancellation behavior.
+   *
+   * @param messages Email messages to send.
+   * @param options Optional transport options, including cancellation.
+   * @returns An async iterable of unmodified delivery receipts.
+   * @throws {DOMException} If the operation is aborted.
+   * @throws {Error} If the wrapped transport throws an error.
+   */
+  async *sendMany(messages, options) {
+    options?.signal?.throwIfAborted();
+
+    if (this.wrappedTransport == null) {
+      for await (const message of messages) {
+        yield await this.sendOne(message, options, 'sendMany');
+      }
+      return;
+    }
+
+    const pending = new PendingQueue();
+    const batchStartedAt = performance.now();
+    let consumedCount = 0;
+    let completedCount = 0;
+    const observedMessages = this.observeMessages(
+      messages,
+      pending,
+      options,
+      () => consumedCount++,
+    );
+
+    try {
+      for await (const receipt of this.wrappedTransport.sendMany(observedMessages, options)) {
+        const current = pending.dequeue();
+        completedCount++;
+        this.logReceipt(receipt, current, 'sendMany');
+        yield receipt;
+      }
+    } catch (error) {
+      this.logBatchThrownError(error, pending, batchStartedAt, consumedCount, completedCount);
+      throw error;
+    }
+  }
+
+  /**
+   * Disposes the wrapped transport when it supports explicit resource
+   * management.
+   */
+  async [Symbol.asyncDispose]() {
+    const transport = this.wrappedTransport;
+    if (transport == null) return;
+
+    if (isAsyncDisposable(transport)) {
+      await transport[Symbol.asyncDispose]();
+      return;
+    }
+
+    if (isDisposable(transport)) {
+      transport[Symbol.dispose]();
+    }
+  }
+
+  async sendOne(message, options, operation) {
+    options?.signal?.throwIfAborted();
+    const startedAt = performance.now();
+    this.logSending(message, operation);
+
+    try {
+      const receipt =
+        this.wrappedTransport == null
+          ? this.createSyntheticReceipt()
+          : await this.wrappedTransport.send(message, options);
+      this.logReceipt(receipt, { message, startedAt }, operation);
+      return receipt;
+    } catch (error) {
+      this.logThrownError(error, message, operation, startedAt);
+      throw error;
+    }
+  }
+  async *observeMessages(messages, pending, options, onConsume) {
+    for await (const message of messages) {
+      options?.signal?.throwIfAborted();
+      const startedAt = performance.now();
+      this.logSending(message, 'sendMany');
+      pending.enqueue({ message, startedAt });
+      onConsume();
+      yield message;
+    }
+  }
+
+  createSyntheticReceipt() {
+    return {
+      successful: true,
+      messageId: `logger-${crypto.randomUUID()}`,
+      provider: this.id,
+      attempts: 1,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  logSending(message, operation) {
+    this.log(this.config.levels.sending, this.getMessageText('Sending email.', message), {
+      ...this.getMessageProperties(message),
+      event: 'email.sending',
+      operation,
+      transportId: this.id,
+    });
+  }
+
+  logReceipt(receipt, pendingMessage, operation) {
+    const durationMilliseconds =
+      pendingMessage == null ? undefined : performance.now() - pendingMessage.startedAt;
+    const messageProperties =
+      pendingMessage == null ? {} : this.getMessageProperties(pendingMessage.message);
+
+    if (receipt.successful) {
+      this.log(
+        this.config.levels.sent,
+        this.getMessageText('Email sent.', pendingMessage?.message),
+        {
+          ...messageProperties,
+          event: 'email.sent',
+          operation,
+          transportId: this.id,
+          durationMilliseconds,
+          messageId: receipt.messageId,
+          provider: receipt.provider ?? this.id,
+          receipt,
+        },
+      );
+      return;
+    }
+
+    this.log(
+      this.config.levels.failed,
+      this.getMessageText('Failed to send email.', pendingMessage?.message),
+      {
+        ...messageProperties,
+        event: 'email.failed',
+        operation,
+        transportId: this.id,
+        durationMilliseconds,
+        errorMessages: receipt.errorMessages,
+        errors: receipt.errors,
+        retryable: receipt.retryable,
+        provider: receipt.provider ?? this.id,
+        attempts: receipt.attempts,
+        receipt,
+      },
+    );
+  }
+
+  logThrownError(error, message, operation, startedAt, extraProperties = {}) {
+    this.log(
+      this.config.levels.failed,
+      this.getMessageText(`Failed to send email: ${describe(error)}`, message),
+      {
+        ...(message == null ? {} : this.getMessageProperties(message)),
+        ...extraProperties,
+        event: 'email.failed',
+        operation,
+        transportId: this.id,
+        durationMilliseconds: performance.now() - startedAt,
+        // pino serializes an error under `err` only; under another key an
+        // Error comes out as {}.
+        err: error,
+      },
+    );
+  }
+
+  logBatchThrownError(error, pending, batchStartedAt, consumedCount, completedCount) {
+    const batchProperties = {
+      consumedCount,
+      completedCount,
+      pendingCount: pending.size,
+    };
+    if (pending.size < 1) {
+      this.logThrownError(error, undefined, 'sendMany', batchStartedAt, batchProperties);
+      return;
+    }
+
+    for (const pendingMessage of pending) {
+      this.logThrownError(
+        error,
+        pendingMessage.message,
+        'sendMany',
+        pendingMessage.startedAt,
+        batchProperties,
+      );
+    }
+  }
+
+  getMessageProperties(message) {
+    return {
+      recipientCount: message.recipients.length,
+      ccRecipientCount: message.ccRecipients.length,
+      bccRecipientCount: message.bccRecipients.length,
+      attachmentCount: message.attachments.length,
+      priority: message.priority,
+      ...(this.config.recordMessage === false ? {} : { message }),
+    };
+  }
+
+  // LogTape interpolated the {message.subject} and {message.content.*}
+  // placeholders of a template; a pino-like logger does not, so the text is
+  // built here.
+  getMessageText(lifecycleMessage, message) {
+    if (this.config.recordMessage !== 'inline' || message == null) {
+      return lifecycleMessage;
+    }
+
+    const content =
+      'text' in message.content && message.content.text !== undefined
+        ? message.content.text
+        : message.content.html;
+    return `${lifecycleMessage}\n\nSubject: ${message.subject}\n\n${content}`;
+  }
+
+  // The properties first and the message second, as pino takes them.
+  log(level, message, properties) {
+    this.logger[level](properties, message);
+  }
+}
+
+const isAsyncDisposable = (value) => {
+  return Symbol.asyncDispose in value && typeof value[Symbol.asyncDispose] === 'function';
+};
+
+const isDisposable = (value) => {
+  return Symbol.dispose in value && typeof value[Symbol.dispose] === 'function';
+};
+
+// What LogTape rendered for {error}: an Error as "TypeError: message", any
+// other value inspected.
+const describe = (value) =>
+  value instanceof Error ? `${value.name}: ${value.message}` : inspect(value);
+
+module.exports = { LoggerTransport };
diff --git a/src/logger/pending-queue.js b/src/logger/pending-queue.js
new file mode 100644
index 0000000..e575d35
--- /dev/null
+++ b/src/logger/pending-queue.js
@@ -0,0 +1,64 @@
+// Ported from upyo v0.7.0 (packages/logtape/src/pending-queue.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+/**
+ * Internal linked FIFO queue for messages awaiting delivery receipts.
+ *
+ * Both enqueue and dequeue operations take constant time, without retaining
+ * references to values that have already been dequeued.
+ *
+ * @typeParam T The queued value type.
+ */
+class PendingQueue {
+  head;
+  tail;
+  valueCount = 0;
+
+  /** Number of values waiting in the queue. */
+  get size() {
+    return this.valueCount;
+  }
+
+  /**
+   * Adds a value to the end of the queue.
+   *
+   * @param value The value to enqueue.
+   */
+  enqueue(value) {
+    const node = { value };
+    if (this.tail == null) {
+      this.head = node;
+    } else {
+      this.tail.next = node;
+    }
+    this.tail = node;
+    this.valueCount++;
+  }
+
+  /**
+   * Removes and returns the value at the front of the queue.
+   *
+   * @returns The first queued value, or `undefined` when the queue is empty.
+   */
+  dequeue() {
+    const node = this.head;
+    if (node == null) return undefined;
+
+    this.head = node.next;
+    node.next = undefined;
+    this.valueCount--;
+    if (this.head == null) this.tail = undefined;
+    return node.value;
+  }
+
+  /** Iterates over queued values without removing them. */
+  *[Symbol.iterator]() {
+    let node = this.head;
+    while (node != null) {
+      yield node.value;
+      node = node.next;
+    }
+  }
+}
+
+module.exports = { PendingQueue };
diff --git a/tests/types/logger.test-d.ts b/tests/types/logger.test-d.ts
new file mode 100644
index 0000000..0bd52cd
--- /dev/null
+++ b/tests/types/logger.test-d.ts
@@ -0,0 +1,42 @@
+import pino from 'pino';
+import { expectAssignable, expectError, expectType } from 'tsd';
+import { createMessage, type Receipt, type Transport } from '../../index.js';
+import { MockTransport } from '../../src/mock/index.js';
+import {
+  LoggerTransport,
+  type Logger,
+  type LoggerTransportOptions,
+} from '../../src/logger/index.js';
+
+// A pino logger, and a child of one, fit the structural type.
+const logger = pino();
+expectAssignable<Logger>(logger);
+expectAssignable<Logger>(logger.child({ component: 'mail' }));
+
+const logOnly = new LoggerTransport({ logger });
+expectType<'logger'>(logOnly.id);
+expectAssignable<Transport<'logger'>>(logOnly);
+expectAssignable<AsyncDisposable>(logOnly);
+
+const decorated = new LoggerTransport({
+  logger,
+  transport: new MockTransport(),
+  recordMessage: 'properties',
+  levels: { sending: 'trace', sent: 'warn', failed: 'fatal' },
+});
+expectAssignable<Transport<'mock'>>(decorated);
+
+const message = createMessage({
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+});
+expectType<Promise<Receipt<'mock'>>>(decorated.send(message));
+
+// Upstream's type-level checks: a provider id needs a wrapped transport, and
+// recordMessage is not a boolean.
+expectError(new LoggerTransport<'base'>({ logger }));
+expectError(new LoggerTransport({ logger, recordMessage: true }));
+expectError(new LoggerTransport({}));
+expectError<LoggerTransportOptions>({ logger, levels: { sent: 'warning' } });
diff --git a/tests/unit/logger-pending-queue.test.js b/tests/unit/logger-pending-queue.test.js
new file mode 100644
index 0000000..64bc218
--- /dev/null
+++ b/tests/unit/logger-pending-queue.test.js
@@ -0,0 +1,33 @@
+// Ported from upyo v0.7.0 (packages/logtape/src/pending-queue.test.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { strict: assert } = require('node:assert');
+const { describe, it } = require('node:test');
+const { PendingQueue } = require('../../src/logger/pending-queue.js');
+
+describe('PendingQueue', () => {
+  it('dequeues values in constant-time FIFO order', () => {
+    const queue = new PendingQueue();
+
+    for (let value = 0; value < 10_000; value++) {
+      queue.enqueue(value);
+    }
+
+    for (let value = 0; value < 10_000; value++) {
+      assert.equal(queue.dequeue(), value);
+    }
+    assert.equal(queue.size, 0);
+    assert.equal(queue.dequeue(), undefined);
+  });
+
+  it('iterates only values that have not been dequeued', () => {
+    const queue = new PendingQueue();
+    queue.enqueue('first');
+    queue.enqueue('second');
+    queue.enqueue('third');
+
+    assert.equal(queue.dequeue(), 'first');
+    assert.deepEqual([...queue], ['second', 'third']);
+    assert.equal(queue.size, 2);
+  });
+});
diff --git a/tests/unit/logger-transport.test.js b/tests/unit/logger-transport.test.js
new file mode 100644
index 0000000..cb61c0b
--- /dev/null
+++ b/tests/unit/logger-transport.test.js
@@ -0,0 +1,752 @@
+// Ported from upyo v0.7.0 (packages/logtape/src/logtape-transport.test.ts), adapted
+// to ./logger: a recording pino-like logger replaces LogTape's recorder, the
+// message is the rendered text (no LogTape template), an error is under `err`,
+// and the levels are pino's.
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+
+const { strict: assert } = require('node:assert');
+const { describe, it } = require('node:test');
+const { createFailedReceipt } = require('../../src/core/receipt.js');
+const { createMessage } = require('../../src/core/message.js');
+const { LoggerTransport } = require('../../src/logger/logger-transport.js');
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: ['first@example.net', 'second@example.net'],
+  cc: 'copy@example.net',
+  bcc: 'blind-copy@example.net',
+  subject: 'Test message',
+  content: { text: 'Hello from Upyo.' },
+  priority: 'high',
+  attachments: [
+    {
+      inline: false,
+      filename: 'hello.txt',
+      contentType: 'text/plain',
+      content: new TextEncoder().encode('Hello.'),
+      contentId: 'hello@example.com',
+    },
+  ],
+});
+// The type-level checks of upstream (a provider id needs a wrapped transport,
+// recordMessage is not a boolean) are in tests/types/logger.test-d.ts.
+
+describe('LoggerTransport', () => {
+  it('logs standalone sends and returns a synthetic receipt', async () => {
+    await withRecorder(async (recorder) => {
+      const transport = new LoggerTransport({ logger: recorder.logger });
+      const typedTransport = transport;
+
+      const receipt = await typedTransport.send(message);
+
+      assert.ok(receipt.successful);
+      assert.match(receipt.messageId, /^logger-[0-9a-f-]+$/);
+      assert.equal(receipt.provider, 'logger');
+      assert.equal(receipt.attempts, 1);
+      assert.ok(receipt.timestamp != null);
+      assert.equal(transport.id, 'logger');
+      assert.equal(transport.config.recordMessage, false);
+      assert.equal(recorder.records.length, 2);
+      recorder.assertLogged({
+        level: 'debug',
+        message: 'Sending email.',
+        properties: {
+          event: 'email.sending',
+          operation: 'send',
+          transportId: 'logger',
+          recipientCount: 2,
+          ccRecipientCount: 1,
+          bccRecipientCount: 1,
+          attachmentCount: 1,
+          priority: 'high',
+        },
+      });
+      recorder.assertLogged({
+        level: 'info',
+        message: 'Email sent.',
+        properties: {
+          event: 'email.sent',
+          operation: 'send',
+          transportId: 'logger',
+          messageId: receipt.messageId,
+          provider: 'logger',
+        },
+      });
+      assert.ok(recorder.records.every((record) => !('message' in record.properties)));
+    });
+  });
+
+  it('supports custom categories, levels, and full message recording', async () => {
+    await withRecorder(async (recorder) => {
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        recordMessage: 'properties',
+        levels: {
+          sending: 'trace',
+          sent: 'warn',
+          failed: 'fatal',
+        },
+      });
+
+      await transport.send(message);
+
+      recorder.assertLogged({
+        level: 'trace',
+        message: 'Sending email.',
+        properties: { event: 'email.sending', message },
+      });
+      recorder.assertLogged({
+        level: 'warn',
+        message: 'Email sent.',
+        properties: { event: 'email.sent', message },
+      });
+    });
+  });
+
+  it('renders message subjects and text content inline', async () => {
+    await withRecorder(async (recorder) => {
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        recordMessage: 'inline',
+      });
+
+      await transport.send(message);
+
+      recorder.assertLogged({
+        message: /^Sending email\.\n\nSubject: Test message\n\nHello from Upyo\.$/,
+        properties: { event: 'email.sending', message },
+      });
+      recorder.assertLogged({
+        message: /^Email sent\.\n\nSubject: Test message\n\nHello from Upyo\.$/,
+        properties: { event: 'email.sent', message },
+      });
+    });
+  });
+
+  it('renders failed receipts inline', async () => {
+    await withRecorder(async (recorder) => {
+      const base = new RecordingTransport();
+      base.nextReceipt = createFailedReceipt('Provider rejected the message.', {
+        provider: 'base',
+        category: 'rejected',
+        code: 'base.rejected',
+        retryable: false,
+      });
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+        recordMessage: 'inline',
+      });
+
+      await transport.send(message);
+
+      recorder.assertLogged({
+        message: /^Failed to send email\.\n\nSubject: Test message\n\nHello from Upyo\.$/,
+        properties: { event: 'email.failed', message },
+      });
+    });
+  });
+
+  it('uses HTML inline only when plain text is undefined', async () => {
+    await withRecorder(async (recorder) => {
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        recordMessage: 'inline',
+      });
+      const htmlMessage = createMessage({
+        from: 'sender@example.com',
+        to: 'recipient@example.net',
+        subject: 'HTML message',
+        content: { html: '<p>Hello from HTML.</p>', text: undefined },
+      });
+      const alternativeMessage = createMessage({
+        from: 'sender@example.com',
+        to: 'recipient@example.net',
+        subject: 'Alternative message',
+        content: { html: '<p>HTML alternative.</p>', text: '' },
+      });
+
+      await transport.send(htmlMessage);
+      await transport.send(alternativeMessage);
+
+      recorder.assertLogged({
+        message: /^Email sent\.\n\nSubject: HTML message\n\n<p>Hello from HTML\.<\/p>$/,
+        properties: { event: 'email.sent', message: htmlMessage },
+      });
+      recorder.assertLogged({
+        message: /^Email sent\.\n\nSubject: Alternative message\n\n$/,
+        properties: { event: 'email.sent', message: alternativeMessage },
+      });
+    });
+  });
+
+  it('decorates a transport without changing successful receipts', async () => {
+    await withRecorder(async (recorder) => {
+      const base = new RecordingTransport();
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+      });
+      const typedTransport = transport;
+      const controller = new AbortController();
+
+      const receipt = await typedTransport.send(message, {
+        signal: controller.signal,
+      });
+
+      assert.deepEqual(receipt, {
+        successful: true,
+        messageId: 'base-message-1',
+        provider: 'base',
+      });
+      assert.equal(transport.id, 'base');
+      assert.deepEqual(base.sentMessages, [message]);
+      assert.equal(base.lastOptions?.signal, controller.signal);
+      recorder.assertLogged({
+        level: 'info',
+        properties: {
+          event: 'email.sent',
+          transportId: 'base',
+          messageId: 'base-message-1',
+          provider: 'base',
+        },
+      });
+    });
+  });
+
+  it('logs and preserves failed receipts', async () => {
+    await withRecorder(async (recorder) => {
+      const base = new RecordingTransport();
+      base.nextReceipt = createFailedReceipt('Provider rejected the message.', {
+        provider: 'base',
+        category: 'rejected',
+        code: 'base.rejected',
+        retryable: false,
+      });
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+        levels: { failed: 'fatal' },
+      });
+
+      const receipt = await transport.send(message);
+
+      assert.ok(!receipt.successful);
+      assert.deepEqual(receipt.errorMessages, ['Provider rejected the message.']);
+      recorder.assertLogged({
+        level: 'fatal',
+        message: 'Failed to send email.',
+        properties: {
+          event: 'email.failed',
+          operation: 'send',
+          transportId: 'base',
+          errorMessages: receipt.errorMessages,
+          retryable: false,
+          provider: 'base',
+        },
+      });
+    });
+  });
+
+  it('logs thrown errors and rethrows the original value', async () => {
+    await withRecorder(async (recorder) => {
+      const base = new RecordingTransport();
+      const error = new TypeError('Transport failed.');
+      base.throwError = error;
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+      });
+
+      let thrown;
+      try {
+        await transport.send(message);
+      } catch (caught) {
+        thrown = caught;
+      }
+
+      assert.equal(thrown, error);
+      recorder.assertLogged({
+        level: 'error',
+        message: /Failed to send email/,
+        properties: {
+          event: 'email.failed',
+          operation: 'send',
+          transportId: 'base',
+          err: error,
+        },
+      });
+    });
+  });
+
+  it('delegates sendMany while logging each message and receipt', async () => {
+    await withRecorder(async (recorder) => {
+      const base = new RecordingTransport();
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+        recordMessage: 'inline',
+      });
+      const secondMessage = createMessage({
+        from: 'sender@example.com',
+        to: 'third@example.net',
+        subject: 'Second message',
+        content: { text: 'Another message.' },
+      });
+      const messages = async function* () {
+        yield message;
+        yield secondMessage;
+      };
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany(messages())) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(base.sendManyCalls, 1);
+      assert.equal(base.sendCalls, 0);
+      assert.deepEqual(base.sentMessages, [message, secondMessage]);
+      assert.deepEqual(
+        receipts.map((receipt) => receipt.successful && receipt.messageId),
+        ['base-batch-1', 'base-batch-2'],
+      );
+      assert.equal(recorder.filter({ properties: { event: 'email.sending' } }).length, 2);
+      assert.equal(recorder.filter({ properties: { event: 'email.sent' } }).length, 2);
+      assert.ok(recorder.records.every((record) => record.properties.operation === 'sendMany'));
+      assert.deepEqual(
+        recorder.records.map((record) => record.properties.message),
+        [message, message, secondMessage, secondMessage],
+      );
+      recorder.assertLogged({
+        message: /^Sending email\.\n\nSubject: Test message\n\nHello from Upyo\.$/,
+        properties: { event: 'email.sending', message },
+      });
+      recorder.assertLogged({
+        message: /^Email sent\.\n\nSubject: Test message\n\nHello from Upyo\.$/,
+        properties: { event: 'email.sent', message },
+      });
+      recorder.assertLogged({
+        message: /^Sending email\.\n\nSubject: Second message\n\nAnother message\.$/,
+        properties: { event: 'email.sending', message: secondMessage },
+      });
+      recorder.assertLogged({
+        message: /^Email sent\.\n\nSubject: Second message\n\nAnother message\.$/,
+        properties: { event: 'email.sent', message: secondMessage },
+      });
+    });
+  });
+
+  it('closes buffered receipts when the sendMany consumer stops early', async () => {
+    await withRecorder(async (recorder) => {
+      const secondMessage = createMessage({
+        from: 'sender@example.com',
+        to: 'third@example.net',
+        subject: 'Second message',
+        content: { text: 'Another message.' },
+      });
+      const base = new BufferedTransport();
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+      });
+
+      // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+      for await (const _receipt of transport.sendMany([message, secondMessage])) {
+        break;
+      }
+
+      assert.deepEqual(base.sentMessages, [message, secondMessage]);
+      assert.equal(base.yieldedReceiptCount, 1);
+      assert.equal(recorder.filter({ properties: { event: 'email.sent' } }).length, 1);
+    });
+  });
+
+  it('does not send more messages when a sequential consumer stops early', async () => {
+    await withRecorder(async (recorder) => {
+      const secondMessage = createMessage({
+        from: 'sender@example.com',
+        to: 'third@example.net',
+        subject: 'Second message',
+        content: { text: 'Another message.' },
+      });
+      const base = new RecordingTransport();
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+      });
+
+      // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+      for await (const _receipt of transport.sendMany([message, secondMessage])) {
+        break;
+      }
+
+      assert.deepEqual(base.sentMessages, [message]);
+      assert.equal(recorder.filter({ properties: { event: 'email.sent' } }).length, 1);
+    });
+  });
+
+  it('does not advance a prefetched batch after its consumer stops', async () => {
+    await withRecorder(async (recorder) => {
+      const secondMessage = createMessage({
+        from: 'sender@example.com',
+        to: 'third@example.net',
+        subject: 'Second message',
+        content: { text: 'Another message.' },
+      });
+      const thirdMessage = createMessage({
+        from: 'sender@example.com',
+        to: 'fourth@example.net',
+        subject: 'Third message',
+        content: { text: 'One more message.' },
+      });
+      const base = new PrefetchingTransport();
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+      });
+
+      // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+      for await (const _receipt of transport.sendMany([message, secondMessage, thirdMessage])) {
+        break;
+      }
+
+      assert.deepEqual(base.sentMessages, [message, secondMessage]);
+      assert.ok(base.closed);
+    });
+  });
+
+  it('logs every pending message when sendMany throws', async () => {
+    await withRecorder(async (recorder) => {
+      const secondMessage = createMessage({
+        from: 'sender@example.com',
+        to: 'third@example.net',
+        subject: 'Second message',
+        content: { text: 'Another message.' },
+      });
+      const error = new TypeError('Batch transport failed.');
+      const base = new ConsumingThenThrowingTransport(error);
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+        recordMessage: 'inline',
+      });
+
+      let thrown;
+      try {
+        // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+        for await (const _receipt of transport.sendMany([message, secondMessage])) {
+          // The wrapped transport throws before yielding a receipt.
+        }
+      } catch (caught) {
+        thrown = caught;
+      }
+
+      assert.equal(thrown, error);
+      assert.deepEqual(base.sentMessages, [message, secondMessage]);
+      const failures = recorder.filter({
+        properties: { event: 'email.failed' },
+      });
+      assert.equal(failures.length, 2);
+      assert.deepEqual(
+        failures.map((record) => record.properties.message),
+        [message, secondMessage],
+      );
+      assert.deepEqual(
+        failures.map((record) => record.properties.recipientCount),
+        [2, 1],
+      );
+      assert.ok(failures.every((record) => record.properties.err === error));
+      recorder.assertLogged({
+        message:
+          /^Failed to send email: TypeError: Batch transport failed\.[\s\S]*\n\nSubject: Test message\n\nHello from Upyo\.$/,
+        properties: { event: 'email.failed', message },
+      });
+      recorder.assertLogged({
+        message:
+          /^Failed to send email: TypeError: Batch transport failed\.[\s\S]*\n\nSubject: Second message\n\nAnother message\.$/,
+        properties: { event: 'email.failed', message: secondMessage },
+      });
+    });
+  });
+
+  it('keeps batch errors without a message on one line', async () => {
+    await withRecorder(async (recorder) => {
+      const error = new TypeError('Batch transport failed before consuming.');
+      const base = new RecordingTransport();
+      const transport = new LoggerTransport({
+        logger: recorder.logger,
+        transport: base,
+        recordMessage: 'inline',
+      });
+      const messages = {
+        [Symbol.asyncIterator]() {
+          return {
+            next: () => Promise.reject(error),
+          };
+        },
+      };
+
+      await assert.rejects(async () => {
+        // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
+        for await (const _receipt of transport.sendMany(messages)) {
+          // The wrapped transport throws before yielding a receipt.
+        }
+      }, error);
+
+      recorder.assertLogged({
+        message: /^Failed to send email: TypeError: Batch transport failed before consuming\./,
+        properties: (properties) =>
+          properties.event === 'email.failed' && !('message' in properties),
+      });
+    });
+  });
+
+  it('handles synchronous sendMany input in log-only mode', async () => {
+    await withRecorder(async (recorder) => {
+      const transport = new LoggerTransport({ logger: recorder.logger });
+      const secondMessage = createMessage({
+        from: 'sender@example.com',
+        to: 'third@example.net',
+        subject: 'Second message',
+        content: { text: 'Another message.' },
+      });
+
+      const receipts = [];
+      for await (const receipt of transport.sendMany([message, secondMessage])) {
+        receipts.push(receipt);
+      }
+
+      assert.equal(receipts.length, 2);
+      assert.ok(receipts.every((receipt) => receipt.successful));
+      assert.notEqual(
+        receipts[0].successful && receipts[0].messageId,
+        receipts[1].successful && receipts[1].messageId,
+      );
+      assert.equal(recorder.filter({ properties: { operation: 'sendMany' } }).length, 4);
+    });
+  });
+
+  it('rejects an already aborted standalone send without logging', async () => {
+    await withRecorder(async (recorder) => {
+      const controller = new AbortController();
+      controller.abort();
+      const transport = new LoggerTransport({ logger: recorder.logger });
+
+      await assert.rejects(() => transport.send(message, { signal: controller.signal }), {
+        name: 'AbortError',
+      });
+      assert.equal(recorder.records.length, 0);
+    });
+  });
+
+  it('disposes an asynchronous wrapped transport', async () => {
+    const base = new AsyncDisposableTransport();
+    const transport = new LoggerTransport({
+      logger: createRecorder().logger,
+      transport: base,
+    });
+
+    await transport[Symbol.asyncDispose]();
+
+    assert.ok(base.disposed);
+  });
+
+  it('falls back to disposing a synchronous wrapped transport', async () => {
+    const base = new DisposableTransport();
+    const transport = new LoggerTransport({
+      logger: createRecorder().logger,
+      transport: base,
+    });
+
+    await transport[Symbol.asyncDispose]();
+
+    assert.ok(base.disposed);
+  });
+});
+
+// A pino-like logger that records each call, and the matching LogTape's
+// recorder offered: assertLogged() and filter() over level, message and
+// properties (a partial object, or a predicate).
+function createRecorder() {
+  const records = [];
+  const logger = {};
+  for (const level of ['trace', 'debug', 'info', 'warn', 'error', 'fatal']) {
+    // oxlint-disable-next-line no-shadow -- upstream
+    logger[level] = (properties, message) => records.push({ level, message, properties });
+  }
+  const matches = (record, expected) => {
+    if (expected.level !== undefined && record.level !== expected.level) return false;
+    if (typeof expected.message === 'string' && record.message !== expected.message) return false;
+    if (expected.message instanceof RegExp && !expected.message.test(record.message)) {
+      return false;
+    }
+    if (typeof expected.properties === 'function') return expected.properties(record.properties);
+    for (const [key, value] of Object.entries(expected.properties ?? {})) {
+      try {
+        assert.deepEqual(record.properties[key], value);
+      } catch {
+        return false;
+      }
+    }
+    return true;
+  };
+  return {
+    logger,
+    records,
+    filter: (expected) => records.filter((record) => matches(record, expected)),
+    assertLogged(expected) {
+      assert.ok(
+        records.some((record) => matches(record, expected)),
+        `No record matches ${JSON.stringify(expected)}`,
+      );
+    },
+  };
+}
+
+async function withRecorder(run) {
+  await run(createRecorder());
+}
+
+class RecordingTransport {
+  id = 'base';
+  sentMessages = [];
+  sendCalls = 0;
+  sendManyCalls = 0;
+  lastOptions;
+  nextReceipt = {
+    successful: true,
+    messageId: 'base-message-1',
+    provider: 'base',
+  };
+  throwError;
+
+  // oxlint-disable-next-line no-shadow -- upstream
+  send(message, options) {
+    this.sendCalls++;
+    this.sentMessages.push(message);
+    this.lastOptions = options;
+    if (this.throwError != null) return Promise.reject(this.throwError);
+    return Promise.resolve(this.nextReceipt);
+  }
+
+  async *sendMany(messages, options) {
+    this.sendManyCalls++;
+    this.lastOptions = options;
+    let index = 0;
+    // oxlint-disable-next-line no-shadow -- upstream
+    for await (const message of messages) {
+      this.sentMessages.push(message);
+      if (this.throwError != null) throw this.throwError;
+      yield {
+        successful: true,
+        messageId: `base-batch-${++index}`,
+        provider: 'base',
+      };
+    }
+  }
+}
+
+class AsyncDisposableTransport extends RecordingTransport {
+  disposed = false;
+
+  [Symbol.asyncDispose]() {
+    this.disposed = true;
+    return Promise.resolve();
+  }
+}
+
+class DisposableTransport extends RecordingTransport {
+  disposed = false;
+
+  [Symbol.dispose]() {
+    this.disposed = true;
+  }
+}
+
+class ConsumingThenThrowingTransport {
+  id = 'base';
+  sentMessages = [];
+
+  error;
+
+  constructor(error) {
+    this.error = error;
+  }
+
+  send() {
+    return Promise.reject(this.error);
+  }
+
+  async *sendMany(messages) {
+    // oxlint-disable-next-line no-shadow -- upstream
+    for await (const message of messages) {
+      this.sentMessages.push(message);
+    }
+    yield* [];
+    throw this.error;
+  }
+}
+
+class BufferedTransport {
+  id = 'base';
+  sentMessages = [];
+  yieldedReceiptCount = 0;
+
+  send() {
+    return Promise.reject(new TypeError('Use sendMany().'));
+  }
+
+  async *sendMany(messages) {
+    // oxlint-disable-next-line no-shadow -- upstream
+    for await (const message of messages) {
+      this.sentMessages.push(message);
+    }
+    for (let index = 0; index < this.sentMessages.length; index++) {
+      this.yieldedReceiptCount++;
+      yield {
+        successful: true,
+        messageId: `base-buffered-${index + 1}`,
+        provider: 'base',
+      };
+    }
+  }
+}
+
+class PrefetchingTransport {
+  id = 'base';
+  sentMessages = [];
+  closed = false;
+
+  send() {
+    return Promise.reject(new TypeError('Use sendMany().'));
+  }
+
+  async *sendMany(messages) {
+    try {
+      const iterator =
+        Symbol.asyncIterator in messages
+          ? messages[Symbol.asyncIterator]()
+          : messages[Symbol.iterator]();
+      const first = await iterator.next();
+      const second = await iterator.next();
+      if (first.done || second.done) return;
+      this.sentMessages.push(first.value, second.value);
+
+      yield {
+        successful: true,
+        messageId: 'base-prefetched-1',
+        provider: 'base',
+      };
+
+      const third = await iterator.next();
+      if (!third.done) this.sentMessages.push(third.value);
+      yield {
+        successful: true,
+        messageId: 'base-prefetched-2',
+        provider: 'base',
+      };
+    } finally {
+      this.closed = true;
+    }
+  }
+}
diff --git a/tests/unit/logger.test.js b/tests/unit/logger.test.js
new file mode 100644
index 0000000..7701446
--- /dev/null
+++ b/tests/unit/logger.test.js
@@ -0,0 +1,66 @@
+// What ./logger adds to the port of @upyo/logtape: the logger is checked when
+// the transport is made, and a real pino logger takes the calls as they are.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { Writable } = require('node:stream');
+const pino = require('pino');
+const { createMessage } = require('../../index.js');
+const { LoggerTransport } = require('../../src/logger/index.js');
+
+const message = () =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+const methods = (...levels) => Object.fromEntries(levels.map((level) => [level, () => {}]));
+
+test('Logger: a missing logger, an unknown level or a missing method is refused', () => {
+  assert.throws(() => new LoggerTransport(), {
+    name: 'TypeError',
+    message: 'Expected a logger: an object with a method per level, such as a pino logger.',
+  });
+  assert.throws(() => new LoggerTransport({ logger: 'pino' }), TypeError);
+  const logger = methods('debug', 'info', 'error');
+  assert.throws(() => new LoggerTransport({ logger, levels: { sent: 'warning' } }), {
+    message: 'Expected levels.sent to be one of trace, debug, info, warn, error, fatal: "warning"',
+  });
+  assert.throws(() => new LoggerTransport({ logger, levels: { failed: 'fatal' } }), {
+    message: 'Expected the logger to have a fatal() method for levels.failed.',
+  });
+  assert.strictEqual(new LoggerTransport({ logger }).id, 'logger');
+});
+
+test('Logger: a pino logger records the lifecycle, with the error serialized', async () => {
+  const lines = [];
+  const destination = new Writable({
+    write(chunk, encoding, callback) {
+      lines.push(JSON.parse(chunk));
+      callback();
+    },
+  });
+  const logger = pino({ level: 'debug', base: undefined, timestamp: false }, destination);
+  const error = new TypeError('Connection refused.');
+  const base = {
+    id: 'base',
+    send: async () => {
+      throw error;
+    },
+    async *sendMany() {},
+  };
+  const transport = new LoggerTransport({ transport: base, logger });
+  await assert.rejects(transport.send(message()), error);
+
+  assert.deepStrictEqual(
+    lines.map(({ level, msg, event }) => [level, msg, event]),
+    [
+      [20, 'Sending email.', 'email.sending'],
+      [50, 'Failed to send email: TypeError: Connection refused.', 'email.failed'],
+    ],
+  );
+  assert.strictEqual(lines[1].err.type, 'TypeError');
+  assert.strictEqual(lines[1].err.message, 'Connection refused.');
+  assert.match(lines[1].err.stack, /TypeError: Connection refused\./);
+  assert.strictEqual(lines[1].transportId, 'base');
+});

From db4ee5b3d95e83eda1891ea1067743624d6d5cc3 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 21:55:09 +0300
Subject: [PATCH 019/158] docs: adapt the guides of upyo for every subpath

The messages (compose, attachments, calendar, MIME) and transports pages of
upyo are adapted for the port: examples in CommonJS on
@alexify/mailer/<subpath>, one install block for the one package, no
Deno, Bun, JSR or edge-runtime claims, and upyo's version notes dropped.
The OpenTelemetry page passes the providers in, and the logger page is new
(a pino-like logger in place of LogTape). Getting Started lists the
transports and decorators, the API page every entry point, and one sidebar
covers the guide, the messages and the transports.

README, llms.txt and CHANGELOG describe the ported transport layer and
credit upyo; CLAUDE.md gets the opt-in test scripts, the platform-dependent
tests, the coverage and lint policies of the port, the docs layout and the
Phase 1 progress, and the npm-publish skill the per-subpath size budgets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/npm-publish/SKILL.md |    4 +-
 CHANGELOG.md                        |   26 +
 CLAUDE.md                           |   49 +-
 README.md                           |   64 +-
 docs/.vitepress/config.mts          |   63 +-
 docs/api/exports.md                 |   75 +-
 docs/guide/getting-started.md       |   94 ++-
 docs/messages/attachments.md        |  206 +++++
 docs/messages/calendar.md           |  223 ++++++
 docs/messages/compose.md            |  368 +++++++++
 docs/messages/mime.md               |  120 +++
 docs/public/llms.txt                |   17 +-
 docs/transports/custom.md           |  499 ++++++++++++
 docs/transports/jmap.md             |  513 +++++++++++++
 docs/transports/lettermint.md       |  214 ++++++
 docs/transports/logger.md           |  161 ++++
 docs/transports/maileroo.md         |  227 ++++++
 docs/transports/mailgun.md          |  270 +++++++
 docs/transports/mailtrap.md         |  185 +++++
 docs/transports/mock.md             |  556 ++++++++++++++
 docs/transports/otel.md             |  677 ++++++++++++++++
 docs/transports/plunk.md            |  297 ++++++++
 docs/transports/pool.md             |  654 ++++++++++++++++
 docs/transports/resend.md           |  264 +++++++
 docs/transports/retry.md            |  206 +++++
 docs/transports/sendgrid.md         |  248 ++++++
 docs/transports/ses.md              |  414 ++++++++++
 docs/transports/smtp.md             | 1103 +++++++++++++++++++++++++++
 28 files changed, 7732 insertions(+), 65 deletions(-)
 create mode 100644 docs/messages/attachments.md
 create mode 100644 docs/messages/calendar.md
 create mode 100644 docs/messages/compose.md
 create mode 100644 docs/messages/mime.md
 create mode 100644 docs/transports/custom.md
 create mode 100644 docs/transports/jmap.md
 create mode 100644 docs/transports/lettermint.md
 create mode 100644 docs/transports/logger.md
 create mode 100644 docs/transports/maileroo.md
 create mode 100644 docs/transports/mailgun.md
 create mode 100644 docs/transports/mailtrap.md
 create mode 100644 docs/transports/mock.md
 create mode 100644 docs/transports/otel.md
 create mode 100644 docs/transports/plunk.md
 create mode 100644 docs/transports/pool.md
 create mode 100644 docs/transports/resend.md
 create mode 100644 docs/transports/retry.md
 create mode 100644 docs/transports/sendgrid.md
 create mode 100644 docs/transports/ses.md
 create mode 100644 docs/transports/smtp.md

diff --git a/.claude/skills/npm-publish/SKILL.md b/.claude/skills/npm-publish/SKILL.md
index 20b277a..2924981 100644
--- a/.claude/skills/npm-publish/SKILL.md
+++ b/.claude/skills/npm-publish/SKILL.md
@@ -37,7 +37,7 @@ pnpm run check:dts               # tsc over the d.ts of every entry of the expor
 These are the same gates `prepublishOnly` runs. CI adds three more; run them too:
 
 ```bash
-pnpm size --max-gzip 7                                           # the bundle budget
+pnpm size --max-gzip 7 --max-gzip-smtp 17 …                     # the budgets: copy the size step of ci.yml
 pnpm docs:comparison && git diff --exit-code docs/guide/comparison.md   # the table matches docs/comparison.json
 pnpm run docs:build                                              # the docs site; a dead link fails it
 ```
@@ -180,7 +180,7 @@ Report the file count and the bundle size from `pnpm run size` to the user.
 Run the gates one more time after all edits:
 
 ```bash
-pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts && pnpm size --max-gzip 7 && pnpm run docs:build
+pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts && pnpm size <the flags of ci.yml> && pnpm run docs:build
 ```
 
 Must exit 0. If it fails, fix and re-run.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4346c32..41489e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,8 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+The transport layer, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0 (MIT, © 2025
+Hong Minhee): the code is upstream's, converted to CommonJS with hand-written types and no
+runtime dependency, one subpath per upstream package. Upstream's known bugs are kept for now and
+listed in CLAUDE.md, to be fixed one by one.
+
 ### Added
 
+- **Messages and the transport contract** at the root entry: `createMessage` and the `Message`,
+  `Address` and `Attachment` model, iCalendar parts, Message-ID and threading helpers, the
+  `Transport`, `RawTransport` and `VerifiableTransport` contract, `Receipt` with classified
+  errors, and raw-message plans.
+- **`./mime`:** `composeMessage`, replayable MIME bytes with a separate envelope, DKIM signing
+  with RSA-SHA256 or Ed25519, buffered or streaming. SHA-256 comes from `node:crypto` instead of
+  `@noble/hashes`.
+- **`./smtp`:** `SmtpTransport` on `node:net` and `node:tls`: pooling, STARTTLS, AUTH PLAIN,
+  LOGIN, XOAUTH2 and OAUTHBEARER, PIPELINING, SIZE, DSN, SMTPUTF8, DKIM, `sendRaw` and
+  `verify`.
+- **HTTP providers** on `fetch`: `./ses` (SES v2 with SigV4), `./resend`, `./sendgrid`,
+  `./mailgun`, `./mailtrap`, `./maileroo`, `./lettermint` and `./plunk`; and `./jmap` for
+  RFC 8620/8621 servers.
+- **Decorators:** `./pool` (strategies and failover), `./retry` (backoff, jitter,
+  `Retry-After`), `./otel` (spans and metrics, with the OpenTelemetry providers passed in, the
+  attributes as `mailer.*`) and `./logger` (the lifecycle logged through any pino-like logger
+  passed in, in place of upstream's LogTape transport); and `./mock` for tests.
+- **Documentation** for every subpath, adapted from upyo's guides.
 - **Package scaffold** set up like the other Alexis libraries: plain CommonJS with no build step,
   a hand-written `index.d.ts`, a closed `exports` map, Node.js 22 or newer, and zero runtime
   dependencies.
@@ -18,6 +41,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   an export-parity check between the runtime and `index.d.ts`, a check that `src/` requires only
   Node builtins, bundle tests through esbuild, a bundle-size budget (`pnpm size`) and a
   zero-dependency benchmark harness (`pnpm bench`).
+- **Tooling for subpaths:** export-parity, bundle, size and `check:dts` read the exports map;
+  a module-graph test forbids require cycles; a size budget per subpath; opt-in suites against
+  Mailpit (`pnpm test:mailpit`) and real providers (`pnpm test:e2e`).
 - **CI** on GitHub Actions and a VitePress documentation site at
   [mailerat.vercel.app](https://mailerat.vercel.app/), with a comparison of 14 Node.js email
   libraries generated from `docs/comparison.json`.
diff --git a/CLAUDE.md b/CLAUDE.md
index b37e991..f2d41ef 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,11 +33,13 @@ Package manager is **pnpm** (pinned in `packageManager`).
 
 ```bash
 pnpm test                          # node --test tests/unit/*.test.js
+pnpm test:mailpit                  # opt-in: tests/mailpit against a local Mailpit (compose file there)
+pnpm test:e2e                      # opt-in: tests/e2e against real providers, from env variables
 node --test tests/unit/mailer.test.js   # a single file
 node --test --test-name-pattern="Bundle" tests/unit/*.test.js   # filter by name
 pnpm run test:coverage             # c8 over src/, gated at 98 lines/statements, 90 branches, 100 functions
-pnpm run test:types                # tsd: tests/types/*.test-d.ts against index.d.ts
-pnpm run check:dts                 # tsc --noEmit --strict over index.d.ts on its own
+pnpm run test:types                # tsd: tests/types/*.test-d.ts, one file per entry
+pnpm run check:dts                 # tsc --noEmit --strict over the d.ts of every entry
 pnpm run lint                      # oxlint src tests scripts bench
 pnpm run format                    # oxfmt src tests scripts bench (format:check in CI)
 pnpm size [--max-gzip <KB>]        # esbuild bundle sizes; CI gates the root at 7 KB min+gzip and each subpath
@@ -110,6 +112,12 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 - A lint rule that upstream code breaks is suppressed on the line,
   `// oxlint-disable-next-line <rule> -- upstream`, rather than rewritten; lifting those is a later
   refactor, like TS `private` fields, which stay plain properties (the tests reach into them).
+  Style-only rules (`curly`, `object-shorthand`) are fixed instead, and a property access split
+  over lines in a test goes through a variable (`no-unexpected-multiline`).
+- **Coverage keeps the gates of the package.** Paths that upstream reached only end to end get flat
+  suites against fakes (`tests/unit/<subpath>.test.js`); `/* c8 ignore */` marks only code that is
+  dead upstream (`convertMessagesToBulk`, `recordRetry`) or unreachable on Node, each with its
+  reason. Upstream tests of a runtime without `AbortSignal.any` are left out with a comment.
 - Ported test suites keep upstream's `describe`/`it`, so they can be compared with upyo's; new
   suites use the flat style of "Testing notes". Tests for paths that upstream's suites leave out go
   into a new flat suite (`tests/unit/core.test.js` for `src/core/`).
@@ -206,9 +214,10 @@ model of states and events. `tenantId` is in the context from the start.
 
 **Phase 1, reliable sending (P0).**
 
-- **The transport of its own:** the MIME builder; the SMTP client (pool, STARTTLS and REQUIRETLS,
+- **The transport of its own** (done, ported from upyo 0.7.0; its known bugs are on the list of
+  "Code ported from upyo"): the MIME builder; the SMTP client (pool, STARTTLS and REQUIRETLS,
   AUTH PLAIN/LOGIN/XOAUTH2, DSN, PIPELINING); DKIM (RSA-SHA256, Ed25519); SES v2 over `fetch` with
-  SigV4; one more HTTP provider (Resend or Postmark).
+  SigV4; seven more HTTP providers and JMAP.
 - **A persistent queue:** the outbox in MongoDB (transactional outbox, no Redis needed) and a
   BullMQ driver (Valkey) for throughput and delays; priorities (auth codes before newsletters).
 - **The audit log** of every state, with a keyed HMAC plus an encrypted block for the recipient
@@ -230,8 +239,10 @@ signature mandatory and replay protection, starting with SES (SNS) and one HTTP
 suppression list per tenant and stream, checked before a message is queued, with a bypass policy
 for transactional mail (password reset, MFA); failover over a pool of providers with health, a
 circuit breaker with a single probe in half-open, and no switch after an ambiguous "submitted"
-without an idempotency key; OpenTelemetry spans and metrics (time in queue, attempts, failure rate
-per provider, outbox size); token-bucket rate limits per provider and per tenant (SES quotas).
+without an idempotency key (`./pool` of the port has strategies and failover, not yet health or a
+breaker); OpenTelemetry spans and metrics (time in queue, attempts, failure rate per provider,
+outbox size; `./otel` of the port covers sends); token-bucket rate limits per provider and per
+tenant (SES quotas).
 
 **Phase 3, multi-tenant (P1–P2).** Provider credentials per tenant (bring your own SES), domains
 and DKIM per tenant, quotas; List-Unsubscribe one-click (RFC 8058) and the split between
@@ -319,15 +330,24 @@ change. **This file wins** if they ever disagree.
   they keep upstream's `describe`/`it` (see "Code ported from upyo").
 - `pnpm test` passes the glob unquoted (`tests/unit/*.test.js`): the shell expands it on Linux and
   macOS, and Node ≥ 22 expands it itself where cmd.exe does not, so Windows runs every version.
-- `tests/unit/bundle.test.js` builds `index.js` with esbuild in memory (minified and not) and calls
-  the API through the result, so the shipped files keep working after a consumer's bundler (a
-  serverless function, a single-file deploy).
+- `tests/unit/bundle.test.js` builds every entry of the exports map with esbuild in memory
+  (minified and not) and checks its exports through the result, so the shipped files keep working
+  after a consumer's bundler (a serverless function, a single-file deploy).
 - `tests/unit/dependencies.test.js` guards "Zero dependencies" above.
 - `tests/unit/scripts.test.js` runs `scripts/size.js` with a budget it always meets and one it
   never can.
-- New behavior needs a test that fails without the change. Network transports will be tested
-  against local fake servers (an SMTP server on `node:net`, an HTTP server on `node:http`), never
-  against a real provider in `pnpm test`.
+- New behavior needs a test that fails without the change. Network transports are tested
+  against local fake servers (`tests/helpers/smtp/mock-smtp-server.js` on `node:net`, servers on
+  `node:http`) or a stubbed `fetch` (`t.mock.method(globalThis, 'fetch', …)`), never against a
+  real provider in `pnpm test`.
+- **Opt-in suites**, outside the gates: `tests/mailpit/` (`pnpm test:mailpit`, serial, as the
+  inbox is shared; `docker compose -f tests/mailpit/docker-compose.yml up -d` and
+  `MAILPIT_SMTP_HOST`/`MAILPIT_API_URL`) and `tests/e2e/` (`pnpm test:e2e`, each suite skipped
+  until its provider's variables are set; Stalwart for JMAP in `tests/e2e/jmap/`).
+- **Platform-dependent tests:** the mock SMTP server tolerates a client's connection reset (macOS
+  and Windows send an RST where Linux sends a FIN); the seven JMAP tests of a 401 to a streamed
+  body are `todo` on Node 24 (known upstream bug 14). `tests/unit/export-parity.test.js` also
+  checks that every d.ts using `AsyncDisposable` references `esnext.disposable` itself.
 
 ## Documentation site
 
@@ -347,6 +367,11 @@ published to npm, and lint/format do not cover it.
 - The brand is a teal "envelope" mark (`#0D6B63`, `#4CC2B5` on dark; a placeholder until a final
   logo): `docs/public/logo-mark*.svg`, `favicon.svg` (follows `prefers-color-scheme`),
   `favicon.png` and `logo.png` (the 1200×630 og:image, rendered from SVG with `rsvg-convert`).
+- **The guides of upyo are adapted, not generated:** `docs/messages/` (compose, attachments,
+  calendar, MIME) and `docs/transports/` (one page per subpath, plus custom transports), with
+  examples in CommonJS on `@alexify/mailer/<subpath>`. `/transports/logger` is new (pino-like
+  logger) and `/transports/otel` passes the providers in. One sidebar (`guide` in
+  `config.mts`) covers the guide, the messages and the transports.
 - When behavior changes, update README and the matching docs page together. Keep example outputs in
   the docs true to the code.
 
diff --git a/README.md b/README.md
index d3a17b4..27b19e9 100644
--- a/README.md
+++ b/README.md
@@ -12,16 +12,19 @@ and HTTP providers, and on top of them what the other libraries leave to the app
 persistent queue and outbox, an audit log, one model of delivery events, suppression and
 idempotency. Zero runtime dependencies.
 
-> 🚧 **Work in progress.** The API is being designed. `createMailer` is exported today as a
-> placeholder that throws.
+> 🚧 **Work in progress.** The transport layer is here, ported from
+> [upyo](https://github.com/dahlia/upyo) 0.7.0: messages, MIME and DKIM, SMTP, Amazon SES and seven
+> more HTTP providers, JMAP, and the pool, retry, OpenTelemetry, logger and mock transports. The
+> reliability layer is being designed: `createMailer` is exported as a placeholder that throws.
 
 ### 📖 [Read the documentation →](https://mailerat.vercel.app/)
 
 ## Why @alexify/mailer
 
-- **Its own transport.** An SMTP client, a MIME builder and DKIM written for this library, and
-  HTTP providers on `fetch`, starting with Amazon SES v2. Secure by default: TLS certificates are
-  verified, AUTH never goes over plain text, CRLF in a header is rejected.
+- **Its own transport.** An SMTP client (pool, STARTTLS, PIPELINING, DSN, SMTPUTF8, OAuth 2.0), a
+  MIME builder and DKIM (RSA-SHA256, Ed25519), and HTTP providers on `fetch`: Amazon SES v2,
+  Resend, SendGrid, Mailgun, Mailtrap, Maileroo, Lettermint, Plunk, and JMAP. Secure by default:
+  TLS certificates are verified, AUTH never goes over plain text, CRLF in a header is rejected.
 - **What happens after `send()`.** A persistent queue and outbox, an append-only audit log and one
   model of delivery events (delivered, bounced, complained, failed). None of the
   [fourteen libraries compared](https://mailerat.vercel.app/guide/comparison) has the three.
@@ -30,9 +33,10 @@ idempotency. Zero runtime dependencies.
   has no idempotency key.
 - **Correct before broad.** Golden `.eml` messages, DKIM checked by an independent verifier, and
   fuzzing of headers, `multipart/related`, dot-stuffing and internationalized addresses.
-- **Zero dependencies.** Built on `node:*` modules and `fetch`. The driver of a queue or a database
-  (BullMQ, MongoDB) is created by your application and passed in. CommonJS with ESM named imports
-  and hand-written TypeScript typings, no build step.
+- **Zero dependencies.** Built on `node:*` modules and `fetch`. What a part needs from your
+  application is passed in: the OpenTelemetry providers, a pino-like logger, and later the driver of
+  a queue or a database (BullMQ, MongoDB). CommonJS with ESM named imports and hand-written
+  TypeScript typings, no build step.
 
 ## Installation
 
@@ -44,17 +48,43 @@ npm install @alexify/mailer
 
 Requires Node.js 22 or newer.
 
-## Exports
+## Usage
 
-```js
-const { createMailer } = require('@alexify/mailer');
-```
+The root entry builds messages; each transport is a subpath of the same package:
 
 ```js
-import { createMailer } from '@alexify/mailer';
+const { createMessage } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  auth: { user: 'user@example.com', pass: 'secret' },
+});
+
+const receipt = await transport.send(
+  createMessage({
+    from: 'Alex <alex@example.com>',
+    to: 'bob@example.net',
+    subject: 'Hello',
+    content: { text: 'Hi there.', html: '<p>Hi there.</p>' },
+  }),
+);
+if (!receipt.successful) console.error(receipt.errorMessages);
 ```
 
-The [API reference](https://mailerat.vercel.app/api/exports) lists every member.
+| Subpath | What it is |
+| --- | --- |
+| `@alexify/mailer` | messages, attachments, calendar parts, the `Transport` contract, receipts |
+| `/mime` | MIME composition and DKIM signing |
+| `/smtp`, `/jmap` | SMTP and JMAP transports |
+| `/ses`, `/resend`, `/sendgrid`, `/mailgun`, `/mailtrap`, `/maileroo`, `/lettermint`, `/plunk` | HTTP providers |
+| `/pool`, `/retry`, `/otel`, `/logger` | decorators: failover, retries, OpenTelemetry, logging |
+| `/mock` | an in-memory transport for tests |
+
+The same names import from ESM (`import { SmtpTransport } from '@alexify/mailer/smtp'`). The
+[API reference](https://mailerat.vercel.app/api/exports) lists every member, and the
+[guide](https://mailerat.vercel.app/guide/getting-started) every transport.
 
 ## Compared with alternatives
 
@@ -62,6 +92,12 @@ The [comparison](https://mailerat.vercel.app/guide/comparison) puts Nodemailer,
 unemail, sently, worker-mailer, edge-mailer, MIMEText and the SDKs of Resend, SendGrid, Mailgun,
 Postmark, Mailtrap and Amazon SES side by side, feature by feature, from their source code.
 
+## Credits
+
+The transport layer is a port of [upyo](https://github.com/dahlia/upyo) 0.7.0 by Hong Minhee
+(MIT), converted to CommonJS with hand-written types and no dependencies; its notice is in
+[LICENSE](./LICENSE).
+
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md).
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index a92086b..d6489f4 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -50,6 +50,54 @@ const jsonLd = {
   offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
 };
 
+// One sidebar for the guide, the messages and the transports, so that reading
+// flows from one to the next.
+const guide = [
+  {
+    text: 'Introduction',
+    items: [
+      { text: 'Why @alexify/mailer?', link: '/guide/why' },
+      { text: 'Getting Started', link: '/guide/getting-started' },
+      { text: 'Compared with alternatives', link: '/guide/comparison' },
+    ],
+  },
+  {
+    text: 'Messages',
+    items: [
+      { text: 'Composing messages', link: '/messages/compose' },
+      { text: 'Attachments', link: '/messages/attachments' },
+      { text: 'Calendar invitations', link: '/messages/calendar' },
+      { text: 'MIME composition', link: '/messages/mime' },
+    ],
+  },
+  {
+    text: 'Transports',
+    items: [
+      { text: 'SMTP', link: '/transports/smtp' },
+      { text: 'Amazon SES', link: '/transports/ses' },
+      { text: 'Resend', link: '/transports/resend' },
+      { text: 'SendGrid', link: '/transports/sendgrid' },
+      { text: 'Mailgun', link: '/transports/mailgun' },
+      { text: 'Mailtrap', link: '/transports/mailtrap' },
+      { text: 'Maileroo', link: '/transports/maileroo' },
+      { text: 'Lettermint', link: '/transports/lettermint' },
+      { text: 'Plunk', link: '/transports/plunk' },
+      { text: 'JMAP', link: '/transports/jmap' },
+      { text: 'Mock', link: '/transports/mock' },
+      { text: 'Custom transports', link: '/transports/custom' },
+    ],
+  },
+  {
+    text: 'Decorators',
+    items: [
+      { text: 'Pool', link: '/transports/pool' },
+      { text: 'Retry', link: '/transports/retry' },
+      { text: 'OpenTelemetry', link: '/transports/otel' },
+      { text: 'Logger', link: '/transports/logger' },
+    ],
+  },
+];
+
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   title: '@alexify/mailer',
@@ -96,6 +144,8 @@ export default defineConfig({
 
     nav: [
       { text: 'Guide', link: '/guide/getting-started', activeMatch: '/guide/' },
+      { text: 'Messages', link: '/messages/compose', activeMatch: '/messages/' },
+      { text: 'Transports', link: '/transports/smtp', activeMatch: '/transports/' },
       { text: 'API', link: '/api/exports', activeMatch: '/api/' },
       {
         text: `v${version}`,
@@ -108,16 +158,9 @@ export default defineConfig({
     ],
 
     sidebar: {
-      '/guide/': [
-        {
-          text: 'Introduction',
-          items: [
-            { text: 'Why @alexify/mailer?', link: '/guide/why' },
-            { text: 'Getting Started', link: '/guide/getting-started' },
-            { text: 'Compared with alternatives', link: '/guide/comparison' },
-          ],
-        },
-      ],
+      '/guide/': guide,
+      '/messages/': guide,
+      '/transports/': guide,
       '/api/': [
         {
           text: 'API',
diff --git a/docs/api/exports.md b/docs/api/exports.md
index 648db5f..f277ef1 100644
--- a/docs/api/exports.md
+++ b/docs/api/exports.md
@@ -1,24 +1,71 @@
 # Exports
 
-::: warning Work in progress
-`createMailer` is a placeholder: it throws until the mailer is implemented, and its signature will
-change with the design of the messages, the transports and the queue.
-:::
+The package has one root entry and a subpath per transport and decorator, each
+with its own hand-written types. Every name is exported by name, so `require()`
+and ESM `import` give the same values:
 
 ```js
-const { createMailer } = require('@alexify/mailer');
+const { createMessage } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
 ```
 
-## `createMailer(options)`
+```js
+import { createMessage } from '@alexify/mailer';
+import { SmtpTransport } from '@alexify/mailer/smtp';
+```
 
-Creates a mailer that sends messages through a transport, with the reliability layer on top.
+## `@alexify/mailer`
 
-```ts
-interface Mailer {
-  send(message: object): Promise<unknown>;
-}
+The message model and the transport contract, ported from `@upyo/core`, and the
+mailer.
 
-function createMailer(options: object): Mailer;
-```
+- **Messages:** `createMessage`, and the `Message`, `MessageConstructor`,
+  `MessageContent`, `Address`, `Attachment` and `Priority` types; `parseAddress`,
+  `formatAddress`, `isEmailAddress`, `isAttachment`, `comparePriority`. See
+  [composing messages](/messages/compose).
+- **Attachments:** `readAttachmentContent`, `iterateAttachmentContent`. See
+  [attachments](/messages/attachments).
+- **Calendar:** `createCalendarAttachment`, `resolveCalendarContent`,
+  `parseCalendarMethod`. See [calendar invitations](/messages/calendar).
+- **Message-ID and threading:** `generateMessageId`, `parseMessageId`,
+  `formatMessageId`, `resolveThreadingHeaders`.
+- **Transports:** the `Transport`, `RawTransport`, `VerifiableTransport` and
+  `TransportOptions` types; `isRawTransport`, `isVerifiableTransport`,
+  `combineSignals`. See [custom transports](/transports/custom).
+- **Receipts:** the `Receipt` and `ReceiptError` types; `createFailedReceipt`,
+  `createReceiptError`, `classifyHttpStatus`, `classifyReceiptError`,
+  `parseRetryAfter`.
+- **Raw messages:** the `RawMessage` type; `createRawMessagePlan`,
+  `iterateRawMessage`, `analyzeRawMessage`, `RawMessageValidationError`.
+- **`createMailer(options)`:** the mailer of the reliability layer.
+
+::: warning Work in progress
+`createMailer` is a placeholder: it throws `createMailer is not implemented yet`
+until the mailer is implemented, and its signature will change with the design of
+the queue and the audit log.
+:::
+
+## Subpaths
+
+| Subpath | Exports | Page |
+| --- | --- | --- |
+| `@alexify/mailer/mime` | `composeMessage`, `MimeAttachmentReplayError` | [MIME](/messages/mime) |
+| `@alexify/mailer/smtp` | `SmtpTransport` and its error classes (`SmtpResponseError`, `SmtpAuthError`, …), `isSmtpResponseProviderDetails` | [SMTP](/transports/smtp) |
+| `@alexify/mailer/ses` | `SesTransport` | [Amazon SES](/transports/ses) |
+| `@alexify/mailer/resend` | `ResendTransport` | [Resend](/transports/resend) |
+| `@alexify/mailer/sendgrid` | `SendGridTransport`, `SendGridApiError` | [SendGrid](/transports/sendgrid) |
+| `@alexify/mailer/mailgun` | `MailgunTransport`, `MailgunApiError` | [Mailgun](/transports/mailgun) |
+| `@alexify/mailer/mailtrap` | `MailtrapTransport`, `createMailtrapConfig` and its error classes | [Mailtrap](/transports/mailtrap) |
+| `@alexify/mailer/maileroo` | `MailerooTransport`, `createMailerooConfig` and its error classes | [Maileroo](/transports/maileroo) |
+| `@alexify/mailer/lettermint` | `LettermintTransport`, `createLettermintConfig` and its error classes | [Lettermint](/transports/lettermint) |
+| `@alexify/mailer/plunk` | `PlunkTransport` | [Plunk](/transports/plunk) |
+| `@alexify/mailer/jmap` | `JmapTransport`, `createJmapConfig`, `JmapApiError`, `JMAP_ERROR_TYPES`, `isCapabilityError`, `uploadBlob` | [JMAP](/transports/jmap) |
+| `@alexify/mailer/mock` | `MockTransport` | [Mock](/transports/mock) |
+| `@alexify/mailer/pool` | `PoolTransport`, `RoundRobinStrategy`, `WeightedStrategy`, `PriorityStrategy`, `SelectorStrategy` | [Pool](/transports/pool) |
+| `@alexify/mailer/retry` | `RetryTransport`, `createRetryTransport` | [Retry](/transports/retry) |
+| `@alexify/mailer/otel` | `OpenTelemetryTransport`, `createOpenTelemetryTransport`, `createEmailAttributeExtractor`, `createErrorClassifier`, `defaultErrorClassifier` | [OpenTelemetry](/transports/otel) |
+| `@alexify/mailer/logger` | `LoggerTransport` | [Logger](/transports/logger) |
 
-Throws `Error('createMailer is not implemented yet')`.
+The types of each subpath (configurations, receipts with provider details, the
+structural `TracerProvider`, `MeterProvider` and `Logger` of the decorators) are in
+its `index.d.ts`, next to the code in `src/<subpath>/`.
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index a6c313c..56c80c5 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -1,8 +1,10 @@
 # Getting Started
 
 ::: warning Work in progress
-@alexify/mailer is being designed. The package can be installed, but `createMailer` is a
-placeholder that throws `createMailer is not implemented yet`.
+The transport layer, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0, is
+here: messages, SMTP, eight HTTP providers, JMAP and the decorators. The reliability
+layer is still being designed: `createMailer` is a placeholder that throws
+`createMailer is not implemented yet`.
 :::
 
 ## Installation
@@ -13,17 +15,95 @@ pnpm add @alexify/mailer
 npm install @alexify/mailer
 ```
 
-Node.js 22 or newer. The package has no runtime dependencies.
+Node.js 22 or newer. The package has no runtime dependencies: every transport is one
+package, reached through a subpath (`@alexify/mailer/smtp`), and what a decorator
+needs from your application (an OpenTelemetry provider, a logger) is passed in.
 
-## Importing
+## Choosing a transport
+
+Each transport implements the same `Transport` contract of the root entry, so they
+can be swapped without changing the code that builds messages:
+
+- [SMTP](/transports/smtp) (`@alexify/mailer/smtp`): universal email protocol, works
+  with any SMTP server; DKIM signing, pooling, STARTTLS, DSN.
+- [Amazon SES](/transports/ses) (`@alexify/mailer/ses`): cost-effective email
+  service for AWS users.
+- [Resend](/transports/resend) (`@alexify/mailer/resend`): developer-friendly API,
+  batch sending.
+- [SendGrid](/transports/sendgrid) (`@alexify/mailer/sendgrid`): popular email API
+  with a deliverability focus.
+- [Mailgun](/transports/mailgun) (`@alexify/mailer/mailgun`): HTTP API with US and
+  EU regions.
+- [Mailtrap](/transports/mailtrap) (`@alexify/mailer/mailtrap`): Email API and Email
+  Sandbox for production delivery and test inbox capture.
+- [Maileroo](/transports/maileroo) (`@alexify/mailer/maileroo`): JSON email API with
+  attachments, tags, custom headers and tracking.
+- [Lettermint](/transports/lettermint) (`@alexify/mailer/lettermint`): transactional
+  email API with routes, metadata, idempotency and batch sending.
+- [Plunk](/transports/plunk) (`@alexify/mailer/plunk`): cloud or self-hosted
+  transactional email.
+- [JMAP](/transports/jmap) (`@alexify/mailer/jmap`): RFC 8620/8621 mail servers
+  such as Stalwart or Fastmail.
+- [Mock](/transports/mock) (`@alexify/mailer/mock`): captures emails without
+  sending, for tests.
+
+And the decorators, which wrap any transport:
+
+- [Pool](/transports/pool) (`@alexify/mailer/pool`): several transports, picked by
+  a strategy, with failover.
+- [Retry](/transports/retry) (`@alexify/mailer/retry`): retries with backoff, jitter
+  and `Retry-After`.
+- [OpenTelemetry](/transports/otel) (`@alexify/mailer/otel`): spans and metrics,
+  with your providers.
+- [Logger](/transports/logger) (`@alexify/mailer/logger`): the delivery lifecycle,
+  logged through your pino-like logger.
+
+If none of these fit your needs, you can also
+[create a custom transport](/transports/custom).
+
+## Sending your first email
+
+Here's a basic example using Gmail through SMTP:
 
 ```js
-const { createMailer } = require('@alexify/mailer');
+const { createMessage } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'smtp.gmail.com',
+  port: 465,
+  secure: true, // Use TLS
+  auth: {
+    user: 'your@gmail.com',
+    pass: 'your-app-password',
+  },
+});
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Hello from mailer!',
+  content: { text: 'This is a test email.' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
 ```
 
+The same names import from ESM:
+
 ```js
-import { createMailer } from '@alexify/mailer';
+import { createMessage } from '@alexify/mailer';
+import { SmtpTransport } from '@alexify/mailer/smtp';
 ```
 
+From here, see [composing messages](/messages/compose) for HTML content, multiple
+recipients and threading, [attachments](/messages/attachments), and
+[calendar invitations](/messages/calendar).
+
 See [Why @alexify/mailer?](/guide/why) for what the library is built to do, and the
-[API](/api/exports) for the current exports.
+[API](/api/exports) for every entry point.
diff --git a/docs/messages/attachments.md b/docs/messages/attachments.md
new file mode 100644
index 0000000..b833c88
--- /dev/null
+++ b/docs/messages/attachments.md
@@ -0,0 +1,206 @@
+# Attachments
+
+Email attachments in @alexify/mailer are handled seamlessly through the `createMessage()`
+function from the root entry, *@alexify/mailer*. You can attach files to your messages
+using either JavaScript [`File`] objects or custom `Attachment` objects,
+giving you flexibility in how you handle file content and metadata.
+
+[`File`]: https://developer.mozilla.org/en-US/docs/Web/API/File
+
+## Attaching files
+
+The simplest way to add attachments to your email is by using JavaScript
+[`File`] objects.  This is particularly useful when working with file uploads
+in web applications or when you have file data available as [`File`] instances:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { readFile } = require('node:fs/promises');
+
+// Read a PDF file from the filesystem
+const fileContent = await readFile('./reports/monthly-report.pdf');
+const file = new File([fileContent], 'monthly-report.pdf', { type: 'application/pdf' });
+
+const message = createMessage({
+  from: 'finance@example.com',
+  to: 'manager@example.com',
+  subject: 'Monthly Report - October 2024',
+  content: { text: 'Please find the October monthly report attached for your review.' },
+  attachments: file,
+});
+```
+
+When you provide a [`File`] object, @alexify/mailer extracts its filename and content type
+and retains the file without reading it.  The attachment will be included as a
+regular (non-inline) attachment.  The `readFile()` call in this example
+allocates the complete file before constructing the message; use a content
+factory below when the file should be read incrementally.
+
+## Multiple attachments
+
+You can attach multiple files to a single message by providing an array of
+[`File`] objects or mixing different attachment types:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { readFile } = require('node:fs/promises');
+
+// Read multiple files from the filesystem
+const contractContent = await readFile('./legal/Q4-contract.pdf');
+const budgetContent = await readFile('./finance/Q4-budget.xlsx');
+
+const document = new File([contractContent], 'Q4-contract.pdf', {
+  type: 'application/pdf',
+});
+
+const spreadsheet = new File([budgetContent], 'Q4-budget.xlsx', {
+  type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+});
+
+const message = createMessage({
+  from: 'finance@example.com',
+  to: 'ceo@example.com',
+  subject: 'Q4 Financial Documents',
+  content: { text: 'Please find the Q4 contract and budget documents attached for your review.' },
+  attachments: [document, spreadsheet],
+});
+```
+
+## Custom attachment objects
+
+For more control over attachment behavior, you can create custom `Attachment`
+objects instead of using [`File`] instances. This approach is useful when you
+need to specify additional metadata or when working with inline attachments for
+HTML emails:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { readFile } = require('node:fs/promises');
+
+// Read company logo for inline attachment
+const logoContent = await readFile('./assets/company-logo.png');
+
+const logoAttachment = {
+  filename: 'company-logo.png',
+  content: logoContent,
+  contentType: 'image/png',
+  contentId: 'company-logo',
+  inline: true,
+};
+
+const message = createMessage({
+  from: 'marketing@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to Acme Corp!',
+  content: {
+    html: `
+      <h1>Welcome to Acme Corp!</h1>
+      <p>We are excited to have you on board.</p>
+      <img src="cid:company-logo" alt="Acme Corp Logo" style="width: 200px;">
+    `,
+    text: 'Welcome to Acme Corp! We are excited to have you on board.',
+  },
+  attachments: logoAttachment,
+});
+```
+
+In this example, the attachment is marked as inline (`inline: true`) and
+referenced in the HTML content using the `contentId` as `cid:company-logo`.
+This allows the image to be displayed directly within the email body rather
+than as a separate downloadable attachment.
+
+## Working with binary content
+
+When working with binary file content, you can provide the attachment data as
+a [`Uint8Array`], a `Promise<Uint8Array>`, a `Blob`, or a replayable content
+factory.  A promise represents a read that has already started; it does not
+defer that read until sending and still allocates the whole attachment.
+
+A factory opens a fresh reader when the transport needs the bytes:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { createReadStream } = require('node:fs');
+
+const attachment = {
+  filename: 'customer-data-2024.csv',
+  content: (signal) => createReadStream('./data/exports/customer-data-2024.csv', { signal }),
+  contentType: 'text/csv',
+  contentId: 'customer-dataset',
+  inline: false,
+};
+
+const message = createMessage({
+  from: 'data@example.com',
+  to: 'analyst@example.com',
+  subject: 'Customer Data Export - 2024',
+  content: {
+    text: 'The 2024 customer dataset you requested is attached. This file contains anonymized customer analytics data.',
+  },
+  attachments: attachment,
+});
+```
+
+The factory receives an optional `AbortSignal` and returns an
+`AsyncIterable<Uint8Array>` or a promise for one.  Every invocation must return
+an independent reader producing identical bytes.  Retries, concurrent sends,
+and streaming DKIM may open the same attachment more than once.  Do not return
+an already-open stream from a factory, or change the underlying file while a
+send is pending.  A rejected byte-array promise cannot restart its read.
+
+Factories should honor cancellation during acquisition and reading, and release
+resources in `finally` when implemented as async generators.  @alexify/mailer requests
+iterator cleanup on early exit but does not wait indefinitely for a producer
+that ignores cancellation.  Yield bounded chunks that remain valid until the
+next read; @alexify/mailer copies them when collecting a complete attachment.
+
+Unsigned SMTP streams attachments through MIME encoding to the socket.  Its
+additional attachment memory is bounded by fixed processing buffers and the
+largest source chunk, excluding caller-owned data, text/HTML, headers, and
+runtime/socket buffers.  HTTP transports accept the same inputs but collect the
+bytes for their provider payloads.  Plunk retains its existing behavior of
+omitting attachments whose reads fail, except that caller cancellation aborts
+the send.  See [SMTP DKIM body modes](/transports/smtp#body-processing) for
+the signing tradeoffs.
+
+[`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
+
+### Reading attachment content in custom transports
+
+Since @alexify/mailer 0.6.0, `Attachment.content` is an `AttachmentContent` union, and
+`createMessage()` retains `File` objects instead of converting them to
+byte-array promises.  Code that previously used `await attachment.content`
+should use `readAttachmentContent()` when it needs a complete byte array:
+
+```js
+const { readAttachmentContent } = require('@alexify/mailer');
+
+async function readFileAttachment(attachment, signal) {
+  return await readAttachmentContent(attachment.content, signal);
+}
+```
+
+Use `iterateAttachmentContent(content, signal)` instead when a custom transport
+can consume chunks incrementally.  Neither helper caches factory results.
+
+## Content type considerations
+
+When creating custom attachments, it's important to specify accurate content
+types (media types) to ensure proper handling by email clients.  Common content
+types include `"application/pdf"` for PDF files, `"image/png"` for PNG images,
+`"text/csv"` for CSV files, and `"application/zip"` for ZIP archives.
+The content type helps email clients determine how to display or handle
+the attachment appropriately.
+
+If the content type comes from outside your application, pass it to
+`createMessage()` rather than to a `Message` object you build yourself.
+The SMTP transport writes the content type and the content ID into the MIME
+part headers as given, so a value carrying a carriage return or line feed would
+end that header field and turn the rest into further header fields.
+`createMessage()` rejects both characters with a `TypeError`.  A browser's
+declared upload type is a common source of such a value.
+
+Whether you're working with simple file uploads or complex inline attachments
+for rich HTML emails, @alexify/mailer's attachment system provides the flexibility you need
+while handling the underlying complexity of email attachment encoding and
+formatting.
diff --git a/docs/messages/calendar.md b/docs/messages/calendar.md
new file mode 100644
index 0000000..02521b0
--- /dev/null
+++ b/docs/messages/calendar.md
@@ -0,0 +1,223 @@
+# Calendar invitations
+
+An appointment confirmation, a reservation, or a meeting invitation is more than
+an email with a date in it.  A calendar client offers to add the event, or shows
+accept and decline buttons, when the message carries a `text/calendar` body part
+whose `method` parameter repeats the iCalendar object's own `METHOD` property,
+as [RFC 6047] describes.  An *.ics* attachment reaches the same place only if
+the part keeps that media type and that parameter; the attachment API leaves
+both to you, and a file typed `application/octet-stream` is just a download.
+
+The `calendar` field on `createMessage()` takes the iCalendar object and lets
+the transport compose the rest:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'organizer@example.com',
+  to: 'attendee@example.net',
+  subject: 'Lunch on Wednesday',
+  content: {
+    text: 'Lunch on Wednesday at noon.  Details are in the invitation.',
+  },
+  calendar: { content: ics },
+});
+```
+
+[RFC 6047]: https://www.rfc-editor.org/rfc/rfc6047
+
+## @alexify/mailer does not generate iCalendar objects
+
+The `content` is an iCalendar object your application already has, whether from
+a template, from your own code, or from a library such as [ical-generator].
+@alexify/mailer checks the syntax of every content line before composing the message.
+The event's meaning and scheduling requirements stay yours:
+
+ -  `ORGANIZER` and `ATTENDEE`, which decide who the invitation is from and who
+    may reply to it.  These are separate fields from the message's `from` and
+    `to`, but they have to agree: [RFC 6047] §2.2 has the receiving side
+    authorize a scheduling message by matching the sender against `ORGANIZER`
+    for a `REQUEST` or a `CANCEL`, and against `ATTENDEE` for a `REPLY`.  An
+    invitation sent from a no-reply address on behalf of an organizer is well
+    formed and still gets treated as forwarded, or refused an RSVP.
+ -  A `UID` that stays the same across the whole life of the event, and a
+    `SEQUENCE` that increases every time you change it.  A client matches an
+    update or a cancellation to the original by `UID`, and ignores one whose
+    `SEQUENCE` has not advanced.
+ -  `DTSTAMP`, `DTSTART`, and any `VTIMEZONE` the event needs.
+
+[RFC 5546] specifies what each method requires.  Getting this wrong produces a
+message that is well formed and still does nothing useful, so it is worth
+reading before sending invitations to real people.
+
+[ical-generator]: https://github.com/sebbo2002/ical-generator
+[RFC 5546]: https://www.rfc-editor.org/rfc/rfc5546
+
+## The method comes from the object
+
+@alexify/mailer takes the method from the object's own `METHOD` property, so the object has
+to declare one.  This is not a formality: where the MIME parameter and the
+`METHOD` property disagree, Outlook uses the property and ignores the parameter,
+so a method supplied anywhere else could not change what a recipient sees.
+
+The optional `method` field asserts what the object says rather than supplying
+it.  Use it when you want the mismatch caught:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const invitation = [
+  'BEGIN:VCALENDAR',
+  'VERSION:2.0',
+  'PRODID:-//Example//Booking//EN',
+  'METHOD:REQUEST',
+  'BEGIN:VEVENT',
+  'UID:booking-42@example.com',
+  'SEQUENCE:0',
+  'DTSTAMP:20260901T090000Z',
+  'DTSTART:20260902T120000Z',
+  'DTEND:20260902T130000Z',
+  'ORGANIZER:mailto:organizer@example.com',
+  'ATTENDEE;RSVP=TRUE:mailto:attendee@example.net',
+  'SUMMARY:Lunch',
+  'END:VEVENT',
+  'END:VCALENDAR',
+].join('\r\n');
+
+const message = createMessage({
+  from: 'organizer@example.com',
+  to: 'attendee@example.net',
+  subject: 'Lunch on Wednesday',
+  content: { text: 'Lunch on Wednesday at noon.' },
+  calendar: { method: 'REQUEST', content: invitation },
+});
+```
+
+An object declaring a different method, or none at all, is rejected with a
+`TypeError` rather than sent as something a client will mishandle.  Line endings
+are normalized to the CRLF [RFC 5545] requires, so an object held with plain
+newlines works as it is.
+
+@alexify/mailer checks every content line against the grammar in [RFC 5545] §3.1,
+including property names, parameters, and the characters allowed in values.
+For example, `SUMMARY;BROKEN:Lunch` is refused because a parameter needs an
+`=` and a value, which may be empty.  A double quote inside an unquoted
+parameter value or a forbidden control character is refused too.  Correct
+these errors in the template or generator that produced the object.
+
+The content must also be one `VCALENDAR` object with balanced components and
+exactly one supported top-level `METHOD`.  This is not full iCalendar or iTIP
+validation: @alexify/mailer does not check property-specific value syntax, required event
+fields, or whether the event itself makes sense.
+
+[RFC 5545]: https://www.rfc-editor.org/rfc/rfc5545
+
+## Replies and cancellations
+
+The three methods an application usually needs are `REQUEST` for an invitation,
+`REPLY` for an answer to one, and `CANCEL` for calling it off.  `PUBLISH`,
+`ADD`, `REFRESH`, `COUNTER`, and `DECLINECOUNTER` are accepted too.
+
+A cancellation is an ordinary message carrying an object with `METHOD:CANCEL`,
+the same `UID` as the invitation, and a higher `SEQUENCE`:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'organizer@example.com',
+  to: 'attendee@example.net',
+  subject: 'Cancelled: Lunch on Wednesday',
+  content: { text: "Wednesday's lunch is cancelled." },
+  calendar: { method: 'CANCEL', content: cancellation },
+});
+```
+
+A reply reverses the direction: the attendee sends it to the organizer, and the
+object carries `METHOD:REPLY` with that one attendee's `PARTSTAT`.  Nothing
+about the transport changes.
+
+## Write the human-readable body too
+
+`content` is still required, and it still matters.  A recipient whose client
+knows nothing about scheduling sees that and nothing else, so it should say what
+the invitation says.
+
+There is a second reason to keep them consistent: on import, Outlook replaces
+the calendar object's `DESCRIPTION` with the first `text/html` alternative in
+the message.  A mismatch between the two shows up as an event whose description
+contradicts the mail it arrived in.
+
+## Transport support
+
+Composing a `text/calendar` alternative requires a transport that builds the
+message structure itself.  Only two do; the rest hand a provider a subject, a
+body, and a list of files.
+
+| Transport          | Calendar handling                         |
+| ------------------ | ----------------------------------------- |
+| *@alexify/mailer/smtp*       | Composed as a `text/calendar` alternative |
+| *@alexify/mailer/jmap*       | Composed as a `text/calendar` alternative |
+| *@alexify/mailer/mailgun*    | Sent as an *invite.ics* attachment        |
+| *@alexify/mailer/sendgrid*   | Sent as an *invite.ics* attachment        |
+| *@alexify/mailer/mailtrap*   | Sent as an *invite.ics* attachment        |
+| *@alexify/mailer/maileroo*   | Sent as an *invite.ics* attachment        |
+| *@alexify/mailer/lettermint* | Sent as an *invite.ics* attachment        |
+| *@alexify/mailer/resend*     | Sent as an *invite.ics* attachment        |
+| *@alexify/mailer/plunk*      | Sent as an *invite.ics* attachment        |
+| *@alexify/mailer/ses*        | Sent as an *invite.ics* attachment        |
+
+The composing transports place the calendar last inside a
+`multipart/alternative`, after the text and HTML bodies, which is the order
+[RFC 2046] §5.1.4 gives for increasing preference.  *@alexify/mailer/smtp* encodes the
+part as Base64, which keeps the object's line structure exactly as written;
+*@alexify/mailer/jmap* hands the object to the server, which picks the transfer encoding
+itself.
+
+*@alexify/mailer/jmap* depends on one thing the standard does not promise.  [RFC 8621]
+§4.1.4 defines a body part's `type` as the media type with its parameters
+stripped, and gives no property for the `method` the invitation needs, so @alexify/mailer
+writes the whole field into `type` and relies on the server passing it through.
+Stalwart does, and the end-to-end test downloads the composed message to check
+it; a server that strips the parameter instead would deliver an invitation no
+client can act on.  The same reliance is not new to calendars, since the text
+and HTML parts already carry their charset the same way, but it is worth knowing
+before pointing this transport at an unfamiliar server.
+
+“Sent as an attachment” describes @alexify/mailer, not the provider.  Those APIs take a
+text body, an HTML body, and files; none of them offers a third body
+alternative, so the object travels as a part named *invite.ics* whose content
+type keeps the `method` parameter.  That is a real degradation rather than a
+different spelling of the same thing: whether a given provider preserves the
+parameter, and whether a given client then treats the part as an invitation
+rather than as a download, has not been verified per provider.  If the
+scheduling semantics matter, send through *@alexify/mailer/smtp* or *@alexify/mailer/jmap*.
+
+The attachment is placed ahead of your own files, so a client looking for the
+first calendar part in the message finds the invitation.  *@alexify/mailer/plunk* carries
+at most five attachments, and rather than quietly drop one of yours to make room
+it refuses a calendar message that would exceed the limit.  *@alexify/mailer/resend* sends
+a calendar message individually rather than through its batch API, which accepts
+no attachments.
+
+> [!NOTE]
+> @alexify/mailer's tests assert the MIME structure, and the JMAP composition is verified
+> against a real server.  They do not assert what Gmail, Outlook, or Apple Mail
+> do with the result.  Send yourself a test invitation before promising anyone
+> that RSVP works.
+
+[RFC 2046]: https://www.rfc-editor.org/rfc/rfc2046
+[RFC 8621]: https://www.rfc-editor.org/rfc/rfc8621
+
+## Recipients and privacy
+
+The addresses in the message and the addresses in the calendar object are
+separate, and only the first are hidden by `bcc`.  @alexify/mailer never writes a `Bcc`
+header, so a blind recipient stays hidden from the others—but every recipient
+receives the same iCalendar object, and any address written into an `ATTENDEE`
+property is in it.
+
+An invitation whose attendee list is private therefore needs a separate message
+per recipient, each carrying an object naming only that attendee.  This is also
+what `REPLY` needs anyway, since a reply speaks for one attendee.
diff --git a/docs/messages/compose.md b/docs/messages/compose.md
new file mode 100644
index 0000000..46609e5
--- /dev/null
+++ b/docs/messages/compose.md
@@ -0,0 +1,368 @@
+# Composing messages
+
+Creating email messages in @alexify/mailer is straightforward and flexible. The library
+provides the `createMessage()` function from the root entry, *@alexify/mailer*,
+which accepts various input formats and automatically handles validation
+and type conversion for you.
+
+To serialize a message without sending it, use the
+[MIME composition API](/messages/mime).
+
+## Basic message creation
+
+To create a simple email message, you need to provide at minimum a sender
+address, recipient address, subject, and content. The `createMessage()` function
+accepts these in a convenient object format:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Hello from mailer!',
+  content: { text: 'This is a test email.' },
+});
+```
+
+The function automatically converts string email addresses to proper `Address`
+objects and validates the input.  You can provide email addresses as simple
+strings like `"user@example.com"` or with display names using the format
+`"Name <user@server.com>"` like `"John Doe <john@example.com>"`.
+You can also provide `Address` objects directly if you prefer to work with
+the structured format.
+
+## Multiple recipients
+
+When you need to send an email to multiple recipients, you can provide arrays
+for the `to`, `cc`, and `bcc` fields.  Each field accepts either a single
+address or an array of addresses, and you can mix different formats including
+plain email addresses, display name formats, and `Address` objects:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'Support Team <support@example.com>',
+  to: ['recipient1@example.com', 'John Smith <john@example.com>'],
+  cc: { name: 'Manager', address: 'manager@example.com' },
+  bcc: ['archive@example.com', 'backup@example.com'],
+  subject: 'Team Update',
+  content: { text: "Here's the latest team update." },
+});
+```
+
+You can also specify a custom reply-to address using the `replyTo` field,
+which is useful when you want replies to go to a different address than
+the sender:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'noreply@example.com',
+  to: 'customer@example.com',
+  replyTo: 'support@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+```
+
+## Internationalized addresses
+
+@alexify/mailer accepts internationalized mailbox addresses with UTF-8 local parts and
+Unicode domains, as defined by the internationalized email framework in
+[RFC 6530]:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'josé@example.com',
+  to: '用户@例子.广告',
+  subject: 'Hello',
+  content: { text: 'Welcome!' },
+});
+```
+
+The local part is limited to 64 UTF-8 octets.  @alexify/mailer preserves the spelling and
+Unicode normalization supplied by the caller because changing a local part can
+change the mailbox it identifies.
+
+Provider support still depends on the selected transport.  The
+[SMTP transport](/transports/smtp#internationalized-addresses) negotiates
+the `SMTPUTF8` extension automatically and reports a failed receipt when the
+server cannot accept an internationalized address.
+
+[RFC 6530]: https://www.rfc-editor.org/rfc/rfc6530
+
+## Rich content
+
+@alexify/mailer supports both plain text and HTML email content.  You can provide just text
+content, just HTML content, or both. When you provide both, email clients will
+choose the appropriate format to display:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'newsletter@example.com',
+  to: 'subscriber@example.com',
+  subject: 'Monthly Newsletter',
+  content: {
+    html: '<h1>Welcome to our newsletter!</h1><p>This month we have exciting updates.</p>',
+    text: 'Welcome to our newsletter! This month we have exciting updates.',
+  },
+});
+```
+
+A message can also carry an iCalendar object alongside the text and HTML, which
+is what turns it into a meeting invitation rather than an email that mentions a
+meeting.  See [Calendar invitations](/messages/calendar).
+
+If you only need plain text, you can simply provide the `text` property:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'system@example.com',
+  to: 'user@example.com',
+  subject: 'System Notification',
+  content: { text: 'Your backup has completed successfully.' },
+});
+```
+
+## Message priority and organization
+
+You can set the priority level of your messages to help recipients understand
+their importance. @alexify/mailer supports three priority levels: `"high"`, `"normal"`,
+and `"low"`:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'alerts@example.com',
+  to: 'admin@example.com',
+  subject: 'Server Alert',
+  content: { text: 'The server is experiencing high load.' },
+  priority: 'high',
+});
+```
+
+For better organization and filtering, you can add tags to your messages.
+Tags are simple strings that can help you categorize and search your
+emails later:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Ticket Update',
+  content: { text: 'Your support ticket has been updated.' },
+  tags: ['support', 'customer-service', 'urgent'],
+});
+```
+
+## Custom headers
+
+Sometimes you need to include custom email headers for specific functionality
+or compliance requirements. You can add custom headers using the `headers` field
+as a simple object, a standard [`Headers`] instance, or an `ImmutableHeaders`
+instance (which is an immutable version compatible with the standard
+[`Headers`] interface):
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+// Using a simple object
+const message1 = createMessage({
+  from: 'app@example.com',
+  to: 'user@example.com',
+  subject: 'Password Reset',
+  content: { text: 'Click the link to reset your password.' },
+  headers: {
+    'X-Mailer': 'mailer Email Library',
+    'X-Priority': '1',
+    'List-Unsubscribe': '<mailto:unsubscribe@example.com>',
+  },
+});
+```
+
+```js
+// Using standard Headers object
+const headers = new Headers();
+headers.set('X-Mailer', 'mailer Email Library');
+headers.set('X-Priority', '1');
+
+const message2 = createMessage({
+  from: 'app@example.com',
+  to: 'user@example.com',
+  subject: 'Password Reset',
+  content: { text: 'Click the link to reset your password.' },
+  headers,
+});
+```
+
+The `createMessage()` function handles all the complexity of email message
+construction, ensuring that your messages are properly formatted and valid
+before sending them through your chosen transport.
+
+[`Headers`]: https://developer.mozilla.org/en-US/docs/Web/API/Headers
+
+### Headers the transport owns
+
+A few header fields come from the message itself rather than from `headers`, so
+a transport that composes the message ignores custom headers that would collide
+with them: `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Subject`, `MIME-Version`,
+`Content-Type`, and `Content-Transfer-Encoding`.  Use the corresponding
+`createMessage()` fields to set those.  Note that `Bcc` in particular is carried
+in the envelope and never written into the message, so blind recipients stay
+hidden from everyone who receives it.
+
+`Date`, `Message-ID`, `In-Reply-To`, and `References` have dedicated fields too,
+described in the next section.  They differ from the fields above in that a
+custom header is still honored when the dedicated field is left unset, so the
+header form keeps working.
+
+## Message identity and reply threading
+
+Applications that correlate replies, such as a helpdesk matching an incoming
+answer back to a ticket, need to choose the outgoing message identifier rather
+than discover it afterwards.  `createMessage()` takes four fields for that:
+
+- `messageId`: The RFC 5322 message identifier.  The enclosing angle brackets are
+  optional and stripped, so `<abc@example.com>` and `abc@example.com` mean
+  the same thing.
+
+- `date`: The origination date.  With neither this nor a custom `Date` header set, a
+  transport that composes the message uses the time of conversion, so a retry
+  carries a later date.
+
+- `inReplyTo`: The identifier, or identifiers, of the messages this one replies to.
+
+- `references`: The identifiers of the conversation, oldest first.  A reply usually carries
+  the parent's references followed by the parent's own identifier, which is
+  how a mail client reconstructs a thread.
+
+Mint an identifier with `generateMessageId()` before sending, store it with
+whatever the message is about, and the value survives conversion and any
+delivery retry, because a retry re-sends the very same message:
+
+```js
+const { createMessage, generateMessageId } = require('@alexify/mailer');
+
+const messageId = generateMessageId('example.com');
+await storeTicketMessageId(messageId);
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.net',
+  subject: 'Re: Your request',
+  content: { text: 'Thanks for getting in touch.' },
+  messageId,
+  date: new Date('2026-09-01T10:00:00Z'),
+});
+```
+
+When the customer answers, their reply carries `In-Reply-To: <that identifier>`,
+which is what ties the answer back to the ticket.  Composing the next message in
+the thread is the mirror image:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+const reply = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.net',
+  subject: 'Re: Your request',
+  content: { text: 'Here is the answer.' },
+  inReplyTo: inbound.messageId,
+  references: [...inbound.references, inbound.messageId],
+});
+```
+
+An identifier that is not valid is rejected rather than repaired, since these
+fields are written into the message as given:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+
+try {
+  createMessage({
+    from: 'support@example.com',
+    to: 'customer@example.net',
+    subject: 'Re: Your request',
+    content: { text: 'Thanks for getting in touch.' },
+    messageId: 'not an identifier',
+  });
+} catch (error) {
+  console.error(error); // TypeError: Invalid message ID: "not an identifier"
+}
+```
+
+`parseMessageId()` normalizes a single identifier and returns `undefined`
+instead of throwing, which is convenient for values arriving from elsewhere.
+It parses one identifier, so an `In-Reply-To` field carrying several has to be
+split first.
+
+### Dropping an inherited header
+
+`inReplyTo` and `references` distinguish three states, which matters when a
+message is assembled from a template that already carries these headers:
+
+ -  Leaving the field unset defers to a custom `In-Reply-To` or `References`
+    header.
+ -  Setting it to a non-empty array replaces that header.
+ -  Setting it to an empty array suppresses the header, so the message
+    deliberately starts a new thread.
+
+### Transport support
+
+`Message-ID` and `Date` are only as durable as the transport carrying them.  A
+provider that composes the message on its own side may assign or rewrite both,
+whatever the message asked for.
+
+| Transport          | `Message-ID` and `Date` | `In-Reply-To` and `References` |
+| ------------------ | ----------------------- | ------------------------------ |
+| *@alexify/mailer/smtp*       | Written as given        | Written as given               |
+| *@alexify/mailer/jmap*       | Written as given        | Written as given               |
+| *@alexify/mailer/mailgun*    | Not sent                | Sent as a custom header        |
+| *@alexify/mailer/sendgrid*   | Not sent                | Sent as a custom header        |
+| *@alexify/mailer/mailtrap*   | Not sent                | Sent as a custom header        |
+| *@alexify/mailer/maileroo*   | Not sent                | Sent as a custom header        |
+| *@alexify/mailer/lettermint* | Not sent                | Sent as a custom header        |
+| *@alexify/mailer/resend*     | Not sent                | Sent as a custom header        |
+| *@alexify/mailer/plunk*      | Not sent                | Sent as a custom header        |
+| *@alexify/mailer/ses*        | Not sent                | Not sent                       |
+
+“Not sent” describes @alexify/mailer, not the provider.  Most of these APIs accept a
+custom `Message-ID` without documenting whether the value survives their
+pipeline; Lettermint documents that it replaces one unless a separate opt-in
+header accompanies it, and Amazon SES documents that it overrides both fields
+even for a raw MIME message.  Rather than promise preservation @alexify/mailer cannot
+verify, those transports leave the fields alone.  *@alexify/mailer/ses* sends no custom
+headers at all.
+
+Providers also cap header values well below the length a long thread produces:
+768 characters for Maileroo, around 995 for Plunk and Amazon SES.  @alexify/mailer does not
+truncate a `References` chain, so an over-long one surfaces as a provider error.
+
+> [!NOTE]
+> A message identifier supports *correlation*.  It is not a capability, so
+> receiving one proves nothing about who sent it; it does not deduplicate
+> anything, nor make delivery exactly-once; and a recipient's mail client may
+> thread by subject regardless.
+
+### `Message-ID` is not `Receipt.messageId`
+
+The `messageId` on a successful `Receipt` is the delivery handle the transport
+or the provider reports back: an SMTP queue identifier, a provider UUID, a JMAP
+submission id.  It is chosen by the far side, differs in shape between
+transports, and is not the RFC 5322 `Message-ID` the message carries.  Use it to
+look a delivery up in a provider's dashboard; use `message.messageId` to
+correlate a reply.
+
diff --git a/docs/messages/mime.md b/docs/messages/mime.md
new file mode 100644
index 0000000..5a208b6
--- /dev/null
+++ b/docs/messages/mime.md
@@ -0,0 +1,120 @@
+# Composing MIME
+
+`composeMessage()` from *@alexify/mailer/mime* turns a structured message into replayable
+MIME bytes without opening a transport connection. Use it to save an *.eml*
+file, inspect a message before delivery, or supply the same serialized message
+to a raw-message transport.
+
+```js
+const { createMessage, readAttachmentContent } = require('@alexify/mailer');
+const { composeMessage } = require('@alexify/mailer/mime');
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.com',
+  bcc: 'archive@example.com',
+  subject: 'A copy for your records',
+  content: { text: 'Hello!', html: '<p>Hello!</p>' },
+});
+const composed = await composeMessage(message);
+const eml = await readAttachmentContent(composed.content);
+// Save eml with your runtime's file or object-storage API.
+```
+
+The result implements `RawMessage`. Its envelope contains the sender and all
+To, Cc, and Bcc recipients; the MIME has no Bcc header. The generated date,
+message identifier, and multipart boundaries stay the same on every read.
+Typed identity and threading fields follow the same precedence as
+[structured messages](/messages/compose).
+
+The bytes use CRLF and include the final line ending. They contain neither SMTP
+dot-stuffing nor the DATA terminator. Collecting them as shown above uses memory
+proportional to the complete message. For large messages, consume the chunks:
+
+```js
+for await (const chunk of composed.content()) {
+  await writeChunk(chunk);
+}
+```
+
+Only treat a saved message as complete after iteration finishes successfully.
+An attachment failure, cancellation, or replay error can occur after some bytes
+have been written.
+
+## Sending composed bytes
+
+Both [SMTP](/transports/smtp) and [JMAP](/transports/jmap) accept the
+result directly through `sendRaw()`:
+
+```js
+await smtp.sendRaw(composed);
+// Or, with a JMAP transport:
+await jmap.sendRaw(composed);
+```
+
+`encoding` is `"7bit"` or `"utf8"`, based on all MIME headers, including nested
+parts and DKIM signatures. Internationalized envelope addresses have their own
+transport requirements. The result has a factory source and an explicit
+encoding, so raw SMTP delivery does not perform a size-analysis pass or announce
+a known `SIZE` before DATA. Server size limits still apply while sending. To
+request the existing analysis pass, pass `{ ...composed, encoding: undefined }`
+to `sendRaw()`, which reads the source an extra time. Alternatively, collect
+bytes first and replace `content` with that byte array.
+
+To change delivery addresses without changing the MIME, pass a copy with a new
+`envelope`. SMTP transport DKIM settings do not sign raw messages; use the
+composition option below. A JMAP server may modify imported MIME during
+submission, so its recipients are not guaranteed to receive identical bytes or
+an intact original DKIM signature.
+
+## Signing and attachment lifetime
+
+Pass `dkim` to sign during composition. It accepts the same signature settings
+as the [SMTP DKIM configuration](/transports/smtp#dkim-signing).
+
+```js
+const { composeMessage } = require('@alexify/mailer/mime');
+
+const composed = await composeMessage(message, {
+  dkim: {
+    bodyMode: 'streaming',
+    signatures: [
+      {
+        signingDomain: 'example.com',
+        selector: 'mail',
+        privateKey,
+      },
+    ],
+  },
+});
+```
+
+Without signing, composition neither awaits promised attachment bytes nor opens
+attachment factories. Each content reader reads the attachments when it reaches
+them. Keep byte arrays immutable, and make factories return fresh, independent
+readers with identical bytes. Metadata and signing options are copied during
+composition; attachment bytes remain caller-owned.
+
+The default DKIM body mode, `"buffered"`, reads the body once before composition
+resolves and retains it for subsequent readers. `"streaming"` hashes it once
+before resolving, then reads it again for every content reader. Multiple
+signatures share those passes. A changed streaming body throws
+`MimeAttachmentReplayError`, a `RawMessageValidationError` whose `field` is
+`"content"`. Raw transports report it as a nonretryable raw-message validation
+failure.
+
+Signing failures throw by default. `onSigningFailure: "send-unsigned"` logs a
+warning and continues; signatures completed before a later signing failure
+remain on the message. Attachment-read failures and cancellation still throw.
+
+## Cancellation
+
+`composeMessage(message, { signal })` uses the signal during preparation and
+for every future reader. Calling `composed.content(readerSignal)` additionally
+cancels that reader alone. Readers can run concurrently; cancelling one does
+not cancel the others. Cancellation preserves the signal's reason.
+
+Stopping a `for await` loop closes the active attachment reader. Factories
+should honor their signal during acquisition and reading so they can release
+resources promptly. No reader stays open after composition itself finishes,
+and the composed result does not need disposal.
diff --git a/docs/public/llms.txt b/docs/public/llms.txt
index f1cd986..a9024e7 100644
--- a/docs/public/llms.txt
+++ b/docs/public/llms.txt
@@ -6,12 +6,17 @@
 > audit log, one model of delivery events, suppression and idempotency.
 
 Key facts:
-- Status: work in progress. The API is being designed; `createMailer` is exported as a
-  placeholder that throws
+- Status: work in progress. The transport layer is ported from upyo 0.7.0 (MIT); the
+  reliability layer is being designed, and `createMailer` is exported as a placeholder that throws
 - Package (npm): `@alexify/mailer`, installed with `npm install @alexify/mailer`
-- Node.js >= 22 only; CommonJS with ESM named-import interop; hand-written `index.d.ts`
-- Zero runtime dependencies: the transports are built on `node:*` modules and `fetch`, and the
-  drivers of a queue or a database (BullMQ, MongoDB) are passed in by the application
-- Exports: `createMailer(options)`
+- Node.js >= 22 only; CommonJS with ESM named-import interop; hand-written d.ts per entry
+- Zero runtime dependencies: the transports are built on `node:*` modules and `fetch`; the
+  OpenTelemetry providers, the logger and the drivers of a queue or a database are passed in
+- Root entry `@alexify/mailer`: `createMessage`, the `Transport` contract, receipts,
+  attachments, calendar parts, Message-ID helpers, `createMailer(options)`
+- Subpaths: `/mime` (MIME, DKIM), `/smtp`, `/jmap`, `/ses`, `/resend`, `/sendgrid`, `/mailgun`,
+  `/mailtrap`, `/maileroo`, `/lettermint`, `/plunk`, `/pool`, `/retry`, `/otel`, `/logger`, `/mock`
+- Guide: https://mailerat.vercel.app/guide/getting-started
+- API: https://mailerat.vercel.app/api/exports
 - Comparison with 14 alternatives (Nodemailer, emailjs, Upyo, unemail, sently, provider SDKs):
   https://mailerat.vercel.app/guide/comparison
diff --git a/docs/transports/custom.md b/docs/transports/custom.md
new file mode 100644
index 0000000..b4ef0de
--- /dev/null
+++ b/docs/transports/custom.md
@@ -0,0 +1,499 @@
+# Custom transport
+
+A custom transport allows you to integrate any email service with @alexify/mailer by
+implementing the simple `Transport` interface. Whether you're connecting to
+a proprietary email API, adding specialized logging, or building testing
+utilities, custom transports provide the flexibility you need.
+
+@alexify/mailer's transport abstraction ensures that custom implementations work
+seamlessly alongside built-in transports like [SMTP](/transports/smtp),
+[Mailgun](/transports/mailgun), and [SendGrid](/transports/sendgrid).
+Your application code remains unchanged when switching between different
+email providers.
+
+This guide walks you through the implementation patterns and best practices
+for creating robust, production-ready custom transports.
+
+## When to create a custom transport
+
+Consider creating a custom transport when:
+
+ -  You need to integrate with an email service not supported by @alexify/mailer
+ -  Your organization has internal email systems with custom APIs
+ -  You require specialized behavior (logging, metrics, preprocessing)
+ -  You want to create transport for testing specific scenarios
+
+## Understanding the `Transport` interface
+
+The `Transport` interface is the foundation of @alexify/mailer's email abstraction.
+It defines a simple contract that all email services must implement,
+ensuring consistent behavior across different providers.
+
+```js
+
+```
+
+This interface is intentionally minimal, with just two methods that handle
+the core email sending operations, plus a stable provider `id` used in
+structured receipt metadata.  The design philosophy prioritizes simplicity and
+reliability over feature complexity.
+
+### Core principles
+
+When implementing a custom transport, these principles ensure compatibility with
+the @alexify/mailer ecosystem:
+
+*Return receipts for delivery failures.* The sending methods report delivery
+failures through `Receipt` objects. Caller cancellation rejects instead.
+The optional `verify()` method also rejects on failure because it does not
+perform a delivery or produce a receipt.
+
+**Support cancellation through [`AbortSignal`].** Modern applications need the
+ability to cancel long-running operations.  Check
+`options?.signal?.throwIfAborted()` at strategic points in your implementation,
+especially before expensive network operations.
+
+**Return descriptive receipts.** Success receipts should include a meaningful
+`messageId` that can be used for tracking and debugging.  Failure receipts
+should provide specific `errorMessages` that help developers understand what
+went wrong.  Use a string literal provider id, such as `Transport<"myservice">`,
+when you want `Receipt.provider` and `ReceiptError.provider` to be type-safe.
+
+[`AbortSignal`]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+
+## Basic HTTP transport example
+
+Most modern email services provide HTTP APIs for sending emails.  This makes
+HTTP-based transports the most common type of custom implementation.
+
+Let's build a complete transport for a fictional service called “MyService”
+to demonstrate the key patterns. The example below shows all the essential
+components: configuration management, HTTP communication, proper error
+handling, and cancellation support.
+
+```js
+const { createFailedReceipt } = require('@alexify/mailer');
+
+class MyServiceTransport {
+  id = 'myservice';
+
+  config;
+
+  constructor(config) {
+    this.config = {
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl ?? 'https://api.myservice.com/v1',
+    };
+  }
+
+  async send(message, options) {
+    // Check for cancellation
+    options?.signal?.throwIfAborted();
+
+    try {
+      // Convert message to API format
+      const payload = {
+        from: message.sender.address,
+        to: message.recipients.map((r) => r.address),
+        subject: message.subject,
+        text: message.content.text,
+        html: 'html' in message.content ? message.content.html : undefined,
+      };
+
+      options?.signal?.throwIfAborted();
+
+      // Send via API
+      const response = await fetch(`${this.config.baseUrl}/send`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(payload),
+        signal: options?.signal,
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        return createFailedReceipt(`HTTP ${response.status}: ${error}`, {
+          provider: this.id,
+          statusCode: response.status,
+        });
+      }
+
+      const result = await response.json();
+      return {
+        successful: true,
+        messageId: result.messageId,
+        provider: this.id,
+      };
+    } catch (error) {
+      return createFailedReceipt(error instanceof Error ? error.message : String(error), {
+        provider: this.id,
+      });
+    }
+  }
+
+  async *sendMany(messages, options) {
+    for await (const message of messages) {
+      options?.signal?.throwIfAborted();
+      yield await this.send(message, options);
+    }
+  }
+}
+```
+
+Let's break down the key implementation details:
+
+**Configuration with defaults:** The constructor uses a simple pattern to
+provide sensible defaults while requiring only essential configuration.
+This makes the transport easy to use while remaining flexible.
+
+**Cancellation checking:** Notice how we check
+`options?.signal?.throwIfAborted()` at two critical points: before starting the
+operation and before making the network request. This ensures operations can be
+cancelled promptly.
+
+**Error conversion:** All errors are caught and converted to failed `Receipt`
+objects. This prevents exceptions from propagating and provides a consistent
+error handling experience.
+
+**HTTP error handling:** The code distinguishes between HTTP errors (4xx/5xx
+status codes) and network errors, providing specific error messages for each
+case.
+
+The `Transport.sendMany()` implementation uses a simple pattern that delegates
+to the `Transport.send()` method for each message.  This approach is
+straightforward and works well for most HTTP APIs that don't support batch
+operations.
+
+## Advanced patterns
+
+### Resource cleanup
+
+Some transports need to manage persistent resources like connection pools, file
+handles, or background timers. Implementing the `AsyncDisposable` interface
+ensures proper cleanup and integrates with modern JavaScript resource
+management patterns.
+
+```js
+const { createFailedReceipt } = require('@alexify/mailer');
+
+class MyTransport {
+  id = 'myservice';
+
+  connections = [];
+
+  async send(message, options) {
+    options?.signal?.throwIfAborted();
+    return createFailedReceipt('No connection is available.', {
+      provider: this.id,
+      category: 'configuration',
+      retryable: false,
+    });
+  }
+
+  async *sendMany(messages, options) {
+    for await (const message of messages) {
+      yield await this.send(message, options);
+    }
+  }
+
+  async closeConnections() {
+    await Promise.all(this.connections.map((conn) => conn.close()));
+    this.connections = [];
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.closeConnections();
+  }
+}
+
+// Usage with automatic cleanup
+await using transport = new MyTransport();
+// Transport automatically cleaned up when scope ends
+```
+
+This pattern is particularly important for production deployments where resource
+leaks can cause memory issues or exhaust connection limits. The [`await using`]
+syntax automatically calls the disposal method when the transport goes out of
+scope, even if an exception occurs.
+
+[`await using`]: https://github.com/tc39/proposal-async-explicit-resource-management#await-using-declarations
+
+### Retry logic
+
+Network operations can fail due to temporary issues like network congestion,
+server overload, or brief service outages. Implementing retry logic with
+exponential backoff makes your transport more resilient in production
+environments.
+
+```js
+async function sendWithRetry(sendFn, maxRetries = 3) {
+  let lastError;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await sendFn();
+
+      // Don't retry client errors (4xx)
+      if (response.status >= 400 && response.status < 500) {
+        throw new Error(`Client error: ${response.status}`);
+      }
+
+      if (!response.ok) {
+        throw new Error(`Server error: ${response.status}`);
+      }
+
+      return response;
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (attempt === maxRetries) {
+        throw lastError;
+      }
+
+      // Exponential backoff: 1s, 2s, 4s...
+      const delay = Math.pow(2, attempt) * 1000;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError;
+}
+```
+
+The retry function implements several important patterns: it avoids retrying
+client errors (4xx status codes) since these indicate problems with the
+request itself, uses exponential backoff to avoid overwhelming struggling
+servers, and provides a configurable maximum retry count to prevent infinite
+loops.
+
+> [!CAUTION]
+> Never retry 4xx client errors as these indicate problems with your request
+> that won't be resolved by retrying. Only retry 5xx server errors and
+> network failures.
+
+### Configuration validation
+
+Robust configuration validation prevents runtime errors and provides clear
+feedback when transports are misconfigured.  This is especially important in
+production environments where configuration errors might not be discovered
+until the first email is sent.
+
+```js
+function createApiConfig(config) {
+  if (!config.apiKey) {
+    throw new Error('API key is required');
+  }
+
+  if (config.timeout && config.timeout < 1000) {
+    throw new Error('Timeout must be at least 1000ms');
+  }
+
+  return {
+    apiKey: config.apiKey,
+    timeout: config.timeout ?? 30000,
+  };
+}
+```
+
+This validation approach uses a factory function that both validates input
+and applies defaults. Throwing errors during construction means configuration
+problems are discovered immediately, rather than when the first email is sent.
+
+## Best practices
+
+Following these practices ensures your custom transport integrates well with
+the @alexify/mailer ecosystem and provides a reliable experience for users.
+
+### Handle cancellation properly
+
+Cancellation support is essential for responsive applications. Users should be
+able to cancel email operations that are taking too long or are no longer
+needed.
+
+```js
+// Check before expensive operations
+options?.signal?.throwIfAborted();
+
+// Pass to network calls
+await fetch(url, { signal: options?.signal });
+```
+
+Check for cancellation before starting expensive operations and pass the signal
+to any network calls.  This ensures operations can be cancelled promptly and
+resources aren't wasted.
+
+### Always return receipts, never throw
+
+Consistent error handling is a core principle of the `Transport` interface.
+Users should never have to catch exceptions from transport methods.
+
+```js [✅ Good]
+try {
+  const result = await sendEmail();
+  return { successful: true, messageId: result.id };
+} catch (error) {
+  return { successful: false, errorMessages: [error.message] };
+}
+```
+
+```js [❌ Bad: don't throw from send()]
+async send(message) {
+  throw new Error('Something went wrong');
+}
+```
+
+This approach provides predictable error handling and allows users to handle
+errors consistently across all transports.
+
+### Use the platform, add no dependency
+
+@alexify/mailer runs on Node.js 22 or newer and has no runtime dependencies.  A
+transport may use `node:*` modules and the global `fetch`; prefer `fetch`,
+`AbortSignal` and the other web standards where they fit, and take a client
+library, if one is needed at all, as an option rather than a dependency.
+
+### Provide sensible configuration defaults
+
+Good defaults make your transport easy to use while still allowing customization
+when needed.
+
+```js
+function createConfig(config) {
+  return {
+    ...config,
+    timeout: config.timeout ?? 30000,
+    retries: config.retries ?? 3,
+    baseUrl: config.baseUrl ?? 'https://api.example.com',
+  };
+}
+```
+
+Use factory functions to apply defaults and validate configuration.
+This pattern makes misconfiguration errors visible early and provides
+a better developer experience.
+
+With these patterns, your custom transport will integrate seamlessly with @alexify/mailer's
+ecosystem and provide a consistent, reliable experience for users.
+
+## Sharing your transport
+
+If you've built a transport that others might find useful, consider sharing
+it with the community! There are several ways to make your custom transport
+available to other developers.
+
+### Publishing as a package
+
+You can package and publish your transport as a standalone npm package.  Name
+it after the service, such as *@yourorg/mailer-servicename*, to make it easy
+for users to discover.
+
+Look at the subpaths of the @alexify/mailer repository (`src/ses`,
+`src/resend`) for reference on structure, documentation, and testing
+patterns.  Each one has hand-written type definitions, comprehensive tests,
+and clear usage examples.
+
+Make sure to add *@alexify/mailer* as a peer dependency in your *package.json*
+rather than a regular dependency. This ensures users can control the core
+version and avoids potential version conflicts:
+
+```json
+{
+  "peerDependencies": {
+    "@alexify/mailer": "^0.1.0"
+  }
+}
+```
+
+### Contributing to @alexify/mailer
+
+We welcome contributions of new transports to the @alexify/mailer repository!
+If you've implemented a transport for a popular email service, don't hesitate
+to submit a pull request—we'd love to see what you've built.
+
+While we have established patterns like comprehensive test coverage, proper
+hand-written types, clear documentation, and zero dependencies, you don't
+need to have everything perfect before contributing. Our maintainers are happy
+to help you polish your implementation and bring it up to project standards.
+
+Feel free to open a draft PR early in your development process if you'd like
+feedback or guidance. Check the existing transport implementations for examples,
+but remember that we're here to help you succeed!
+
+## Raw MIME delivery
+
+`RawTransport` extends `Transport` with an optional `sendRaw()` capability.
+Use `isRawTransport()` before sending through a transport supplied by another
+component; decorators must explicitly expose this capability themselves.
+
+```js
+const { isRawTransport } = require('@alexify/mailer');
+
+if (isRawTransport(transport)) {
+  await transport.sendRaw({
+    envelope: { from: 'sender@example.com', to: ['recipient@example.net'] },
+    content: new TextEncoder().encode('Subject: Hello\r\n\r\nHello!\r\n'),
+    encoding: '7bit',
+  });
+}
+```
+
+The envelope is required and independent of all MIME headers, including Bcc.
+Use `null` for a null reverse-path. Content accepts `Uint8Array`, a Promise of
+bytes, `Blob`, or an attachment-style factory that opens an independent reader
+on every call. Do not pass a one-shot stream directly.
+
+An explicit `encoding` reads the source once per successful send. Omitting it
+reads twice: analysis followed by transmission. Factories must reproduce
+identical bytes on both passes, and on concurrent sends. @alexify/mailer checks structure
+and known size again but does not compare a digest of the two passes.
+
+`7bit` requires ASCII bytes. `8bit` allows non-ASCII body bytes and asserts that
+all MIME headers, including nested part headers, are ASCII. This is a caller
+guarantee: @alexify/mailer checks only the top-level headers and does not parse nested
+MIME. Use `utf8` or omit `encoding` if you cannot guarantee ASCII headers
+throughout. `utf8` permits
+internationalized headers. Automatic analysis conservatively selects `utf8`
+for any non-ASCII byte, even in the body; specify `8bit` to avoid that
+additional transport requirement when the headers are ASCII. These values do
+not request transcoding and do not permit binary MIME with NUL bytes.
+
+Raw content must use CRLF throughout, end in CRLF, have a nonempty header
+section, and contain no NUL or line longer than 998 bytes excluding CRLF.
+Headers without a body are valid. @alexify/mailer validates these wire constraints, not
+full MIME syntax or signatures, and never repairs the content. Server-side
+processing can still modify the message.
+
+Transport implementers can use the raw-message source helpers to validate and
+read incrementally. Extra memory is limited to bounded work buffers, the
+largest chunk supplied by the source, and runtime buffers. Sources should
+honor cancellation promptly and release resources when iteration ends.
+
+## Verifying transport configuration
+
+`VerifiableTransport` is an optional capability for checking a transport's
+connection, configured authentication, and prerequisites without sending mail.
+The base `Transport` interface does not require it. Use
+`isVerifiableTransport()` to discover support while retaining the provider ID
+type:
+
+```js
+const { isVerifiableTransport } = require('@alexify/mailer');
+
+if (isVerifiableTransport(transport)) {
+  await transport.verify({ signal: AbortSignal.timeout(10_000) });
+}
+```
+
+`verify()` resolves without a value on success and rejects with a
+transport-specific error on failure. It preserves the caller's abort reason
+when cancelled. A successful check describes setup at that time; it does not
+promise acceptance of any particular message or successful delivery.
+
+[SMTP](/transports/smtp#verifying-the-configuration) and
+[JMAP](/transports/jmap#verifying-the-configuration) implement this capability.
+Retry, pool, and observability wrappers do not automatically forward it.
+Verify the underlying transport before wrapping it, or implement the
+capability explicitly in a custom wrapper.
diff --git a/docs/transports/jmap.md b/docs/transports/jmap.md
new file mode 100644
index 0000000..660797b
--- /dev/null
+++ b/docs/transports/jmap.md
@@ -0,0 +1,513 @@
+# JMAP
+
+[JMAP] (JSON Meta Application Protocol) is a modern, efficient protocol for
+email access and submission, designed as a replacement for IMAP and SMTP.
+It provides a standardized JSON-based API for interacting with mail servers,
+with features like efficient synchronization, typed error responses, and
+stateless operations. JMAP is defined in [RFC 8620] (core) and [RFC 8621]
+(mail) and is increasingly adopted by modern email providers.
+
+@alexify/mailer provides a fully compliant JMAP transport through the *@alexify/mailer/jmap*
+package, supporting session discovery, automatic identity resolution,
+configurable retry logic, and comprehensive error handling.
+
+[JMAP]: https://jmap.io/
+[RFC 8620]: https://www.rfc-editor.org/rfc/rfc8620
+[RFC 8621]: https://www.rfc-editor.org/rfc/rfc8621
+
+## Installation
+
+To use the JMAP transport, you need to install the *@alexify/mailer/jmap* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Getting started
+
+Before using the JMAP transport, you'll need access to a JMAP-compatible
+mail server and authentication credentials. The JMAP session URL
+is typically available at `/.well-known/jmap` on the mail server.
+
+### Bearer token authentication
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+});
+```
+
+### Basic authentication
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  basicAuth: {
+    username: 'user@example.com',
+    password: 'your-password',
+  },
+});
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The JMAP transport handles session discovery automatically, caching the
+session for performance while refreshing it when needed. It automatically
+finds the appropriate account with mail capabilities and resolves the
+sender identity based on the from address.
+
+## Session discovery and caching
+
+JMAP uses a session resource to discover server capabilities, API endpoints,
+and account information. The transport automatically fetches and caches
+this session:
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+  sessionCacheTtl: 600000, // Cache session for 10 minutes
+});
+```
+
+The session cache TTL (time-to-live) controls how long the session is
+cached before being refreshed. The default is 5 minutes (300000ms), which
+balances performance with keeping the session reasonably fresh.
+
+If you know your account ID ahead of time, you can specify it directly
+to skip the account discovery step:
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+  accountId: 'u1234567', // Specific account ID
+});
+```
+
+## Identity resolution
+
+JMAP requires an identity ID for email submission. The transport
+automatically resolves the appropriate identity by matching the sender
+email address with the identities available on the server:
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+});
+
+// Identity is automatically resolved from the "from" address
+const message = createMessage({
+  from: 'alice@example.com', // Will match identity with this email
+  to: 'bob@example.net',
+  subject: 'Meeting tomorrow',
+  content: { text: 'See you at 10am!' },
+});
+
+await transport.send(message);
+```
+
+If you want to use a specific identity, you can provide the identity ID
+directly in the configuration:
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+  identityId: 'i1234567', // Specific identity ID
+});
+```
+
+## Bulk email sending
+
+For sending multiple emails, the JMAP transport provides efficient
+batch processing that combines all messages into a single HTTP request:
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new JmapTransport({
+  sessionUrl: "https://mail.example.com/.well-known/jmap",
+  bearerToken: "your-bearer-token",
+  retries: 3,
+  timeout: 30000,
+});
+
+const subscribers = [
+  "user1@example.com",
+  "user2@example.com",
+  "user3@example.com",
+];
+
+const messages = subscribers.map(email =>
+  createMessage({
+    from: "newsletter@example.com",
+    to: email,
+    subject: "Weekly Update",
+    content: { text: "Here's what's new this week..." },
+  })
+);
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Email sent: ${receipt.messageId}`);
+  } else {
+    console.error(`Failed: ${receipt.errorMessages.join(", ")}`);
+  }
+}
+```
+
+The `JmapTransport.sendMany()` method batches all emails into a single
+JMAP request, significantly reducing HTTP round-trips. Each message
+gets its own receipt, and partial failures are handled gracefully—if
+some emails fail, others in the batch can still succeed.
+
+## Error handling
+
+The JMAP transport provides detailed error information through the
+`JmapApiError` class and helper functions:
+
+```js
+const { JmapTransport, JmapApiError, isCapabilityError } = require('@alexify/mailer/jmap');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+});
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Test',
+  content: { text: 'Hello!' },
+});
+
+try {
+  const receipt = await transport.send(message);
+  if (!receipt.successful) {
+    console.error('Send failed:', receipt.errorMessages);
+  }
+} catch (error) {
+  if (error instanceof JmapApiError) {
+    console.error('JMAP API error:', error.statusCode, error.responseBody);
+    if (error.jmapErrorType) {
+      console.error('Error type:', error.jmapErrorType);
+    }
+  }
+  if (isCapabilityError(error)) {
+    console.error('Server missing required JMAP capabilities');
+  }
+}
+```
+
+## Advanced configuration
+
+The JMAP transport includes comprehensive configuration options for
+timeout handling, retry behavior, and custom headers:
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+  timeout: 15000, // 15 second timeout
+  retries: 5, // Retry failed requests 5 times
+  sessionCacheTtl: 60000, // Cache session for 1 minute
+  headers: {
+    'X-Custom-Header': 'MyApp-v1.0',
+    'X-Environment': 'production',
+  },
+});
+```
+
+The transport uses exponential backoff for retries, with delays of 1s,
+2s, 4s, etc. between attempts. Client errors (4xx responses) are not
+retried, as they typically indicate a problem with the request itself.
+
+### URL rewriting
+
+Some JMAP servers may return internal hostnames in session URLs that are
+not accessible from the client. The `baseUrl` option allows you to rewrite
+these URLs:
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+  // Rewrite URLs returned by the server to use this base URL
+  baseUrl: 'https://mail.example.com',
+});
+```
+
+This is useful when connecting to containerized servers or when the server
+returns hostnames that differ from the external access URL.
+
+## Request cancellation
+
+The JMAP transport supports request cancellation using the standard
+`AbortSignal` API:
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+});
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Test',
+  content: { text: 'Hello!' },
+});
+
+const controller = new AbortController();
+
+// Cancel after 5 seconds
+setTimeout(() => controller.abort(), 5000);
+
+const receipt = await transport.send(message, {
+  signal: controller.signal,
+});
+
+if (!receipt.successful) {
+  console.log('Send was cancelled or failed:', receipt.errorMessages);
+}
+```
+
+## Attachments
+
+The JMAP transport supports file attachments via blob upload. Attachments
+are uploaded to the server before being referenced in the email:
+
+```js
+// @noErrors: 2322
+const { JmapTransport } = require('@alexify/mailer/jmap');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+});
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Document attached',
+  content: { text: 'Please find the document attached.' },
+  attachments: [
+    new File(
+      [await fetch('https://example.com/doc.pdf').then((r) => r.arrayBuffer())],
+      'document.pdf',
+      { type: 'application/pdf' },
+    ),
+  ],
+});
+
+await transport.send(message);
+```
+
+### Inline attachments
+
+For inline images in HTML emails, use the `inline` property and reference
+the attachment via `cid:` URL in the HTML content:
+
+```js
+// @noErrors: 2322
+const { JmapTransport } = require('@alexify/mailer/jmap');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+});
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Email with inline image',
+  content: {
+    html: '<p>Here is an image:</p><img src="cid:logo">',
+  },
+  attachments: [
+    {
+      filename: 'logo.png',
+      content: await fetch('https://example.com/logo.png').then((r) => r.arrayBuffer()),
+      contentType: 'image/png',
+      contentId: 'logo',
+      inline: true,
+    },
+  ],
+});
+
+await transport.send(message);
+```
+
+## Compatible servers
+
+The JMAP transport works with any JMAP-compliant mail server. Some notable
+JMAP implementations include:
+
+- [Stalwart Mail Server]: Open source JMAP server
+
+- [Cyrus IMAP]: Supports JMAP alongside IMAP
+
+- [Fastmail]: Commercial email provider with full JMAP support
+
+- [Apache James]: Modular mail server with JMAP support
+
+[Stalwart Mail Server]: https://stalw.art/
+[Cyrus IMAP]: https://www.cyrusimap.org/
+[Fastmail]: https://www.fastmail.com/
+[Apache James]: https://james.apache.org/
+
+## Sending raw MIME
+
+Use [MIME composition](/messages/mime) to create raw bytes from an @alexify/mailer
+message without opening a transport connection.
+
+`JmapTransport` implements the optional `RawTransport` interface. It uploads
+serialized MIME, imports the uploaded blob into Drafts, and submits that Email
+with an explicit delivery envelope:
+
+```js
+const { JmapTransport } = require('@alexify/mailer/jmap');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-token',
+});
+const receipt = await transport.sendRaw({
+  envelope: { from: 'sender@example.com', to: ['recipient@example.net'] },
+  content: new TextEncoder().encode('From: sender@example.com\r\nSubject: Hello\r\n\r\nHello!\r\n'),
+  encoding: '7bit',
+});
+```
+
+Content accepts bytes, promised bytes, Blob, or replayable attachment-style
+factories. Declaring `encoding` reads the source once per successful send;
+omitting it adds an analysis pass before upload. Every reader must reproduce
+the same bytes. `7bit` requires ASCII, `8bit` asserts ASCII MIME headers with an
+8-bit body, and `utf8` permits internationalized headers. Automatic analysis
+conservatively selects `utf8` for any non-ASCII byte. With `8bit`, the caller
+must ensure nested MIME headers are ASCII; @alexify/mailer checks only top-level headers.
+Use `utf8` or omit `encoding` if unsure. No transcoding occurs.
+
+Sources must have CRLF line endings including the final CRLF, nonempty headers,
+no NUL, and no line longer than 998 bytes excluding CRLF. Uploads stream without
+collecting the message in memory. Progress refreshes the inactivity timeout;
+cancellation stops source reads and requests source cleanup. Response parsing
+also remains subject to timeout. Pass an `AbortSignal` through `signal` in the
+second argument to `sendRaw()`.
+
+The envelope is independent of MIME headers. A configured `identityId` takes
+precedence; otherwise @alexify/mailer selects the identity matching the envelope sender,
+or falls back to the first available identity. A null sender also uses that
+fallback. The server may reject the chosen identity, envelope, or null sender.
+
+@alexify/mailer does not compose or repair the uploaded bytes. JMAP servers may repair
+imported MIME and modify messages during submission; RFC 8621 requires removal
+of Bcc during submission. Raw JMAP delivery therefore does not guarantee that
+an existing signature or byte-for-byte representation reaches the recipient.
+
+Import and submission are each attempted once. `jmap.raw_import_failed` with
+`retryable: true` means no submission was issued, although an imported Email
+may remain after a lost response. A definite server rejection is non-retryable.
+`jmap.raw_submission_unknown` means submission may have succeeded: inspect the
+server state before attempting another send. It is marked non-retryable to
+avoid duplicate delivery. Cancellation cannot recall a submitted message.
+
+An `alreadyExists` import result is reused only when the existing Email refers
+to the exact uploaded blob; matching Message-ID alone is insufficient. @alexify/mailer
+leaves imported Emails in Drafts and does not delete them after success or
+failure. The server expires unreferenced uploaded blobs according to its policy.
+
+See [RFC 8620] for uploads and request errors, and [RFC 8621] for import and
+submission behavior.
+
+## Verifying the configuration
+
+`JmapTransport.verify()` checks live JMAP settings without creating or sending
+an email. It fetches a fresh Session, checks the required capabilities and a
+writable account, and reads the drafts mailbox and available identities.
+A configured `identityId` is checked against the server as well.
+
+```js
+const { JmapApiError, JmapTransport } = require('@alexify/mailer/jmap');
+
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+});
+
+try {
+  await transport.verify({ signal: AbortSignal.timeout(10_000) });
+} catch (error) {
+  if (error instanceof JmapApiError) {
+    console.error(error.message, error.statusCode, error.jmapErrorType);
+  } else {
+    throw error;
+  }
+}
+```
+
+Verification rejects with `JmapApiError` on failure, including malformed
+responses and timeouts. Cancellation preserves the caller's abort reason.
+It does not return a delivery receipt. Existing HTTP error details remain
+available on the error.
+
+With no `accountId`, verification uses the first mail-capable account, as
+`send()` does. It fails if that account lacks submission capability or is
+read-only. Set `accountId` explicitly in a multi-account session. The default
+account selection for `sendRaw()` can differ.
+
+Each Session fetch, `Mailbox/get`, and `Identity/get` operation has `timeout`
+as its total budget, including reading the response body and any retries.
+This can stop an operation before all configured retries have run. The three
+operations run sequentially; an abort signal can bound the entire verification.
+Verification neither reads nor updates the transport's Session cache.
+
+Only Session discovery and read-only JMAP methods are used. No blobs, drafts,
+or submissions are created. Success does not guarantee a mailbox's write
+permissions, acceptance of a particular sender or message, or eventual
+delivery. See the
+[optional verification capability](/transports/custom#verifying-transport-configuration)
+for use with a generic transport.
diff --git a/docs/transports/lettermint.md b/docs/transports/lettermint.md
new file mode 100644
index 0000000..8040d80
--- /dev/null
+++ b/docs/transports/lettermint.md
@@ -0,0 +1,214 @@
+# Lettermint
+
+[Lettermint] is a transactional email provider with a straightforward HTTP
+API for sending emails. It supports common email fields such as recipients,
+HTML and text content, reply-to addresses, custom headers, attachments, and
+inline images, plus provider-specific features such as routes, tags, metadata,
+tracking settings, and idempotency keys.
+
+@alexify/mailer provides the Lettermint transport through the *@alexify/mailer/lettermint* subpath.
+It supports single sends, batch sends of up to 500 messages per request,
+attachments, idempotency, retry logic, and `AbortSignal` cancellation.
+
+[Lettermint]: https://lettermint.co/
+
+## Installation
+
+To use the Lettermint transport, install the *@alexify/mailer/lettermint* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Getting started
+
+Before using the Lettermint transport, you'll need a Lettermint project and a
+sending API token. The token is sent to Lettermint as the
+`x-lettermint-token` request header.
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { LettermintTransport } = require('@alexify/mailer/lettermint');
+
+const transport = new LettermintTransport({
+  apiToken: 'lm_project_1234567890abcdef',
+});
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The transport converts @alexify/mailer messages to Lettermint's JSON format and sends
+them through the `/v1/send` endpoint. HTML and text alternatives, CC, BCC,
+reply-to, custom headers, priority, attachments, and inline Content-ID
+attachments are handled automatically.
+
+## Routes, tags, metadata, and tracking
+
+Lettermint supports provider-specific fields for categorizing and routing
+messages. Configure defaults on the transport when every message sent through
+that transport should share the same route, metadata, or tracking settings:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { LettermintTransport } = require('@alexify/mailer/lettermint');
+
+const transport = new LettermintTransport({
+  apiToken: 'lm_project_1234567890abcdef',
+  route: 'transactional',
+  tag: 'welcome',
+  metadata: {
+    environment: 'production',
+    service: 'accounts',
+  },
+  settings: {
+    trackOpens: false,
+    trackClicks: true,
+  },
+});
+
+const message = createMessage({
+  from: 'onboarding@example.com',
+  to: 'newuser@example.com',
+  subject: 'Welcome to our platform',
+  content: {
+    html: '<h1>Welcome!</h1><p>Thank you for joining us.</p>',
+    text: 'Welcome! Thank you for joining us.',
+  },
+});
+
+await transport.send(message);
+```
+
+Lettermint accepts one tag per message. If a message has exactly one
+`Message.tags` value, that tag overrides the transport's default `tag`. If it
+has more than one tag, the transport returns a failed receipt instead of
+sending the message.
+
+## Batch sending
+
+The `sendMany()` method uses Lettermint's batch endpoint and automatically
+splits large inputs into chunks of 500 messages:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { LettermintTransport } = require('@alexify/mailer/lettermint');
+
+const transport = new LettermintTransport({
+  apiToken: "lm_project_1234567890abcdef",
+});
+
+const recipients = [
+  "user1@example.com",
+  "user2@example.com",
+  "user3@example.com",
+];
+
+const messages = recipients.map(email =>
+  createMessage({
+    from: "updates@example.com",
+    to: email,
+    subject: "Monthly update",
+    content: {
+      html: "<h2>This month's updates</h2><p>Here's what's new.</p>",
+      text: "This month's updates\n\nHere's what's new.",
+    },
+  })
+);
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Email sent with ID: ${receipt.messageId}`);
+  } else {
+    console.error(`Failed to send: ${receipt.errorMessages.join(", ")}`);
+  }
+}
+```
+
+For batch sends, messages without `idempotencyKey` values are grouped into
+Lettermint batch requests with generated request idempotency keys. If any
+message has an `idempotencyKey`, `sendMany()` sends that chunk through the
+single-message API instead so each message's key is preserved.
+
+## Idempotency and reliability
+
+Lettermint supports the `Idempotency-Key` HTTP header to prevent duplicate
+sends during retries. @alexify/mailer maps `Message.idempotencyKey` to that header:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { LettermintTransport } = require('@alexify/mailer/lettermint');
+
+const transport = new LettermintTransport({
+  apiToken: 'lm_project_1234567890abcdef',
+  retries: 3,
+  timeout: 30000,
+});
+
+const message = createMessage({
+  from: 'alerts@example.com',
+  to: 'admin@example.com',
+  subject: 'System alert',
+  content: { text: 'CPU usage has exceeded 90%.' },
+  priority: 'high',
+  idempotencyKey: 'alert-cpu-2026-05-17T10:00Z',
+});
+
+await transport.send(message);
+```
+
+The transport retries temporary failures with exponential backoff. Client
+errors from Lettermint are returned as failed receipts without retrying, and
+`AbortSignal` cancellation is supported through @alexify/mailer's standard transport
+options.
+
+## Attachments and inline images
+
+Attachments are encoded as base64 before being sent to Lettermint. Inline
+attachments include their `content_id` so HTML content can reference them with
+`cid:` URLs:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { LettermintTransport } = require('@alexify/mailer/lettermint');
+
+const transport = new LettermintTransport({
+  apiToken: 'lm_project_1234567890abcdef',
+});
+
+const logo = new TextEncoder().encode('fake image bytes');
+
+const message = createMessage({
+  from: 'brand@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome',
+  content: {
+    html: '<h1>Welcome</h1><img src="cid:logo" alt="Logo">',
+    text: 'Welcome',
+  },
+  attachments: [
+    {
+      filename: 'logo.png',
+      content: logo,
+      contentType: 'image/png',
+      inline: true,
+      contentId: 'logo',
+    },
+  ],
+});
+
+await transport.send(message);
+```
diff --git a/docs/transports/logger.md b/docs/transports/logger.md
new file mode 100644
index 0000000..3676972
--- /dev/null
+++ b/docs/transports/logger.md
@@ -0,0 +1,161 @@
+# Logger transport
+
+The logger transport records email delivery lifecycle events as structured logs,
+through a logger the application passes in: a [pino] logger, a child of one, or
+anything with a method per level that takes the properties first and the message
+second (`logger.info(properties, message)`). It can be used by itself during local
+development, where no message is actually delivered, or as a decorator around
+another transport. In decorator mode, the wrapped transport still performs delivery
+and its receipts and errors pass through unchanged.
+
+@alexify/mailer does not create or configure a logger, and requires none: the
+application keeps its destinations, redaction and levels.
+
+The transport is the `./logger` subpath, adapted from the LogTape transport of
+[upyo](https://github.com/dahlia/upyo).
+
+[pino]: https://getpino.io/
+
+## Installation
+
+```bash
+pnpm add @alexify/mailer pino
+# or
+npm install @alexify/mailer pino
+```
+
+Any pino-like logger works; pino is only the example here.
+
+## Log-only usage
+
+With no wrapped transport, `LoggerTransport` records the send and returns a
+synthetic successful receipt. This is useful for exercising email workflows without
+sending real messages:
+
+```js
+const pino = require('pino');
+const { createMessage } = require('@alexify/mailer');
+const { LoggerTransport } = require('@alexify/mailer/logger');
+
+const logger = pino({ level: 'debug' });
+const transport = new LoggerTransport({ logger });
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Welcome',
+  content: { text: 'Welcome to our service.' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log(receipt.messageId); // "logger-..."
+}
+```
+
+A log-only receipt uses the provider id `"logger"` and a generated message id, but
+it does not imply that an email was delivered outside the application.
+
+## Decorating another transport
+
+Pass another transport through the `transport` option to add logs around real
+delivery:
+
+```js
+const pino = require('pino');
+const { LoggerTransport } = require('@alexify/mailer/logger');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const smtp = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'smtp-user@example.com',
+    pass: 'smtp-password',
+  },
+});
+
+const transport = new LoggerTransport({
+  transport: smtp,
+  logger: pino().child({ component: 'outbound-email' }),
+});
+```
+
+The decorator preserves the wrapped provider id, forwards `AbortSignal`, uses the
+wrapped `sendMany()` implementation, and passes successful and failed receipts
+through unchanged. Exceptions are logged under `err`, the key pino serializes with
+its type, message and stack, and then rethrown. Explicit disposal is also forwarded
+to disposable wrapped transports. Completion logs are emitted as callers consume
+receipts. If a caller stops reading a batch early, the wrapped iterator is closed
+without being drained so the logging layer does not start additional delivery work.
+
+The logger transport can be nested with retry, pool, and OpenTelemetry transports.
+The outer decorator observes the complete operation performed by the inner
+transport, so choose the order according to which retries or failovers should
+appear as one logged operation.
+
+## Levels
+
+The lifecycle levels can be changed independently, by pino's level names
+(`trace`, `debug`, `info`, `warn`, `error`, `fatal`):
+
+```js
+const { LoggerTransport } = require('@alexify/mailer/logger');
+
+const transport = new LoggerTransport({
+  logger,
+  levels: {
+    sending: 'trace',
+    sent: 'info',
+    failed: 'fatal',
+  },
+});
+```
+
+- `sending`: Level for `email.sending` events. Defaults to `"debug"`.
+- `sent`: Level for `email.sent` events. Defaults to `"info"`.
+- `failed`: Level for failed receipts and thrown errors. Defaults to `"error"`.
+
+The transport checks when it is made that the logger has a method for each of the
+three levels, and throws a `TypeError` otherwise.
+
+Every event includes the operation, transport id, recipient counts, attachment
+count, and priority. Completion events additionally include duration and receipt or
+error details. Instead of a category, give the transport a child logger with the
+bindings you want (`logger.child({ component: 'mail' })`).
+
+## Recording message content
+
+Messages are excluded from logs by default. The `recordMessage` option has two
+modes:
+
+- `"properties"`: Adds the complete `Message` object to the structured properties
+  of every lifecycle event. The log message itself remains on one line.
+- `"inline"`: Adds the same `message` property and renders the subject and body
+  beneath the lifecycle message. This format is convenient when reading local
+  development logs.
+
+Use `"properties"` when a destination will process the message as structured data:
+
+```js
+const transport = new LoggerTransport({ logger, recordMessage: 'properties' });
+```
+
+Use `"inline"` to include the subject and body in the log message:
+
+```js
+const transport = new LoggerTransport({ logger, recordMessage: 'inline' });
+```
+
+Inline mode uses plain text whenever the `text` property is defined, even when it
+is an empty string. If no plain-text body is defined, it uses the HTML body. The
+text is built by the transport, since a pino-like logger interpolates no template.
+Lifecycle errors without an associated message stay on one line.
+
+> [!CAUTION]
+> Both modes expose complete messages. These can contain personal addresses,
+> subjects, email bodies, custom headers, and large attachment data. Enable either
+> mode only for destinations with suitable access controls, or with pino's
+> [redaction].
+
+[redaction]: https://getpino.io/#/docs/redaction
diff --git a/docs/transports/maileroo.md b/docs/transports/maileroo.md
new file mode 100644
index 0000000..7b18b23
--- /dev/null
+++ b/docs/transports/maileroo.md
@@ -0,0 +1,227 @@
+# Maileroo
+
+[Maileroo] is an email delivery provider with a JSON-based Email API for
+sending basic, templated, and bulk email. @alexify/mailer provides the Maileroo transport
+through the *@alexify/mailer/maileroo* subpath. It supports single sends, sequential
+`sendMany()`, attachments, custom headers, tags, tracking settings, retry
+logic, structured failure receipts, and `AbortSignal` cancellation.
+
+[Maileroo]: https://maileroo.com/
+
+## Installation
+
+To use the Maileroo transport, install the *@alexify/mailer/maileroo* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Getting started
+
+Before using the Maileroo transport, you need a verified Maileroo sending
+domain and a sending key. The key is sent as an `X-API-Key` header.
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MailerooTransport } = require('@alexify/mailer/maileroo');
+
+const transport = new MailerooTransport({
+  apiKey: 'your-maileroo-sending-key',
+});
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The transport converts @alexify/mailer messages to Maileroo's JSON format and sends them
+through the `/emails` endpoint. HTML and text alternatives, CC, BCC, reply-to,
+custom headers, priority, attachments, and inline attachments are handled
+automatically.
+
+## Tags, headers, and tracking
+
+Maileroo accepts custom tags and headers as maps. Configure default tags and
+tracking on the transport when every message sent through it should share the
+same settings:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MailerooTransport } = require('@alexify/mailer/maileroo');
+
+const transport = new MailerooTransport({
+  apiKey: 'your-maileroo-sending-key',
+  tracking: true,
+  tags: {
+    environment: 'production',
+    service: 'accounts',
+  },
+});
+
+const headers = new Headers();
+headers.set('X-Campaign-ID', 'welcome');
+
+const message = createMessage({
+  from: 'onboarding@example.com',
+  to: 'newuser@example.com',
+  subject: 'Welcome to our platform',
+  content: {
+    html: '<h1>Welcome!</h1><p>Thank you for joining us.</p>',
+    text: 'Welcome! Thank you for joining us.',
+  },
+  headers,
+  tags: ['welcome'],
+});
+
+await transport.send(message);
+```
+
+`Message.tags` values are added as generated Maileroo tag keys such as `tag1`
+and `tag2`, alongside any default tags configured on the transport.
+
+## Sending multiple emails
+
+The `sendMany()` method sends messages sequentially through the single-message
+Maileroo endpoint:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MailerooTransport } = require('@alexify/mailer/maileroo');
+
+const transport = new MailerooTransport({
+  apiKey: "your-maileroo-sending-key",
+});
+
+const recipients = [
+  "user1@example.com",
+  "user2@example.com",
+  "user3@example.com",
+];
+
+const messages = recipients.map(email =>
+  createMessage({
+    from: "updates@example.com",
+    to: email,
+    subject: "Monthly update",
+    content: {
+      html: "<h2>This month's updates</h2><p>Here's what's new.</p>",
+      text: "This month's updates\n\nHere's what's new.",
+    },
+  })
+);
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Email sent with ID: ${receipt.messageId}`);
+  } else {
+    console.error(`Failed to send: ${receipt.errorMessages.join(", ")}`);
+  }
+}
+```
+
+Maileroo also has a bulk endpoint, but its subject, body, headers,
+attachments, tags, and tracking settings are shared across the whole request.
+@alexify/mailer uses sequential sends so each `Message` keeps its own subject, content,
+attachments, and metadata.
+
+## Attachments and inline images
+
+Attachments are encoded as base64 before being sent to Maileroo. Inline
+attachments set Maileroo's `inline` flag so HTML content can reference them
+with `cid:` URLs. For inline attachments, @alexify/mailer sends the attachment's
+`contentId` as Maileroo's attachment name so the `cid:` reference and the
+embedded image use the same identifier:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MailerooTransport } = require('@alexify/mailer/maileroo');
+
+const transport = new MailerooTransport({
+  apiKey: 'your-maileroo-sending-key',
+});
+
+const logo = new TextEncoder().encode('fake image bytes');
+
+const message = createMessage({
+  from: 'brand@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome',
+  content: {
+    html: '<h1>Welcome</h1><img src="cid:logo" alt="Logo">',
+    text: 'Welcome',
+  },
+  attachments: [
+    {
+      filename: 'logo.png',
+      content: logo,
+      contentType: 'image/png',
+      inline: true,
+      contentId: 'logo',
+    },
+  ],
+});
+
+await transport.send(message);
+```
+
+## Advanced configuration and reliability
+
+The Maileroo transport supports custom API endpoints, request timeouts,
+retries, and additional request headers:
+
+```js
+const { MailerooTransport } = require('@alexify/mailer/maileroo');
+
+const transport = new MailerooTransport({
+  apiKey: 'your-maileroo-sending-key',
+  baseUrl: 'https://smtp.maileroo.com/api/v2',
+  timeout: 15000,
+  retries: 5,
+  headers: {
+    'X-Environment': 'production',
+  },
+});
+```
+
+Timeout settings control how long to wait for Maileroo's API responses.
+Temporary failures such as rate limits, request timeouts, and server errors
+are retried with exponential backoff. Permanent client errors are returned as
+failed receipts with provider details so application code can decide whether
+to report, retry later, or discard the message.
+
+`AbortSignal` cancellation is supported through the standard @alexify/mailer transport
+options:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MailerooTransport } = require('@alexify/mailer/maileroo');
+
+const transport = new MailerooTransport({
+  apiKey: 'your-maileroo-sending-key',
+});
+
+const controller = new AbortController();
+
+const message = createMessage({
+  from: 'alerts@example.com',
+  to: 'admin@example.com',
+  subject: 'System alert',
+  content: { text: 'CPU usage has exceeded 90%.' },
+});
+
+const receipt = await transport.send(message, {
+  signal: controller.signal,
+});
+```
diff --git a/docs/transports/mailgun.md b/docs/transports/mailgun.md
new file mode 100644
index 0000000..3d0b0dc
--- /dev/null
+++ b/docs/transports/mailgun.md
@@ -0,0 +1,270 @@
+# Mailgun
+
+[Mailgun] is a powerful email service provider that specializes in reliable
+email delivery for developers and businesses.  It offers robust APIs for
+sending, receiving, and tracking emails, making it particularly well-suited
+for transactional emails such as password resets, order confirmations,
+notifications, and marketing campaigns. Mailgun provides advanced features
+like email analytics, A/B testing, bounce handling, and comprehensive tracking
+capabilities.
+
+@alexify/mailer provides a feature-rich Mailgun transport through the *@alexify/mailer/mailgun*
+package, supporting all major Mailgun features including tracking, tagging,
+regional endpoints, and bulk sending with retry logic.
+
+[Mailgun]: https://www.mailgun.com/
+
+## Installation
+
+To use the Mailgun transport, you need to install the *@alexify/mailer/mailgun* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Getting started
+
+Before using the Mailgun transport, you'll need a Mailgun account and a verified
+domain. Mailgun provides API keys and domain settings through their control
+panel, which you'll use to configure the transport.
+
+```js
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new MailgunTransport({
+  apiKey: '1234567890abcdef1234567890abcdef',
+  domain: 'mg.example.com',
+  region: 'us',
+});
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The Mailgun transport handles authentication automatically using your API key
+and sends emails through Mailgun's reliable infrastructure.  The service manages
+bounces, spam filtering, and delivery optimization automatically.
+
+## Regional configuration
+
+Mailgun operates in multiple regions, and you can choose which region to use
+based on your location and compliance requirements.  The transport supports both
+US and EU regions with automatic endpoint selection:
+
+```js
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+
+// US region (default)
+const usTransport = new MailgunTransport({
+  apiKey: '1234567890abcdef1234567890abcdef',
+  domain: 'mg.example.com',
+  region: 'us',
+});
+
+// EU region for GDPR compliance
+const euTransport = new MailgunTransport({
+  apiKey: '1234567890abcdef1234567890abcdef',
+  domain: 'mg.eu.example.com',
+  region: 'eu',
+});
+
+// Custom endpoint for special configurations
+const customTransport = new MailgunTransport({
+  apiKey: '1234567890abcdef1234567890abcdef',
+  domain: 'mg.example.com',
+  baseUrl: 'https://api.mailgun.net/v3',
+});
+```
+
+The region setting determines which Mailgun servers your emails are sent through
+and where your data is stored.  EU region is particularly important for
+organizations that need to comply with GDPR data residency requirements.
+
+## Email tracking and analytics
+
+One of Mailgun's key features is comprehensive email tracking and analytics.
+The transport enables tracking by default, but you can customize tracking
+behavior based on your needs:
+
+```js
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+
+const transport = new MailgunTransport({
+  apiKey: '1234567890abcdef1234567890abcdef',
+  domain: 'mg.example.com',
+  tracking: true,
+  clickTracking: true,
+  openTracking: true,
+});
+```
+
+With tracking enabled, Mailgun provides detailed analytics about email delivery,
+opens, clicks, and bounces through their dashboard and webhooks.
+This information is invaluable for improving email campaigns and monitoring
+delivery success.
+
+## Message tagging and organization
+
+Mailgun allows you to tag messages for better organization and analytics.
+Tags help you categorize emails and track performance across different types
+of messages:
+
+```js
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new MailgunTransport({
+  apiKey: '1234567890abcdef1234567890abcdef',
+  domain: 'mg.example.com',
+});
+
+const welcomeMessage = createMessage({
+  from: 'onboarding@example.com',
+  to: 'newuser@example.com',
+  subject: 'Welcome to our platform',
+  content: {
+    html: '<h1>Welcome!</h1><p>Thank you for joining us.</p>',
+    text: 'Welcome! Thank you for joining us.',
+  },
+  tags: ['onboarding', 'welcome', 'transactional'],
+});
+
+const receipt = await transport.send(welcomeMessage);
+```
+
+Tags appear in Mailgun's analytics dashboard, allowing you to track open rates,
+click rates, and delivery statistics for specific message categories.
+This helps you understand which types of emails perform best with your audience.
+
+## Bulk email sending
+
+For sending newsletters, notifications, or other bulk emails, the Mailgun
+transport provides efficient batch processing with automatic retry logic
+and error handling:
+
+```js
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new MailgunTransport({
+  apiKey: "1234567890abcdef1234567890abcdef",
+  domain: "mg.example.com",
+  retries: 3,
+  timeout: 30000,
+});
+
+const subscribers = [
+  "user1@example.com",
+  "user2@example.com",
+  "user3@example.com",
+];
+
+const messages = subscribers.map(email =>
+  createMessage({
+    from: "newsletter@example.com",
+    to: email,
+    subject: "Monthly Newsletter - December 2024",
+    content: {
+      html: "<h2>This Month's Updates</h2><p>Here's what's new...</p>",
+      text: "This Month's Updates\n\nHere's what's new...",
+    },
+    tags: ["newsletter", "monthly"],
+  })
+);
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Newsletter sent to ${receipt.messageId}`);
+  } else {
+    console.error(`Failed to send: ${receipt.errorMessages.join(", ")}`);
+  }
+}
+```
+
+The `MailgunTransport.sendMany()` method processes emails sequentially with
+built-in retry logic.  Failed emails don't prevent subsequent emails from being
+sent, and detailed error information helps you identify and resolve delivery
+issues.
+
+## Advanced configuration and reliability
+
+The Mailgun transport includes comprehensive configuration options for timeout
+handling, retry behavior, and SSL validation to ensure reliable email delivery:
+
+```js
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+
+const transport = new MailgunTransport({
+  apiKey: '1234567890abcdef1234567890abcdef',
+  domain: 'mg.example.com',
+  region: 'us',
+  timeout: 15000,
+  retries: 5,
+  validateSsl: true,
+  headers: {
+    'X-Custom-Header': 'MyApp-v1.0',
+    'X-Environment': 'production',
+  },
+  tracking: true,
+  clickTracking: false,
+  openTracking: true,
+});
+```
+
+Timeout settings control how long to wait for Mailgun's API responses,
+while retry configuration determines how many times to retry failed requests.
+The transport uses exponential backoff for retries, reducing load on Mailgun's
+servers during temporary outages.
+
+## Development and testing
+
+For development and testing, you can use Mailgun's [sandbox domain] or configure
+the transport for testing environments.  Mailgun provides sandbox domains that
+accept emails but don't deliver them, perfect for development:
+
+```js
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+
+// Development configuration with sandbox domain
+const devTransport = new MailgunTransport({
+  apiKey: 'test1234567890abcdef1234567890ab',
+  domain: 'sandbox-abc123.mailgun.org', // Mailgun sandbox domain
+  region: 'us',
+  timeout: 5000, // Shorter timeout for development
+});
+
+// Testing configuration with reduced retries
+const testTransport = new MailgunTransport({
+  apiKey: process.env.MAILGUN_TEST_API_KEY ?? 'test123',
+  domain: process.env.MAILGUN_TEST_DOMAIN ?? 'test.example.com',
+  retries: 1, // Fewer retries for faster test execution
+  timeout: 10000,
+  tracking: false, // Disable tracking in tests
+});
+```
+
+Sandbox domains allow you to test email functionality without sending real
+emails, while still receiving confirmation that your integration works
+correctly. This is essential for automated testing and development workflows.
+
+> [!CAUTION]
+> Mailgun's sandbox domains have strict rate limits (typically 50 emails per
+> day) and are intended for basic testing only.  For extensive testing,
+> performance testing, or CI/CD pipelines that send many emails, consider
+> using a verified domain with appropriate rate limits for your testing needs.
+
+[sandbox domain]: https://documentation.mailgun.com/docs/mailgun/user-manual/domains/#sandbox-domain
diff --git a/docs/transports/mailtrap.md b/docs/transports/mailtrap.md
new file mode 100644
index 0000000..95466b2
--- /dev/null
+++ b/docs/transports/mailtrap.md
@@ -0,0 +1,185 @@
+# Mailtrap
+
+[Mailtrap] provides both a production Email API and an Email Sandbox for
+capturing test messages in a virtual inbox. The HTTP API supports HTML and
+text content, attachments, custom headers, categories, and custom variables.
+
+@alexify/mailer provides the Mailtrap transport through the *@alexify/mailer/mailtrap* subpath.
+It supports single sends, batch sends of up to 500 messages per request,
+attachments, retry logic, and `AbortSignal` cancellation.
+
+[Mailtrap]: https://mailtrap.io/
+
+## Installation
+
+To use the Mailtrap transport, install the *@alexify/mailer/mailtrap* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Getting started
+
+Before using the Mailtrap transport, you'll need a Mailtrap API token. The
+token is sent to Mailtrap as the `Api-Token` request header.
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MailtrapTransport } = require('@alexify/mailer/mailtrap');
+
+const transport = new MailtrapTransport({
+  apiToken: 'your-mailtrap-api-token',
+  sandbox: true,
+  inboxId: 12345,
+});
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The transport converts @alexify/mailer messages to Mailtrap's JSON format and sends
+them through the `/api/send` endpoint (or `/api/send/{inboxId}` in sandbox
+mode). HTML and text alternatives, CC, BCC, reply-to, custom headers,
+priority, attachments, and inline Content-ID attachments are handled
+automatically.
+
+## Email API and Email Sandbox
+
+Mailtrap uses one API token for both environments. Set `sandbox: true` and
+provide an `inboxId` to capture messages in a test inbox instead of sending
+through the production Email API:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MailtrapTransport } = require('@alexify/mailer/mailtrap');
+
+const sandboxTransport = new MailtrapTransport({
+  apiToken: 'your-mailtrap-api-token',
+  sandbox: true,
+  inboxId: 12345,
+});
+
+const productionTransport = new MailtrapTransport({
+  apiToken: 'your-mailtrap-api-token',
+});
+
+const message = createMessage({
+  from: 'onboarding@example.com',
+  to: 'newuser@example.com',
+  subject: 'Welcome',
+  content: { text: 'Welcome to our platform.' },
+});
+```
+
+- `sandbox`: When `true`, messages are sent to the Email Sandbox API at
+  `sandbox.api.mailtrap.io` and captured in the inbox identified by
+  `inboxId`.
+
+- `inboxId`: Sandbox inbox ID from `mailtrap.io/sandboxes/{id}`. Required when
+  `sandbox` is `true`.
+
+## Categories, tags, and metadata
+
+Mailtrap uses a `category` field for message classification. @alexify/mailer maps the
+first tag in `Message.tags` to `category`, or falls back to
+`defaultCategory` (default: `transactional`). Additional tags become custom
+variables prefixed with `tag_`. Configure transport-level metadata when
+every message should carry the same tracking fields:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MailtrapTransport } = require('@alexify/mailer/mailtrap');
+
+const transport = new MailtrapTransport({
+  apiToken: 'your-mailtrap-api-token',
+  defaultCategory: 'transactional',
+  metadata: {
+    environment: 'production',
+    service: 'accounts',
+  },
+});
+
+const message = createMessage({
+  from: 'billing@example.com',
+  to: 'customer@example.com',
+  subject: 'Your invoice',
+  content: { text: 'Your invoice is ready.' },
+  tags: ['billing', 'invoice'],
+});
+```
+
+## Batch sending
+
+Use `sendMany()` to send multiple messages. The transport batches up to 500
+messages per API call:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MailtrapTransport } = require('@alexify/mailer/mailtrap');
+
+const transport = new MailtrapTransport({
+  apiToken: "your-mailtrap-api-token",
+  sandbox: true,
+  inboxId: 12345,
+});
+
+const messages = [
+  createMessage({
+    from: "sender@example.com",
+    to: "user1@example.com",
+    subject: "Hello 1",
+    content: { text: "Message 1" },
+  }),
+  createMessage({
+    from: "sender@example.com",
+    to: "user2@example.com",
+    subject: "Hello 2",
+    content: { text: "Message 2" },
+  }),
+];
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log("Sent:", receipt.messageId);
+  } else {
+    console.error("Failed:", receipt.errorMessages.join(", "));
+  }
+}
+```
+
+## Configuration options
+
+- `apiToken`: Your Mailtrap API token.
+
+- `sandbox`: Use Email Sandbox instead of Email API. Default: `false`.
+
+- `inboxId`: Sandbox inbox ID. Required when `sandbox` is `true`.
+
+- `sendBaseUrl`: Email API base URL. Default: `https://send.api.mailtrap.io`.
+
+- `sandboxBaseUrl`: Sandbox API base URL. Default: `https://sandbox.api.mailtrap.io`.
+
+- `defaultCategory`: Default category when a message has no tags. Default: `transactional`.
+
+- `metadata`: Metadata merged into Mailtrap `custom_variables` for every message.
+
+- `userAgent`: User-Agent header sent with requests. Default: `@alexify/mailer/mailtrap`.
+
+- `timeout`: Request timeout in milliseconds. Default: `30000`.
+
+- `retries`: Number of retry attempts for transient failures. Default: `3`.
+
+- `headers`: Additional HTTP headers to include with every request.
diff --git a/docs/transports/mock.md b/docs/transports/mock.md
new file mode 100644
index 0000000..c288808
--- /dev/null
+++ b/docs/transports/mock.md
@@ -0,0 +1,556 @@
+# Mock transport
+
+The mock transport is a specialized testing utility that simulates email sending
+without actually delivering messages. Instead of connecting to email servers
+or APIs, it stores all “sent” messages in memory where they can be
+inspected, verified, and manipulated during testing. This makes it invaluable
+for unit testing, integration testing, and development workflows where you need
+to verify email functionality without sending real emails.
+
+@alexify/mailer provides a comprehensive mock transport through the *@alexify/mailer/mock* subpath,
+offering configurable behavior simulation, message querying capabilities,
+async testing utilities, and full compatibility with all @alexify/mailer transport
+features.
+
+## Installation
+
+To use the mock transport, you need to install the *@alexify/mailer/mock* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Basic testing
+
+The mock transport implements the same `Transport` interface as all other @alexify/mailer
+transports, making it a drop-in replacement for testing purposes. You can swap
+out real transports with the mock transport in your tests without changing any
+other code:
+
+```js
+const { MockTransport } = require('@alexify/mailer/mock');
+const { createMessage } = require('@alexify/mailer');
+
+// Create a basic mock transport
+const transport = new MockTransport();
+
+const message = createMessage({
+  from: 'test-sender@example.com',
+  to: 'test-recipient@example.com',
+  subject: 'Test Email',
+  content: { text: 'This is a test email for verification.' },
+});
+
+// "Send" the email (stored in memory)
+const receipt = await transport.send(message);
+
+// Verify the operation succeeded
+console.log(receipt.successful); // true
+if (receipt.successful) {
+  console.log(receipt.messageId); // "mock-message-1"
+}
+
+// Inspect what was "sent"
+const sentMessages = transport.getSentMessages();
+console.log(sentMessages.length); // 1
+console.log(sentMessages[0].subject); // "Test Email"
+console.log(sentMessages[0].recipients[0].address); // "test-recipient@example.com"
+```
+
+The mock transport generates unique message IDs automatically and tracks all
+sent messages, making it easy to verify that your email logic works correctly
+without any external dependencies.
+
+## Simulating realistic behavior
+
+Real email services have network delays, rate limits, and occasional failures.
+The mock transport can simulate these conditions to make your tests more
+realistic and help you build robust error handling:
+
+```js
+const { MockTransport } = require('@alexify/mailer/mock');
+
+// Configure realistic behavior simulation
+const transport = new MockTransport({
+  // Simulate network delay (100ms fixed)
+  delay: 100,
+
+  // Or use random delays for more realistic testing
+  randomDelayRange: { min: 50, max: 200 },
+
+  // Simulate random failures (10% failure rate)
+  failureRate: 0.1,
+
+  // Custom message ID generation
+  generateUniqueMessageIds: true,
+});
+
+// Test your error handling
+try {
+  const receipt = await transport.send(message);
+
+  if (receipt.successful) {
+    console.log('Email sent successfully');
+  } else {
+    console.log('Email failed:', receipt.errorMessages);
+  }
+} catch (error) {
+  console.log('Network error:', String(error));
+}
+```
+
+Delay simulation helps test timeout handling and ensures your application
+can handle slower network conditions. Failure simulation verifies that your
+error handling code works correctly when email services are unavailable.
+
+## Testing specific failure scenarios
+
+For testing specific error conditions, you can configure the mock transport
+to fail in controlled ways. This is essential for verifying that your
+application handles various email service errors gracefully:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MockTransport } = require('@alexify/mailer/mock');
+
+const transport = new MockTransport();
+
+// Test authentication failure
+transport.setNextResponse({
+  successful: false,
+  errorMessages: ['Authentication failed: Invalid API key'],
+});
+
+const authFailMessage = createMessage({
+  from: 'test@example.com',
+  to: 'user@example.com',
+  subject: 'Auth Test',
+  content: { text: 'Testing auth failure' },
+});
+
+const authResult = await transport.send(authFailMessage);
+console.log(authResult.successful); // false
+if (!authResult.successful) {
+  console.log(authResult.errorMessages); // ["Authentication failed: Invalid API key"]
+}
+
+// Test rate limiting
+transport.setNextResponse({
+  successful: false,
+  errorMessages: ['Rate limit exceeded: Too many requests'],
+});
+
+const rateLimitResult = await transport.send(authFailMessage);
+if (!rateLimitResult.successful) {
+  console.log(rateLimitResult.errorMessages); // ["Rate limit exceeded: Too many requests"]
+}
+
+// Next send will use default (successful) behavior
+const normalResult = await transport.send(authFailMessage);
+console.log(normalResult.successful); // true
+```
+
+The `setNextResponse()` method affects only the next send operation, making it
+perfect for testing specific failure scenarios while keeping the rest of your
+test using normal behavior.
+
+## Message verification and querying
+
+A key feature of the mock transport is its ability to inspect and verify
+sent messages. This goes beyond just counting messages—you can search by
+recipient, subject, content, and custom criteria:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MockTransport } = require('@alexify/mailer/mock');
+
+const transport = new MockTransport();
+
+// Send different types of messages
+await transport.send(
+  createMessage({
+    from: 'support@example.com',
+    to: 'user1@example.com',
+    subject: 'Welcome to our service',
+    content: { text: 'Welcome! Thanks for signing up.' },
+    tags: ['onboarding', 'welcome'],
+  }),
+);
+
+await transport.send(
+  createMessage({
+    from: 'billing@example.com',
+    to: 'user1@example.com',
+    subject: 'Invoice #1234',
+    content: { text: 'Your monthly invoice is ready.' },
+    tags: ['billing', 'invoice'],
+  }),
+);
+
+await transport.send(
+  createMessage({
+    from: 'support@example.com',
+    to: 'user2@example.com',
+    subject: 'Welcome to our service',
+    content: { text: 'Welcome! Thanks for signing up.' },
+    tags: ['onboarding', 'welcome'],
+  }),
+);
+
+// Query messages by recipient
+const user1Messages = transport.getMessagesTo('user1@example.com');
+console.log(user1Messages.length); // 2
+
+// Query by subject
+const welcomeMessages = transport.getMessagesBySubject('Welcome to our service');
+console.log(welcomeMessages.length); // 2
+
+// Custom filtering with predicates
+const billingMessages = transport.findMessagesBy((msg) => msg.tags.includes('billing'));
+console.log(billingMessages.length); // 1
+
+const supportMessages = transport.findMessagesBy(
+  (msg) => msg.sender.address === 'support@example.com',
+);
+console.log(supportMessages.length); // 2
+
+// Find specific message
+const invoice = transport.findMessageBy(
+  (msg) =>
+    msg.subject.includes('Invoice') &&
+    msg.recipients.some((r) => r.address === 'user1@example.com'),
+);
+console.log(invoice?.subject); // "Invoice #1234"
+```
+
+These querying capabilities make it easy to write comprehensive tests that
+verify not just that emails were sent, but that the right emails were sent
+to the right recipients with the correct content.
+
+## Async testing patterns
+
+Many email workflows are asynchronous, such as sending emails after user
+registration or periodic notifications. The mock transport provides utilities
+for testing these async patterns effectively:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MockTransport } = require('@alexify/mailer/mock');
+
+const transport = new MockTransport();
+
+// Simulate an async user registration flow
+async function registerUser(email, name) {
+  // ... registration logic ...
+
+  // Send welcome email asynchronously
+  setTimeout(async () => {
+    await transport.send(
+      createMessage({
+        from: 'welcome@example.com',
+        to: email,
+        subject: `Welcome ${name}!`,
+        content: { text: `Hi ${name}, welcome to our platform!` },
+      }),
+    );
+  }, 100);
+
+  // Send verification email asynchronously
+  setTimeout(async () => {
+    await transport.send(
+      createMessage({
+        from: 'verify@example.com',
+        to: email,
+        subject: 'Please verify your email',
+        content: { text: 'Click here to verify your email address.' },
+      }),
+    );
+  }, 200);
+}
+
+// Test the async workflow
+await registerUser('newuser@example.com', 'John');
+
+// Wait for both emails to be sent
+await transport.waitForMessageCount(2, 5000); // 5 second timeout
+
+// Verify the emails were sent correctly
+const welcomeEmail = await transport.waitForMessage(
+  (msg) =>
+    msg.subject.includes('Welcome') &&
+    msg.recipients.some((r) => r.address === 'newuser@example.com'),
+  3000, // 3 second timeout
+);
+
+console.log(welcomeEmail.subject); // "Welcome John!"
+
+const verificationEmail = await transport.waitForMessage(
+  (msg) => msg.subject.includes('verify'),
+  3000,
+);
+
+console.log(verificationEmail.subject); // "Please verify your email"
+```
+
+The `waitForMessageCount()` and `waitForMessage()` methods are essential for
+testing async email workflows. They prevent race conditions in tests and
+ensure reliable verification of async behavior.
+
+## Bulk email testing
+
+For applications that send newsletters, notifications, or other bulk emails,
+the mock transport efficiently handles large message volumes while providing
+detailed verification capabilities:
+
+```js
+const { MockTransport } = require('@alexify/mailer/mock');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new MockTransport();
+
+// Simulate bulk newsletter sending
+const subscribers = [
+  "alice@example.com",
+  "bob@example.com",
+  "charlie@example.com",
+  "diana@example.com",
+];
+
+const newsletterMessages = subscribers.map(email =>
+  createMessage({
+    from: "newsletter@example.com",
+    to: email,
+    subject: "Monthly Newsletter - December 2024",
+    content: {
+      html: "<h2>This Month's Updates</h2><p>Here's what's new...</p>",
+      text: "This Month's Updates\n\nHere's what's new...",
+    },
+    tags: ["newsletter", "monthly", "december-2024"],
+  })
+);
+
+// Send all newsletters
+const receipts        = [];
+for await (const receipt of transport.sendMany(newsletterMessages)) {
+  receipts.push(receipt);
+
+  if (!receipt.successful) {
+    console.error(`Failed to send to recipient: ${receipt.errorMessages}`);
+  }
+}
+
+// Verify bulk sending results
+console.log(`Sent ${receipts.length} newsletters`);
+console.log(`Successfully sent: ${receipts.filter(r => r.successful).length}`);
+console.log(`Failed: ${receipts.filter(r => !r.successful).length}`);
+
+// Verify all subscribers received the newsletter
+for (const email of subscribers) {
+  const userNewsletters = transport.getMessagesTo(email);
+  console.log(`${email}: ${userNewsletters.length} newsletters`);
+}
+
+// Check newsletter content and tagging
+const allNewsletters = transport.findMessagesBy(msg =>
+  msg.tags.includes("newsletter")
+);
+console.log(`Total newsletters in system: ${allNewsletters.length}`);
+```
+
+The mock transport handles bulk sending efficiently and provides detailed
+verification of each message, making it perfect for testing newsletter
+systems, notification broadcasts, and other high-volume email features.
+
+## Test cleanup and isolation
+
+When running multiple tests, it's important to ensure that each test starts
+with a clean state. The mock transport provides several methods for managing
+test isolation:
+
+```js
+const { MockTransport } = require('@alexify/mailer/mock');
+const { afterEach, beforeEach, describe, test } = require('node:test');
+
+// Example test setup
+describe('Email functionality', () => {
+  let transport;
+
+  beforeEach(() => {
+    // Create fresh transport for each test
+    transport = new MockTransport();
+  });
+
+  afterEach(() => {
+    // Clean up between tests
+    transport.reset(); // Clears messages and resets configuration
+  });
+
+  test('user registration sends welcome email', async () => {
+    // ... test implementation ...
+
+    // Verify clean starting state
+    console.log(transport.getSentMessagesCount()); // 0
+
+    // ... send emails ...
+
+    // Verify test results
+    const messages = transport.getSentMessages();
+    // ... assertions ...
+  });
+
+  test('password reset sends notification', async () => {
+    // This test starts with empty message history
+    console.log(transport.getSentMessagesCount()); // 0
+
+    // ... test implementation ...
+  });
+});
+
+// Alternative: selective cleanup
+function cleanupTransport(transport) {
+  // Clear just the messages, keep configuration
+  transport.clearSentMessages();
+
+  // Or reset everything to defaults
+  transport.reset();
+}
+```
+
+The `reset()` method clears all messages and returns the transport to its
+initial configuration, while `clearSentMessages()` removes only the message
+history while preserving any custom configuration like delays or failure rates.
+
+## Integration with testing frameworks
+
+The mock transport integrates seamlessly with popular testing frameworks
+like Jest, Mocha, Vitest and Node's built-in `node:test`. Here's how to
+set it up for comprehensive email testing:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MockTransport } = require('@alexify/mailer/mock');
+const assert = require('node:assert/strict');
+const { beforeEach, afterEach, test } = require('node:test');
+
+// Test utility functions
+function createTestTransport() {
+  return new MockTransport();
+}
+
+function createTestMessage(overrides = {}) {
+  return createMessage({
+    from: 'test@example.com',
+    to: 'user@example.com',
+    subject: 'Test Email',
+    content: { text: 'Test content' },
+    ...overrides,
+  });
+}
+
+// Example test suite
+let transport;
+
+beforeEach(() => {
+  transport = createTestTransport();
+});
+
+afterEach(() => {
+  transport.reset();
+});
+
+test('should send welcome email after user registration', async () => {
+  // Arrange
+  const userEmail = 'newuser@example.com';
+  const welcomeMessage = createTestMessage({
+    to: userEmail,
+    subject: 'Welcome to our platform!',
+  });
+
+  // Act
+  const receipt = await transport.send(welcomeMessage);
+
+  // Assert
+  assert.ok(receipt.successful);
+  assert.equal(transport.getSentMessagesCount(), 1);
+
+  const sentMessage = transport.getLastSentMessage();
+  assert.equal(sentMessage?.recipients[0].address, userEmail);
+  assert.ok(sentMessage?.subject.includes('Welcome'));
+});
+
+test('should handle email sending failures gracefully', async () => {
+  // Arrange
+  transport.setNextResponse({
+    successful: false,
+    errorMessages: ['SMTP server unavailable'],
+  });
+
+  // Act
+  const receipt = await transport.send(createTestMessage());
+
+  // Assert
+  assert.equal(receipt.successful, false);
+  assert.ok(receipt.errorMessages.includes('SMTP server unavailable'));
+
+  // Message should still be tracked even when it "fails"
+  assert.equal(transport.getSentMessagesCount(), 1);
+});
+```
+
+This pattern provides a robust foundation for testing email functionality
+across your entire application, ensuring that emails are sent correctly
+and error conditions are handled appropriately.
+
+## Development and debugging
+
+During development, the mock transport serves as an excellent debugging tool
+for understanding email flows and troubleshooting issues. You can inspect
+exactly what emails your application would send without cluttering real
+inboxes or hitting email service rate limits:
+
+```js
+const { MockTransport } = require('@alexify/mailer/mock');
+
+// Development configuration with detailed logging
+const transport = new MockTransport({
+  delay: 0, // No delays for faster development
+  failureRate: 0, // No random failures during development
+  generateUniqueMessageIds: true,
+});
+
+// Add development logging
+const originalSend = transport.send.bind(transport);
+transport.send = async function (message, options) {
+  console.log('📧 Sending email:', {
+    from: message.sender.address,
+    to: message.recipients.map((r) => r.address),
+    subject: message.subject,
+    tags: message.tags,
+  });
+
+  const result = await originalSend(message, options);
+
+  console.log('✉️  Email result:', {
+    successful: result.successful,
+    messageId: result.successful ? result.messageId : 'failed',
+    errors: result.successful ? [] : result.errorMessages,
+  });
+
+  return result;
+};
+
+// Use throughout your development workflow
+// All email sending will be logged and stored for inspection
+```
+
+> [!TIP]
+> The mock transport is perfect for development environments where you want
+> to test email functionality without sending real emails. You can inspect
+> the `transport.getSentMessages()` output in your browser's developer console
+> or server logs to see exactly what emails your application generates.
+
+This approach gives you complete visibility into your application's email
+behavior during development, making it much easier to debug complex email
+workflows and ensure they work correctly before deploying to production.
diff --git a/docs/transports/otel.md b/docs/transports/otel.md
new file mode 100644
index 0000000..2bab62c
--- /dev/null
+++ b/docs/transports/otel.md
@@ -0,0 +1,677 @@
+# OpenTelemetry
+
+[OpenTelemetry] is the leading open source observability framework for
+cloud-native software, providing comprehensive standards for collecting,
+processing, and exporting telemetry data including traces, metrics, and logs.
+OpenTelemetry enables you to instrument your applications with vendor-neutral
+observability, allowing you to monitor performance, track distributed requests,
+and analyze system behavior across different environments and observability
+backends.
+
+@alexify/mailer provides seamless OpenTelemetry integration through the
+*@alexify/mailer/otel* subpath, which acts as a decorator around any existing
+email transport to add automatic tracing and metrics collection without
+requiring code changes. This zero-configuration observability makes it easy to
+monitor email delivery performance, track failures, and analyze usage patterns
+across your application.
+
+> [!TIP]
+> The OpenTelemetry transport is a decorator that wraps existing transports,
+> meaning you can add observability to any @alexify/mailer transport (SMTP, Mailgun,
+> SendGrid, etc.) by simply wrapping it with the OpenTelemetry transport.
+> This approach preserves all existing functionality while adding comprehensive
+> monitoring capabilities.
+
+[OpenTelemetry]: https://opentelemetry.io/
+
+## Installation
+
+The transport is the *@alexify/mailer/otel* subpath. @alexify/mailer does not
+require the OpenTelemetry API: the application sets OpenTelemetry up and passes
+its tracer and meter providers in, so install the API (and an SDK) next to it:
+
+```bash
+pnpm add @alexify/mailer @opentelemetry/api
+# or
+npm install @alexify/mailer @opentelemetry/api
+```
+
+## Basic usage
+
+The OpenTelemetry transport wraps any existing @alexify/mailer transport to add automatic
+observability.  You'll typically create your base transport first, then wrap
+it with the OpenTelemetry transport to enable monitoring:
+
+```js
+const { trace, metrics } = require('@opentelemetry/api');
+const { createMessage } = require('@alexify/mailer');
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+const { OpenTelemetryTransport } = require('@alexify/mailer/otel');
+
+// Create your base transport
+const baseTransport = new MailgunTransport({
+  apiKey: 'your-mailgun-api-key',
+  domain: 'mg.example.com',
+  region: 'us',
+});
+
+// Wrap with OpenTelemetry observability
+const transport = new OpenTelemetryTransport(baseTransport, {
+  tracerProvider: trace.getTracerProvider(),
+  meterProvider: metrics.getMeterProvider(),
+  metrics: { enabled: true },
+  tracing: { enabled: true },
+});
+
+const message = createMessage({
+  from: 'system@example.com',
+  to: 'user@example.com',
+  subject: 'Account Created',
+  content: { text: 'Welcome to our platform!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+
+// Clean up resources when done
+await transport[Symbol.asyncDispose]();
+```
+
+The wrapped transport behaves identically to the base transport while
+automatically generating traces and metrics for every email operation.
+These telemetry data points are sent to your configured OpenTelemetry backend
+for analysis and monitoring.
+
+## Simplified setup
+
+For easier configuration, use the factory function, which applies sensible
+defaults:
+
+```js
+const { trace, metrics } = require('@opentelemetry/api');
+const { createOpenTelemetryTransport } = require('@alexify/mailer/otel');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const baseTransport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'smtp-user@example.com',
+    pass: 'smtp-password',
+  },
+});
+
+const transport = createOpenTelemetryTransport(baseTransport, {
+  tracerProvider: trace.getTracerProvider(),
+  meterProvider: metrics.getMeterProvider(),
+  serviceName: 'email-service',
+  serviceVersion: '1.2.0',
+  metrics: {
+    enabled: true,
+    prefix: 'myapp',
+  },
+  tracing: {
+    enabled: true,
+    recordSensitiveData: false,
+  },
+});
+```
+
+The providers are always passed in, while tracing or metrics are enabled: there
+is no fallback to the global providers of `@opentelemetry/api`, since this
+package does not require it.  Pass `trace.getTracerProvider()` and
+`metrics.getMeterProvider()` for the global ones, or providers of your own as
+below.
+
+## Using existing providers
+
+If your application already has OpenTelemetry configured with custom providers,
+you can pass them directly to the transport configuration. This is the most
+common pattern in production applications where observability is set up
+at the application level:
+
+```js
+const { Resource } = require('@opentelemetry/resources');
+const { MeterProvider } = require('@opentelemetry/sdk-metrics');
+const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base');
+const {
+  SEMRESATTRS_SERVICE_NAME,
+  SEMRESATTRS_SERVICE_VERSION,
+} = require('@opentelemetry/semantic-conventions');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { createOpenTelemetryTransport, OpenTelemetryTransport } = require('@alexify/mailer/otel');
+
+// Your application's existing OpenTelemetry setup
+const tracerProvider = new BasicTracerProvider({
+  resource: new Resource({
+    [SEMRESATTRS_SERVICE_NAME]: 'my-application',
+    [SEMRESATTRS_SERVICE_VERSION]: '1.0.0',
+  }),
+});
+
+const meterProvider = new MeterProvider({
+  resource: new Resource({
+    [SEMRESATTRS_SERVICE_NAME]: 'my-application',
+    [SEMRESATTRS_SERVICE_VERSION]: '1.0.0',
+  }),
+});
+
+// Use your existing providers with the email transport
+const transport = createOpenTelemetryTransport(
+  new SmtpTransport({
+    host: 'smtp.example.com',
+    port: 587,
+    secure: false,
+    auth: { user: 'user', pass: 'password' },
+  }),
+  {
+    tracerProvider, // Use your existing tracer provider
+    meterProvider, // Use your existing meter provider
+    serviceName: 'my-application',
+    serviceVersion: '1.0.0',
+    tracing: {
+      enabled: true,
+      recordSensitiveData: false,
+    },
+    metrics: {
+      enabled: true,
+      prefix: 'myapp', // Custom prefix to match your naming convention
+    },
+  },
+);
+
+// Alternatively, use the class constructor directly
+const directTransport = new OpenTelemetryTransport(
+  new SmtpTransport({
+    host: 'smtp.example.com',
+    port: 587,
+    secure: false,
+    auth: { user: 'user', pass: 'password' },
+  }),
+  {
+    tracerProvider, // Your existing providers
+    meterProvider,
+    tracing: { enabled: true, recordSensitiveData: false },
+    metrics: { enabled: true, prefix: 'myapp' },
+  },
+);
+```
+
+This approach ensures that email telemetry data appears alongside other
+application telemetry in your existing observability infrastructure,
+maintaining consistent resource attributes and following your established
+naming conventions.
+
+## Automatic resource management
+
+This and the following examples take `tracerProvider` and `meterProvider`
+from your OpenTelemetry setup, such as `trace.getTracerProvider()` and
+`metrics.getMeterProvider()` of `@opentelemetry/api`.
+
+The OpenTelemetry transport supports automatic resource cleanup using
+the `await using` statement, which ensures proper disposal of both
+the observability components and the wrapped transport:
+
+```js
+const { createOpenTelemetryTransport } = require('@alexify/mailer/otel');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { createMessage } = require('@alexify/mailer');
+
+await using transport = createOpenTelemetryTransport(
+  new SmtpTransport({
+    host: 'smtp.example.com',
+    port: 587,
+    secure: false,
+    auth: { user: 'user', pass: 'password' },
+  }),
+  {
+    tracerProvider,
+    meterProvider,
+    serviceName: 'notification-service',
+    tracing: { enabled: true },
+    metrics: { enabled: true },
+  },
+);
+
+const message = createMessage({
+  from: 'notifications@example.com',
+  to: 'customer@example.com',
+  subject: 'Order Confirmation',
+  content: { text: 'Your order has been confirmed.' },
+});
+
+await transport.send(message);
+// Both OpenTelemetry components and SMTP transport are automatically disposed
+```
+
+This approach ensures that connection pools, observability exporters,
+and other resources are properly cleaned up even if errors occur during
+email sending operations.
+
+## Distributed tracing
+
+One of OpenTelemetry's most powerful features is distributed tracing,
+which tracks requests across multiple services and components.  The email
+transport automatically participates in distributed traces by creating
+child spans that inherit the current trace context:
+
+```js
+const { trace } = require('@opentelemetry/api');
+const { createMessage } = require('@alexify/mailer');
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+const { createOpenTelemetryTransport } = require('@alexify/mailer/otel');
+
+const transport = createOpenTelemetryTransport(
+  new MailgunTransport({
+    apiKey: 'your-api-key',
+    domain: 'mg.example.com',
+  }),
+  {
+    tracerProvider,
+    meterProvider,
+    serviceName: 'user-service',
+    tracing: {
+      enabled: true,
+      recordSensitiveData: false,
+    },
+  },
+);
+
+// Example of a distributed trace across multiple operations
+const tracer = trace.getTracer('user-registration');
+
+await tracer.startActiveSpan('user-registration', async (span) => {
+  try {
+    // Simulate user creation logic
+    span.setAttributes({
+      'user.id': '12345',
+      'user.email': 'newuser@example.com',
+    });
+
+    // Send welcome email - this automatically becomes a child span
+    const message = createMessage({
+      from: 'welcome@example.com',
+      to: 'newuser@example.com',
+      subject: 'Welcome to our platform',
+      content: { text: 'Thank you for joining us!' },
+    });
+
+    await transport.send(message);
+
+    span.setStatus({ code: 1 }); // OK
+  } catch (error) {
+    if (error instanceof Error) {
+      span.recordException(error);
+    }
+    span.setStatus({ code: 2, message: String(error) }); // ERROR
+    throw error;
+  } finally {
+    span.end();
+  }
+});
+```
+
+The email sending operation appears as a child span in your distributed trace,
+showing its relationship to the broader user registration flow.
+This makes it easy to understand how email delivery affects overall request
+performance and to identify bottlenecks in your system.
+
+## Metrics and monitoring
+
+The OpenTelemetry transport automatically collects comprehensive metrics
+about email operations, including delivery rates, latency, message sizes,
+and error categorization.  These metrics are essential for monitoring
+email system health and performance:
+
+```js
+const { createOpenTelemetryTransport } = require('@alexify/mailer/otel');
+const { SendGridTransport } = require('@alexify/mailer/sendgrid');
+
+const transport = createOpenTelemetryTransport(
+  new SendGridTransport({
+    apiKey: 'your-sendgrid-api-key',
+  }),
+  {
+    tracerProvider,
+    meterProvider,
+    serviceName: 'marketing-service',
+    metrics: {
+      enabled: true,
+      prefix: 'marketing',
+      samplingRate: 1.0,
+      durationBuckets: [0.1, 0.5, 1.0, 2.0, 5.0, 10.0],
+    },
+    tracing: {
+      enabled: true,
+      samplingRate: 0.1, // Sample 10% of traces
+    },
+  },
+);
+```
+
+The transport collects the following key metrics:
+
+- Email delivery counters: Track successful and failed send attempts
+
+- Duration histograms: Measure how long email operations take
+
+- Message size histograms: Monitor email size distribution
+
+- Active operation gauges: Track concurrent email sending operations
+
+- Error classification: Categorize failures by type (auth, network, etc.)
+
+These metrics are exported to your configured observability backend
+(Prometheus, DataDog, etc.) where you can create dashboards and alerts
+to monitor your email system's health.
+
+## Error classification and analysis
+
+The OpenTelemetry transport includes intelligent error classification that
+automatically categorizes email failures into meaningful groups.  This helps
+you quickly identify and respond to different types of issues:
+
+```js
+const { createOpenTelemetryTransport, createErrorClassifier } = require('@alexify/mailer/otel');
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+
+// Custom error classifier for your specific needs
+const customClassifier = createErrorClassifier({
+  patterns: {
+    spam_filter: /blocked.*spam|spam.*detected|reputation/i,
+    bounce: /bounce|undeliverable|invalid.*recipient/i,
+    quota_exceeded: /quota.*exceeded|mailbox.*full/i,
+    temporary_failure: /temporary.*failure|try.*again.*later/i,
+  },
+  fallback: 'email_error',
+});
+
+const transport = createOpenTelemetryTransport(
+  new MailgunTransport({
+    apiKey: 'your-api-key',
+    domain: 'mg.example.com',
+  }),
+  {
+    tracerProvider,
+    meterProvider,
+    serviceName: 'notification-service',
+    errorClassifier: customClassifier,
+    metrics: { enabled: true },
+    tracing: { enabled: true },
+  },
+);
+```
+
+Error classifications appear in both metrics and trace data, allowing you to:
+
+ -  Monitor error rates by category in dashboards
+ -  Set up targeted alerts for specific error types
+ -  Analyze error patterns across different email types
+ -  Identify systematic issues vs. temporary problems
+
+The default classifier recognizes common email error patterns including
+authentication failures, rate limiting, network issues, validation errors,
+and server problems.
+
+## Custom attributes and context
+
+You can enhance telemetry data with custom attributes that provide additional
+context about your email operations.  This is particularly useful for
+tracking business metrics alongside technical metrics:
+
+```js
+const {
+  createOpenTelemetryTransport,
+  createEmailAttributeExtractor,
+} = require('@alexify/mailer/otel');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const customExtractor = createEmailAttributeExtractor('smtp', {
+  recordSensitiveData: false,
+  transportVersion: '1.0.0',
+  customAttributes: (operation, transportName, messageCount, totalSize) => ({
+    'app.version': '2.1.0',
+    'app.environment': process.env.NODE_ENV || 'development',
+    'deployment.id': process.env.DEPLOYMENT_ID || 'unknown',
+    'email.campaign.type': 'transactional', // Custom business context
+    'email.priority': 'high',
+  }),
+});
+
+const transport = createOpenTelemetryTransport(
+  new SmtpTransport({
+    host: 'smtp.example.com',
+    port: 587,
+    secure: false,
+    auth: { user: 'smtp-user', pass: 'smtp-password' },
+  }),
+  {
+    tracerProvider,
+    meterProvider,
+    serviceName: 'transactional-email',
+    attributeExtractor: customExtractor,
+    tracing: { enabled: true },
+    metrics: { enabled: true },
+  },
+);
+```
+
+Custom attributes appear in both traces and metrics, enabling you to:
+
+ -  Filter and group telemetry data by business context
+ -  Correlate email performance with deployment versions
+ -  Track different email campaigns or types separately
+ -  Add environment-specific context for debugging
+
+## Bulk email monitoring
+
+For applications that send large volumes of emails, the OpenTelemetry transport
+provides specialized monitoring for batch operations with detailed performance
+tracking and error analysis:
+
+```js
+const { createOpenTelemetryTransport } = require('@alexify/mailer/otel');
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = createOpenTelemetryTransport(
+  new MailgunTransport({
+    apiKey: 'your-api-key',
+    domain: 'mg.example.com',
+    retries: 3,
+  }),
+  {
+    tracerProvider,
+    meterProvider,
+    serviceName: 'newsletter-service',
+    metrics: {
+      enabled: true,
+      samplingRate: 1.0, // Monitor all bulk operations
+    },
+    tracing: {
+      enabled: true,
+      samplingRate: 0.01, // Sample 1% of individual messages
+    },
+  },
+);
+
+// Generate newsletter messages for subscribers
+const subscribers = await getNewsletterSubscribers();
+const messages = subscribers.map((subscriber) =>
+  createMessage({
+    from: 'newsletter@example.com',
+    to: subscriber.email,
+    subject: 'Weekly Update - December 2024',
+    content: {
+      html: generateNewsletterHtml(subscriber),
+      text: generateNewsletterText(subscriber),
+    },
+    tags: ['newsletter', 'weekly', subscriber.segment],
+  }),
+);
+
+// Send with comprehensive monitoring
+let successCount = 0;
+let failureCount = 0;
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    successCount++;
+  } else {
+    failureCount++;
+    console.error(`Failed to send to ${receipt.errorMessages.join(', ')}`);
+  }
+}
+
+console.log(`Newsletter sent: ${successCount} successful, ${failureCount} failed`);
+```
+
+Batch operations generate additional metrics including:
+
+- Batch size tracking: Monitor the distribution of batch sizes
+
+- Success/failure ratios: Track delivery rates across batches
+
+- Processing duration: Measure how long large batches take
+
+- Partial failure analysis: Understand patterns in batch failures
+
+This information helps you optimize batch processing, identify optimal
+batch sizes, and detect issues that affect bulk email delivery.
+
+## Performance optimization
+
+The OpenTelemetry transport includes several features to minimize performance
+impact while providing comprehensive observability.  You can tune sampling
+rates and feature toggles based on your monitoring needs:
+
+```js
+const { createOpenTelemetryTransport } = require('@alexify/mailer/otel');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+// Production configuration with optimized performance
+const transport = createOpenTelemetryTransport(
+  new SmtpTransport({
+    host: 'smtp.example.com',
+    port: 587,
+    secure: false,
+    auth: { user: 'user', pass: 'password' },
+    pool: true,
+    poolSize: 10,
+  }),
+  {
+    tracerProvider,
+    meterProvider,
+    serviceName: 'production-email',
+    metrics: {
+      enabled: true,
+      samplingRate: 1.0, // Always collect metrics
+      prefix: 'prod',
+    },
+    tracing: {
+      enabled: true,
+      samplingRate: 0.05, // Sample 5% of traces
+      recordSensitiveData: false, // Optimize for privacy and performance
+    },
+  },
+);
+
+// High-throughput configuration for bulk operations
+const bulkTransport = createOpenTelemetryTransport(
+  new SmtpTransport({
+    host: 'bulk-smtp.example.com',
+    port: 587,
+    secure: false,
+    auth: { user: 'bulk-user', pass: 'bulk-password' },
+    pool: true,
+    poolSize: 20,
+  }),
+  {
+    tracerProvider,
+    meterProvider,
+    serviceName: 'bulk-email',
+    metrics: { enabled: true },
+    tracing: { enabled: false }, // Disable tracing for maximum performance
+  },
+);
+```
+
+Performance considerations for different scenarios:
+
+- High-frequency transactional emails: Enable metrics, sample traces at 1–5%
+
+- Bulk campaigns: Focus on metrics, disable or heavily sample tracing
+
+- Development environments: Enable full observability for debugging
+
+- Testing: Disable observability or use mock backends
+
+## Development and testing
+
+For development and testing environments, you can configure the OpenTelemetry
+transport to provide comprehensive observability without affecting external
+monitoring systems:
+
+```js
+const { createOpenTelemetryTransport } = require('@alexify/mailer/otel');
+const { MockTransport } = require('@alexify/mailer/mock');
+
+// Development configuration with full observability
+const devTransport = createOpenTelemetryTransport(
+  new MockTransport({
+    failureRate: 0,
+    delay: 100,
+  }),
+  {
+    tracerProvider,
+    meterProvider,
+    serviceName: 'email-service-dev',
+    serviceVersion: 'dev',
+    metrics: {
+      enabled: true,
+      samplingRate: 1.0,
+    },
+    tracing: {
+      enabled: true,
+      samplingRate: 1.0,
+      recordSensitiveData: true, // OK for development
+    },
+  },
+);
+
+// Testing configuration with observability validation
+const testTransport = createOpenTelemetryTransport(new MockTransport({ failureRate: 0 }), {
+  tracerProvider,
+  meterProvider,
+  serviceName: 'email-service-test',
+  metrics: { enabled: true },
+  tracing: { enabled: true },
+  errorClassifier: (error) => {
+    if (error instanceof Error) {
+      // Custom test error classification
+      if (error.message.includes('test-auth-failure')) return 'auth';
+      if (error.message.includes('test-rate-limit')) return 'rate-limit';
+    }
+    return 'test_error';
+  },
+});
+```
+
+> [!TIP]
+> When testing OpenTelemetry integration, consider using in-memory exporters
+> or console exporters to validate that telemetry data is being generated
+> correctly without requiring external observability infrastructure.
+> The OpenTelemetry SDK provides excellent testing utilities for validating
+> trace and metric data in your test suites.
+
+The observability data from development and testing helps you:
+
+ -  Validate that instrumentation is working correctly
+ -  Test error handling and classification logic
+ -  Verify that custom attributes are being applied properly
+ -  Optimize observability configuration before production deployment
diff --git a/docs/transports/plunk.md b/docs/transports/plunk.md
new file mode 100644
index 0000000..a99671c
--- /dev/null
+++ b/docs/transports/plunk.md
@@ -0,0 +1,297 @@
+# Plunk
+
+[Plunk] is a modern, developer-friendly email service that offers both
+cloud-hosted and self-hosted solutions for transactional email delivery.
+Built with simplicity and reliability in mind, Plunk provides straightforward
+APIs for sending emails with features like tracking, templates, and excellent
+deliverability rates. It's particularly well-suited for developers who want
+a clean, no-nonsense email service without the complexity of larger platforms,
+making it ideal for transactional emails such as welcome messages, password
+resets, notifications, and system alerts.
+
+@alexify/mailer provides a feature-rich Plunk transport through the *@alexify/mailer/plunk*
+package, supporting all major Plunk features including self-hosted instances,
+batch sending, automatic retry logic, and comprehensive error handling.
+
+[Plunk]: https://www.useplunk.com/
+
+## Installation
+
+To use the Plunk transport, you need to install the *@alexify/mailer/plunk* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Getting started
+
+Before using the Plunk transport, you'll need a Plunk account and an API
+key. For cloud-hosted Plunk, you can get API keys from the Plunk dashboard
+at [useplunk.com]. For self-hosted instances, API keys are managed through
+your own Plunk installation.
+
+```js
+const { PlunkTransport } = require('@alexify/mailer/plunk');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new PlunkTransport({
+  apiKey: 'sk_1234567890abcdef1234567890abcdef1234567890abcdef',
+});
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The Plunk transport handles authentication automatically using your API key
+and sends emails through Plunk's reliable infrastructure. The service manages
+bounces, spam filtering, and delivery optimization automatically, providing
+excellent deliverability rates with minimal configuration.
+
+[useplunk.com]: https://www.useplunk.com/
+
+## Self-hosted instances
+
+One of Plunk's key advantages is its support for self-hosted deployments
+using Docker. This gives you complete control over your email infrastructure
+while maintaining the simplicity of Plunk's API:
+
+```js
+const { PlunkTransport } = require('@alexify/mailer/plunk');
+const { createMessage } = require('@alexify/mailer');
+
+// Self-hosted Plunk instance
+const transport = new PlunkTransport({
+  apiKey: 'your-self-hosted-api-key',
+  baseUrl: 'https://mail.yourcompany.com/api',
+  validateSsl: true,
+});
+
+const message = createMessage({
+  from: 'noreply@yourcompany.com',
+  to: 'employee@yourcompany.com',
+  subject: 'Internal notification',
+  content: {
+    html: '<h2>System Update</h2><p>The maintenance is complete.</p>',
+    text: 'System Update\n\nThe maintenance is complete.',
+  },
+});
+
+const receipt = await transport.send(message);
+```
+
+Self-hosted Plunk instances are deployed using the [driaug/plunk] Docker
+image, giving you full control over your email infrastructure, data privacy,
+and compliance requirements. This is particularly valuable for organizations
+with strict data residency requirements or those who prefer to keep email
+infrastructure in-house.
+
+[driaug/plunk]: https://hub.docker.com/r/driaug/plunk
+
+## Message organization and batch sending
+
+Plunk supports message tagging for better organization and analytics.
+The transport also provides efficient batch processing for sending multiple
+emails with automatic retry logic:
+
+```js
+const { PlunkTransport } = require('@alexify/mailer/plunk');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new PlunkTransport({
+  apiKey: "sk_1234567890abcdef1234567890abcdef1234567890abcdef",
+  retries: 3,
+  timeout: 30000,
+});
+
+const subscribers = [
+  "user1@example.com",
+  "user2@example.com",
+  "user3@example.com",
+];
+
+const messages = subscribers.map(email =>
+  createMessage({
+    from: "newsletter@example.com",
+    to: email,
+    subject: "Monthly Newsletter - December 2024",
+    content: {
+      html: "<h2>This Month's Updates</h2><p>Here's what's new...</p>",
+      text: "This Month's Updates\n\nHere's what's new...",
+    },
+    tags: ["newsletter", "monthly", "transactional"],
+  })
+);
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Newsletter sent with ID: ${receipt.messageId}`);
+  } else {
+    console.error(`Failed to send: ${receipt.errorMessages.join(", ")}`);
+  }
+}
+```
+
+Tags help you categorize emails and track performance through Plunk's
+analytics dashboard. The `sendMany()` method processes emails efficiently
+with built-in retry logic, ensuring reliable delivery even when some
+individual messages encounter temporary issues.
+
+## Advanced features and reliability
+
+The Plunk transport includes comprehensive configuration options for timeout
+handling, retry behavior, SSL validation, and custom headers to ensure reliable
+email delivery in production environments:
+
+```js
+const { PlunkTransport } = require('@alexify/mailer/plunk');
+const { createMessage } = require('@alexify/mailer');
+const { readFile } = require('node:fs/promises');
+
+const transport = new PlunkTransport({
+  apiKey: 'sk_1234567890abcdef1234567890abcdef1234567890abcdef',
+  baseUrl: 'https://next-api.useplunk.com',
+  timeout: 15000,
+  retries: 5,
+  validateSsl: true,
+  headers: {
+    'X-Custom-Header': 'MyApp-v1.0',
+    'X-Environment': 'production',
+  },
+});
+
+// Sending with attachments (limited to 5 per Plunk API)
+const fileContent = await readFile('./reports/report.pdf');
+const message = createMessage({
+  from: 'documents@example.com',
+  to: 'client@example.com',
+  subject: 'Your requested documents',
+  content: {
+    text: 'Please find the requested documents attached.',
+    html: '<p>Please find the requested <strong>documents</strong> attached.</p>',
+  },
+  attachments: new File([fileContent], 'report.pdf', { type: 'application/pdf' }),
+  priority: 'high', // Sets appropriate email headers
+  tags: ['documents', 'client'],
+});
+
+const receipt = await transport.send(message);
+```
+
+The transport automatically handles attachment conversion to base64 format
+as required by Plunk's API, with a limit of 5 attachments per message.
+Priority levels are converted to appropriate email headers for better
+inbox placement of urgent messages.
+
+## Cancellation and error handling
+
+The Plunk transport supports request cancellation using AbortSignal and
+provides comprehensive error handling for various failure scenarios:
+
+```js
+const { PlunkTransport } = require('@alexify/mailer/plunk');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new PlunkTransport({
+  apiKey: 'sk_1234567890abcdef1234567890abcdef1234567890abcdef',
+  timeout: 30000,
+  retries: 3,
+});
+
+const controller = new AbortController();
+
+// Cancel after 10 seconds
+setTimeout(() => controller.abort(), 10000);
+
+const message = createMessage({
+  from: 'alerts@example.com',
+  to: 'admin@example.com',
+  subject: '🚨 System Alert: High CPU Usage',
+  content: {
+    text: 'Server CPU usage has exceeded 90% for the past 5 minutes.',
+  },
+  priority: 'high',
+  tags: ['alert', 'system'],
+});
+
+const receipt = await transport.send(message, {
+  signal: controller.signal,
+});
+
+if (receipt.successful) {
+  console.log('Alert sent with ID:', receipt.messageId);
+} else {
+  console.error('Alert failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The transport includes comprehensive retry logic with exponential backoff,
+automatically handling transient network errors, rate limiting, and temporary
+service interruptions. Failed requests provide detailed error information
+to help diagnose and resolve delivery issues.
+
+## Development and testing
+
+For development and testing, you can configure the Plunk transport for
+testing environments. When using self-hosted instances, you can set up
+dedicated testing environments with isolated email delivery:
+
+```js
+const { PlunkTransport } = require('@alexify/mailer/plunk');
+const { createMessage } = require('@alexify/mailer');
+
+// Development configuration with shorter timeouts
+const devTransport = new PlunkTransport({
+  apiKey: 'sk_test1234567890abcdef1234567890abcdef1234567890ab',
+  timeout: 5000, // Shorter timeout for development
+  retries: 1, // Fewer retries for faster feedback
+});
+
+// Testing configuration with environment variables
+const testTransport = new PlunkTransport({
+  apiKey: process.env.PLUNK_TEST_API_KEY ?? 'sk_test123',
+  baseUrl: process.env.PLUNK_TEST_URL ?? 'https://next-api.useplunk.com',
+  timeout: 10000,
+  retries: 1, // Fewer retries for faster test execution
+});
+
+// Example test message
+const testMessage = createMessage({
+  from: 'test@yourdomain.com',
+  to: 'testuser@yourdomain.com', // Use verified test addresses
+  subject: 'Test Email',
+  content: { text: 'This is a test email from development.' },
+  tags: ['test', 'development'],
+});
+
+const receipt = await testTransport.send(testMessage);
+```
+
+For local development, use verified sender addresses and test recipient
+addresses to avoid sending emails to real users. Self-hosted Plunk instances
+provide excellent isolation for testing, allowing you to monitor email
+delivery without affecting production systems.
+
+> [!TIP]
+> Plunk provides a clean, straightforward dashboard for monitoring email
+> delivery, viewing sent emails, and debugging issues. This is particularly
+> valuable for self-hosted instances where you have full access to logs
+> and delivery details.
+
+> [!CAUTION]
+> Always use test API keys and verified domains during development to avoid
+> sending test emails to real users. For self-hosted instances, consider
+> setting up separate testing environments with isolated email delivery
+> to prevent accidental sends to production email addresses.
diff --git a/docs/transports/pool.md b/docs/transports/pool.md
new file mode 100644
index 0000000..b6e4d46
--- /dev/null
+++ b/docs/transports/pool.md
@@ -0,0 +1,654 @@
+# Pool transport
+
+The pool transport is a specialized orchestration utility that combines multiple
+email transports into a single, resilient email delivery system. Rather than
+connecting to a specific email service, it intelligently routes messages across
+multiple underlying transports using configurable strategies like round-robin,
+weighted distribution, priority-based failover, and custom routing logic.
+This makes it invaluable for high-availability systems, cost optimization,
+and gradual migration between email providers.
+
+@alexify/mailer provides a comprehensive pool transport through the *@alexify/mailer/pool* subpath,
+offering multiple load balancing strategies, automatic failover, resource
+management, and full compatibility with all @alexify/mailer transport features.
+
+## Installation
+
+To use the pool transport, you need to install the *@alexify/mailer/pool* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Basic pooling
+
+The pool transport implements the same `Transport` interface as all other @alexify/mailer
+transports, making it a drop-in replacement that can combine multiple email
+providers seamlessly. You can group transports from different providers and
+use them as a single unit:
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+const { createMessage } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { MailgunTransport } = require('@alexify/mailer/mailgun');
+const { SendGridTransport } = require('@alexify/mailer/sendgrid');
+
+// Create individual transports
+const smtpTransport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  auth: { user: 'user', pass: 'pass' },
+});
+
+const mailgunTransport = new MailgunTransport({
+  apiKey: 'your-mailgun-api-key',
+  domain: 'your-domain.com',
+});
+
+const sendgridTransport = new SendGridTransport({
+  apiKey: 'your-sendgrid-api-key',
+});
+
+// Combine them into a pool with round-robin strategy
+const poolTransport = new PoolTransport({
+  strategy: 'round-robin',
+  transports: [
+    { transport: smtpTransport },
+    { transport: mailgunTransport },
+    { transport: sendgridTransport },
+  ],
+});
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.com',
+  subject: 'Pooled Email Delivery',
+  content: { text: 'This email was sent through a pool of providers.' },
+});
+
+// Send through the pool (will use round-robin selection)
+const receipt = await poolTransport.send(message);
+
+console.log(receipt.successful); // true
+if (receipt.successful) {
+  console.log(receipt.messageId); // ID from whichever provider was used
+}
+```
+
+The pool automatically handles provider selection, error aggregation, and
+resource management, giving you a single interface for multiple email services.
+
+## Load balancing strategies
+
+Different applications need different approaches to distributing email traffic.
+The pool transport provides four built-in strategies, each optimized for
+specific use cases:
+
+### Round-robin distribution
+
+Cycles through transports in order, ensuring perfectly even distribution:
+
+```js
+const pool = new PoolTransport({
+  strategy: 'round-robin',
+  transports: [{ transport: transport1 }, { transport: transport2 }, { transport: transport3 }],
+});
+
+// First message goes to transport1
+// Second message goes to transport2
+// Third message goes to transport3
+// Fourth message goes to transport1 again
+// And so on...
+```
+
+Round-robin is perfect when you want equal load distribution and have providers
+with similar capabilities and costs.
+
+### Weighted distribution
+
+Distributes traffic proportionally based on configured weights, allowing you
+to send more traffic through preferred or higher-capacity providers:
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+
+const pool = new PoolTransport({
+  strategy: 'weighted',
+  transports: [
+    { transport: primaryProvider, weight: 5 }, // Gets ~71% of traffic
+    { transport: secondaryProvider, weight: 2 }, // Gets ~29% of traffic
+    { transport: backupProvider, weight: 0 }, // Gets no traffic (disabled)
+  ],
+});
+
+// Traffic is distributed randomly but proportionally to weights
+// Over many sends, primaryProvider gets 5/(5+2+0) ≈ 71% of messages
+// secondaryProvider gets 2/(5+2+0) ≈ 29% of messages
+```
+
+Weighted distribution is ideal for cost optimization, capacity management,
+or gradual migration between providers.
+
+### Priority-based failover
+
+Always attempts the highest priority transport first, falling back to lower
+priorities only when higher ones fail:
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+
+const pool = new PoolTransport({
+  strategy: 'priority',
+  transports: [
+    { transport: primaryTransport, priority: 100 },
+    { transport: secondaryTransport, priority: 50 },
+    { transport: emergencyTransport, priority: 10 },
+  ],
+  maxRetries: 3, // Try up to 3 different transports
+});
+
+// Always tries primaryTransport first
+// If it fails, tries secondaryTransport
+// If that fails too, tries emergencyTransport
+// If all fail, returns aggregated error messages
+```
+
+Priority-based routing ensures you always use your preferred provider when
+possible, with automatic failover to backup systems.
+
+### Custom routing with selectors
+
+Routes messages based on custom logic, allowing content-based or rule-based
+email provider selection:
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+
+const pool = new PoolTransport({
+  strategy: 'selector-based',
+  transports: [
+    {
+      transport: bulkEmailProvider,
+      selector: (msg) => msg.tags?.includes('newsletter'),
+    },
+    {
+      transport: transactionalProvider,
+      selector: (msg) => msg.priority === 'high',
+    },
+    {
+      transport: euProvider,
+      selector: (msg) => msg.headers.get('region') === 'EU',
+    },
+    {
+      transport: defaultProvider, // No selector - catches everything else
+    },
+  ],
+});
+
+// Newsletter emails automatically use bulkEmailProvider
+// High-priority emails use transactionalProvider
+// EU-region emails use euProvider
+// Everything else uses defaultProvider
+```
+
+Selector-based routing enables sophisticated email routing based on content,
+metadata, recipient domains, or any custom logic.
+
+## Failover and retry logic
+
+Real email services occasionally fail due to network issues, rate limits,
+or maintenance. The pool transport provides robust failover capabilities
+that automatically retry failed sends using different providers:
+
+```js
+const pool = new PoolTransport({
+  strategy: 'priority',
+  transports: [
+    { transport: unreliableProvider, priority: 100 },
+    { transport: reliableProvider, priority: 50 },
+    { transport: backupProvider, priority: 10 },
+  ],
+  maxRetries: 3, // Try up to 3 different transports
+  timeout: 10000, // 10-second timeout per attempt
+});
+
+// If unreliableProvider fails, automatically tries reliableProvider
+// If that fails too, tries backupProvider
+// If all fail, returns aggregated error messages from all attempts
+const receipt = await pool.send(message);
+
+if (!receipt.successful) {
+  // Contains error messages from all failed attempts
+  console.error('All providers failed:', receipt.errorMessages);
+  console.error(
+    'Failed providers:',
+    receipt.errors?.map((e) => e.provider),
+  );
+  // Example: [
+  //   "Provider 1: Connection timeout",
+  //   "Provider 2: Rate limit exceeded",
+  //   "Provider 3: Invalid API key"
+  // ]
+}
+```
+
+The pool aggregates error messages and structured errors from all failed
+attempts, giving you complete visibility into what went wrong across all
+providers.  Structured errors use each child transport's provider `id`, so
+fallback failures remain tied to the transport that produced them.
+
+## Custom strategies
+
+For advanced use cases, you can implement custom routing strategies by
+creating a class that implements the `Strategy` interface. This allows
+you to build sophisticated routing logic based on any criteria:
+
+```js
+class TimeBasedStrategy {
+  select(message, transports, attemptedIndices) {
+    const hour = new Date().getHours();
+
+    // Use different providers based on time of day
+    // Morning hours: use provider 0 (cheaper bulk rates)
+    // Evening hours: use provider 1 (better deliverability)
+    const preferredIndex = hour < 12 ? 0 : 1;
+
+    if (!attemptedIndices.has(preferredIndex) && transports[preferredIndex]?.enabled) {
+      return {
+        entry: transports[preferredIndex],
+        index: preferredIndex,
+      };
+    }
+
+    // Fallback to any available transport
+    for (let i = 0; i < transports.length; i++) {
+      if (!attemptedIndices.has(i) && transports[i].enabled) {
+        return { entry: transports[i], index: i };
+      }
+    }
+
+    return undefined;
+  }
+
+  reset() {
+    // Custom reset logic if needed
+  }
+}
+
+class RegionBasedStrategy {
+  select(message, transports, attemptedIndices) {
+    // Route based on recipient domain
+    const recipient = message.recipients[0]?.address;
+    const domain = recipient?.split('@')[1];
+
+    let preferredIndex = 0;
+
+    if (domain?.endsWith('.eu') || domain?.endsWith('.de')) {
+      preferredIndex = 1; // EU provider
+    } else if (domain?.endsWith('.com') || domain?.endsWith('.org')) {
+      preferredIndex = 0; // US provider
+    } else {
+      preferredIndex = 2; // Global provider
+    }
+
+    if (!attemptedIndices.has(preferredIndex) && transports[preferredIndex]?.enabled) {
+      return {
+        entry: transports[preferredIndex],
+        index: preferredIndex,
+      };
+    }
+
+    // Fallback logic...
+    for (let i = 0; i < transports.length; i++) {
+      if (!attemptedIndices.has(i) && transports[i].enabled) {
+        return { entry: transports[i], index: i };
+      }
+    }
+
+    return undefined;
+  }
+
+  reset() {}
+}
+
+// Use custom strategies
+const timeBasedPool = new PoolTransport({
+  strategy: new TimeBasedStrategy(),
+  transports: [
+    { transport: cheapProvider }, // Used in mornings
+    { transport: premiumProvider }, // Used in evenings
+  ],
+});
+
+const regionBasedPool = new PoolTransport({
+  strategy: new RegionBasedStrategy(),
+  transports: [
+    { transport: usProvider }, // .com, .org domains
+    { transport: euProvider }, // .eu, .de domains
+    { transport: globalProvider }, // Everything else
+  ],
+});
+```
+
+Custom strategies enable unlimited flexibility in routing logic, from simple
+time-based rules to complex machine learning-driven provider selection.
+
+## Bulk email distribution
+
+For applications that send newsletters, notifications, or other bulk emails,
+the pool transport efficiently distributes large message volumes across
+multiple providers while maintaining proper load balancing:
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+const { createMessage } = require('@alexify/mailer');
+
+const pool = new PoolTransport({
+  strategy: "weighted",
+  transports: [
+    { transport: provider1, weight: 3 }, // Gets ~50% of traffic
+    { transport: provider2, weight: 2 }, // Gets ~33% of traffic
+    { transport: provider3, weight: 1 }, // Gets ~17% of traffic
+  ],
+});
+
+// Bulk newsletter sending
+const subscribers = [
+  "alice@example.com",
+  "bob@example.com",
+  "charlie@example.com",
+  // ... thousands more
+];
+
+const newsletterMessages = subscribers.map(email =>
+  createMessage({
+    from: "newsletter@example.com",
+    to: email,
+    subject: "Monthly Newsletter - December 2024",
+    content: {
+      html: "<h2>This Month's Updates</h2><p>Here's what's new...</p>",
+      text: "This Month's Updates\n\nHere's what's new...",
+    },
+    tags: ["newsletter", "monthly"],
+  })
+);
+
+// Send all newsletters with automatic load balancing
+const receipts        = [];
+let successCount = 0;
+let failureCount = 0;
+
+for await (const receipt of pool.sendMany(newsletterMessages)) {
+  receipts.push(receipt);
+
+  if (receipt.successful) {
+    successCount++;
+  } else {
+    failureCount++;
+    console.error(`Failed to send newsletter: ${receipt.errorMessages}`);
+  }
+
+  // Log progress every 100 messages
+  if (receipts.length % 100 === 0) {
+    console.log(`Processed ${receipts.length}/${newsletterMessages.length} newsletters`);
+  }
+}
+
+console.log(`Newsletter campaign complete:`);
+console.log(`  Successful: ${successCount}`);
+console.log(`  Failed: ${failureCount}`);
+console.log(`  Total: ${receipts.length}`);
+```
+
+The pool automatically distributes bulk emails according to your configured
+strategy, ensuring optimal load distribution and maximizing deliverability
+across multiple providers.
+
+## Resource management
+
+The pool transport implements `AsyncDisposable` for automatic cleanup of
+all underlying transports. This is especially important when using connection-
+based transports like SMTP that maintain persistent connections:
+
+```js
+// Automatic cleanup with 'using' statement
+await using pool = new PoolTransport({
+  strategy: 'round-robin',
+  transports: [{ transport: transport1 }, { transport: transport2 }],
+});
+
+await pool.send(message);
+// All underlying transports are disposed automatically when pool goes out of scope
+
+// Or manual cleanup
+const pool2 = new PoolTransport({
+  strategy: 'priority',
+  transports: [{ transport: transport1 }, { transport: transport2 }],
+});
+
+try {
+  await pool2.send(message);
+} finally {
+  // Properly dispose all underlying transports
+  await pool2[Symbol.asyncDispose]();
+}
+```
+
+The pool ensures that all underlying transports are properly cleaned up,
+preventing connection leaks and ensuring graceful shutdown.
+
+## Testing with pools
+
+Pool transports integrate seamlessly with testing workflows using mock
+transports. You can verify load balancing behavior, test failover scenarios,
+and ensure proper error handling:
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+const { MockTransport } = require('@alexify/mailer/mock');
+const { createMessage } = require('@alexify/mailer');
+const assert = require('node:assert/strict');
+
+// Create mock transports for testing
+const mockTransport1 = new MockTransport();
+const mockTransport2 = new MockTransport();
+const failingTransport = new MockTransport();
+
+// Configure one transport to always fail
+failingTransport.setNextResponse({
+  successful: false,
+  errorMessages: ['Simulated provider failure'],
+});
+
+const pool = new PoolTransport({
+  strategy: 'round-robin',
+  transports: [
+    { transport: mockTransport1 },
+    { transport: mockTransport2 },
+    { transport: failingTransport },
+  ],
+});
+
+const testMessage = createMessage({
+  from: 'test@example.com',
+  to: 'user@example.com',
+  subject: 'Test Email',
+  content: { text: 'Testing pool behavior' },
+});
+
+// Test round-robin distribution
+await pool.send(testMessage); // Should use mockTransport1
+await pool.send(testMessage); // Should use mockTransport2
+await pool.send(testMessage); // Should use failingTransport (will fail)
+await pool.send(testMessage); // Should use mockTransport1 again
+
+// Verify distribution
+assert.equal(mockTransport1.getSentMessagesCount(), 2);
+assert.equal(mockTransport2.getSentMessagesCount(), 1);
+assert.equal(failingTransport.getSentMessagesCount(), 1);
+
+// Test failover behavior
+const poolWithFailover = new PoolTransport({
+  strategy: 'priority',
+  transports: [
+    { transport: failingTransport, priority: 100 },
+    { transport: mockTransport1, priority: 50 },
+  ],
+  maxRetries: 2,
+});
+
+const receipt = await poolWithFailover.send(testMessage);
+
+// Should succeed using mockTransport1 after failingTransport fails
+assert.ok(receipt.successful);
+assert.equal(mockTransport1.getSentMessagesCount(), 3); // One more message
+```
+
+Mock transports provide complete visibility into pool behavior, making it
+easy to verify that load balancing and failover work correctly.
+
+## Production deployment
+
+When deploying pool transports to production, consider these best practices
+for optimal performance and reliability:
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+
+// Production configuration with monitoring and fallbacks
+const productionPool = new PoolTransport({
+  strategy: 'priority',
+  transports: [
+    {
+      transport: primaryProvider,
+      priority: 100,
+      enabled: true, // Can be toggled via configuration
+    },
+    {
+      transport: secondaryProvider,
+      priority: 80,
+      enabled: true,
+    },
+    {
+      transport: emergencyProvider,
+      priority: 10,
+      enabled: true, // Emergency backup
+    },
+  ],
+  maxRetries: 3, // Allow fallback through all providers
+  timeout: 15000, // 15-second timeout per provider
+});
+
+// Add monitoring and logging
+const originalSend = productionPool.send.bind(productionPool);
+productionPool.send = async function (message, options) {
+  const startTime = Date.now();
+
+  try {
+    const result = await originalSend(message, options);
+    const duration = Date.now() - startTime;
+
+    // Log successful sends
+    console.log(`✅ Email sent successfully`, {
+      messageId: result.successful ? result.messageId : 'failed',
+      duration,
+      recipient: message.recipients[0]?.address,
+      subject: message.subject,
+    });
+
+    return result;
+  } catch (error) {
+    const duration = Date.now() - startTime;
+
+    // Log errors for monitoring
+    console.error(`❌ Email send failed`, {
+      error: String(error),
+      duration,
+      recipient: message.recipients[0]?.address,
+      subject: message.subject,
+    });
+
+    throw error;
+  }
+};
+
+// Graceful shutdown handling
+process.on('SIGTERM', async () => {
+  console.log('Shutting down email pool...');
+  await productionPool[Symbol.asyncDispose]();
+  console.log('Email pool shutdown complete');
+});
+```
+
+This configuration provides comprehensive error handling, monitoring, and
+graceful shutdown capabilities suitable for production environments.
+
+## Use cases and patterns
+
+### High availability with geographic distribution
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+
+const geoDistributedPool = new PoolTransport({
+  strategy: 'priority',
+  transports: [
+    { transport: usEastProvider, priority: 100 }, // Primary
+    { transport: usWestProvider, priority: 90 }, // Regional backup
+    { transport: euProvider, priority: 50 }, // Cross-region backup
+  ],
+  maxRetries: 3,
+});
+```
+
+### Cost optimization with tiered providers
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+
+const costOptimizedPool = new PoolTransport({
+  strategy: 'selector-based',
+  transports: [
+    {
+      transport: cheapProvider,
+      selector: (msg) => msg.tags?.includes('bulk') || msg.tags?.includes('newsletter'),
+    },
+    {
+      transport: premiumProvider,
+      selector: (msg) => msg.priority === 'high' || msg.tags?.includes('transactional'),
+    },
+    {
+      transport: standardProvider, // Default for everything else
+    },
+  ],
+});
+```
+
+### Gradual migration between providers
+
+```js
+const { PoolTransport } = require('@alexify/mailer/pool');
+
+// Start with 90% old, 10% new traffic
+const migrationPool = new PoolTransport({
+  strategy: 'weighted',
+  transports: [
+    { transport: oldProvider, weight: 90 },
+    { transport: newProvider, weight: 10 },
+  ],
+});
+
+// Gradually adjust weights over time:
+// Week 1: 90/10
+// Week 2: 70/30
+// Week 3: 50/50
+// Week 4: 20/80
+// Week 5: 0/100 (migration complete)
+```
+
+The pool transport provides the flexibility to implement sophisticated email
+delivery strategies that adapt to your application's specific requirements
+for reliability, cost, and performance.
diff --git a/docs/transports/resend.md b/docs/transports/resend.md
new file mode 100644
index 0000000..e906f09
--- /dev/null
+++ b/docs/transports/resend.md
@@ -0,0 +1,264 @@
+# Resend
+
+[Resend] is a modern email service provider that offers a developer-friendly
+API for sending transactional emails. Built with simplicity and reliability
+in mind, Resend provides excellent deliverability, comprehensive tracking,
+and intuitive tools for managing email infrastructure. It's particularly
+well-suited for transactional emails such as welcome messages, password resets,
+notifications, and system alerts, with features designed specifically for
+developers and modern web applications.
+
+@alexify/mailer provides a feature-rich Resend transport through the *@alexify/mailer/resend*
+package, supporting all major Resend features including batch sending,
+automatic idempotency, smart optimization, and comprehensive error handling.
+
+[Resend]: https://resend.com/
+
+## Installation
+
+To use the Resend transport, you need to install the *@alexify/mailer/resend* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Getting started
+
+Before using the Resend transport, you'll need a Resend account and an API
+key. Resend provides API keys through their dashboard at [resend.com/api-keys],
+where you can create keys with specific permissions for your application's
+needs.
+
+```js
+const { ResendTransport } = require('@alexify/mailer/resend');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new ResendTransport({
+  apiKey: 're_1234567890abcdef_1234567890abcdef1234567890',
+});
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The Resend transport handles authentication automatically using your API key
+and sends emails through Resend's reliable infrastructure. The service manages
+bounces, spam filtering, and delivery optimization automatically, providing
+excellent deliverability rates with minimal configuration.
+
+[resend.com/api-keys]: https://resend.com/api-keys
+
+## Batch sending and optimization
+
+One of Resend's key features is intelligent batch optimization. The transport
+automatically chooses the most efficient sending method based on your message
+characteristics, using Resend's batch API when possible for optimal performance:
+
+```js
+const { ResendTransport } = require('@alexify/mailer/resend');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new ResendTransport({
+  apiKey: "re_1234567890abcdef_1234567890abcdef1234567890",
+});
+
+const subscribers = [
+  "user1@example.com",
+  "user2@example.com",
+  "user3@example.com",
+];
+
+const messages = subscribers.map(email =>
+  createMessage({
+    from: "newsletter@example.com",
+    to: email,
+    subject: "Monthly Newsletter - December 2024",
+    content: {
+      html: "<h2>This Month's Updates</h2><p>Here's what's new...</p>",
+      text: "This Month's Updates\n\nHere's what's new...",
+    },
+  })
+);
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Newsletter sent with ID: ${receipt.messageId}`);
+  } else {
+    console.error(`Failed to send: ${receipt.errorMessages.join(", ")}`);
+  }
+}
+```
+
+The transport automatically determines the optimal sending strategy:
+
+ -  **≤100 messages without attachments/tags**: Uses Resend's batch API for
+    fastest delivery
+ -  **>100 messages**: Automatically chunks into multiple batch requests
+ -  **Messages with attachments or tags**: Falls back to individual requests
+ -  **Mixed scenarios**: Intelligently separates batch-compatible from
+    individual messages
+
+This optimization happens transparently, ensuring maximum performance while
+maintaining full feature compatibility.
+
+## Message tagging and organization
+
+Resend supports message tagging for better organization and analytics.
+Tags help you categorize emails and track performance across different types
+of messages and campaigns:
+
+```js
+const { ResendTransport } = require('@alexify/mailer/resend');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new ResendTransport({
+  apiKey: 're_1234567890abcdef_1234567890abcdef1234567890',
+});
+
+const welcomeMessage = createMessage({
+  from: 'onboarding@example.com',
+  to: 'newuser@example.com',
+  subject: 'Welcome to our platform',
+  content: {
+    html: '<h1>Welcome!</h1><p>Thank you for joining us.</p>',
+    text: 'Welcome! Thank you for joining us.',
+  },
+  tags: ['onboarding', 'welcome', 'transactional'],
+});
+
+const receipt = await transport.send(welcomeMessage);
+```
+
+Tags appear in Resend's analytics dashboard, allowing you to track delivery
+statistics, open rates, and engagement metrics for specific message categories.
+This helps you understand which types of emails perform best with your audience
+and optimize your email strategies accordingly.
+
+## Idempotency and reliability
+
+Resend provides built-in idempotency support to prevent duplicate email sends
+during network issues or application retries. The transport automatically
+generates idempotency keys, but you can provide custom keys for specific
+use cases:
+
+```js
+const { ResendTransport } = require('@alexify/mailer/resend');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new ResendTransport({
+  apiKey: 're_1234567890abcdef_1234567890abcdef1234567890',
+  retries: 3,
+  timeout: 30000,
+});
+
+const message = createMessage({
+  from: 'alerts@example.com',
+  to: 'admin@example.com',
+  subject: '🚨 System Alert: High CPU Usage',
+  content: {
+    text: 'Server CPU usage has exceeded 90% for the past 5 minutes.',
+  },
+  priority: 'high', // Sets X-Priority header
+  tags: ['alert', 'system'],
+});
+
+// Send the alert (idempotency key is automatically generated)
+const receipt = await transport.send(message);
+```
+
+The transport includes comprehensive retry logic with exponential backoff,
+ensuring reliable delivery even during temporary service interruptions.
+Priority levels are automatically converted to appropriate email headers
+for better inbox placement of urgent messages.
+
+## Advanced configuration and reliability
+
+The Resend transport includes comprehensive configuration options for timeout
+handling, retry behavior, SSL validation, and custom headers to ensure reliable
+email delivery in production environments:
+
+```js
+const { ResendTransport } = require('@alexify/mailer/resend');
+
+const transport = new ResendTransport({
+  apiKey: 're_1234567890abcdef_1234567890abcdef1234567890',
+  baseUrl: 'https://api.resend.com',
+  timeout: 15000,
+  retries: 5,
+  validateSsl: true,
+  headers: {
+    'X-Custom-Header': 'MyApp-v1.0',
+    'X-Environment': 'production',
+  },
+});
+```
+
+Timeout settings control how long to wait for Resend's API responses,
+while retry configuration determines how many times to retry failed requests.
+The transport uses exponential backoff for retries, reducing load on Resend's
+servers during temporary outages and improving overall reliability.
+
+## Development and testing
+
+For development and testing, you can configure the Resend transport for
+testing environments. Resend provides test API keys and domains that allow
+you to test email functionality without sending real emails to users:
+
+```js
+const { ResendTransport } = require('@alexify/mailer/resend');
+const { createMessage } = require('@alexify/mailer');
+
+// Development configuration with test domain
+const devTransport = new ResendTransport({
+  apiKey: 're_test1234567890ab_cdef1234567890abcdef1234567890ab',
+  timeout: 5000, // Shorter timeout for development
+  retries: 1, // Fewer retries for faster feedback
+});
+
+// Testing configuration with environment variables
+const testTransport = new ResendTransport({
+  apiKey: process.env.RESEND_TEST_API_KEY ?? 're_test123',
+  timeout: 10000,
+  retries: 1, // Fewer retries for faster test execution
+});
+
+// Example test message using onboarding@resend.dev
+const testMessage = createMessage({
+  from: 'onboarding@resend.dev', // Resend's test domain
+  to: 'delivered@resend.dev', // Test recipient address
+  subject: 'Test Email',
+  content: { text: 'This is a test email.' },
+});
+
+const receipt = await testTransport.send(testMessage);
+```
+
+For local development, you can use Resend's test domains
+(`onboarding@resend.dev`) which accept emails but don't deliver them to real
+recipients. This allows you to test the complete email sending workflow without
+affecting real users.
+
+> [!TIP]
+> Resend provides excellent debugging tools through their dashboard where you
+> can view all sent emails, delivery status, and detailed logs. This is
+> invaluable for testing email flows and debugging delivery issues in
+> development environments.
+
+> [!CAUTION]
+> Always use test API keys and verified domains during development to avoid
+> sending test emails to real users. Resend's test domains like
+> `onboarding@resend.dev` are perfect for development but have rate limits
+> suitable for testing rather than production use.
diff --git a/docs/transports/retry.md b/docs/transports/retry.md
new file mode 100644
index 0000000..a2d88cf
--- /dev/null
+++ b/docs/transports/retry.md
@@ -0,0 +1,206 @@
+# Retry transport
+
+The retry transport is a decorator that wraps another @alexify/mailer transport and
+retries transient delivery failures before returning a final receipt.  It is
+useful when a single provider occasionally returns rate limits, temporary
+server errors, or network failures that should be retried with backoff.
+
+Retrying depends on structured failure metadata from *@alexify/mailer*.  Transports
+that return failed receipts with `retryable` or structured `errors` fields can
+be retried without custom logic.  Cancellation via `AbortSignal` is never
+retried and still rejects the send operation.
+
+> [!NOTE]
+> Retry transport is not a cross-provider failover system.  To fail over across
+> several providers, use [pool transport](/transports/pool), and place retry transport
+> inside or outside the pool depending on whether you want per-provider retries
+> or retries of the whole pooled operation.
+
+## Installation
+
+To use retry transport, install the *@alexify/mailer/retry* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Basic usage
+
+Create your regular transport first, then wrap it with `RetryTransport`.
+The wrapper implements the same `Transport` interface and keeps the wrapped
+transport provider id in receipts:
+
+```js
+const { createFailedReceipt, createMessage } = require('@alexify/mailer');
+const { MockTransport } = require('@alexify/mailer/mock');
+const { RetryTransport } = require('@alexify/mailer/retry');
+
+const baseTransport = new MockTransport({
+  defaultResponse: createFailedReceipt('Temporarily unavailable.', {
+    provider: 'mock',
+    statusCode: 503,
+  }),
+});
+
+const transport = new RetryTransport(baseTransport, {
+  maxAttempts: 3,
+  backoff: {
+    baseDelayMilliseconds: 1000,
+    maxDelayMilliseconds: 30000,
+    factor: 2,
+  },
+});
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.com',
+  subject: 'Hello',
+  content: { text: 'Hello from mailer.' },
+});
+
+const receipt = await transport.send(message);
+
+if (!receipt.successful) {
+  console.error(receipt.errorMessages.join(', '));
+  console.error('Attempts:', receipt.attempts);
+}
+```
+
+By default, retry transport makes up to three total attempts, waits with
+exponential backoff, caps computed delays at 30 seconds, and applies full
+jitter to computed backoff delays.
+
+## Retry classification
+
+Retry transport uses the final failed receipt from each attempt to decide
+whether another attempt should be made.  It retries when the receipt or one of
+its structured errors is marked retryable.  This includes common transient
+HTTP statuses such as `429`, `408`, and `5xx` when transports expose them as
+structured receipt errors.
+
+If a wrapped transport throws a transient error instead of returning a failed
+receipt, retry transport retries it using the same classifier used by
+*@alexify/mailer*.  After all attempts are exhausted, thrown delivery failures are
+converted into a failed receipt.  Caller cancellation errors are rethrown.
+
+You can override classification with `shouldRetry` when a provider needs
+application-specific logic:
+
+```js
+const { MockTransport } = require('@alexify/mailer/mock');
+const { RetryTransport } = require('@alexify/mailer/retry');
+
+const baseTransport = new MockTransport();
+
+const transport = new RetryTransport(baseTransport, {
+  shouldRetry(failure) {
+    if (failure.kind === 'receipt') {
+      return failure.receipt.errorMessages.some((message) => message.includes('temporary'));
+    }
+    return failure.error instanceof TypeError;
+  },
+});
+```
+
+## Backoff and `Retry-After`
+
+Computed retry delays use exponential backoff:
+
+- `baseDelayMilliseconds * factor ^ (attempt - 1)`: The delay before the next attempt, capped by `maxDelayMilliseconds`.
+
+- `jitter`: `"full"` by default.  Set it to `false` or `"none"` for deterministic
+  computed delays.
+
+- `Retry-After`: When a structured receipt error includes `retryAfterMilliseconds`, retry
+  transport uses that provider-supplied delay before computed backoff.  The
+  delay is still capped by `maxDelayMilliseconds`.
+
+Tests or host environments can replace waiting by passing a custom `wait`
+function:
+
+```js
+const { MockTransport } = require('@alexify/mailer/mock');
+const { RetryTransport } = require('@alexify/mailer/retry');
+
+const delays = [];
+const baseTransport = new MockTransport();
+
+const transport = new RetryTransport(baseTransport, {
+  jitter: false,
+  wait(context, signal) {
+    signal?.throwIfAborted();
+    delays.push(context.delayMilliseconds);
+    return Promise.resolve();
+  },
+});
+```
+
+## `sendMany()` throttling
+
+`sendMany()` retries each message independently by calling the wrapped
+transport's `send()` method for each input message.  This means provider-native
+batch APIs are not used through retry transport.  Use the provider transport
+directly when its batch API semantics matter more than per-message retry.
+
+For bulk sends, configure `maxConcurrent` and `intervalMilliseconds` to limit
+how aggressively messages are launched:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { MockTransport } = require('@alexify/mailer/mock');
+const { RetryTransport } = require('@alexify/mailer/retry');
+
+const baseTransport = new MockTransport();
+const transport = new RetryTransport(baseTransport, {
+  maxAttempts: 3,
+  sendMany: {
+    maxConcurrent: 4,
+    intervalMilliseconds: 250,
+  },
+});
+
+const messages = [
+  createMessage({
+    from: "sender@example.com",
+    to: "one@example.com",
+    subject: "One",
+    content: { text: "First message." },
+  }),
+  createMessage({
+    from: "sender@example.com",
+    to: "two@example.com",
+    subject: "Two",
+    content: { text: "Second message." },
+  }),
+];
+
+for await (const receipt of transport.sendMany(messages)) {
+  console.log(receipt.successful);
+}
+```
+
+Receipts are yielded in the same order as input messages, even when later
+messages finish first.
+
+## Composition
+
+Retry transport composes with other decorators because it preserves the
+standard @alexify/mailer transport interface.  Put it closest to the provider when you
+want provider-level retries before another decorator observes or aggregates
+the result:
+
+```js
+const { MockTransport } = require('@alexify/mailer/mock');
+const { createRetryTransport } = require('@alexify/mailer/retry');
+
+const providerTransport = new MockTransport();
+const transport = createRetryTransport(providerTransport, {
+  maxAttempts: 4,
+});
+```
+
+When wrapping disposable transports, `RetryTransport` forwards async disposal
+to the wrapped transport.  If the wrapped transport only supports synchronous
+disposal, that is used as a fallback.
diff --git a/docs/transports/sendgrid.md b/docs/transports/sendgrid.md
new file mode 100644
index 0000000..408b7bd
--- /dev/null
+++ b/docs/transports/sendgrid.md
@@ -0,0 +1,248 @@
+# SendGrid
+
+[SendGrid] is a comprehensive cloud-based email delivery platform that provides
+reliable email infrastructure for businesses of all sizes. It offers powerful
+APIs for sending transactional and marketing emails, with advanced features
+including email templates, A/B testing, real-time analytics, and sophisticated
+deliverability tools. SendGrid is particularly well-suited for transactional
+emails such as account verification, password resets, order confirmations,
+and automated notifications.
+
+@alexify/mailer provides a feature-rich SendGrid transport through the *@alexify/mailer/sendgrid*
+package, supporting all major SendGrid features including tracking, templates,
+personalization, and bulk sending with comprehensive error handling and retry
+logic.
+
+[SendGrid]: https://sendgrid.com/
+
+## Installation
+
+To use the SendGrid transport, you need to install the *@alexify/mailer/sendgrid* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Getting started
+
+Before using the SendGrid transport, you'll need a SendGrid account and an API
+key. SendGrid provides API keys through their web interface under *Settings* →
+*API Keys*, where you can create keys with specific permissions for your
+application's needs.
+
+```js
+const { SendGridTransport } = require('@alexify/mailer/sendgrid');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new SendGridTransport({
+  apiKey: 'SG.1234567890abcdef.1234567890abcdef1234567890abcdef12345678',
+});
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The SendGrid transport handles authentication automatically using your API key
+and sends emails through SendGrid's robust infrastructure. The service manages
+bounces, spam filtering, and delivery optimization automatically, providing
+excellent deliverability rates.
+
+## Email tracking and analytics
+
+SendGrid provides comprehensive email tracking and analytics capabilities.
+The transport enables tracking by default, but you can customize tracking
+behavior to match your privacy requirements and analytics needs:
+
+```js
+const { SendGridTransport } = require('@alexify/mailer/sendgrid');
+
+const transport = new SendGridTransport({
+  apiKey: 'SG.1234567890abcdef.1234567890abcdef1234567890abcdef12345678',
+  clickTracking: true,
+  openTracking: true,
+  subscriptionTracking: false,
+  googleAnalytics: false,
+});
+```
+
+With tracking enabled, SendGrid provides detailed analytics about email
+delivery, opens, clicks, unsubscribes, and bounces through their dashboard
+and webhooks. This data is essential for monitoring email campaign performance
+and improving engagement rates.
+
+## Message tagging and organization
+
+SendGrid allows you to tag messages for better organization and analytics.
+Tags help you categorize emails and track performance across different types
+of messages and campaigns:
+
+```js
+const { SendGridTransport } = require('@alexify/mailer/sendgrid');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new SendGridTransport({
+  apiKey: 'SG.1234567890abcdef.1234567890abcdef1234567890abcdef12345678',
+});
+
+const welcomeMessage = createMessage({
+  from: 'onboarding@example.com',
+  to: 'newuser@example.com',
+  subject: 'Welcome to our platform',
+  content: {
+    html: '<h1>Welcome!</h1><p>Thank you for joining us.</p>',
+    text: 'Welcome! Thank you for joining us.',
+  },
+  tags: ['onboarding', 'welcome', 'transactional'],
+});
+
+const receipt = await transport.send(welcomeMessage);
+```
+
+Tags appear in SendGrid's analytics dashboard and can be used with webhooks,
+allowing you to track open rates, click rates, and delivery statistics for
+specific message categories. This helps you understand which types of emails
+perform best with your audience.
+
+## Bulk email sending
+
+For sending newsletters, notifications, or other bulk emails, the SendGrid
+transport provides efficient batch processing with automatic retry logic
+and comprehensive error handling:
+
+```js
+const { SendGridTransport } = require('@alexify/mailer/sendgrid');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new SendGridTransport({
+  apiKey: "SG.1234567890abcdef.1234567890abcdef1234567890abcdef12345678",
+  retries: 3,
+  timeout: 30000,
+});
+
+const subscribers = [
+  "user1@example.com",
+  "user2@example.com",
+  "user3@example.com",
+];
+
+const messages = subscribers.map(email =>
+  createMessage({
+    from: "newsletter@example.com",
+    to: email,
+    subject: "Monthly Newsletter - December 2024",
+    content: {
+      html: "<h2>This Month's Updates</h2><p>Here's what's new...</p>",
+      text: "This Month's Updates\n\nHere's what's new...",
+    },
+    tags: ["newsletter", "monthly"],
+  })
+);
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Newsletter sent to ${receipt.messageId}`);
+  } else {
+    console.error(`Failed to send: ${receipt.errorMessages.join(", ")}`);
+  }
+}
+```
+
+The `SendGridTransport.sendMany()` method processes emails sequentially with
+built-in retry logic. Failed emails don't prevent subsequent emails from being
+sent, and detailed error information helps you identify and resolve delivery
+issues quickly.
+
+## Advanced configuration and reliability
+
+The SendGrid transport includes comprehensive configuration options for timeout
+handling, retry behavior, SSL validation, and custom headers to ensure reliable
+email delivery in production environments:
+
+```js
+const { SendGridTransport } = require('@alexify/mailer/sendgrid');
+
+const transport = new SendGridTransport({
+  apiKey: 'SG.1234567890abcdef.1234567890abcdef1234567890abcdef12345678',
+  baseUrl: 'https://api.sendgrid.com/v3',
+  timeout: 15000,
+  retries: 5,
+  validateSsl: true,
+  headers: {
+    'X-Custom-Header': 'MyApp-v1.0',
+    'X-Environment': 'production',
+  },
+  clickTracking: true,
+  openTracking: true,
+  subscriptionTracking: false,
+  googleAnalytics: true,
+});
+```
+
+Timeout settings control how long to wait for SendGrid's API responses,
+while retry configuration determines how many times to retry failed requests.
+The transport uses exponential backoff for retries, reducing load on SendGrid's
+servers during temporary outages and improving overall reliability.
+
+## Development and testing
+
+For development and testing, you can configure the SendGrid transport for
+testing environments or use SendGrid's sandbox mode. SendGrid doesn't provide
+dedicated sandbox domains like some providers, but you can use test API keys
+and monitor emails through their Event Webhook for testing:
+
+```js
+const { SendGridTransport } = require('@alexify/mailer/sendgrid');
+
+// Development configuration with reduced timeouts
+const devTransport = new SendGridTransport({
+  apiKey: 'SG.test1234567890ab.cdef1234567890abcdef1234567890abcdef123456',
+  timeout: 5000, // Shorter timeout for development
+  retries: 1, // Fewer retries for faster feedback
+  clickTracking: false,
+  openTracking: false,
+});
+
+// Testing configuration with environment variables
+const testTransport = new SendGridTransport({
+  apiKey: process.env.SENDGRID_TEST_API_KEY ?? 'SG.test123',
+  timeout: 10000,
+  retries: 1, // Fewer retries for faster test execution
+  clickTracking: false, // Disable tracking in tests
+  openTracking: false,
+  subscriptionTracking: false,
+});
+```
+
+For testing, consider using restricted API keys that can only send to verified
+email addresses or specific domains. This prevents accidental email sends to
+real users during development while still allowing you to test the complete
+email sending workflow.
+
+> [!TIP]
+> SendGrid provides excellent testing tools through their Event Webhook feature.
+> You can configure webhooks to receive real-time notifications about email
+> events (delivered, opened, clicked, etc.) which is invaluable for testing
+> email flows and debugging delivery issues in development environments.
+
+> [!CAUTION]
+> Unlike some email providers, SendGrid doesn't have a true sandbox mode that
+> prevents email delivery. Always use test API keys with restricted permissions
+> and verified recipient addresses during development to avoid sending test
+> emails to real users. Consider using services like [MailHog] or [Mailpit]
+> for local development testing.
+
+[MailHog]: https://github.com/mailhog/MailHog
+[Mailpit]: https://github.com/axllent/mailpit
diff --git a/docs/transports/ses.md b/docs/transports/ses.md
new file mode 100644
index 0000000..2588fb5
--- /dev/null
+++ b/docs/transports/ses.md
@@ -0,0 +1,414 @@
+# Amazon SES
+
+[Amazon SES] (Simple Email Service) is AWS's reliable, scalable email sending
+service designed for high-volume transactional and marketing emails. Built on
+Amazon's proven infrastructure, SES provides excellent deliverability rates,
+comprehensive analytics, and seamless integration with other AWS services.
+The service automatically handles bounce and complaint processing, reputation
+monitoring, and compliance with industry standards, making it ideal for
+applications that need reliable email delivery at scale.
+
+@alexify/mailer provides a comprehensive Amazon SES transport through the *@alexify/mailer/ses*
+package, offering AWS Signature v4 authentication, zero dependencies for
+cross-runtime compatibility, and efficient bulk sending capabilities.
+
+[Amazon SES]: https://aws.amazon.com/ses/
+
+## Installation
+
+To use the Amazon SES transport, you need to install the *@alexify/mailer/ses* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Getting started
+
+Before using the Amazon SES transport, you'll need an AWS account with SES
+enabled and appropriate IAM permissions. You can use AWS access keys, session
+tokens, or IAM roles for authentication. SES requires verified email addresses
+or domains for sending, which you can configure through the AWS Console.
+
+```js
+const { SesTransport } = require('@alexify/mailer/ses');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new SesTransport({
+  authentication: {
+    type: 'credentials',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  },
+  region: 'us-east-1',
+});
+
+const message = createMessage({
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome to our service',
+  content: { text: 'Thank you for signing up!' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+```
+
+The SES transport handles AWS authentication automatically using Signature v4
+signing and sends emails through Amazon's reliable infrastructure. The service
+provides excellent deliverability and detailed bounce handling.
+
+## Authentication methods
+
+The Amazon SES transport supports two primary authentication methods, each
+designed for different use cases and security requirements. Both methods use
+discriminated union types for type safety:
+
+```js
+const { SesTransport } = require('@alexify/mailer/ses');
+
+// AWS access key credentials (for long-term access)
+const credentialsTransport = new SesTransport({
+  authentication: {
+    type: 'credentials',
+    accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+    secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+  },
+  region: 'us-west-2',
+});
+
+// Session tokens (for temporary credentials)
+const sessionTransport = new SesTransport({
+  authentication: {
+    type: 'session',
+    accessKeyId: 'ASIAXYZ...',
+    secretAccessKey: 'abc123...',
+    sessionToken: 'FwoGZXIvYXdzE...',
+  },
+  region: 'eu-west-1',
+});
+```
+
+Session authentication is particularly useful when using temporary credentials
+from AWS STS, IAM roles, or federated authentication systems. The transport
+automatically handles the inclusion of session tokens in AWS API requests.
+
+## IAM roles and external authentication
+
+For applications running on AWS infrastructure or requiring IAM role-based
+access, you can use external tools to assume roles and provide the resulting
+temporary credentials to the transport:
+
+```js
+const { SesTransport } = require('@alexify/mailer/ses');
+
+// First, assume the role externally (e.g., using AWS CLI or SDK):
+// aws sts assume-role --role-arn "arn:aws:iam::123456789012:role/SesRole" --role-session-name "ses-session"
+
+const transport = new SesTransport({
+  authentication: {
+    type: 'session',
+    accessKeyId: 'ASIAXYZ...', // From AssumeRole response
+    secretAccessKey: 'abc123...', // From AssumeRole response
+    sessionToken: 'FwoGZXIv...', // From AssumeRole response
+  },
+  region: 'eu-west-1',
+});
+```
+
+This approach gives you full control over role assumption logic, credential
+refresh, and session management while keeping the transport focused on email
+delivery. You can implement custom credential providers that automatically
+refresh temporary credentials as needed.
+
+> [!TIP]
+> While the SES transport currently requires external role assumption, direct
+> IAM role support may be added in future versions. This would enable automatic
+> credential refresh and simplified configuration for applications running on
+> AWS infrastructure. The current external approach maintains the transport's
+> zero-dependency design while ensuring maximum flexibility and compatibility
+> across different deployment environments.
+
+## Regional configuration
+
+Amazon SES operates in multiple AWS regions, and you should choose the region
+closest to your application or based on compliance requirements. The transport
+automatically constructs the correct SES endpoints for your chosen region:
+
+```js
+const { SesTransport } = require('@alexify/mailer/ses');
+
+// US East (N. Virginia) - Default region
+const usEastTransport = new SesTransport({
+  authentication: {
+    type: 'credentials',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  },
+  region: 'us-east-1',
+});
+
+// EU (Ireland) for GDPR compliance
+const euTransport = new SesTransport({
+  authentication: {
+    type: 'credentials',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  },
+  region: 'eu-west-1',
+});
+
+// Asia Pacific (Sydney)
+const apacTransport = new SesTransport({
+  authentication: {
+    type: 'credentials',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  },
+  region: 'ap-southeast-2',
+});
+```
+
+Choose your region based on latency requirements, data residency regulations,
+and SES feature availability. Some SES features may not be available in all
+regions, so consult the AWS documentation for your specific needs.
+
+## Rich message features
+
+The SES transport supports all major email features including HTML content,
+attachments, tags, and priority settings. These features integrate seamlessly
+with SES's tracking and analytics capabilities:
+
+```js
+// @noErrors: 2322
+const { SesTransport } = require('@alexify/mailer/ses');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new SesTransport({
+  authentication: {
+    type: 'credentials',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  },
+  region: 'us-east-1',
+  defaultTags: {
+    environment: 'production',
+    application: 'user-notifications',
+  },
+});
+
+const message = createMessage({
+  from: { address: 'support@example.com', name: 'Support Team' },
+  to: [{ address: 'customer@example.com', name: 'John Customer' }, 'backup@example.com'],
+  cc: 'manager@example.com',
+  replyTo: 'noreply@example.com',
+  subject: 'Your Monthly Report',
+  content: {
+    html: '<h1>Monthly Report</h1><p>Please find your report attached.</p>',
+    text: 'Monthly Report\n\nPlease find your report attached.',
+  },
+  attachments: [
+    new File(
+      [await fetch('https://example.com/report.pdf').then((r) => r.arrayBuffer())],
+      'monthly-report.pdf',
+      { type: 'application/pdf' },
+    ),
+  ],
+  tags: ['report', 'monthly', 'automated'],
+  priority: 'high',
+});
+
+const receipt = await transport.send(message);
+```
+
+Tags are particularly powerful in SES as they enable detailed tracking and
+analytics through CloudWatch metrics. You can set default tags at the transport
+level and additional tags per message for comprehensive categorization.
+
+## Bulk email sending
+
+For sending newsletters, notifications, or other bulk emails, the SES transport
+provides efficient batch processing that respects SES rate limits and handles
+errors gracefully:
+
+```js
+const { SesTransport } = require('@alexify/mailer/ses');
+const { createMessage } = require('@alexify/mailer');
+
+const transport = new SesTransport({
+  authentication: {
+    type: "credentials",
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID ,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ,
+  },
+  region: "us-east-1",
+  batchSize: 25, // Process 25 messages concurrently
+  retries: 3,
+});
+
+const subscribers = [
+  "user1@example.com",
+  "user2@example.com",
+  "user3@example.com",
+  // ... potentially thousands more
+];
+
+const messages = subscribers.map(email =>
+  createMessage({
+    from: "newsletter@example.com",
+    to: email,
+    subject: "Weekly Newsletter - December 2024",
+    content: {
+      html: "<h2>This Week's Updates</h2><p>Here's what's new...</p>",
+      text: "This Week's Updates\n\nHere's what's new...",
+    },
+    tags: ["newsletter", "weekly"],
+  })
+);
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Newsletter sent: ${receipt.messageId}`);
+  } else {
+    console.error(`Failed to send: ${receipt.errorMessages.join(", ")}`);
+  }
+}
+```
+
+The `SesTransport.sendMany()` method processes messages concurrently using
+individual `SendEmail` API calls rather than SES's `SendBulkEmail` API.
+This approach provides maximum flexibility for different message content
+while still achieving excellent throughput through concurrent processing.
+
+## Configuration sets and tracking
+
+Amazon SES provides configuration sets for advanced tracking, reputation
+monitoring, and event publishing. You can specify a configuration set
+to enable detailed analytics and webhook notifications:
+
+```js
+const { SesTransport } = require('@alexify/mailer/ses');
+
+const transport = new SesTransport({
+  authentication: {
+    type: 'credentials',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  },
+  region: 'us-east-1',
+  configurationSetName: 'my-production-config-set',
+  defaultTags: {
+    source: 'mailer',
+    version: '1.0',
+  },
+});
+```
+
+Configuration sets enable features like:
+
+ -  Event publishing to CloudWatch, Kinesis, or SNS
+ -  Reputation tracking and automatic bounce handling
+ -  IP pool management for dedicated sending
+ -  Click and open tracking integration
+ -  Suppression list management
+
+Consult the [SES Configuration Sets documentation] for detailed setup
+instructions and available features.
+
+[SES Configuration Sets documentation]: https://docs.aws.amazon.com/ses/latest/dg/using-configuration-sets.html
+
+## Advanced configuration and reliability
+
+The SES transport includes comprehensive configuration options for timeout
+handling, retry behavior, SSL validation, and custom headers to ensure
+reliable email delivery in production environments:
+
+```js
+const { SesTransport } = require('@alexify/mailer/ses');
+
+const transport = new SesTransport({
+  authentication: {
+    type: 'session',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    sessionToken: process.env.AWS_SESSION_TOKEN,
+  },
+  region: 'us-east-1',
+  timeout: 15000,
+  retries: 5,
+  validateSsl: true,
+  headers: {
+    'X-Application': 'MyApp-v2.1',
+    'X-Environment': 'production',
+  },
+  configurationSetName: 'production-emails',
+  defaultTags: {
+    service: 'notifications',
+    environment: 'prod',
+  },
+  batchSize: 30,
+});
+```
+
+Timeout settings control how long to wait for SES API responses, while retry
+configuration determines how many times to retry failed requests. The transport
+uses exponential backoff for retries, reducing load on SES during temporary
+issues and improving overall reliability.
+
+## Development and testing
+
+For development and testing, you can configure the SES transport for testing
+environments. SES provides a sandbox mode for new accounts that restricts
+sending to verified email addresses, perfect for development workflows:
+
+```js
+const { SesTransport } = require('@alexify/mailer/ses');
+
+// Development configuration with sandbox restrictions
+const devTransport = new SesTransport({
+  authentication: {
+    type: 'credentials',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  },
+  region: 'us-east-1',
+  timeout: 5000, // Shorter timeout for development
+  retries: 1, // Fewer retries for faster feedback
+  batchSize: 5, // Smaller batches for testing
+  defaultTags: {
+    environment: 'development',
+  },
+});
+
+// Testing configuration with environment variables
+const testTransport = new SesTransport({
+  authentication: {
+    type: 'credentials',
+    accessKeyId: process.env.SES_TEST_ACCESS_KEY_ID ?? 'test-key',
+    secretAccessKey: process.env.SES_TEST_SECRET_ACCESS_KEY ?? 'test-secret',
+  },
+  region: process.env.SES_TEST_REGION ?? 'us-east-1',
+  timeout: 10000,
+  retries: 1, // Fewer retries for faster test execution
+  validateSsl: false, // For testing with local endpoints
+});
+```
+
+> [!TIP]
+> When starting with Amazon SES, your account begins in sandbox mode, which
+> restricts sending to verified email addresses and domains. This is perfect
+> for development and testing as it prevents accidental email sends to real
+> users. To send to unverified addresses in production, you'll need to request
+> production access through the AWS Console.
+
+> [!CAUTION]
+> SES sandbox mode has strict sending limits (typically 200 emails per 24-hour
+> period and 1 email per second). For extensive testing, performance testing,
+> or CI/CD pipelines that send many emails, consider requesting production
+> access or using alternative testing approaches like mock transports for
+> unit tests.
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
new file mode 100644
index 0000000..80b9ad8
--- /dev/null
+++ b/docs/transports/smtp.md
@@ -0,0 +1,1103 @@
+# SMTP
+
+SMTP (Simple Mail Transfer Protocol) is the standard protocol for sending emails
+across networks, as defined in [RFC 5321].  Most email providers offer SMTP
+servers alongside their proprietary APIs, making SMTP a universal fallback
+option when specific transports aren't available for your email provider.
+The SMTP protocol provides reliable, widely-supported email delivery with
+features like authentication, encryption, and delivery confirmation.
+
+@alexify/mailer provides a comprehensive SMTP transport through the *@alexify/mailer/smtp* subpath,
+offering connection pooling, TLS support, multiple authentication methods,
+and efficient bulk sending capabilities.
+
+> [!CAUTION]
+> The SMTP transport currently does not support edge functions or web browsers.
+> If you need to use @alexify/mailer in these environments, consider using other transports
+> like [Mailgun](/transports/mailgun) or similar services that provide HTTP APIs.
+
+[RFC 5321]: https://datatracker.ietf.org/doc/html/rfc5321
+
+## Installation
+
+To use the SMTP transport, you need to install the *@alexify/mailer/smtp* subpath:
+
+```bash
+pnpm add @alexify/mailer
+# or
+npm install @alexify/mailer
+```
+
+## Basic usage
+
+The SMTP transport requires connection details for your SMTP server,
+including the hostname, port, and authentication credentials.
+Most email providers offer SMTP access through their settings or
+developer documentation.
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { createMessage } = require('@alexify/mailer');
+
+// Create transport with basic configuration
+const transport = new SmtpTransport({
+  host: 'smtp.gmail.com',
+  port: 465,
+  secure: true,
+  auth: {
+    user: 'your-email@gmail.com',
+    pass: 'your-app-password',
+  },
+});
+
+const message = createMessage({
+  from: 'sender@example.com',
+  to: 'recipient@example.com',
+  subject: 'Hello from mailer SMTP',
+  content: { text: 'This email was sent using the SMTP transport.' },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log('Message sent with ID:', receipt.messageId);
+} else {
+  console.error('Send failed:', receipt.errorMessages.join(', '));
+}
+
+// Clean up connections when done
+await transport.closeAllConnections();
+```
+
+The transport automatically handles connection management, protocol negotiation,
+and message formatting. When you're finished sending emails, it's important to
+close connections to free up resources.
+
+## Automatic resource management
+
+Modern JavaScript environments support automatic resource cleanup using
+the [`await using`] statement, which automatically closes SMTP connections
+when the transport goes out of scope:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { createMessage } = require('@alexify/mailer');
+
+await using transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'username',
+    pass: 'password',
+  },
+});
+
+const message = createMessage({
+  from: 'system@example.com',
+  to: 'user@example.com',
+  subject: 'System Notification',
+  content: { text: 'Your backup completed successfully.' },
+});
+
+await transport.send(message);
+// Connections are automatically closed when transport goes out of scope
+```
+
+This approach eliminates the need to manually call
+`SmtpTransport.closeAllConnections()` and ensures proper cleanup
+even if errors occur.
+
+[`await using`]: https://github.com/tc39/proposal-async-explicit-resource-management#await-using-declarations
+
+## Connection configuration
+
+The SMTP transport offers extensive configuration options to work with different
+email providers and security requirements.  Connection settings control
+timeouts, pooling, and protocol behavior:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'mail.example.com',
+  port: 587,
+  secure: false,
+  requireTls: true,
+  auth: {
+    user: 'user@example.com',
+    pass: 'secure-password',
+    method: 'plain',
+  },
+  connectionTimeout: 30000,
+  socketTimeout: 60000,
+  localName: 'mail.mycompany.com',
+  pool: true,
+  poolSize: 10,
+});
+```
+
+The `SmtpConfig.host` and `SmtpConfig.port` specify your SMTP server details,
+while `SmtpConfig.secure` determines whether to use implicit TLS and
+`SmtpConfig.requireTls` makes a STARTTLS upgrade mandatory for plaintext
+connections.  Connection and socket timeouts prevent hanging connections, and
+the `SmtpConfig.localName` identifies your server during the SMTP handshake.
+Connection pooling improves performance by reusing connections across multiple
+messages.
+
+`SmtpConfig.poolSize` caps how many connections one transport may have open at
+the same time.  The cap counts connections that are being established,
+connections that are currently sending, and idle connections kept for reuse, so
+it applies whether or not `SmtpConfig.pool` is enabled.  Concurrent
+`SmtpTransport.send()` and `SmtpTransport.sendMany()` calls that arrive once
+the cap is reached wait for a connection to be handed back rather than opening
+another one, which is what lets you match `SmtpConfig.poolSize` to the
+simultaneous-connection limit your provider enforces.  A waiting call still
+honours its `AbortSignal`, so cancelling it rejects without sending the message.
+Setting `SmtpConfig.poolSize` to `Infinity` opts out of the limit entirely.
+
+> [!NOTE]
+> Because a `SmtpTransport.sendMany()` call holds its connection until the
+> iteration ends, running more concurrent `SmtpTransport.sendMany()` calls than
+> `SmtpConfig.poolSize` makes the extra ones wait for an earlier iteration to
+> finish.  Raise `SmtpConfig.poolSize`, or use separate transports, when you
+> need more bulk streams at once.
+
+## Command pipelining
+
+When a server advertises the `PIPELINING` extension defined by [RFC 2920], @alexify/mailer
+sends `MAIL FROM` and all `RCPT TO` commands together instead of waiting for a
+reply after each command.  This cuts the number of network round trips for
+messages with multiple recipients.  @alexify/mailer then reads every reply in command
+order, including multiline replies, before continuing with `DATA`.
+
+Pipelining is negotiated automatically and does not require a configuration
+option.  Servers that do not advertise it keep the standard sequential command
+flow.  A rejected recipient is still reported through
+`SmtpReceipt.rejectedRecipients` when at least one other recipient accepts the
+message.
+
+[RFC 2920]: https://www.rfc-editor.org/rfc/rfc2920
+
+## Message size declaration
+
+@alexify/mailer automatically uses the `SIZE` extension defined by [RFC 1870] when the
+server advertises it.  The transport adds the encoded message size in octets to
+`MAIL FROM`, allowing the server to reject the message before its content is
+uploaded.
+
+If the server advertises a fixed maximum, @alexify/mailer returns a failed receipt without
+sending `MAIL FROM` when the message exceeds that limit.  A bare `SIZE`
+capability, or `SIZE 0`, means that no fixed maximum was advertised, so @alexify/mailer
+still declares the message size without rejecting it locally.  Servers that do
+not advertise `SIZE` retain the existing SMTP flow.
+
+The declared size covers the headers, encoded body, and line endings sent after
+the server accepts `DATA`.  It does not include the DATA terminator or dots
+added for SMTP transparency.
+
+[RFC 1870]: https://www.rfc-editor.org/rfc/rfc1870
+
+## Enhanced status codes
+
+SMTP servers can prefix reply text with an enhanced status code such as
+`5.1.1`, as defined by [RFC 2034] and [RFC 3463].  When a failure contains a
+valid code, @alexify/mailer preserves the final reply line's text in
+`providerDetails.response` and exposes the parsed value through
+`providerDetails.enhancedStatusCode`.  The parsed
+`SmtpEnhancedStatusCode` contains the complete `code` and numeric `class`,
+`subject`, and `detail` fields.
+
+Use `isSmtpResponseProviderDetails()` to narrow the provider-specific details:
+
+```js
+const { isSmtpResponseProviderDetails } = require('@alexify/mailer/smtp');
+
+const error = receipt.successful ? undefined : receipt.errors?.[0];
+if (isSmtpResponseProviderDetails(error?.providerDetails)) {
+  const status = error.providerDetails.enhancedStatusCode;
+  if (status != null) {
+    console.log(status.code, status.class, status.subject, status.detail);
+  }
+}
+```
+
+If delivery succeeds for at least one recipient, each rejected entry in
+`SmtpReceipt.rejectedRecipients` exposes its enhanced code through
+`SmtpRejectedRecipient.enhancedStatusCode`.
+
+@alexify/mailer uses the enhanced subject to refine categories where its meaning is
+unambiguous.  Address and message-content statuses use `validation`, while
+network/routing statuses use `network`.  Other subjects retain the category
+derived from the traditional reply class.  A `4.x.x` code remains retryable and
+a `5.x.x` code remains non-retryable.
+
+The enhanced code must appear at the start of the reply text, use fields of one
+to three digits without leading zeroes, and have the same class as the
+three-digit SMTP reply.  If any condition is not met, @alexify/mailer preserves the reply
+line's text but ignores the enhanced code.  Servers that return only
+traditional replies continue to work unchanged.  Because the code space is
+extensible through the [IANA registry], @alexify/mailer does not reject an otherwise valid
+code merely because its subject or detail is unknown.
+
+[RFC 2034]: https://www.rfc-editor.org/rfc/rfc2034
+[RFC 3463]: https://www.rfc-editor.org/rfc/rfc3463
+[IANA registry]: https://www.iana.org/assignments/smtp-enhanced-status-codes/
+
+## Envelope overrides
+
+Use the `envelope` send option when delivery errors or recipient routing need
+addresses that differ from the visible message headers.  The following message
+still displays `billing@example.com` as its From address and
+`customer@example.net` as its To address:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 465,
+  secure: true,
+});
+const message = createMessage({
+  from: 'billing@example.com',
+  to: 'customer@example.net',
+  subject: 'Invoice',
+  content: { text: 'Your invoice is attached.' },
+});
+
+await transport.send(message, {
+  envelope: {
+    from: 'bounces+customer-42@bounce.example.com',
+    to: ['delivery@example.net'],
+  },
+});
+```
+
+`SmtpEnvelopeOptions.from` controls `MAIL FROM`, while
+`SmtpEnvelopeOptions.to` supplies the addresses for `RCPT TO`.  Omit either
+field to derive that side from the message as before.  Set `from` to `null` for
+the null reverse-path used by delivery notifications:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 465,
+  secure: true,
+});
+const notification = createMessage({
+  from: 'postmaster@example.com',
+  to: 'sender@example.net',
+  subject: 'Delivery status notification',
+  content: { text: 'The message could not be delivered.' },
+});
+
+await transport.send(notification, {
+  envelope: { from: null },
+});
+```
+
+The option also accepts a resolver for bulk VERP delivery.  The resolver
+receives each message and its zero-based position in the send operation:
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: "smtp.example.com",
+  port: 465,
+  secure: true,
+});
+const messages = [
+  createMessage({
+    from: "newsletter@example.com",
+    to: "first@example.net",
+    subject: "Newsletter",
+    content: { text: "Hello, first subscriber." },
+  }),
+  createMessage({
+    from: "newsletter@example.com",
+    to: "second@example.net",
+    subject: "Newsletter",
+    content: { text: "Hello, second subscriber." },
+  }),
+];
+
+for await (const receipt of transport.sendMany(messages, {
+  envelope: (_message, index) => ({
+    from: `bounces+${index}@bounce.example.com`,
+  }),
+})) {
+  console.log(receipt);
+}
+```
+
+A plain override applies to every message passed to
+`SmtpTransport.sendMany()`.  Invalid addresses and empty recipient lists
+produce a non-retryable failed receipt with the code `smtp.envelope-invalid`.
+@alexify/mailer rejects them before sending `MAIL FROM`, and a bad item in `sendMany()`
+does not prevent later messages from using the same connection.
+
+The effective envelope drives DSN recipient validation and SMTPUTF8
+negotiation.  Mailbox addresses written to visible From, To, Cc, and Reply-To
+headers can still require SMTPUTF8 even when the envelope overrides them.  The
+override does not alter message headers or DKIM signatures.
+
+## Internationalized addresses
+
+@alexify/mailer automatically uses the `SMTPUTF8` extension defined by [RFC 6531] when the
+effective SMTP envelope or a visible From, To, Cc, or Reply-To mailbox contains
+a non-ASCII character.  The default envelope includes the message's Bcc
+addresses.  The transport requires the server to advertise both `SMTPUTF8` and
+`8BITMIME`, then adds `BODY=8BITMIME SMTPUTF8` to `MAIL FROM`.  This supports
+UTF-8 local parts and Unicode domain labels without another configuration
+option.
+
+If either required extension is missing, @alexify/mailer returns a non-retryable failed
+receipt with the code `smtp.smtputf8-unsupported` before sending `MAIL FROM`.
+The connection remains available for a later ASCII-only message.
+
+Unicode display names and subjects do not by themselves require SMTPUTF8.
+@alexify/mailer continues to encode those values as RFC 2047 encoded words, so an address
+such as `José <jose@example.com>` follows the ordinary ASCII SMTP flow.  An
+ASCII A-label domain such as `xn--r8jz45g.xn--zckzah` likewise does not require
+SMTPUTF8, while its Unicode U-label form does.
+
+[RFC 6531]: https://www.rfc-editor.org/rfc/rfc6531
+
+## Delivery status notifications
+
+Use the `dsn` send option to request delivery status notifications through the
+SMTP `DSN` extension defined by [RFC 3461].  These settings become parameters
+on `MAIL FROM` and `RCPT TO`; they are not message headers.
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 465,
+  secure: true,
+});
+const message = createMessage({
+  from: 'sender@example.com',
+  to: ['first@example.com', 'second@example.com'],
+  subject: 'Delivery report',
+  content: { text: 'Track this delivery.' },
+});
+
+const receipt = await transport.send(message, {
+  dsn: {
+    envelopeId: 'campaign+42',
+    return: 'headers',
+    recipients: {
+      'first@example.com': {
+        notify: ['success', 'failure', 'delay'],
+        originalRecipient: 'first@example.com',
+      },
+      'second@example.com': {
+        notify: ['never'],
+      },
+    },
+  },
+});
+```
+
+`SmtpDsnOptions.envelopeId` sets `ENVID`, a non-empty identifier copied into a
+later notification.  `SmtpDsnOptions.return` sets `RET=FULL` or `RET=HDRS`
+and controls how much of a failed message may be returned.  Each key in
+`SmtpDsnOptions.recipients` must exactly match an address in the effective
+SMTP envelope.  When `SmtpTransportOptions.envelope` replaces the recipients,
+the DSN keys must match the replacement addresses rather than the message's To,
+Cc, or Bcc fields.
+
+The `SmtpDsnRecipientOptions.notify` array accepts `"success"`, `"failure"`,
+and `"delay"`.  Use `["never"]` by itself to suppress notifications for one
+recipient.  If `notify` is omitted, the server keeps its default failure and
+optional delay behavior.  `SmtpDsnRecipientOptions.originalRecipient` sets an
+`ORCPT` value with the `rfc822` address type.  On initial submission, RFC 3461
+requires this value to equal the corresponding envelope recipient.
+
+@alexify/mailer validates notification combinations, recipient keys, parameter lengths,
+and the printable US-ASCII range before sending the SMTP envelope.  It also
+applies RFC 3461 `xtext` escaping to spaces, plus signs, and equals signs in
+`ENVID` and `ORCPT`.  @alexify/mailer emits the RFC 3461 `rfc822` form and does not
+implement the UTF-8 address type or encodings defined by [RFC 6533].
+
+If any DSN parameter is requested but the server does not advertise `DSN`, the
+send returns a non-retryable failed receipt with the code
+`smtp.dsn-unsupported`; @alexify/mailer does not send `MAIL FROM`.  Invalid settings use
+the code `smtp.dsn-invalid`.  An empty `dsn` object has no effect, preserving
+the ordinary SMTP flow.
+
+The SMTP server sends a requested notification later as a separate message in
+the [RFC 3464] format.  A successful `SmtpTransport.send()` receipt confirms
+only that the server accepted the original message; it is not the later DSN.
+
+When passed to `SmtpTransport.sendMany()`, one `dsn` option applies to every
+message.  Every configured recipient key must therefore be present in each
+effective envelope.  Call `SmtpTransport.send()` separately when messages
+need different DSN settings.
+
+[RFC 3461]: https://www.rfc-editor.org/rfc/rfc3461
+[RFC 6533]: https://www.rfc-editor.org/rfc/rfc6533
+[RFC 3464]: https://www.rfc-editor.org/rfc/rfc3464
+
+## Authentication methods
+
+The SMTP transport supports multiple authentication mechanisms commonly used by
+email providers.  The most widely supported method is PLAIN authentication,
+which works with virtually all SMTP servers:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+// PLAIN authentication (most common)
+const gmailTransport = new SmtpTransport({
+  host: 'smtp.gmail.com',
+  port: 465,
+  secure: true,
+  auth: {
+    user: 'your-email@gmail.com',
+    pass: 'your-app-password',
+    method: 'plain',
+  },
+});
+
+// LOGIN authentication for older servers
+const outlookTransport = new SmtpTransport({
+  host: 'smtp-mail.outlook.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'your-email@outlook.com',
+    pass: 'your-password',
+    method: 'login',
+  },
+});
+```
+
+When using services like Gmail, you'll need to generate an app-specific password
+rather than using your regular account password.  The transport automatically
+detects server capabilities and chooses the appropriate authentication method
+if you don't specify one.
+
+> [!IMPORTANT]
+> SMTP authentication requires a secure connection (`secure: true`, or a
+> successful STARTTLS upgrade on port 587).  To protect passwords and access
+> tokens, authentication over a cleartext connection to a non-loopback host is
+> refused.  Loopback hosts remain available for local development.
+
+### OAuth 2.0 authentication
+
+Many providers—including Gmail and Outlook—now require OAuth 2.0 instead of
+passwords.  The transport supports the SASL *XOAUTH2* mechanism (the de-facto
+standard used by Google and Microsoft) and *OAUTHBEARER* ([RFC 7628]).  Instead
+of `pass`, provide an `accessToken`:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'smtp.gmail.com',
+  port: 465,
+  secure: true,
+  auth: {
+    user: 'your-email@gmail.com',
+    accessToken: 'ya29.a0Af…your-access-token',
+  },
+});
+```
+
+When `method` is omitted, the transport selects a mechanism advertised by the
+server, preferring *XOAUTH2*.  Set `method: "oauthbearer"` to force OAUTHBEARER.
+
+#### Refreshing tokens automatically
+
+Access tokens are short-lived, so a static string is rarely enough.  To refresh
+tokens transparently, pass a callback as `accessToken`.  It is invoked each time
+a new connection authenticates, which lets you delegate to an OAuth client such
+as [google-auth-library] (Gmail) or [msal-node] (Outlook):
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'smtp.gmail.com',
+  port: 465,
+  secure: true,
+  auth: {
+    user: 'your-email@gmail.com',
+    // Called for every new connection; obtain a fresh token here.
+    accessToken: () => getFreshAccessToken(),
+  },
+});
+```
+
+Alternatively, let the transport run the `refresh_token` grant itself.  Provide
+your client credentials, a refresh token, and the token endpoint; the transport
+exchanges them for an access token and caches it until shortly before it
+expires, sharing the cached token across all pooled connections:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'smtp.gmail.com',
+  port: 465,
+  secure: true,
+  auth: {
+    user: 'your-email@gmail.com',
+    clientId: '…apps.googleusercontent.com',
+    clientSecret: 'GOCSPX-…',
+    refreshToken: '1//…',
+    tokenEndpoint: 'https://oauth2.googleapis.com/token',
+  },
+});
+```
+
+Because a connection authenticates once when it is established, the callback or
+refresh runs per new connection rather than per message.
+
+[RFC 7628]: https://www.rfc-editor.org/rfc/rfc7628
+[google-auth-library]: https://github.com/googleapis/google-auth-library-nodejs
+[msal-node]: https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node
+
+## TLS and security configuration
+
+Security is crucial for email transmission, and the SMTP transport provides
+comprehensive TLS configuration options.  You can control encryption,
+certificate validation, and TLS protocol versions:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'secure-smtp.example.com',
+  port: 465,
+  secure: true,
+  auth: {
+    user: 'secure@example.com',
+    pass: 'password',
+  },
+  tls: {
+    rejectUnauthorized: true,
+    minVersion: 'TLSv1.2',
+    maxVersion: 'TLSv1.3',
+    ca: ['-----BEGIN CERTIFICATE-----\n...'],
+  },
+});
+```
+
+Setting `secure: true` establishes a TLS connection from the start,
+while `rejectUnauthorized: true` ensures certificate validation.
+You can specify custom certificate authorities, client certificates,
+and acceptable TLS versions based on your security requirements.
+
+### STARTTLS support
+
+The SMTP transport automatically supports STARTTLS, which allows upgrading
+a plain connection to an encrypted TLS connection.  When `secure` is set to
+`false` and the server advertises STARTTLS capability, the transport will
+automatically upgrade the connection before authentication.  Set `requireTls`
+to `true` when the connection must be encrypted even if the server does not
+advertise STARTTLS:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+// STARTTLS will be used automatically with port 587
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587, // Standard submission port with STARTTLS
+  secure: false, // Start with plain connection
+  requireTls: true, // Fail unless the STARTTLS upgrade succeeds
+  auth: {
+    user: 'user@example.com',
+    pass: 'password',
+  },
+});
+```
+
+This configuration is commonly used with port 587 (mail submission port)
+and is required by many modern email providers including Protonmail, Office 365,
+and others that enforce encryption via STARTTLS.  When `requireTls` is `true`,
+the transport issues `STARTTLS` even if the server does not advertise the
+capability and fails delivery if the upgrade is rejected or cannot be
+completed.  This also protects message content on connections that do not use
+SMTP authentication.  The transport follows [RFC 3207] for STARTTLS negotiation
+and automatically re-negotiates capabilities after the connection is upgraded.
+
+> [!TIP]
+> Use `secure: false` with `requireTls: true` on port 587 for mandatory
+> STARTTLS, or `secure: true` on port 465 for direct TLS connections.  Even when
+> `requireTls` is `false`, the transport refuses to authenticate to a
+> non-loopback server over cleartext.
+
+[RFC 3207]: https://datatracker.ietf.org/doc/html/rfc3207
+
+## DKIM signing
+
+DKIM (DomainKeys Identified Mail) is an email authentication method that allows
+the sender to attach a digital signature to outgoing emails.  This helps
+recipients verify that the email was actually sent from the claimed domain
+and hasn't been modified in transit, improving deliverability and reducing
+the chance of emails being marked as spam.
+
+The SMTP transport supports DKIM signing through the `SmtpConfig.dkim`
+configuration option.  DKIM signatures are generated using the standard
+Web Crypto API of Node.js.
+
+> [!NOTE]
+> The DKIM implementation follows [RFC 6376] and [RFC 8463], supporting both
+> `rsa-sha256` (most widely used) and `ed25519-sha256` (shorter keys)
+> algorithms.
+
+[RFC 6376]: https://www.rfc-editor.org/rfc/rfc6376
+[RFC 8463]: https://www.rfc-editor.org/rfc/rfc8463
+
+### Basic DKIM configuration
+
+To enable DKIM signing, provide a `dkim` configuration with your private key
+and domain information:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { readFileSync } = require('node:fs');
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'user@example.com',
+    pass: 'password',
+  },
+  dkim: {
+    signatures: [
+      {
+        signingDomain: 'example.com',
+        selector: 'mail',
+        privateKey: readFileSync('./dkim-private.pem', 'utf8'),
+      },
+    ],
+  },
+});
+```
+
+The `signingDomain` should match your email's From address domain, and the
+`selector` is used to look up the public key in DNS
+(e.g., `mail._domainkey.example.com`).
+
+### DkimSignature options
+
+Each signature in the `signatures` array can have the following options:
+
+| Option             | Type                               | Default                             | Description                           |
+| ------------------ | ---------------------------------- | ----------------------------------- | ------------------------------------- |
+| `signingDomain`    | `string`                           | (required)                          | Domain for DKIM key (d= tag)          |
+| `selector`         | `string`                           | (required)                          | DKIM selector (s= tag)                |
+| `privateKey`       | `string \| CryptoKey`              | (required)                          | Private key (PEM string or CryptoKey) |
+| `algorithm`        | `"rsa-sha256" \| "ed25519-sha256"` | `"rsa-sha256"`                      | Signing algorithm (a= tag)            |
+| `canonicalization` | `string`                           | `"relaxed/relaxed"`                 | Header/body canonicalization (c= tag) |
+| `headerFields`     | `string[]`                         | `["from", "to", "subject", "date"]` | Headers to sign (h= tag)              |
+
+### Using Ed25519 keys
+
+Ed25519 offers shorter keys than RSA while providing equivalent security.
+This is particularly useful when DNS TXT record size is a concern:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { readFileSync } = require('node:fs');
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'user@example.com',
+    pass: 'password',
+  },
+  dkim: {
+    signatures: [
+      {
+        signingDomain: 'example.com',
+        selector: 'ed25519',
+        privateKey: readFileSync('./dkim-ed25519.pem', 'utf8'),
+        algorithm: 'ed25519-sha256',
+      },
+    ],
+  },
+});
+```
+
+### Using `CryptoKey`
+
+If you already have a [`CryptoKey`] object (from Web Crypto API),
+you can pass it directly instead of a PEM string:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+// Import a private key using Web Crypto API
+const privateKey = await crypto.subtle.importKey(
+  'pkcs8',
+  new Uint8Array([/* ... key bytes ... */]),
+  { name: 'Ed25519' },
+  false,
+  ['sign'],
+);
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  dkim: {
+    signatures: [
+      {
+        signingDomain: 'example.com',
+        selector: 'mykey',
+        privateKey: privateKey, // CryptoKey object
+        algorithm: 'ed25519-sha256',
+      },
+    ],
+  },
+});
+```
+
+[`CryptoKey`]: https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey
+
+### Body processing
+
+*Since @alexify/mailer 0.6.0.*
+
+`dkim.bodyMode` selects how attachment bytes are read for signing:
+
+| Mode                   | Source reads per send | Additional attachment memory                |
+| ---------------------- | --------------------- | ------------------------------------------- |
+| No DKIM signatures     | One                   | Fixed buffers plus the largest source chunk |
+| `"buffered"` (default) | One                   | Complete MIME body                          |
+| `"streaming"`          | Two                   | Fixed buffers plus the largest source chunk |
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { readFileSync } = require('node:fs');
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 465,
+  secure: true,
+  dkim: {
+    bodyMode: 'streaming',
+    signatures: [
+      {
+        signingDomain: 'example.com',
+        selector: 'mail',
+        privateKey: readFileSync('./dkim-private.pem', 'utf8'),
+      },
+    ],
+  },
+});
+```
+
+Streaming hashes the body before `MAIL FROM`, then reopens the attachment
+sources for DATA.  All signatures share these two reads.  The extra I/O and
+hashing delay delivery and hold an authenticated connection during the first
+pass; the receiving server's idle limit still applies.  The memory bound
+excludes caller-owned data, text/HTML, headers, and runtime/socket buffers.  An
+empty `signatures` array behaves like unsigned sending.
+
+Attachment factories must reopen identical bytes on every invocation.  A changed
+second pass fails before the DATA terminator with the non-retryable
+`smtp.attachment-replay-mismatch` receipt code.  Source errors, cancellation,
+size-limit failures, and replay mismatches never trigger `send-unsigned`
+fallback. If a later signature fails cryptographically, earlier successful
+signatures remain on the message.
+
+Unsigned factory sources have no known size, so SMTP omits the optional
+`MAIL FROM SIZE` parameter and enforces the server's advertised limit while
+writing DATA.  Known byte-array and `Blob` sizes are checked before `MAIL FROM`.
+DKIM's first pass establishes the final size before submission.  A failure
+during DATA closes the connection without accepting a truncated message.
+
+`socketTimeout` measures inactivity while reading or writing attachments, not
+total transfer duration.  Nonempty source progress and completed writes reset
+the timer; an endless stream of empty chunks does not.  Cancellation is passed
+to the source, and failed DATA connections are not returned to the pool.
+
+See
+[attachment factories](/messages/attachments#working-with-binary-content)
+for file-backed sources and the custom-transport migration guide.
+
+### Multiple DKIM signatures
+
+You can add multiple DKIM signatures to a single email, which is useful when
+sending on behalf of multiple domains or when rotating keys:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { readFileSync } = require('node:fs');
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'user@example.com',
+    pass: 'password',
+  },
+  dkim: {
+    signatures: [
+      {
+        signingDomain: 'example.com',
+        selector: 'mail2024',
+        privateKey: readFileSync('./dkim-2024.pem', 'utf8'),
+      },
+      {
+        signingDomain: 'example.com',
+        selector: 'mail2025',
+        privateKey: readFileSync('./dkim-2025.pem', 'utf8'),
+      },
+    ],
+  },
+});
+```
+
+### Error handling
+
+By default, if DKIM signing fails (e.g., due to an invalid private key),
+the transport throws an error.  You can change this behavior using the
+`onSigningFailure` option:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'user@example.com',
+    pass: 'password',
+  },
+  dkim: {
+    signatures: [
+      {
+        signingDomain: 'example.com',
+        selector: 'mail',
+        privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
+      },
+    ],
+    onSigningFailure: 'send-unsigned', // or "throw" (default)
+  },
+});
+```
+
+With `onSigningFailure: "send-unsigned"`, the email will be sent without
+a DKIM signature if signing fails, rather than failing the entire send
+operation.
+
+## Bulk email sending
+
+For sending multiple emails efficiently, the SMTP transport provides
+a `SmtpTransport.sendMany()` method that reuses connections and handles errors
+gracefully.  This approach is much more efficient than
+calling `SmtpTransport.send()` multiple times:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { createMessage } = require('@alexify/mailer');
+
+await using transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'bulk@example.com',
+    pass: 'password',
+  },
+  poolSize: 5,
+});
+
+const messages = [
+  createMessage({
+    from: 'newsletter@example.com',
+    to: 'subscriber1@example.com',
+    subject: 'Weekly Newsletter #1',
+    content: { text: 'Welcome to our newsletter!' },
+  }),
+  createMessage({
+    from: 'newsletter@example.com',
+    to: 'subscriber2@example.com',
+    subject: 'Weekly Newsletter #2',
+    content: { text: 'Thank you for subscribing!' },
+  }),
+];
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Message ${receipt.messageId} sent successfully`);
+  } else {
+    console.error(`Failed to send message: ${receipt.errorMessages.join(', ')}`);
+  }
+}
+```
+
+The `SmtpTransport.sendMany()` method processes messages sequentially,
+providing individual receipts for each message.  Connection pooling ensures
+efficient resource usage, and failed messages don't prevent subsequent messages
+from being sent.  The whole iteration runs on a single connection drawn from the
+same `SmtpConfig.poolSize` budget as `SmtpTransport.send()`.
+
+## Development and testing
+
+For local development and testing, you can use development SMTP servers or
+configure the transport for testing environments.  The package supports various
+testing scenarios including mock servers:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+// Local development with Mailpit (popular SMTP testing tool)
+const devTransport = new SmtpTransport({
+  host: 'localhost',
+  port: 1025,
+  secure: false,
+  // No authentication needed for local testing
+});
+
+// Testing configuration with relaxed security
+const testTransport = new SmtpTransport({
+  host: 'test-smtp.example.com',
+  port: 587,
+  secure: false,
+  auth: {
+    user: 'test@example.com',
+    pass: 'test-password',
+  },
+  tls: {
+    rejectUnauthorized: false, // For self-signed certificates in test environments
+  },
+  connectionTimeout: 5000, // Shorter timeouts for faster test feedback
+});
+```
+
+> [!TIP]
+> [Mailpit] is an excellent development SMTP server that provides a modern
+> web interface for testing email functionality.  It acts as an SMTP server
+> that accepts all emails but doesn't deliver them, instead storing them
+> locally for inspection.  Mailpit offers features like HTML and plain text
+> email viewing, attachment downloads, search functionality, and even webhook
+> testing for email events.
+>
+> You can install Mailpit as a standalone binary, run it via Docker,
+> or use package managers like Homebrew.  The default configuration listens on
+> port 1025 for SMTP and provides a web UI on port 8025, making it perfect for
+> local development workflows where you need to verify email content and
+> formatting without sending real emails.
+
+[Mailpit]: https://mailpit.axllent.org/
+
+## Sending raw MIME
+
+Use [MIME composition](/messages/mime) to create raw bytes from an @alexify/mailer
+message without opening a transport connection.
+
+`SmtpTransport` implements `RawTransport` for already serialized messages,
+including signed or encrypted MIME. Provide delivery addresses separately:
+
+```js
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const transport = new SmtpTransport({ host: 'localhost', port: 1025 });
+try {
+  await transport.sendRaw({
+    envelope: { from: 'sender@example.com', to: ['recipient@example.net'] },
+    content: new TextEncoder().encode('Subject: Hello\r\n\r\nHello!\r\n'),
+    encoding: '7bit',
+  });
+} finally {
+  await transport.closeAllConnections();
+}
+```
+
+Raw sources accept bytes, promised bytes, Blob, or replayable attachment-style
+factories. With `encoding` specified, the source is read once; otherwise it is
+analyzed and then read again. Every reader must produce identical bytes.
+Automatic analysis requires SMTPUTF8 for any non-ASCII byte. Specify `8bit`
+when all MIME headers are ASCII and only the body needs 8BITMIME. @alexify/mailer checks
+only top-level headers; the caller must ensure nested MIME headers are ASCII.
+Use `utf8` or omit `encoding` if unsure. Both `utf8` and internationalized
+envelope addresses require SMTPUTF8 and 8BITMIME.
+Unsupported capabilities produce a failed receipt before MAIL FROM.
+
+The content must already have CRLF line endings including the final CRLF,
+nonempty headers, no NUL, and no line longer than 998 bytes excluding CRLF.
+SMTP delivery adds only dot-stuffing and protocol framing. It does not compose
+headers, remove Bcc, add Date or Message-ID, or run configured DKIM signing.
+The caller is responsible for the MIME structure and any existing signatures.
+
+`sendRaw()` accepts `dsn` and `signal` options. Its envelope cannot be
+overridden through options; use `envelope.from: null` for a null reverse-path.
+Receipts include partial recipient rejections just like `send()`. The returned
+message ID identifies the SMTP transaction, not necessarily the MIME Message-ID.
+
+Known sizes exclude dot-stuffing and protocol framing. A factory with an
+explicit encoding starts reading after the server accepts DATA and does not
+need a preliminary size pass. Inactivity limits and cancellation cover reading
+and writing; a failure during DATA closes that connection without completing
+the message. Raw delivery is not retried automatically.
+
+## Verifying the configuration
+
+Call `SmtpTransport.verify()` to check your SMTP settings without sending
+an email. It opens a fresh connection, checks the server greeting and
+EHLO/HELO negotiation, applies the same TLS policy as sending, and performs
+any configured authentication, including OAuth 2.0. Relay configurations
+without authentication are supported.
+
+```js
+const { SmtpAuthError, SmtpResponseError, SmtpTransport } = require('@alexify/mailer/smtp');
+
+await using transport = new SmtpTransport({
+  host: 'smtp.example.com',
+  port: 587,
+  requireTls: true,
+});
+
+try {
+  await transport.verify({ signal: AbortSignal.timeout(10_000) });
+} catch (error) {
+  if (error instanceof SmtpAuthError) {
+    console.error('Check the SMTP credentials.');
+  } else if (error instanceof SmtpResponseError) {
+    console.error(error.command, error.code, error.response);
+  } else {
+    throw error;
+  }
+}
+```
+
+Unlike sending, verification rejects on failure and does not return a receipt.
+`SmtpAuthResponseError` extends `SmtpAuthError` with the SMTP reply's `code`,
+`command`, and `response`. Network, TLS, and timeout failures may use native
+error types. Cancellation preserves the caller's abort reason.
+
+Verification shares the transport's `poolSize` limit and shutdown barrier.
+It waits when all slots are busy; when necessary, it replaces one idle
+connection to make room for a fresh handshake. Its connection is closed
+afterward, including on failure or cancellation, and is never pooled.
+The existing connection and socket timeouts apply; use an abort signal to
+bound the whole call, including waiting for capacity.
+
+Success confirms setup at verification time. It does not guarantee that a
+particular sender, recipient, or message will be accepted, or that delivery
+will succeed. No envelope or message data is sent. Verification is an
+[optional transport capability](/transports/custom#verifying-transport-configuration);
+wrappers do not automatically expose it.

From 8e02f5db5e66d86071f5f008e82edf3b48c1c7b3 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 23:28:56 +0300
Subject: [PATCH 020/158] refactor: remove the createMailer placeholder

createMailer only threw "createMailer is not implemented yet": it held the
name of the root entry while nothing else was exported. The root entry now
exports the ported message model and transport contract, so the placeholder,
its Mailer type and tests go. It was never released, so nothing depends on
it; the reliability layer gets its own API when it is designed.

The bundle test of the root entry now builds a message through the bundle,
and the README, the guide, the API page, llms.txt, CHANGELOG and CLAUDE.md
no longer mention the placeholder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                  |  2 --
 CLAUDE.md                     | 15 +++++++--------
 README.md                     |  2 +-
 docs/api/exports.md           | 10 +---------
 docs/guide/getting-started.md |  3 +--
 docs/guide/why.md             |  4 ++--
 docs/public/llms.txt          |  4 ++--
 index.d.ts                    | 22 ++--------------------
 src/index.js                  |  4 +---
 src/mailer.js                 | 10 ----------
 tests/types/index.test-d.ts   | 10 ----------
 tests/unit/bundle.test.js     |  8 +++++---
 tests/unit/mailer.test.js     |  7 -------
 13 files changed, 22 insertions(+), 79 deletions(-)
 delete mode 100644 src/mailer.js
 delete mode 100644 tests/unit/mailer.test.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 41489e1..b3c56eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,8 +35,6 @@ listed in CLAUDE.md, to be fixed one by one.
 - **Package scaffold** set up like the other Alexis libraries: plain CommonJS with no build step,
   a hand-written `index.d.ts`, a closed `exports` map, Node.js 22 or newer, and zero runtime
   dependencies.
-- **`createMailer` placeholder.** It throws until the mailer is implemented; its signature is
-  provisional.
 - **Tooling:** pnpm, oxlint and oxfmt, `node:test` suites with c8 coverage gates, tsd type tests,
   an export-parity check between the runtime and `index.d.ts`, a check that `src/` requires only
   Node builtins, bundle tests through esbuild, a bundle-size budget (`pnpm size`) and a
diff --git a/CLAUDE.md b/CLAUDE.md
index f2d41ef..b2885ad 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,10 +17,10 @@ Nodemailer, emailjs or Upyo, made of two parts:
 
 It has zero runtime dependencies and runs on Node.js ≥ 22 only (no browser entry).
 
-**Status: the transport is being ported, the mailer designed.** The root entry exports the message
-model and the transport contract of upyo; the subpaths land one by one. `createMailer`, the entry of
-the reliability layer, is a placeholder that throws (`src/mailer.js`); its signature in
-`index.d.ts` is provisional. The direction is in "Roadmap" below.
+**Status: the transport is ported, the reliability layer is being designed.** The root entry
+exports the message model and the transport contract of upyo, each transport and decorator is a
+subpath. The reliability layer (queue, audit log, delivery events) has no API yet; its direction
+is in "Roadmap" below.
 
 It is maintained by Alexis Technologies and set up like the sibling libraries
 `@alexify/metaschema` and `@alexify/protoarray` (the scaffold follows protoarray's
@@ -57,9 +57,9 @@ is no build step.
 - `src/` is plain CommonJS (`require`/`module.exports`) and ships as is. No TypeScript syntax, no
   `import`/`export`, no `'use strict'`.
 - The root `index.js` is a one-line shim over `src/index.js`.
-- `src/index.js` lists every export **by name** (`module.exports = { createMailer }`), never by
-  spreading module objects. cjs-module-lexer only sees named keys, and ESM
-  `import { createMailer } from '@alexify/mailer'` depends on it.
+- `src/index.js` lists every export **by name** (`module.exports = { createMessage, … }`), never
+  by spreading module objects. cjs-module-lexer only sees named keys, and ESM
+  `import { createMessage } from '@alexify/mailer'` depends on it.
 - `index.d.ts` is the only source of the public types, written by hand. A public API change touches
   `src/index.js`, `index.d.ts` and a test together. `tests/unit/export-parity.test.js` compares
   runtime exports with the declared value exports and imports every name from ESM.
@@ -156,7 +156,6 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 index.js  index.d.ts   root entry shim + hand-written types
 src/
   index.js          public barrel (explicit named exports)
-  mailer.js         createMailer placeholder
   version.js        the package name and version (OpenTelemetry scope), kept equal to package.json
   <subpath>/        one directory per subpath: index.js + index.d.ts + its modules
 tests/
diff --git a/README.md b/README.md
index 27b19e9..106191f 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ idempotency. Zero runtime dependencies.
 > 🚧 **Work in progress.** The transport layer is here, ported from
 > [upyo](https://github.com/dahlia/upyo) 0.7.0: messages, MIME and DKIM, SMTP, Amazon SES and seven
 > more HTTP providers, JMAP, and the pool, retry, OpenTelemetry, logger and mock transports. The
-> reliability layer is being designed: `createMailer` is exported as a placeholder that throws.
+> reliability layer (queue, audit log, delivery events) is being designed.
 
 ### 📖 [Read the documentation →](https://mailerat.vercel.app/)
 
diff --git a/docs/api/exports.md b/docs/api/exports.md
index f277ef1..0686cd5 100644
--- a/docs/api/exports.md
+++ b/docs/api/exports.md
@@ -16,8 +16,7 @@ import { SmtpTransport } from '@alexify/mailer/smtp';
 
 ## `@alexify/mailer`
 
-The message model and the transport contract, ported from `@upyo/core`, and the
-mailer.
+The message model and the transport contract, ported from `@upyo/core`.
 
 - **Messages:** `createMessage`, and the `Message`, `MessageConstructor`,
   `MessageContent`, `Address`, `Attachment` and `Priority` types; `parseAddress`,
@@ -37,13 +36,6 @@ mailer.
   `parseRetryAfter`.
 - **Raw messages:** the `RawMessage` type; `createRawMessagePlan`,
   `iterateRawMessage`, `analyzeRawMessage`, `RawMessageValidationError`.
-- **`createMailer(options)`:** the mailer of the reliability layer.
-
-::: warning Work in progress
-`createMailer` is a placeholder: it throws `createMailer is not implemented yet`
-until the mailer is implemented, and its signature will change with the design of
-the queue and the audit log.
-:::
 
 ## Subpaths
 
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 56c80c5..a8bd05d 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -3,8 +3,7 @@
 ::: warning Work in progress
 The transport layer, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0, is
 here: messages, SMTP, eight HTTP providers, JMAP and the decorators. The reliability
-layer is still being designed: `createMailer` is a placeholder that throws
-`createMailer is not implemented yet`.
+layer (queue, audit log, delivery events) is still being designed.
 :::
 
 ## Installation
diff --git a/docs/guide/why.md b/docs/guide/why.md
index f2c841e..7e2baea 100644
--- a/docs/guide/why.md
+++ b/docs/guide/why.md
@@ -1,8 +1,8 @@
 # Why @alexify/mailer?
 
 ::: warning Work in progress
-@alexify/mailer is being designed. The direction below is settled; the API is not. `createMailer`
-is exported today as a placeholder that throws.
+The transport layer is here, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0. The
+reliability layer is being designed: the direction below is settled, its API is not.
 :::
 
 ## Two parts
diff --git a/docs/public/llms.txt b/docs/public/llms.txt
index a9024e7..1ba510e 100644
--- a/docs/public/llms.txt
+++ b/docs/public/llms.txt
@@ -7,13 +7,13 @@
 
 Key facts:
 - Status: work in progress. The transport layer is ported from upyo 0.7.0 (MIT); the
-  reliability layer is being designed, and `createMailer` is exported as a placeholder that throws
+  reliability layer (queue, audit log, delivery events) is being designed
 - Package (npm): `@alexify/mailer`, installed with `npm install @alexify/mailer`
 - Node.js >= 22 only; CommonJS with ESM named-import interop; hand-written d.ts per entry
 - Zero runtime dependencies: the transports are built on `node:*` modules and `fetch`; the
   OpenTelemetry providers, the logger and the drivers of a queue or a database are passed in
 - Root entry `@alexify/mailer`: `createMessage`, the `Transport` contract, receipts,
-  attachments, calendar parts, Message-ID helpers, `createMailer(options)`
+  attachments, calendar parts, Message-ID helpers
 - Subpaths: `/mime` (MIME, DKIM), `/smtp`, `/jmap`, `/ses`, `/resend`, `/sendgrid`, `/mailgun`,
   `/mailtrap`, `/maileroo`, `/lettermint`, `/plunk`, `/pool`, `/retry`, `/otel`, `/logger`, `/mock`
 - Guide: https://mailerat.vercel.app/guide/getting-started
diff --git a/index.d.ts b/index.d.ts
index 9f5ce4f..be7feec 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -1,5 +1,5 @@
-// The types of @alexify/mailer, written by hand: the message model and the
-// transport contract (src/core/) are ported from @upyo/core 0.7.0
+// The types of the root entry of @alexify/mailer, written by hand: the message
+// model and the transport contract (src/core/), ported from @upyo/core 0.7.0
 // (https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee).
 
 /**
@@ -1208,21 +1208,3 @@ export declare function analyzeRawMessage(
   signal?: AbortSignal,
   onProgress?: (analysis: RawMessageAnalysis) => void,
 ): Promise<RawMessageAnalysis>;
-
-/**
- * A mailer: sends messages through a transport, with the reliability layer
- * (queue, audit log, delivery events) on top.
- *
- * Provisional: the shape is defined with the Phase 0 contracts.
- */
-export interface Mailer {
-  send(message: object): Promise<unknown>;
-}
-
-/**
- * Creates a mailer.
- *
- * Placeholder: throws until the mailer is implemented. The signature is
- * provisional.
- */
-export declare function createMailer(options: object): Mailer;
diff --git a/src/index.js b/src/index.js
index 9f3b503..5248e7e 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,5 +1,5 @@
 // The root entry: the message model and the transport contract ported from
-// @upyo/core 0.7.0 (src/core/), in upstream's order, and the mailer.
+// @upyo/core 0.7.0 (src/core/), in upstream's order.
 const { formatAddress, parseAddress, isEmailAddress } = require('./core/address.js');
 const { combineSignals } = require('./core/abort-signal.js');
 const {
@@ -34,7 +34,6 @@ const {
   iterateRawMessage,
   analyzeRawMessage,
 } = require('./core/raw-message.js');
-const { createMailer } = require('./mailer.js');
 
 module.exports = {
   formatAddress,
@@ -64,5 +63,4 @@ module.exports = {
   createRawMessagePlan,
   iterateRawMessage,
   analyzeRawMessage,
-  createMailer,
 };
diff --git a/src/mailer.js b/src/mailer.js
deleted file mode 100644
index 3af82e4..0000000
--- a/src/mailer.js
+++ /dev/null
@@ -1,10 +0,0 @@
-// Placeholder until the Phase 0 contracts (Message, Transport, QueueDriver,
-// AuditSink) are designed: the package, its typings, tests, bundle checks and
-// docs are wired end to end around this name, and its signature will change
-// with the real API.
-
-const createMailer = (options) => {
-  throw new Error('createMailer is not implemented yet');
-};
-
-module.exports = { createMailer };
diff --git a/tests/types/index.test-d.ts b/tests/types/index.test-d.ts
index d636af5..4bae67e 100644
--- a/tests/types/index.test-d.ts
+++ b/tests/types/index.test-d.ts
@@ -1,7 +1,6 @@
 import { expectAssignable, expectError, expectType } from 'tsd';
 import {
   createFailedReceipt,
-  createMailer,
   createMessage,
   createReceiptError,
   isRawTransport,
@@ -9,7 +8,6 @@ import {
   parseAddress,
   RawMessageValidationError,
   type Address,
-  type Mailer,
   type Message,
   type RawTransport,
   type Receipt,
@@ -18,14 +16,6 @@ import {
   type VerifiableTransport,
 } from '../../index.js';
 
-const mailer = createMailer({});
-expectType<Mailer>(mailer);
-expectType<Promise<unknown>>(mailer.send({ to: 'alex@example.com', subject: 'Hello' }));
-
-expectError(createMailer());
-expectError(createMailer('smtp://localhost'));
-expectError(mailer.send('Hello'));
-
 // The message model.
 const message = createMessage({
   from: 'Alex <alex@example.com>',
diff --git a/tests/unit/bundle.test.js b/tests/unit/bundle.test.js
index 677f2b4..46627ff 100644
--- a/tests/unit/bundle.test.js
+++ b/tests/unit/bundle.test.js
@@ -29,9 +29,11 @@ const loadNode = async (entry, minify) => {
 for (const minify of [false, true]) {
   const label = minify ? 'minified' : 'unminified';
   test(`Bundle: node entry, ${label}`, async () => {
-    const { createMailer } = await loadNode('index.js', minify);
-    assert.strictEqual(typeof createMailer, 'function');
-    assert.throws(() => createMailer({}), { message: 'createMailer is not implemented yet' });
+    const { createMessage } = await loadNode('index.js', minify);
+    const fields = { to: 'bob@example.com', subject: 'Hello', content: { text: 'Hi' } };
+    const message = createMessage({ ...fields, from: 'Alex <alex@example.com>' });
+    assert.deepStrictEqual(message.sender, { name: 'Alex', address: 'alex@example.com' });
+    assert.throws(() => createMessage({ ...fields, from: 'not an address' }), TypeError);
   });
 
   // Every entry of the exports map bundles on its own and keeps the names and
diff --git a/tests/unit/mailer.test.js b/tests/unit/mailer.test.js
deleted file mode 100644
index bf288a9..0000000
--- a/tests/unit/mailer.test.js
+++ /dev/null
@@ -1,7 +0,0 @@
-const { test } = require('node:test');
-const assert = require('node:assert');
-const { createMailer } = require('../../index.js');
-
-test('Mailer: createMailer is a placeholder until the mailer is implemented', () => {
-  assert.throws(() => createMailer({}), { message: 'createMailer is not implemented yet' });
-});

From c8aab7b150a0912997ead70f478c9ce5bf52ae92 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Wed, 14 Oct 2026 23:35:52 +0300
Subject: [PATCH 021/158] docs: show the ported transport layer on the home
 page

The home page still described a library being designed, with tiles of what
it would do and a warning that the package did none of it yet. The tiles
now show what is here: the SMTP client, MIME and DKIM, the eight HTTP
providers and JMAP, the decorators and the zero-dependency design, with one
tile for the reliability layer as the next step. The hero tagline follows,
a Transports action replaces the Why link (the last tile leads there), the
warning becomes a status note crediting upyo, and a short example shows a
message sent through SMTP with retries.

The why page no longer says the transport starts with SES alone, signed on
node:crypto, or that the library starts with few providers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guide/why.md | 16 +++++----
 docs/index.md     | 82 +++++++++++++++++++++++++++++++++++------------
 2 files changed, 70 insertions(+), 28 deletions(-)

diff --git a/docs/guide/why.md b/docs/guide/why.md
index 7e2baea..6eb7016 100644
--- a/docs/guide/why.md
+++ b/docs/guide/why.md
@@ -10,11 +10,13 @@ reliability layer is being designed: the direction below is settled, its API is
 @alexify/mailer is an email library of its own, in the place of Nodemailer, emailjs or Upyo, made
 of two parts:
 
-1. **The transport.** An SMTP client, a MIME builder and DKIM signing written for this library,
-   and HTTP providers on `fetch`, starting with Amazon SES v2 (signed with SigV4 on
-   `node:crypto`, without the AWS SDK).
-2. **A reliability layer on top of it.** A persistent queue and outbox, an append-only audit log,
-   one model of delivery events, suppression, idempotency and failover between providers.
+1. **The transport,** here today, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0: an
+   SMTP client, a MIME builder and DKIM signing, Amazon SES v2 (signed with SigV4, without the AWS
+   SDK) and seven more HTTP providers on `fetch`, JMAP, and decorators for failover, retries,
+   telemetry and logs.
+2. **A reliability layer on top of it,** being designed. A persistent queue and outbox, an
+   append-only audit log, one model of delivery events, suppression, idempotency and failover
+   between providers.
 
 ## The gap it fills
 
@@ -26,8 +28,8 @@ That work is left to every application: a job that dies between "submitted" and
 retry after a timeout that sends the same password reset twice, a bounce that nobody records.
 
 The breadth of providers is not where the gap is. Each provider added is one more webhook format
-and one more API that drifts, so the library starts with few providers and puts its effort into
-what happens to a message after `send()`.
+and one more API that drifts, so beyond the eight that came with the port, a new provider waits
+for a user who needs it, and the effort goes into what happens to a message after `send()`.
 
 ## Design
 
diff --git a/docs/index.md b/docs/index.md
index ba3c0c7..bd2afa2 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,7 +7,7 @@ titleTemplate: Email for Node.js, with a reliability layer
 hero:
   name: mailer
   text: Email for Node.js, with a reliability layer
-  tagline: Its own SMTP client, MIME builder, DKIM and HTTP providers, and on top of them what the other libraries leave to you — a persistent queue, an audit log, delivery events, suppression and idempotency. Zero dependencies.
+  tagline: SMTP, MIME and DKIM of its own, eight HTTP providers and JMAP, with failover, retries and telemetry around them. Zero dependencies. Next on top, what other libraries leave to you, a persistent queue, an audit log and delivery events.
   image:
     src: /logo-mark.svg
     alt: mailer
@@ -16,36 +16,76 @@ hero:
       text: Get Started
       link: /guide/getting-started
     - theme: alt
-      text: Why mailer?
-      link: /guide/why
+      text: Transports
+      link: /guide/getting-started#choosing-a-transport
     - theme: alt
       text: Compared with alternatives
       link: /guide/comparison
 
 features:
   - icon: ✉️
-    title: Its own transport
-    details: "An SMTP client, a MIME builder and DKIM signing of its own, and HTTP providers on fetch, starting with Amazon SES v2. Secure defaults: TLS is verified and AUTH never goes over plain text."
-    link: /guide/why
-    linkText: The transport
-  - icon: 🧾
-    title: A reliability layer
-    details: "A persistent queue and outbox, an append-only audit log and one model of delivery events. None of the fourteen libraries in the comparison has the three."
-    link: /guide/comparison
-    linkText: The comparison
-  - icon: 🔁
-    title: Sent once, or known to be unknown
-    details: "Idempotency keys with deduplication, errors classified as permanent or temporary, and a delivery_unknown state instead of a blind retry when a provider has no idempotency key."
-    link: /guide/why
-    linkText: The design
+    title: SMTP of its own
+    details: "Pooling, STARTTLS, AUTH PLAIN, LOGIN and OAuth 2.0, PIPELINING, SIZE, DSN and SMTPUTF8, on node:net and node:tls. Certificates are verified, and credentials never cross plain text."
+    link: /transports/smtp
+    linkText: SMTP transport
+  - icon: 🔏
+    title: MIME and DKIM
+    details: "createMessage validates addresses, headers and attachments. The MIME keeps the Bcc out of the headers, carries inline images and iCalendar invitations, and is DKIM-signed with RSA or Ed25519."
+    link: /messages/compose
+    linkText: Composing messages
+  - icon: 🌐
+    title: Eight HTTP providers and JMAP
+    details: "Amazon SES v2, Resend, SendGrid, Mailgun, Mailtrap, Maileroo, Lettermint and Plunk on fetch, and JMAP. One Transport contract and one Receipt with classified errors: swap the provider, keep the messages."
+    link: /guide/getting-started#choosing-a-transport
+    linkText: Choose a transport
+  - icon: 🧩
+    title: Decorators around any transport
+    details: "A pool with strategies and failover, retries with backoff, jitter and Retry-After, OpenTelemetry spans and metrics, logs through your pino logger, and a mock for tests."
+    link: /transports/pool
+    linkText: Pool, retry, telemetry
   - icon: 🪶
     title: Zero dependencies
-    details: "Built on node:* modules and fetch. A queue or a database driver (BullMQ, MongoDB) is passed in by your application, never installed by the package. Node.js 22+, CommonJS with ESM named imports and hand-written typings."
+    details: "Built on node:* and fetch. The OpenTelemetry providers, the logger and, later, the queue driver come from your application. Node.js 22+, CommonJS with ESM imports, hand-written types."
     link: /api/exports
     linkText: API
+  - icon: 🧾
+    title: "Next: the reliability layer"
+    details: "In design: a persistent queue and outbox, an append-only audit log, one model of delivery events, suppression and idempotency. None of the fourteen libraries compared has the three."
+    link: /guide/why
+    linkText: The plan
 ---
 
-::: warning Work in progress
-The library is being designed: the features above are what it is built to do, not what the
-published package does yet. See [Why @alexify/mailer?](/guide/why) for the plan.
+::: tip Status
+The transport layer is here, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0 (MIT): one
+package, with a subpath per transport and decorator. The reliability layer is being designed; see
+[Why @alexify/mailer?](/guide/why) for the plan.
 :::
+
+## A quick look
+
+```js
+const { createMessage } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { createRetryTransport } = require('@alexify/mailer/retry');
+
+const transport = createRetryTransport(
+  new SmtpTransport({
+    host: 'smtp.example.com',
+    port: 587,
+    auth: { user: 'user@example.com', pass: 'secret' },
+  }),
+  { maxAttempts: 3 },
+);
+
+const receipt = await transport.send(
+  createMessage({
+    from: 'Alex <alex@example.com>',
+    to: 'bob@example.net',
+    subject: 'Your invoice',
+    content: { text: 'Attached.', html: '<p>Attached.</p>' },
+  }),
+);
+
+if (receipt.successful) console.log(receipt.messageId);
+else console.error(receipt.errorMessages, receipt.retryable);
+```

From ecf4c231c4c7456f424f45d3e028923970969abd Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Thu, 15 Oct 2026 23:53:08 +0300
Subject: [PATCH 022/158] fix(core): hold the domain of an address to host-name
 characters

isEmailAddress toggled quotes over the whole address and validated the
domain with URL.canParse alone, which reads "@", ":", "/", "?" and "#" as
other parts of a URL. A quote in the domain hid a second "@" from the scan,
so `user@example.com> NOTIFY=NEVER ORCPT=rfc822;a"@x.com` passed createMessage
and the SMTP envelope and was written as
`RCPT TO:<user@example.com> NOTIFY=NEVER ...>`, injecting ESMTP parameters.

Only a quoted local part may now hold an "@", the domain is held to letters,
digits, "-", "." and non-ASCII characters with no empty label, and a domain
literal must be an IPv4 address or an IPv6 one (tagged "IPv6:" or not, no
zone index). As defense in depth, ./smtp re-checks each path right before it
writes MAIL FROM and RCPT TO (checkSmtpPath).

An upstream bug, recorded as the first of the "fixed after the port" list in
CLAUDE.md. The ported test that delivered a sender with a port now expects
the envelope to refuse it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  | 11 +++
 CLAUDE.md                                     |  8 ++
 src/core/address.js                           | 85 ++++++++++++-------
 src/mime/message.js                           |  9 +-
 src/smtp/envelope.js                          | 31 ++++++-
 src/smtp/smtp-connection.js                   |  3 +
 tests/unit/core.test.js                       | 47 ++++++++++
 ...smtp-message-converter.integration.test.js | 19 +++--
 tests/unit/smtp.test.js                       | 39 +++++++++
 9 files changed, 208 insertions(+), 44 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b3c56eb..ead6b41 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -46,4 +46,15 @@ listed in CLAUDE.md, to be fixed one by one.
   [mailerat.vercel.app](https://mailerat.vercel.app/), with a comparison of 14 Node.js email
   libraries generated from `docs/comparison.json`.
 
+### Security
+
+- **An address can no longer end the path of an SMTP command** (an upstream bug). A quote in the
+  domain hid a second `@` from the scan of `isEmailAddress`, and `URL.canParse` accepted the rest
+  as userinfo, so `user@example.com> NOTIFY=NEVER ORCPT=rfc822;a"@x.com` passed and became
+  `RCPT TO:<user@example.com> NOTIFY=NEVER …>`. A domain is now held to host-name characters
+  (letters, digits, `-`, `.` and non-ASCII), so a port, path, query, fragment, comma, space,
+  underscore or an empty label is refused too; a domain literal is an IPv4 address or an IPv6
+  one, with or without the `IPv6:` tag. `./smtp` checks every path again right before it writes
+  `MAIL FROM` and `RCPT TO`.
+
 [unreleased]: https://github.com/Alexis-Technologies/mailer/commits/main
diff --git a/CLAUDE.md b/CLAUDE.md
index b2885ad..8a73256 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -150,6 +150,14 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
     response, so an authentication rejection becomes a retryable network error. Node 22 returns
     the 401. The tests of it are `todo` on Node 24 until the fix.
 
+**Upstream bugs found and fixed after the port** (each in its own `fix:` commit, with a test that
+fails without it; ported tests that pinned the old behavior say "Changed after the port"):
+
+15. core: `isEmailAddress` toggled quotes over the whole address and checked the domain with
+    `URL.canParse` alone, so a domain could carry `>`, spaces, a port or userinfo and inject
+    ESMTP parameters into `RCPT TO`. The domain is held to host-name characters, a domain
+    literal to an IP address, and `./smtp` re-checks each path (`checkSmtpPath`).
+
 ## Repository layout
 
 ```
diff --git a/src/core/address.js b/src/core/address.js
index 5d04235..63309f9 100644
--- a/src/core/address.js
+++ b/src/core/address.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/core/src/address.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const net = require('node:net');
+
 /**
  * Formats an address object into a string representation.  This function is
  * an inverse of the {@link parseAddress} function.
@@ -110,29 +112,11 @@ const isValidEmail = (email) => {
     return false;
   }
 
-  // Find the @ symbol that separates local and domain parts
-  // If the local part is quoted, we need to find the @ after the closing quote
-  let atIndex = -1;
-  let inQuotes = false;
-  let escaped = false;
-
-  for (let i = 0; i < email.length; i++) {
-    const char = email[i];
-
-    if (char === '"' && !escaped) {
-      inQuotes = !inQuotes;
-    } else if (char === '@' && !inQuotes) {
-      if (atIndex === -1) {
-        atIndex = i;
-      } else {
-        // Multiple @ symbols outside quotes
-        return false;
-      }
-    }
-    escaped = char === '\\' && !escaped;
-  }
-
-  if (atIndex === -1) {
+  // Only a quoted local part may hold an @, and only at its start may a quote
+  // open; the domain holds none.  Toggling on every quote let a quote in the
+  // domain hide a second @ from the scan.
+  const atIndex = findLocalPartEnd(email);
+  if (atIndex < 1 || email.indexOf('@', atIndex + 1) !== -1) {
     return false;
   }
 
@@ -142,6 +126,19 @@ const isValidEmail = (email) => {
   return isValidLocalPart(localPart) && isValidDomainPart(domainPart);
 };
 
+const findLocalPartEnd = (email) => {
+  if (email.charCodeAt(0) !== 0x22) return email.indexOf('@');
+  for (let i = 1; i < email.length; i++) {
+    const code = email.charCodeAt(i);
+    if (code === 0x5c) {
+      i++;
+    } else if (code === 0x22) {
+      return email.charCodeAt(i + 1) === 0x40 ? i + 1 : -1;
+    }
+  }
+  return -1;
+};
+
 const isValidLocalPart = (localPart) => {
   if (!localPart || localPart.length === 0 || new TextEncoder().encode(localPart).byteLength > 64) {
     return false;
@@ -205,13 +202,17 @@ const isValidDomainPart = (domainPart) => {
 
   // Check for domain literal format [IP]
   if (domainPart.startsWith('[') && domainPart.endsWith(']')) {
-    const literal = domainPart.slice(1, -1);
-    // Use URL.canParse() for IP validation
-    try {
-      return URL.canParse(`http://${literal}/`);
-    } catch {
-      return false;
-    }
+    return isValidAddressLiteral(domainPart.slice(1, -1));
+  }
+
+  // URL.canParse() reads "@", ":", "/", "?" and "#" as delimiters of other
+  // parts of a URL, so on its own it accepts a domain that carries a port, a
+  // path or userinfo, such as "example.com> NOTIFY=NEVER …@x.com", which
+  // would end the path of an SMTP command early.  A host name has letters,
+  // digits, hyphens and dots, plus the non-ASCII characters of an
+  // internationalized name.
+  if (!hasHostNameCharacters(domainPart)) {
+    return false;
   }
 
   // For regular domain format, use URL.canParse() for validation
@@ -223,6 +224,30 @@ const isValidDomainPart = (domainPart) => {
   }
 };
 
+const hasHostNameCharacters = (domainPart) => {
+  let previous = 0x2e;
+  for (let i = 0; i < domainPart.length; i++) {
+    const code = domainPart.charCodeAt(i);
+    if (code === 0x2e && previous === 0x2e) return false;
+    const isLetterOrDigit =
+      (code >= 0x61 && code <= 0x7a) ||
+      (code >= 0x41 && code <= 0x5a) ||
+      (code >= 0x30 && code <= 0x39);
+    if (!isLetterOrDigit && code !== 0x2d && code !== 0x2e && code < 0x80) return false;
+    previous = code;
+  }
+  return true;
+};
+
+// RFC 5321 §4.1.3: an IPv4 address, or an IPv6 one after the "IPv6:" tag
+// (taken without the tag too, as written in practice).  A zone index has no
+// place in an address.
+const isValidAddressLiteral = (literal) => {
+  if (literal.includes('%')) return false;
+  if (literal.slice(0, 5).toLowerCase() === 'ipv6:') return net.isIPv6(literal.slice(5));
+  return net.isIPv4(literal) || net.isIPv6(literal);
+};
+
 /**
  * Type guard function that checks if a given value is a valid email address.
  *
diff --git a/src/mime/message.js b/src/mime/message.js
index 5d0e698..4c72721 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -427,11 +427,10 @@ const resolveMessageId = (message) => {
 /**
  * Generates an identifier rooted in the sender's domain.
  *
- * `parseAddress()` validates a domain with `URL`, which accepts spellings the
- * identifier grammar does not, such as the trailing dot of a fully qualified
- * name or a host carrying a port.  A sender written that way used to be
- * delivered, so an unusable domain falls back to `localhost` rather than
- * failing the send.  Uniqueness holds either way: the left half is a UUID.
+ * `parseAddress()` accepts spellings the identifier grammar does not, such as
+ * the trailing dot of a fully qualified name, which is dropped here.  A domain
+ * the grammar still refuses falls back to `localhost` rather than failing the
+ * send.  Uniqueness holds either way: the left half is a UUID.
  *
  * @param address The sender's address.
  * @returns A bare message identifier.
diff --git a/src/smtp/envelope.js b/src/smtp/envelope.js
index 2ca2c0e..66276f8 100644
--- a/src/smtp/envelope.js
+++ b/src/smtp/envelope.js
@@ -69,4 +69,33 @@ const resolveSmtpEnvelope = (message, override) => {
   return { from, to: [...recipients] };
 };
 
-module.exports = { SmtpEnvelopeValidationError, resolveSmtpEnvelope };
+/**
+ * Checks a path right before it goes between the angle brackets of `MAIL FROM`
+ * or `RCPT TO`, whatever validated it before: outside a quoted local part it
+ * may hold no "<", ">", space or control character, any of which would end
+ * the path and let the rest of the address pass as ESMTP parameters.
+ *
+ * @param path The reverse- or forward-path, `''` for the null sender.
+ * @throws {SmtpEnvelopeValidationError} If the path could end the command's
+ * path early.
+ * @internal
+ */
+const checkSmtpPath = (path) => {
+  let isQuoted = path.charCodeAt(0) === 0x22;
+  let isEscaped = false;
+  for (let i = isQuoted ? 1 : 0; i < path.length; i++) {
+    const code = path.charCodeAt(i);
+    const isControl = code < 0x20 || code === 0x7f;
+    const endsPath = !isQuoted && (code === 0x20 || code === 0x3c || code === 0x3e);
+    if (isControl || endsPath) {
+      throw new SmtpEnvelopeValidationError(
+        'SMTP envelope address must not contain "<", ">", a space or a control character.',
+      );
+    }
+    if (isEscaped) isEscaped = false;
+    else if (isQuoted && code === 0x5c) isEscaped = true;
+    else if (isQuoted && code === 0x22) isQuoted = false;
+  }
+};
+
+module.exports = { SmtpEnvelopeValidationError, checkSmtpPath, resolveSmtpEnvelope };
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index b6278b2..e9e3dd1 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -7,6 +7,7 @@ const { Socket } = require('node:net');
 const { connect: tlsConnect, TLSSocket } = require('node:tls');
 const { createSmtpConfig } = require('./config.js');
 const { SmtpDsnUnsupportedError } = require('./delivery-status.js');
+const { checkSmtpPath } = require('./envelope.js');
 const {
   formatOauthbearer,
   formatXoauth2,
@@ -892,6 +893,8 @@ class SmtpConnection {
 
   async sendPreparedMessage(message, signal) {
     signal?.throwIfAborted();
+    checkSmtpPath(message.envelope.from ?? '');
+    for (const recipient of message.envelope.to) checkSmtpPath(recipient);
 
     let smtpUtf8Parameters = '';
     const negotiate = (encoding) => {
diff --git a/tests/unit/core.test.js b/tests/unit/core.test.js
index c3abcf1..006623a 100644
--- a/tests/unit/core.test.js
+++ b/tests/unit/core.test.js
@@ -33,6 +33,53 @@ test('Address: a value that is not a string, or a bad quoted local part, is no a
   assert.strictEqual(isEmailAddress('alex@[127.0.0.1]'), true);
 });
 
+test('Address: a domain is held to host-name characters, so it cannot end an SMTP path', () => {
+  const injected = 'user@example.com> NOTIFY=NEVER ORCPT=rfc822;a"@x.com';
+  const invalid = [
+    injected,
+    'user@example.com:25',
+    'user@example.com/path',
+    'user@example.com?query',
+    'user@example.com#fragment',
+    'user@x.com,evil.com',
+    'user@exa\tmple.com',
+    'user@exa mple.com',
+    'user@example..com',
+    'user@.example.com',
+    'user@ex_ample.com',
+    'user@"x"@example.com',
+  ];
+  for (const address of invalid) assert.strictEqual(isEmailAddress(address), false, address);
+  assert.throws(() => createMessage({ ...base, to: injected }), TypeError);
+  assert.throws(() => createMessage({ ...base, to: `Bob <${injected}>` }), TypeError);
+});
+
+test('Address: host names, internationalized names and quoted local parts still pass', () => {
+  const valid = [
+    'user@example.com',
+    'user@sub-domain.example.co.uk',
+    'user@\u043f\u0440\u0438\u043c\u0435\u0440.\u0440\u0444',
+    'user@example.com.',
+    '"a@b"@example.com',
+    '"john doe"@example.com',
+  ];
+  for (const address of valid) assert.strictEqual(isEmailAddress(address), true, address);
+});
+
+test('Address: a domain literal is an IPv4 address or an IPv6 one, tagged or not', () => {
+  const valid = ['u@[192.0.2.1]', 'u@[IPv6:2001:db8::1]', 'u@[ipv6:::1]', 'u@[2001:db8::1]'];
+  for (const address of valid) assert.strictEqual(isEmailAddress(address), true, address);
+  const invalid = [
+    'u@[999.1.1.1]',
+    'u@[example.com]',
+    'u@[fe80::1%en0]',
+    'u@[a@evil.com]',
+    'u@[127.0.0.1:25]',
+    'u@[IPv6:192.0.2.1]',
+  ];
+  for (const address of invalid) assert.strictEqual(isEmailAddress(address), false, address);
+});
+
 test('Message: an attachment that is neither a File nor an Attachment is rejected', () => {
   assert.throws(() => createMessage({ ...base, attachments: [{}] }), {
     name: 'TypeError',
diff --git a/tests/unit/smtp-message-converter.integration.test.js b/tests/unit/smtp-message-converter.integration.test.js
index c9f6174..101a14d 100644
--- a/tests/unit/smtp-message-converter.integration.test.js
+++ b/tests/unit/smtp-message-converter.integration.test.js
@@ -1076,21 +1076,24 @@ describe('Message Converter Integration Tests', () => {
     });
 
     test('should still generate an identifier for an unusual sender domain', async () => {
-      // `parseAddress()` validates domains with `URL`, which accepts spellings
-      // the identifier grammar does not.  Neither may fail the send.
+      // `parseAddress()` accepts the trailing dot of a fully qualified name,
+      // which the identifier grammar does not; it must not fail the send.
       const trailingDot = await convertMessage(
         createTestMessage({
           sender: { address: 'john@example.com.' },
         }),
       );
-      const withPort = await convertMessage(
-        createTestMessage({
-          sender: { address: 'john@example.com:8080' },
-        }),
-      );
 
       assert.match(occurrences(trailingDot.raw, 'Message-ID')[0], /^<[0-9a-f-]+@example\.com>$/);
-      assert.match(occurrences(withPort.raw, 'Message-ID')[0], /^<[0-9a-f-]+@localhost>$/);
+
+      // Changed after the port: upstream also delivered a sender whose domain
+      // carries a port, as `URL` accepts it.  A domain is now held to host-name
+      // characters (CLAUDE.md, upstream bugs fixed after the port), so such a
+      // sender is no address and never reaches `MAIL FROM`.
+      await assert.rejects(
+        convertMessage(createTestMessage({ sender: { address: 'john@example.com:8080' } })),
+        { name: 'SmtpEnvelopeValidationError' },
+      );
     });
 
     test('should write a year beyond four digits', async () => {
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 34aea8a..4614bed 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -8,6 +8,7 @@ const { createServer } = require('node:net');
 const { createMessage } = require('../../index.js');
 const { SmtpTransport } = require('../../src/smtp/index.js');
 const { prepareOnSocket, writeMessageData } = require('../../src/smtp/data-stream.js');
+const { checkSmtpPath } = require('../../src/smtp/envelope.js');
 const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
 
 const message = () =>
@@ -131,6 +132,44 @@ test('SMTP: a rejection after DATA fails the send', async () => {
   }
 });
 
+test('SMTP: an address that would end the RCPT TO path never reaches the server', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  try {
+    const transport = new SmtpTransport({ host: 'localhost', port, pool: false });
+    const receipt = await transport.send(message(), {
+      envelope: { to: ['user@example.com> NOTIFY=NEVER ORCPT=rfc822;a"@x.com'] },
+    });
+    assert.strictEqual(receipt.successful, false);
+    const rcpt = server.getReceivedCommands().filter((command) => command.startsWith('RCPT'));
+    assert.deepStrictEqual(rcpt, []);
+  } finally {
+    await server.stop();
+  }
+});
+
+test('SMTP: a path that could end MAIL FROM or RCPT TO early is refused before it is written', () => {
+  const unsafe = [
+    'a@b.com> NOTIFY=NEVER',
+    'a b@c.com',
+    'a<b@c.com',
+    'a@b.com\u0000',
+    'a@b\u007f.com',
+    '"x\\\u0001"@b.com',
+  ];
+  for (const path of unsafe) {
+    assert.throws(() => checkSmtpPath(path), { name: 'SmtpEnvelopeValidationError' }, path);
+  }
+  const safe = [
+    '',
+    'a@b.com',
+    '"john doe"@example.com',
+    '"a>b"@example.com',
+    '"a\\"b"@example.com',
+  ];
+  for (const path of safe) assert.doesNotThrow(() => checkSmtpPath(path), path);
+});
+
 const fakeSocket = (state = {}) =>
   Object.assign(new EventEmitter(), { destroyed: false, writable: true, destroy() {} }, state);
 

From a102e105049a63010225e54131aa0f8fe7c60ddf Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:01:11 +0300
Subject: [PATCH 023/158] fix(mime): quote a display name that could add a
 mailbox

The MIME builder and formatAddress wrote a printable display name as it
was, ./ses wrote it in quotes without escaping, and ./mailgun and ./resend
escaped `"` but not `\`. A name such as `Support <attacker@evil.com>, Real`
therefore put a second address into Reply-To, and `x\", eve@evil.example, "`
broke out of the provider's quoted string.

src/core/address.js now formats every mailbox: a name of atoms goes as it
is, anything else (or text that reads as an encoded word) as a quoted
string with `\` and `"` escaped (formatMailbox, formatQuotedMailbox for the
providers whose output was always quoted, formatPhrase for the MIME builder,
which keeps encoded words for non-ASCII names). createMessage refuses a line
break in a name, the formatters a control character, and parseAddress reads
a quoted name holding "<" or "," back, so it inverts formatAddress.

An upstream bug, recorded in CLAUDE.md. The fixes of this phase add code to
the root entry, so its CI size budget goes from 7 to 8 KB min+gzip, which
still catches a bundled third-party module.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml         |   2 +-
 CHANGELOG.md                     |   7 ++
 CLAUDE.md                        |   6 +-
 src/core/address.js              | 118 +++++++++++++++++++++++++++++--
 src/core/message.js              |   3 +
 src/mailgun/message-converter.js |  16 +----
 src/mime/message.js              |   9 ++-
 src/resend/message-converter.js  |  22 +-----
 src/ses/message-converter.js     |   8 +--
 tests/unit/core.test.js          |  23 ++++++
 tests/unit/mailgun.test.js       |  23 ++++++
 tests/unit/mime.test.js          |  20 ++++++
 tests/unit/resend.test.js        |  21 ++++++
 tests/unit/ses.test.js           |  24 +++++++
 14 files changed, 248 insertions(+), 54 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ab0a5bf..98d5034 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 7 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 4 --max-gzip-logger 2
+      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 4 --max-gzip-logger 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ead6b41..b2e7ded 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -56,5 +56,12 @@ listed in CLAUDE.md, to be fixed one by one.
   underscore or an empty label is refused too; a domain literal is an IPv4 address or an IPv6
   one, with or without the `IPv6:` tag. `./smtp` checks every path again right before it writes
   `MAIL FROM` and `RCPT TO`.
+- **A display name can no longer add a mailbox** (an upstream bug). The MIME builder and
+  `formatAddress` wrote a printable name as it was, and `./ses`, `./mailgun` and `./resend`
+  escaped `"` but not `\` (SES escaped nothing), so the name `Support <attacker@evil.com>, Real`
+  put a second address into `Reply-To`. A name that is more than atoms is now written as a quoted
+  string with `\` and `"` escaped, as is one that reads as an encoded word; `createMessage`
+  refuses a name with a line break and the formatters one with a control character; and
+  `parseAddress` reads a quoted name holding `<` or `,` back, so it inverts `formatAddress`.
 
 [unreleased]: https://github.com/Alexis-Technologies/mailer/commits/main
diff --git a/CLAUDE.md b/CLAUDE.md
index 8a73256..f951100 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,7 +42,7 @@ pnpm run test:types                # tsd: tests/types/*.test-d.ts, one file per
 pnpm run check:dts                 # tsc --noEmit --strict over the d.ts of every entry
 pnpm run lint                      # oxlint src tests scripts bench
 pnpm run format                    # oxfmt src tests scripts bench (format:check in CI)
-pnpm size [--max-gzip <KB>]        # esbuild bundle sizes; CI gates the root at 7 KB min+gzip and each subpath
+pnpm size [--max-gzip <KB>]        # esbuild bundle sizes; CI gates the root at 8 KB min+gzip and each subpath
 pnpm bench [filter] [--json] [--save] [--compare]   # ops/sec harness, manual only; --save writes bench/baseline.json
 pnpm docs:comparison               # renders docs/comparison.json into docs/guide/comparison.md
 pnpm run docs:dev                  # VitePress dev server for docs/ (docs:build, docs:preview)
@@ -157,6 +157,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     `URL.canParse` alone, so a domain could carry `>`, spaces, a port or userinfo and inject
     ESMTP parameters into `RCPT TO`. The domain is held to host-name characters, a domain
     literal to an IP address, and `./smtp` re-checks each path (`checkSmtpPath`).
+16. mime, core, ses, mailgun, resend: a printable display name was written as it was (SES), or
+    with `"` but not `\` escaped (mailgun, resend), so `<`, `,` and `@` in it added a mailbox.
+    `formatMailbox`, `formatQuotedMailbox` and `formatPhrase` in `src/core/address.js` quote it;
+    `createMessage` refuses a line break in a name.
 
 ## Repository layout
 
diff --git a/src/core/address.js b/src/core/address.js
index 63309f9..f1122a3 100644
--- a/src/core/address.js
+++ b/src/core/address.js
@@ -25,7 +25,81 @@ const net = require('node:net');
  * @return A string representation of the address.
  */
 const formatAddress = (address) => {
-  return address.name == null ? address.address : `${address.name} <${address.address}>`;
+  return address.name == null ? address.address : formatMailbox(address);
+};
+
+// RFC 5322 §3.2.3: the characters of an atom.
+const ATEXT = new Uint8Array(128);
+for (let code = 0x30; code <= 0x39; code++) ATEXT[code] = 1;
+for (let code = 0x41; code <= 0x5a; code++) {
+  ATEXT[code] = 1;
+  ATEXT[code + 0x20] = 1;
+}
+for (const symbol of "!#$%&'*+-/=?^_`{|}~") ATEXT[symbol.charCodeAt(0)] = 1;
+
+// A phrase of atoms separated by spaces goes as it is; anything else, such as
+// "<", ",", "@" or "." that would make a second mailbox or end this one, goes
+// as a quoted string (RFC 5322 §3.4).  So does text that reads as an encoded
+// word, which a reader would otherwise decode (RFC 2047 §5).
+const isAtomPhrase = (name) => {
+  const last = name.length - 1;
+  if (last < 0 || name.charCodeAt(0) === 0x20 || name.charCodeAt(last) === 0x20) return false;
+  for (let i = 0; i <= last; i++) {
+    const code = name.charCodeAt(i);
+    if (code !== 0x20 && (code > 0x7f || ATEXT[code] !== 1)) return false;
+  }
+  return !name.includes('=?');
+};
+
+const quoteString = (text) => `"${text.replace(/[\\"]/g, '\\$&')}"`;
+
+/**
+ * Formats a display name of printable text: as it is when it is atoms, as a
+ * quoted string otherwise.
+ *
+ * @param name A display name with no control character.
+ * @returns The phrase for the header.
+ * @internal
+ */
+const formatPhrase = (name) => (isAtomPhrase(name) ? name : quoteString(name));
+
+const checkDisplayName = (name) => {
+  for (let i = 0; i < name.length; i++) {
+    const code = name.charCodeAt(i);
+    if ((code < 0x20 && code !== 0x09) || code === 0x7f) {
+      throw new TypeError('A display name must not contain a control character.');
+    }
+  }
+};
+
+/**
+ * Formats a mailbox for a header or an API that takes one as a string: the
+ * display name as atoms when it has nothing else, otherwise as a quoted string.
+ *
+ * @param address The address, with or without a display name.
+ * @returns `name <address>`, `"name" <address>`, or the bare address.
+ * @throws {TypeError} If the display name holds a control character.
+ * @internal
+ */
+const formatMailbox = (address) => {
+  if (!address.name) return address.address;
+  checkDisplayName(address.name);
+  return `${formatPhrase(address.name)} <${address.address}>`;
+};
+
+/**
+ * Formats a mailbox with the display name always quoted, for APIs whose
+ * output has always been `"name" <address>`.
+ *
+ * @param address The address, with or without a display name.
+ * @returns `"name" <address>`, or the bare address.
+ * @throws {TypeError} If the display name holds a control character.
+ * @internal
+ */
+const formatQuotedMailbox = (address) => {
+  if (!address.name) return address.address;
+  checkDisplayName(address.name);
+  return `${quoteString(address.name)} <${address.address}>`;
 };
 
 /**
@@ -67,6 +141,20 @@ const parseAddress = (address) => {
     return undefined;
   }
 
+  // A quoted display name may hold "<", ">" and ",", so its end is found by
+  // scanning the quoted string rather than by the first "<".
+  if (trimmed.charCodeAt(0) === 0x22) {
+    const nameEnd = findClosingQuote(trimmed);
+    const rest = nameEnd === -1 ? '' : trimmed.slice(nameEnd + 1).trim();
+    if (rest.startsWith('<') && rest.endsWith('>')) {
+      const email = rest.slice(1, -1).trim();
+      if (!isValidEmail(email)) {
+        return undefined;
+      }
+      return { name: trimmed.slice(1, nameEnd).replace(/\\(.)/g, '$1'), address: email };
+    }
+  }
+
   // Check for name and angle bracket format: "Name <email@domain.com>"
   const nameAngleBracketMatch = trimmed.match(/^(.+?)\s*<(.+?)>$/);
   if (nameAngleBracketMatch) {
@@ -77,8 +165,10 @@ const parseAddress = (address) => {
       return undefined;
     }
 
-    // Remove quotes from name if present
-    const cleanName = name.replace(/^"(.+)"$/, '$1');
+    // Remove quotes from name if present, and the backslashes of the pairs
+    // they quote, so a name formatted by formatAddress() comes back as it was.
+    const quoted = /^"(.+)"$/.exec(name);
+    const cleanName = quoted == null ? name : quoted[1].replace(/\\(.)/g, '$1');
     return { name: cleanName, address: email };
   }
 
@@ -128,12 +218,19 @@ const isValidEmail = (email) => {
 
 const findLocalPartEnd = (email) => {
   if (email.charCodeAt(0) !== 0x22) return email.indexOf('@');
-  for (let i = 1; i < email.length; i++) {
-    const code = email.charCodeAt(i);
+  const quoteEnd = findClosingQuote(email);
+  return quoteEnd !== -1 && email.charCodeAt(quoteEnd + 1) === 0x40 ? quoteEnd + 1 : -1;
+};
+
+// The index of the quote that closes the quoted string opening `text`, past
+// its backslash pairs, or -1.
+const findClosingQuote = (text) => {
+  for (let i = 1; i < text.length; i++) {
+    const code = text.charCodeAt(i);
     if (code === 0x5c) {
       i++;
     } else if (code === 0x22) {
-      return email.charCodeAt(i + 1) === 0x40 ? i + 1 : -1;
+      return i;
     }
   }
   return -1;
@@ -269,4 +366,11 @@ const isEmailAddress = (email) => {
   return typeof email === 'string' && isValidEmail(email);
 };
 
-module.exports = { formatAddress, parseAddress, isEmailAddress };
+module.exports = {
+  formatAddress,
+  formatMailbox,
+  formatPhrase,
+  formatQuotedMailbox,
+  parseAddress,
+  isEmailAddress,
+};
diff --git a/src/core/message.js b/src/core/message.js
index 259c600..c2257e9 100644
--- a/src/core/message.js
+++ b/src/core/message.js
@@ -107,6 +107,9 @@ const checkAddress = (label, address) => {
   if (/[\r\n]/.test(parsed.address)) {
     throwTypeError(`Invalid ${label} address: ${JSON.stringify(parsed.address)}`);
   }
+  if (parsed.name != null && /[\r\n]/.test(parsed.name)) {
+    throwTypeError(`Invalid ${label} display name: it contains a carriage return or line feed.`);
+  }
   return parsed;
 };
 
diff --git a/src/mailgun/message-converter.js b/src/mailgun/message-converter.js
index cd9faf6..aadb098 100644
--- a/src/mailgun/message-converter.js
+++ b/src/mailgun/message-converter.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/mailgun/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { formatQuotedMailbox: formatAddress } = require('../core/address.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
@@ -122,21 +123,6 @@ const convertMessage = async (message, config, signal) => {
   return formData;
 };
 
-/**
- * Formats an address for Mailgun API.
- *
- * @param address - The address to format
- * @returns Formatted address string
- */
-const formatAddress = (address) => {
-  if (address.name) {
-    // Escape quotes in the name
-    const escapedName = address.name.replace(/"/g, '\\"');
-    return `"${escapedName}" <${address.address}>`;
-  }
-  return address.address;
-};
-
 /**
  * Appends an attachment to the FormData.
  *
diff --git a/src/mime/message.js b/src/mime/message.js
index 4c72721..808bd5d 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/mime/src/message.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { formatPhrase } = require('../core/address.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const {
   formatMessageId,
@@ -516,9 +517,13 @@ const encodeAddress = (address) => {
     return address.address;
   }
 
-  // Encode only the display name part, leave email address as-is
+  // Encode only the display name part, leave email address as-is.  An
+  // encoded word holds no specials, but plain text that is more than atoms is
+  // quoted, or "<", "," and "@" in it would make another mailbox.
   const encodedDisplayName = encodeHeaderValue(address.name, true);
-  return `${encodedDisplayName} <${address.address}>`;
+  const displayName =
+    encodedDisplayName === address.name ? formatPhrase(address.name) : encodedDisplayName;
+  return `${displayName} <${address.address}>`;
 };
 
 const encodeHeaderValue = (value, encodeLongAsciiWords = false) => {
diff --git a/src/resend/message-converter.js b/src/resend/message-converter.js
index cd64332..86f7e25 100644
--- a/src/resend/message-converter.js
+++ b/src/resend/message-converter.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/resend/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { formatMailbox: formatAddress } = require('../core/address.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
 const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
@@ -171,27 +172,6 @@ const convertMessagesBatch = async (messages, _config) => {
   return batchData;
 };
 
-/**
- * Formats an Address object into a string suitable for Resend API.
- *
- * @param address - The address to format
- * @returns Formatted address string
- */
-const formatAddress = (address) => {
-  if (address.name) {
-    // If the name contains special characters, quote it
-    const name =
-      address.name.includes('"') ||
-      address.name.includes(',') ||
-      address.name.includes('<') ||
-      address.name.includes('>')
-        ? `"${address.name.replace(/"/g, '\\"')}"`
-        : address.name;
-    return `${name} <${address.address}>`;
-  }
-  return address.address;
-};
-
 /**
  * Converts a Upyo Attachment to Resend attachment format.
  *
diff --git a/src/ses/message-converter.js b/src/ses/message-converter.js
index e34daf6..c744334 100644
--- a/src/ses/message-converter.js
+++ b/src/ses/message-converter.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { combineSignals } = require('../core/abort-signal.js');
+const { formatQuotedMailbox: formatAddress } = require('../core/address.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
 
@@ -132,13 +133,6 @@ const createSimpleContent = async (message, signal) => {
   return content;
 };
 
-const formatAddress = (address) => {
-  if (address.name) {
-    return `"${address.name}" <${address.address}>`;
-  }
-  return address.address;
-};
-
 // Dead upstream: nothing calls it (CLAUDE.md, known upstream bugs).
 /* c8 ignore start */
 const convertMessagesToBulk = async (messages, config, signal) => {
diff --git a/tests/unit/core.test.js b/tests/unit/core.test.js
index 006623a..b90a6d8 100644
--- a/tests/unit/core.test.js
+++ b/tests/unit/core.test.js
@@ -10,9 +10,11 @@ const {
   createMessage,
   createRawMessagePlan,
   createReceiptError,
+  formatAddress,
   isEmailAddress,
   iterateAttachmentContent,
   iterateRawMessage,
+  parseAddress,
   RawMessageValidationError,
   readAttachmentContent,
   resolveCalendarContent,
@@ -66,6 +68,27 @@ test('Address: host names, internationalized names and quoted local parts still
   for (const address of valid) assert.strictEqual(isEmailAddress(address), true, address);
 });
 
+test('Address: formatAddress() quotes a name that is more than atoms; parseAddress() reads it back', () => {
+  const cases = [
+    ['John Doe', 'John Doe <j@example.com>'],
+    ['Support <attacker@evil.com>, Real', '"Support <attacker@evil.com>, Real" <j@example.com>'],
+    ['x\\", eve@evil.example, "', '"x\\\\\\", eve@evil.example, \\"" <j@example.com>'],
+    ['Joe Q. Public', '"Joe Q. Public" <j@example.com>'],
+    ['=?utf-8?q?Admin?=', '"=?utf-8?q?Admin?=" <j@example.com>'],
+  ];
+  for (const [name, formatted] of cases) {
+    const address = { name, address: 'j@example.com' };
+    assert.strictEqual(formatAddress(address), formatted);
+    assert.deepStrictEqual(parseAddress(formatted), address);
+  }
+});
+
+test('Address: a display name with a line break is refused', () => {
+  const to = { name: 'Bob\r\nBcc: eve@evil.example', address: 'bob@example.com' };
+  assert.throws(() => createMessage({ ...base, to }), TypeError);
+  assert.throws(() => formatAddress({ name: 'Bob\nX', address: 'bob@example.com' }), TypeError);
+});
+
 test('Address: a domain literal is an IPv4 address or an IPv6 one, tagged or not', () => {
   const valid = ['u@[192.0.2.1]', 'u@[IPv6:2001:db8::1]', 'u@[ipv6:::1]', 'u@[2001:db8::1]'];
   for (const address of valid) assert.strictEqual(isEmailAddress(address), true, address);
diff --git a/tests/unit/mailgun.test.js b/tests/unit/mailgun.test.js
index 5243f04..3413b5c 100644
--- a/tests/unit/mailgun.test.js
+++ b/tests/unit/mailgun.test.js
@@ -4,6 +4,8 @@ const { test } = require('node:test');
 const assert = require('node:assert');
 const { createMessage } = require('../../index.js');
 const { MailgunTransport } = require('../../src/mailgun/index.js');
+const PostalMime = require('postal-mime');
+const { convertMessage } = require('../../src/mailgun/message-converter.js');
 
 const message = () =>
   createMessage({
@@ -52,3 +54,24 @@ test('Mailgun: sendMany reads an async iterable', async (t) => {
   assert.strictEqual(ids.length, 2);
   assert.ok(ids.every((id) => /^<?m\d@mg\.example\.com>?$/.test(id)));
 });
+
+test('Mailgun: a display name with "<", "," or "@" stays a single mailbox', async () => {
+  const name = 'x\\", eve@evil.example, "';
+  const converted = await convertMessage(
+    createMessage({
+      from: { name: 'Support <attacker@evil.com>, Real', address: 'alex@example.com' },
+      to: { name, address: 'bob@example.com' },
+      subject: 'Hello',
+      content: { text: 'Hi' },
+    }),
+    config,
+  );
+  const parsed = await PostalMime.parse(
+    `From: ${converted.get('from')}\r\nTo: ${converted.get('to')}\r\n\r\n`,
+  );
+  assert.deepStrictEqual(parsed.from, {
+    address: 'alex@example.com',
+    name: 'Support <attacker@evil.com>, Real',
+  });
+  assert.deepStrictEqual(parsed.to, [{ address: 'bob@example.com', name }]);
+});
diff --git a/tests/unit/mime.test.js b/tests/unit/mime.test.js
index 26a53ab..124e323 100644
--- a/tests/unit/mime.test.js
+++ b/tests/unit/mime.test.js
@@ -54,6 +54,26 @@ test('MIME: non-ASCII names, subjects and filenames round-trip through encoded w
   );
 });
 
+test('MIME: a display name with "<", "," or "@" stays a single mailbox', async () => {
+  const name = 'Support <attacker@evil.com>, Real';
+  const tricky = 'x\\", eve@evil.example, "';
+  const text = await wire(
+    createMessage({
+      ...base,
+      subject: 'a',
+      to: { name: tricky, address: 'bob@example.com' },
+      replyTo: { name, address: 'help@example.com' },
+    }),
+  );
+  assert.match(
+    headerBlock(text),
+    /^Reply-To: "Support <attacker@evil.com>, Real" <help@example.com>$/m,
+  );
+  const parsed = await PostalMime.parse(text);
+  assert.deepStrictEqual(parsed.replyTo, [{ address: 'help@example.com', name }]);
+  assert.deepStrictEqual(parsed.to, [{ address: 'bob@example.com', name: tricky }]);
+});
+
 test('MIME: a message without content gets an empty text part', async () => {
   const parsed = await PostalMime.parse(
     await wire(createMessage({ ...base, subject: 'Empty', content: {} })),
diff --git a/tests/unit/resend.test.js b/tests/unit/resend.test.js
index 09dc16e..3a10ded 100644
--- a/tests/unit/resend.test.js
+++ b/tests/unit/resend.test.js
@@ -4,6 +4,8 @@ const { test } = require('node:test');
 const assert = require('node:assert');
 const { createMessage } = require('../../index.js');
 const { ResendTransport } = require('../../src/resend/index.js');
+const PostalMime = require('postal-mime');
+const { convertMessage } = require('../../src/resend/message-converter.js');
 
 const message = (index = 0) =>
   createMessage({
@@ -80,3 +82,22 @@ test('Resend: a failed batch fails each of its messages', async (t) => {
     [['Bad batch'], ['Bad batch']],
   );
 });
+
+test('Resend: a display name with "<", "," or "@" stays a single mailbox', async () => {
+  const name = 'x\\", eve@evil.example, "';
+  const converted = await convertMessage(
+    createMessage({
+      from: { name: 'Support <attacker@evil.com>, Real', address: 'alex@example.com' },
+      to: { name, address: 'bob@example.com' },
+      subject: 'Hello',
+      content: { text: 'Hi' },
+    }),
+    {},
+  );
+  const parsed = await PostalMime.parse(`From: ${converted.from}\r\nTo: ${converted.to}\r\n\r\n`);
+  assert.deepStrictEqual(parsed.from, {
+    address: 'alex@example.com',
+    name: 'Support <attacker@evil.com>, Real',
+  });
+  assert.deepStrictEqual(parsed.to, [{ address: 'bob@example.com', name }]);
+});
diff --git a/tests/unit/ses.test.js b/tests/unit/ses.test.js
index 3d853a8..d988d61 100644
--- a/tests/unit/ses.test.js
+++ b/tests/unit/ses.test.js
@@ -5,6 +5,9 @@ const { test } = require('node:test');
 const assert = require('node:assert');
 const { createMessage } = require('../../index.js');
 const { SesTransport } = require('../../src/ses/index.js');
+const PostalMime = require('postal-mime');
+const { createSesConfig } = require('../../src/ses/config.js');
+const { convertMessage } = require('../../src/ses/message-converter.js');
 
 const message = (extra = {}) =>
   createMessage({
@@ -142,3 +145,24 @@ test('SES: sendMany reads an async iterable', async (t) => {
   }
   assert.deepStrictEqual(receipts.sort(), ['m1', 'm2']);
 });
+
+test('SES: a display name with "<", "," or "@" stays a single mailbox', async () => {
+  const name = 'x\\", eve@evil.example, "';
+  const converted = await convertMessage(
+    createMessage({
+      from: { name: 'Support <attacker@evil.com>, Real', address: 'alex@example.com' },
+      to: { name, address: 'bob@example.com' },
+      subject: 'Hello',
+      content: { text: 'Hi' },
+    }),
+    createSesConfig({}),
+  );
+  const parsed = await PostalMime.parse(
+    `From: ${converted.FromEmailAddress}\r\nTo: ${converted.Destination.ToAddresses[0]}\r\n\r\n`,
+  );
+  assert.deepStrictEqual(parsed.from, {
+    address: 'alex@example.com',
+    name: 'Support <attacker@evil.com>, Real',
+  });
+  assert.deepStrictEqual(parsed.to, [{ address: 'bob@example.com', name }]);
+});

From c3bd7f1323b67ffea0c4b4fc4e991568cf892864 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:02:38 +0300
Subject: [PATCH 024/158] fix(mime): check an attachment's content type and
 content ID again

composeMessage wrote an attachment's contentType and contentId into the
part headers as given; only createMessage refused a line break in them. A
message built by hand, as one read back from the planned queue would be,
could therefore inject part headers such as `X-Injected: 1`. The MIME
builder already re-checks addresses and custom headers, so it now runs the
same checkAttachment as createMessage. Parameters in a content type, such as
`text/plain; charset=utf-8`, are still written as they are.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  3 +++
 CLAUDE.md               |  2 ++
 src/core/message.js     |  3 ++-
 src/mime/message.js     |  6 +++++-
 tests/unit/mime.test.js | 21 +++++++++++++++++++++
 5 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b2e7ded..2e09d54 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -63,5 +63,8 @@ listed in CLAUDE.md, to be fixed one by one.
   string with `\` and `"` escaped, as is one that reads as an encoded word; `createMessage`
   refuses a name with a line break and the formatters one with a control character; and
   `parseAddress` reads a quoted name holding `<` or `,` back, so it inverts `formatAddress`.
+- **`composeMessage` checks an attachment's content type and content ID again** (an upstream
+  bug): only `createMessage` refused a line break in them, so a message built by hand, such as one
+  read back from a queue, could inject part headers.
 
 [unreleased]: https://github.com/Alexis-Technologies/mailer/commits/main
diff --git a/CLAUDE.md b/CLAUDE.md
index f951100..abf551d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -161,6 +161,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     with `"` but not `\` escaped (mailgun, resend), so `<`, `,` and `@` in it added a mailbox.
     `formatMailbox`, `formatQuotedMailbox` and `formatPhrase` in `src/core/address.js` quote it;
     `createMessage` refuses a line break in a name.
+17. mime: the content type and content ID of an attachment went into part headers unchecked when
+    the message was not built by `createMessage`; `composeMessage` runs `checkAttachment` again.
 
 ## Repository layout
 
diff --git a/src/core/message.js b/src/core/message.js
index c2257e9..48c5a25 100644
--- a/src/core/message.js
+++ b/src/core/message.js
@@ -126,6 +126,7 @@ const checkAddress = (label, address) => {
  * @returns The attachment, unchanged.
  * @throws {TypeError} If the content type or content ID contains a carriage
  * return or line feed.
+ * @internal
  */
 const checkAttachment = (attachment) => {
   if (/[\r\n]/.test(attachment.contentType)) {
@@ -192,4 +193,4 @@ const ensureArray = (value) => {
   return Array.isArray(value) ? value : value == null ? [] : [value];
 };
 
-module.exports = { createMessage };
+module.exports = { checkAttachment, createMessage };
diff --git a/src/mime/message.js b/src/mime/message.js
index 808bd5d..293fd84 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -3,6 +3,7 @@
 
 const { formatPhrase } = require('../core/address.js');
 const { readAttachmentContent } = require('../core/attachment.js');
+const { checkAttachment } = require('../core/message.js');
 const {
   formatMessageId,
   generateMessageId,
@@ -198,8 +199,11 @@ const buildMimeParts = (message) => {
       lines.push(alternatives[0].body);
     }
 
-    // Attachments
+    // Attachments.  A message is structural input, not only one built by
+    // createMessage(), so the fields written into part headers as given are
+    // checked again here, as the addresses and the custom headers are.
     for (const attachment of message.attachments) {
+      checkAttachment(attachment);
       lines.push('');
       lines.push(`--${boundary}`);
       lines.push(
diff --git a/tests/unit/mime.test.js b/tests/unit/mime.test.js
index 124e323..b93e69a 100644
--- a/tests/unit/mime.test.js
+++ b/tests/unit/mime.test.js
@@ -74,6 +74,27 @@ test('MIME: a display name with "<", "," or "@" stays a single mailbox', async (
   assert.deepStrictEqual(parsed.to, [{ address: 'bob@example.com', name: tricky }]);
 });
 
+test('MIME: a hand-built message cannot inject part headers through an attachment', async () => {
+  const attachment = {
+    inline: true,
+    filename: 'a.txt',
+    content: new Uint8Array([0x61]),
+    contentType: 'text/plain',
+    contentId: 'a@example.com',
+  };
+  const built = createMessage({ ...base, subject: 'a', attachments: [attachment] });
+  const injected = [
+    { ...attachment, contentType: 'text/plain\r\nX-Injected: 1' },
+    { ...attachment, contentId: 'a@example.com>\r\nX-Injected: 1\r\nX: <b' },
+  ];
+  for (const bad of injected) {
+    await assert.rejects(composeMessage({ ...built, attachments: [bad] }), TypeError);
+  }
+  const withParameter = { ...attachment, contentType: 'text/plain; charset=utf-8' };
+  const text = await wire({ ...built, attachments: [withParameter] });
+  assert.match(text, /^Content-Type: text\/plain; charset=utf-8; name="a.txt"$/m);
+});
+
 test('MIME: a message without content gets an empty text part', async () => {
   const parsed = await PostalMime.parse(
     await wire(createMessage({ ...base, subject: 'Empty', content: {} })),

From 4244d8d2c0824deca87cc1fbb85726a6cf2bba2f Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:10:01 +0300
Subject: [PATCH 025/158] fix(smtp): bound and correctly split the replies of a
 server

The SMTP client appended every chunk of a reply to a string and split the
whole of it again, so a server that never ended a line made each chunk
rescan everything received until the socket timeout, and a reply could hold
any number of lines. createReplyReader keeps only the incomplete last line
between chunks and refuses a line over 8192 characters or a reply over 1000
lines with a RangeError, destroying the socket; the reply to DATA was
already bounded at 64 KiB.

Three parsing bugs go with it. A final reply line that is the code alone
("250"), which RFC 5321 section 4.2 allows, was taken for a continuation
and hung until the timeout, in commands, the greeting and after DATA; the
greeting resolved on a line still waiting for its CRLF; and toString() per
chunk replaced a UTF-8 character split across two chunks. The reader
decodes with a StringDecoder and only complete lines count.

Upstream bugs, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  10 ++++
 CLAUDE.md                   |   5 ++
 src/smtp/data-stream.js     |   3 +-
 src/smtp/smtp-connection.js | 108 ++++++++++++++++++++++++++++++------
 tests/unit/smtp.test.js     | 103 ++++++++++++++++++++++++++++++++++
 5 files changed, 210 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2e09d54..4159aec 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -66,5 +66,15 @@ listed in CLAUDE.md, to be fixed one by one.
 - **`composeMessage` checks an attachment's content type and content ID again** (an upstream
   bug): only `createMessage` refused a line break in them, so a message built by hand, such as one
   read back from a queue, could inject part headers.
+- **`./smtp` bounds what a server's replies can take** (an upstream bug): a reply line is at most
+  8192 characters and a reply at most 1000 lines, where a server that never ended a line made the
+  client rescan everything received on every chunk until the socket timeout.
+
+### Fixed
+
+- **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
+  (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
+  any step or after DATA; the greeting waits for a complete line; and a UTF-8 character split
+  across two chunks of a reply stays whole.
 
 [unreleased]: https://github.com/Alexis-Technologies/mailer/commits/main
diff --git a/CLAUDE.md b/CLAUDE.md
index abf551d..004d0d4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -163,6 +163,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     `createMessage` refuses a line break in a name.
 17. mime: the content type and content ID of an attachment went into part headers unchecked when
     the message was not built by `createMessage`; `composeMessage` runs `checkAttachment` again.
+18. smtp: replies were re-split whole on every chunk with no bound on a line or on the lines of a
+    reply; a bare final line (`250`) was taken for a continuation and hung until the timeout; the
+    greeting resolved on an incomplete line; and `toString()` per chunk broke a split UTF-8
+    character. `createReplyReader` in `smtp-connection.js` decodes with a `StringDecoder` and
+    bounds both (8192 characters, 1000 lines).
 
 ## Repository layout
 
diff --git a/src/smtp/data-stream.js b/src/smtp/data-stream.js
index 922a1e3..f587514 100644
--- a/src/smtp/data-stream.js
+++ b/src/smtp/data-stream.js
@@ -83,7 +83,8 @@ const writeMessageData = async (socket, source, timeoutMs, checkSize, signal) =>
       const line = buffer.slice(0, end);
       buffer = buffer.slice(end + 2);
       lines.push(line);
-      if (/^\d{3} /.test(line)) {
+      // RFC 5321 §4.2: a final line is the code alone or with a space.
+      if (/^\d{3}(?: |$)/.test(line)) {
         if (!terminated) {
           fail(new TypeError(`Premature SMTP DATA reply: ${line}`));
         } else {
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index e9e3dd1..5be9c73 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -4,6 +4,7 @@
 const { prepareRawSmtpStream, Smtp8BitMimeUnsupportedError } = require('./raw-message.js');
 const { Buffer } = require('node:buffer');
 const { Socket } = require('node:net');
+const { StringDecoder } = require('node:string_decoder');
 const { connect: tlsConnect, TLSSocket } = require('node:tls');
 const { createSmtpConfig } = require('./config.js');
 const { SmtpDsnUnsupportedError } = require('./delivery-status.js');
@@ -19,6 +20,54 @@ const { prepareMessageStream } = require('./message-stream.js');
 const { prepareOnSocket, writeMessageData } = require('./data-stream.js');
 const { parseEnhancedSmtpStatusCode } = require('./smtp-status-code.js');
 
+// RFC 5321 §4.5.3.1.5 limits a reply line to 512 octets, but servers send
+// longer text; these bound the memory a broken or hostile server can take
+// rather than enforce the RFC.  The reply to DATA is bounded in data-stream.js.
+const MAX_REPLY_LINE_LENGTH = 8192;
+const MAX_REPLY_LINES = 1000;
+
+const createReplyLimitError = () =>
+  new RangeError(
+    `SMTP reply exceeds ${MAX_REPLY_LINE_LENGTH} characters in a line ` +
+      `or ${MAX_REPLY_LINES} lines.`,
+  );
+
+// RFC 5321 §4.2: the last line of a reply is its code, alone or followed by a
+// space and text; every other line puts a hyphen after the code.
+const isFinalReplyLine = (line) => line.length === 3 || (line.length > 3 && line[3] === ' ');
+
+/**
+ * Splits replies into lines as their bytes arrive.  The decoder keeps a
+ * character split across chunks whole, and only the incomplete last line is
+ * kept between chunks, so a server that never ends a line costs neither
+ * memory nor a rescan of everything received.
+ *
+ * @returns A reader whose `read()` returns the complete lines of a chunk, or
+ * `undefined` once a line is longer than {@link MAX_REPLY_LINE_LENGTH}.
+ */
+const createReplyReader = () => {
+  const decoder = new StringDecoder('utf8');
+  let pending = '';
+  return {
+    get pending() {
+      return pending;
+    },
+    read(data) {
+      pending += decoder.write(data);
+      const lines = [];
+      let start = 0;
+      let end;
+      while ((end = pending.indexOf('\r\n', start)) !== -1) {
+        if (end - start > MAX_REPLY_LINE_LENGTH) return undefined;
+        lines.push(pending.slice(start, end));
+        start = end + 2;
+      }
+      if (start > 0) pending = pending.slice(start);
+      return pending.length > MAX_REPLY_LINE_LENGTH ? undefined : lines;
+    },
+  };
+};
+
 /**
  * Error thrown when a message exceeds the fixed limit advertised through the
  * SMTP SIZE extension.
@@ -404,7 +453,7 @@ class SmtpConnection {
     signal?.throwIfAborted();
 
     return new Promise((resolve, reject) => {
-      let buffer = '';
+      const reader = createReplyReader();
       let responseLines = [];
       const responses = [];
       const startTimeout = () =>
@@ -419,15 +468,21 @@ class SmtpConnection {
       };
 
       const onData = (data) => {
-        buffer += data.toString();
-        const lines = buffer.split('\r\n');
-
-        // Keep incomplete line in buffer
-        const incompleteLine = lines.pop() || '';
+        const lines = reader.read(data);
+        if (lines === undefined) {
+          failOnLimit();
+          return;
+        }
 
-        for (const [lineIndex, line] of lines.entries()) {
+        for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+          const line = lines[lineIndex];
           responseLines.push(line);
-          if (line.length >= 4 && line[3] === ' ') {
+          if (!isFinalReplyLine(line)) {
+            if (responseLines.length > MAX_REPLY_LINES) {
+              failOnLimit();
+              return;
+            }
+          } else {
             const code = parseInt(line.substring(0, 3), 10);
             const message = line.substring(4);
             const response = {
@@ -443,7 +498,7 @@ class SmtpConnection {
               cleanup();
               if (
                 commands[0] === 'DATA' &&
-                (lineIndex + 1 < lines.length || incompleteLine.length > 0)
+                (lineIndex + 1 < lines.length || reader.pending.length > 0)
               ) {
                 this.socket?.destroy();
                 reject(new TypeError('Premature SMTP reply after DATA readiness.'));
@@ -462,9 +517,6 @@ class SmtpConnection {
             resetTimeout();
           }
         }
-
-        // Update buffer with incomplete line
-        buffer = incompleteLine;
       };
 
       const onError = (error) => {
@@ -472,6 +524,12 @@ class SmtpConnection {
         reject(error);
       };
 
+      const failOnLimit = () => {
+        cleanup();
+        this.socket?.destroy();
+        reject(createReplyLimitError());
+      };
+
       const onClose = () => {
         cleanup();
         const responseIndex = responses.findIndex(
@@ -524,22 +582,36 @@ class SmtpConnection {
     signal?.throwIfAborted();
 
     return new Promise((resolve, reject) => {
-      let buffer = '';
+      const reader = createReplyReader();
+      const replyLines = [];
       const timeout = setTimeout(() => {
         onError(new Error('Greeting timeout.'));
       }, this.config.socketTimeout);
 
+      // Only complete lines count: a final line still waiting for its CRLF
+      // could be cut short.
       const onData = (data) => {
-        buffer += data.toString();
-        const lines = buffer.split('\r\n');
+        const lines = reader.read(data);
+        if (lines === undefined) {
+          this.socket?.destroy();
+          onError(createReplyLimitError());
+          return;
+        }
 
-        for (const line of lines) {
-          if (line.length >= 4 && line[3] === ' ') {
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i];
+          replyLines.push(line);
+          if (isFinalReplyLine(line)) {
             const code = parseInt(line.substring(0, 3), 10);
             const message = line.substring(4);
 
             cleanup();
-            resolve({ code, message, raw: buffer });
+            resolve({ code, message, raw: replyLines.join('\r\n') });
+            return;
+          }
+          if (replyLines.length > MAX_REPLY_LINES) {
+            this.socket?.destroy();
+            onError(createReplyLimitError());
             return;
           }
         }
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 4614bed..8d78461 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -47,6 +47,109 @@ const failureOf = async (transport) => {
   return receipt.errorMessages.join(' | ');
 };
 
+// Answers a whole transaction through `reply(verb)`, with DATA_END for the
+// reply to the end of the message data.
+const transaction = (reply) => {
+  let inData = false;
+  return (line, socket) => {
+    if (inData) {
+      if (line === '.') {
+        inData = false;
+        socket.write(reply('DATA_END'));
+      }
+      return;
+    }
+    const verb = /^[A-Za-z]+/.exec(line)[0].toUpperCase();
+    if (verb === 'QUIT') socket.end(reply(verb));
+    else socket.write(reply(verb));
+    if (verb === 'DATA') inData = true;
+  };
+};
+const ok = { EHLO: '250 localhost\r\n', DATA: '354 go\r\n', QUIT: '221 bye\r\n' };
+const okReply = (verb) => ok[verb] ?? '250 ok\r\n';
+
+test('SMTP: a reply line that is the code alone ends the reply', async () => {
+  const bare = { DATA: '354\r\n', QUIT: '221\r\n' };
+  const { server, port } = await scripted(
+    transaction((verb) => bare[verb] ?? '250\r\n'),
+    (socket) => socket.write('220\r\n'),
+  );
+  try {
+    const transport = new SmtpTransport({
+      host: '127.0.0.1',
+      port,
+      pool: false,
+      socketTimeout: 1000,
+    });
+    const receipt = await transport.send(message());
+    assert.strictEqual(receipt.successful, true, receipt.errorMessages?.join(' | '));
+  } finally {
+    await stop(server);
+  }
+});
+
+test('SMTP: a reply line or a reply too long to be one fails the send at once', async () => {
+  const servers = [
+    // A greeting that never ends its line.
+    () =>
+      scripted(
+        () => {},
+        (socket) => socket.write(`220 ${'x'.repeat(9000)}`),
+      ),
+    // A greeting of more lines than a reply holds.
+    () =>
+      scripted(
+        () => {},
+        (socket) => socket.write('220-x\r\n'.repeat(1001)),
+      ),
+    // An EHLO reply of more lines than any server has capabilities.
+    () =>
+      scripted(
+        transaction((verb) =>
+          verb === 'EHLO' ? `${'250-x\r\n'.repeat(1001)}250 ok\r\n` : okReply(verb),
+        ),
+      ),
+  ];
+  for (const start of servers) {
+    const { server, port } = await start();
+    try {
+      const transport = new SmtpTransport({
+        host: '127.0.0.1',
+        port,
+        pool: false,
+        socketTimeout: 2000,
+      });
+      assert.match(await failureOf(transport), /SMTP reply exceeds/);
+    } finally {
+      await stop(server);
+    }
+  }
+});
+
+test('SMTP: a character split across two chunks of a reply stays whole', async () => {
+  const rejection = Buffer.from('550 Скриньки немає\r\n');
+  const { server, port } = await scripted(
+    transaction((verb) => {
+      if (verb !== 'RCPT') return okReply(verb);
+      return '';
+    }),
+  );
+  server.on('connection', (socket) => {
+    socket.on('data', (chunk) => {
+      if (!chunk.toString('latin1').includes('RCPT TO')) return;
+      // "С" is two bytes; the reply is cut between them.
+      socket.write(rejection.subarray(0, 5));
+      setTimeout(() => socket.write(rejection.subarray(5)), 20);
+    });
+  });
+  try {
+    const transport = new SmtpTransport({ host: '127.0.0.1', port, pool: false });
+    assert.match(await failureOf(transport), /Скриньки немає/);
+  } finally {
+    await stop(server);
+  }
+});
+
 test('SMTP: a server that closes before its greeting fails the send', async () => {
   const { server, port } = await scripted(
     () => {},

From f97f9e42008bf43749eb3ad8364431e6f95b3aa5 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:15:38 +0300
Subject: [PATCH 026/158] fix: keep the credentials of a transport out of
 inspect and JSON

The transports keep their configuration, and with it API keys, passwords,
OAuth tokens and DKIM private keys, on plain properties: TypeScript's
`private` is not private at run time. util.inspect(), console.log() and
JSON.stringify() of a transport, or of a ./retry or ./pool around one, so
printed them to any log or error reporter that serialized it.

src/internal/redact.js copies an object with every credential field and
credential header (Authorization, X-API-Key, ...) replaced by [REDACTED],
naming emitters such as sockets rather than walking them and cutting
cycles with a WeakSet. The ten transports that hold credentials return that
copy from toJSON() and inspect it from [util.inspect.custom]; the
configuration itself keeps its values. src/internal/ holds private modules
any subpath may require; it is not in the exports map, so the module graph
test needs no new edge.

The helper adds about 0.5 KB min+gzip to each of those subpaths, so the
budgets of smtp, jmap, mailgun, maileroo, lettermint and plunk go up by
1 KB. Recorded in CLAUDE.md as an upstream bug.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml               |   2 +-
 CHANGELOG.md                           |   5 ++
 CLAUDE.md                              |   5 ++
 src/internal/redact.js                 |  83 +++++++++++++++++++
 src/jmap/jmap-transport.js             |  18 +++++
 src/lettermint/lettermint-transport.js |  18 +++++
 src/maileroo/maileroo-transport.js     |  18 +++++
 src/mailgun/mailgun-transport.js       |  18 +++++
 src/mailtrap/mailtrap-transport.js     |  18 +++++
 src/plunk/plunk-transport.js           |  18 +++++
 src/resend/resend-transport.js         |  18 +++++
 src/sendgrid/sendgrid-transport.js     |  18 +++++
 src/ses/ses-transport.js               |  18 +++++
 src/smtp/smtp-transport.js             |  18 +++++
 tests/unit/graph.test.js               |   3 +-
 tests/unit/secrets.test.js             | 107 +++++++++++++++++++++++++
 16 files changed, 383 insertions(+), 2 deletions(-)
 create mode 100644 src/internal/redact.js
 create mode 100644 tests/unit/secrets.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 98d5034..0c6fc00 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 17 --max-gzip-jmap 8 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 2 --max-gzip-mailtrap 4 --max-gzip-maileroo 3 --max-gzip-lettermint 3 --max-gzip-plunk 2 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 4 --max-gzip-logger 2
+      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 18 --max-gzip-jmap 9 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 3 --max-gzip-mailtrap 4 --max-gzip-maileroo 4 --max-gzip-lettermint 4 --max-gzip-plunk 3 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 4 --max-gzip-logger 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4159aec..27327b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -69,6 +69,11 @@ listed in CLAUDE.md, to be fixed one by one.
 - **`./smtp` bounds what a server's replies can take** (an upstream bug): a reply line is at most
   8192 characters and a reply at most 1000 lines, where a server that never ended a line made the
   client rescan everything received on every chunk until the socket timeout.
+- **A transport no longer prints its credentials** (an upstream bug): `util.inspect`,
+  `console.log` and `JSON.stringify` of `./smtp`, `./ses`, `./jmap` or an HTTP provider showed its
+  API key, password, tokens or DKIM key, also through `./retry` and `./pool`. They now show
+  `[REDACTED]`, as do credential headers such as `Authorization`; `transport.config` keeps the
+  values.
 
 ### Fixed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 004d0d4..b5bfc5c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -168,6 +168,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     greeting resolved on an incomplete line; and `toString()` per chunk broke a split UTF-8
     character. `createReplyReader` in `smtp-connection.js` decodes with a `StringDecoder` and
     bounds both (8192 characters, 1000 lines).
+19. every transport: credentials sit on plain properties (TS `private` is not private at run
+    time), so `util.inspect`, `console.log` and `JSON.stringify` of a transport printed API keys,
+    passwords, tokens and DKIM keys. `src/internal/redact.js` backs `toJSON()` and
+    `[util.inspect.custom]` on the ten transports that hold them; `config` keeps its values.
 
 ## Repository layout
 
@@ -177,6 +181,7 @@ src/
   index.js          public barrel (explicit named exports)
   version.js        the package name and version (OpenTelemetry scope), kept equal to package.json
   <subpath>/        one directory per subpath: index.js + index.d.ts + its modules
+  internal/         private modules shared by subpaths, not in the exports map (redact.js)
 tests/
   unit/*.test.js    node:test suites, one per area (<subpath>-<module>.test.js for a subpath)
   helpers/<sub>/    shared test code of a subpath (fake servers, fixtures builders)
diff --git a/src/internal/redact.js b/src/internal/redact.js
new file mode 100644
index 0000000..8916465
--- /dev/null
+++ b/src/internal/redact.js
@@ -0,0 +1,83 @@
+// Not ported from upyo: keeps credentials out of a transport that is logged,
+// inspected or serialized.  The configuration stays readable as it is.
+
+const { EventEmitter } = require('node:events');
+
+/**
+ * The key `util.inspect()` calls a custom inspection method under.
+ */
+const INSPECT = Symbol.for('nodejs.util.inspect.custom');
+
+const REDACTED = '[REDACTED]';
+
+// The credential fields of the transports' configurations, and the header
+// names that carry credentials, compared in lower case.
+const SECRET_KEYS = new Set([
+  'accesstoken',
+  'api-token',
+  'apikey',
+  'apitoken',
+  'authorization',
+  'bearertoken',
+  'clientsecret',
+  'cookie',
+  'pass',
+  'password',
+  'privatekey',
+  'proxy-authorization',
+  'refreshtoken',
+  'secret',
+  'secretaccesskey',
+  'sessiontoken',
+  'token',
+  'x-api-key',
+  'x-lettermint-token',
+]);
+
+// Plain objects and class instances are copied; built-in values such as a
+// Map, a Date, bytes or an AbortSignal are kept as they are, and an emitter,
+// such as a socket, is named rather than walked.
+const copyRedacted = (value, ancestors) => {
+  if (value === null || typeof value !== 'object') return value;
+  if (value instanceof EventEmitter) return `[${value.constructor.name}]`;
+  const isArray = Array.isArray(value);
+  if (!isArray && Object.prototype.toString.call(value) !== '[object Object]') return value;
+  if (ancestors.has(value)) return '[Circular]';
+  ancestors.add(value);
+  let copy;
+  if (isArray) {
+    copy = [];
+    for (let i = 0; i < value.length; i++) copy.push(copyRedacted(value[i], ancestors));
+  } else {
+    copy = {};
+    for (const key of Object.keys(value)) {
+      const isSecret = SECRET_KEYS.has(key.toLowerCase()) && value[key] != null;
+      copy[key] = isSecret ? REDACTED : copyRedacted(value[key], ancestors);
+    }
+  }
+  ancestors.delete(value);
+  return copy;
+};
+
+/**
+ * Copies an object with every credential replaced by `[REDACTED]`.
+ *
+ * @param value The object to copy, typically a transport.
+ * @returns A plain copy without credentials.
+ * @internal
+ */
+const redactSecrets = (value) => copyRedacted(value, new WeakSet());
+
+/**
+ * Inspects an object without its credentials, under its class name.
+ *
+ * @param value The object to inspect.
+ * @param options The options `util.inspect()` passed to the custom method.
+ * @param inspect The `util.inspect()` function it passed.
+ * @returns The inspected text.
+ * @internal
+ */
+const inspectRedacted = (value, options, inspect) =>
+  `${value.constructor.name} ${inspect(redactSecrets(value), options)}`;
+
+module.exports = { INSPECT, inspectRedacted, redactSecrets };
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index d16567f..6f3fec1 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -13,6 +13,7 @@ const { JmapApiError } = require('./errors.js');
 const { JmapHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { findMailAccount } = require('./session.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 /**
  * JMAP capabilities required for email sending.
@@ -42,6 +43,23 @@ class JmapTransport {
     this.httpClient = new JmapHttpClient(this.config);
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Checks a fresh Session, the account used by send(), its drafts mailbox,
    * and the configured or available identity without creating or sending mail.
diff --git a/src/lettermint/lettermint-transport.js b/src/lettermint/lettermint-transport.js
index 7cf0413..9124421 100644
--- a/src/lettermint/lettermint-transport.js
+++ b/src/lettermint/lettermint-transport.js
@@ -9,6 +9,7 @@ const {
   LettermintTimeoutError,
 } = require('./http-client.js');
 const { convertMessage, generateIdempotencyKey } = require('./message-converter.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 const MAX_BATCH_SIZE = 500;
 
@@ -52,6 +53,23 @@ class LettermintTransport {
     this.httpClient = new LettermintHttpClient(this.config);
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Sends a single email message via Lettermint API.
    *
diff --git a/src/maileroo/maileroo-transport.js b/src/maileroo/maileroo-transport.js
index bba499a..fe5a767 100644
--- a/src/maileroo/maileroo-transport.js
+++ b/src/maileroo/maileroo-transport.js
@@ -5,6 +5,7 @@ const { createFailedReceipt } = require('../core/receipt.js');
 const { createMailerooConfig } = require('./config.js');
 const { MailerooApiError, MailerooHttpClient, MailerooTimeoutError } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 /**
  * Maileroo transport implementation for sending emails via Maileroo API.
@@ -46,6 +47,23 @@ class MailerooTransport {
     this.httpClient = new MailerooHttpClient(this.config);
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Sends a single email message via Maileroo API.
    *
diff --git a/src/mailgun/mailgun-transport.js b/src/mailgun/mailgun-transport.js
index ac4f999..c09fc32 100644
--- a/src/mailgun/mailgun-transport.js
+++ b/src/mailgun/mailgun-transport.js
@@ -5,6 +5,7 @@ const { createFailedReceipt } = require('../core/receipt.js');
 const { createMailgunConfig } = require('./config.js');
 const { MailgunApiError, MailgunHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 /**
  * Mailgun transport implementation for sending emails via Mailgun API.
@@ -50,6 +51,23 @@ class MailgunTransport {
     this.httpClient = new MailgunHttpClient(this.config);
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Sends a single email message via Mailgun API.
    *
diff --git a/src/mailtrap/mailtrap-transport.js b/src/mailtrap/mailtrap-transport.js
index 5f36dcf..9d6cc8e 100644
--- a/src/mailtrap/mailtrap-transport.js
+++ b/src/mailtrap/mailtrap-transport.js
@@ -10,6 +10,7 @@ const {
   MailtrapTimeoutError,
 } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 const MAX_BATCH_SIZE = 500;
 
@@ -55,6 +56,23 @@ class MailtrapTransport {
     this.httpClient = new MailtrapHttpClient(this.config);
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Sends a single email message via Mailtrap API.
    *
diff --git a/src/plunk/plunk-transport.js b/src/plunk/plunk-transport.js
index 95bdf76..6d8e72a 100644
--- a/src/plunk/plunk-transport.js
+++ b/src/plunk/plunk-transport.js
@@ -5,6 +5,7 @@ const { createFailedReceipt } = require('../core/receipt.js');
 const { createPlunkConfig } = require('./config.js');
 const { PlunkApiError, PlunkHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 /**
  * Plunk transport implementation for sending emails via Plunk API.
@@ -52,6 +53,23 @@ class PlunkTransport {
     this.httpClient = new PlunkHttpClient(this.config);
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Sends a single email message via Plunk API.
    *
diff --git a/src/resend/resend-transport.js b/src/resend/resend-transport.js
index 1d6cae8..010a5e6 100644
--- a/src/resend/resend-transport.js
+++ b/src/resend/resend-transport.js
@@ -9,6 +9,7 @@ const {
   convertMessagesBatch,
   generateIdempotencyKey,
 } = require('./message-converter.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 /**
  * Resend transport implementation for sending emails via Resend API.
@@ -55,6 +56,23 @@ class ResendTransport {
     this.httpClient = new ResendHttpClient(this.config);
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Sends a single email message via Resend API.
    *
diff --git a/src/sendgrid/sendgrid-transport.js b/src/sendgrid/sendgrid-transport.js
index 9a4c46f..d9ed22d 100644
--- a/src/sendgrid/sendgrid-transport.js
+++ b/src/sendgrid/sendgrid-transport.js
@@ -5,6 +5,7 @@ const { createFailedReceipt } = require('../core/receipt.js');
 const { createSendGridConfig } = require('./config.js');
 const { SendGridApiError, SendGridHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 /**
  * SendGrid transport implementation for sending emails via SendGrid API.
@@ -50,6 +51,23 @@ class SendGridTransport {
     this.httpClient = new SendGridHttpClient(this.config);
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Sends a single email message via SendGrid API.
    *
diff --git a/src/ses/ses-transport.js b/src/ses/ses-transport.js
index 7435cb3..05a7d23 100644
--- a/src/ses/ses-transport.js
+++ b/src/ses/ses-transport.js
@@ -5,6 +5,7 @@ const { createFailedReceipt } = require('../core/receipt.js');
 const { createSesConfig } = require('./config.js');
 const { SesApiError, SesHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 /**
  * Amazon SES email transport implementation.
@@ -59,6 +60,23 @@ class SesTransport {
     this.httpClient = new SesHttpClient(this.config);
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Sends a single email message through Amazon SES.
    *
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index d2d74bb..8fa60bf 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -22,6 +22,7 @@ const { prepareMessage } = require('./message-converter.js');
 const { SmtpAttachmentReplayError } = require('./message-stream.js');
 const { validateDkimBodyMode } = require('../mime/dkim/types.js');
 const { parseEnhancedSmtpStatusCode } = require('./smtp-status-code.js');
+const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 /**
  * SMTP transport implementation for sending emails via SMTP protocol.
@@ -133,6 +134,23 @@ class SmtpTransport {
         : undefined;
   }
 
+  /**
+   * Leaves the credentials of the configuration out of `JSON.stringify()`.
+   *
+   * @returns A plain copy of the transport with its credentials redacted.
+   */
+  toJSON() {
+    return redactSecrets(this);
+  }
+
+  /**
+   * Leaves the credentials of the configuration out of `util.inspect()`, and
+   * so out of `console.log()` and of loggers that inspect what they log.
+   */
+  [INSPECT](_depth, options, inspect) {
+    return inspectRedacted(this, options, inspect);
+  }
+
   /**
    * Checks a fresh SMTP connection, TLS policy, and configured authentication
    * without sending mail. Uses the shared connection limit and closes the
diff --git a/tests/unit/graph.test.js b/tests/unit/graph.test.js
index adb455f..2e34d1b 100644
--- a/tests/unit/graph.test.js
+++ b/tests/unit/graph.test.js
@@ -77,7 +77,8 @@ test('Graph: the modules of src/ require each other without a cycle', () => {
 
 // The directories of the subpaths, from the exports map: `./smtp` lives in
 // src/smtp/. Everything else (src/*.js, src/core/) is the root entry, which
-// requires no subpath.
+// requires no subpath, and src/internal/ holds private modules any subpath may
+// require, which require no subpath either.
 const SUBPATHS = Object.keys(pkg.exports)
   .filter((subpath) => subpath !== '.')
   .map((subpath) => pkg.exports[subpath].default.split('/')[2]);
diff --git a/tests/unit/secrets.test.js b/tests/unit/secrets.test.js
new file mode 100644
index 0000000..c7f4218
--- /dev/null
+++ b/tests/unit/secrets.test.js
@@ -0,0 +1,107 @@
+// Credentials of the transports stay out of what logs and error reporters
+// print: util.inspect(), console.log() and JSON.stringify() of a transport.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { Socket } = require('node:net');
+const { inspect } = require('node:util');
+const { redactSecrets } = require('../../src/internal/redact.js');
+const { JmapTransport } = require('../../src/jmap/index.js');
+const { LettermintTransport } = require('../../src/lettermint/index.js');
+const { MailerooTransport } = require('../../src/maileroo/index.js');
+const { MailgunTransport } = require('../../src/mailgun/index.js');
+const { MailtrapTransport } = require('../../src/mailtrap/index.js');
+const { PlunkTransport } = require('../../src/plunk/index.js');
+const { PoolTransport } = require('../../src/pool/index.js');
+const { ResendTransport } = require('../../src/resend/index.js');
+const { RetryTransport } = require('../../src/retry/index.js');
+const { SendGridTransport } = require('../../src/sendgrid/index.js');
+const { SesTransport } = require('../../src/ses/index.js');
+const { SmtpTransport } = require('../../src/smtp/index.js');
+
+const SECRET = 'secret-value-1f3a';
+
+const transports = () => [
+  new SmtpTransport({
+    host: 'smtp.example.com',
+    auth: { user: 'alex', pass: SECRET },
+    dkim: { signatures: [{ signingDomain: 'example.com', selector: 's', privateKey: SECRET }] },
+  }),
+  new SmtpTransport({
+    host: 'smtp.example.com',
+    auth: {
+      type: 'oauth2',
+      user: 'alex',
+      clientId: 'client',
+      clientSecret: SECRET,
+      refreshToken: SECRET,
+      tokenEndpoint: 'https://auth.example.com/token',
+      accessToken: SECRET,
+    },
+  }),
+  new SesTransport({
+    authentication: {
+      type: 'credentials',
+      accessKeyId: 'AKIAEXAMPLE',
+      secretAccessKey: SECRET,
+      sessionToken: SECRET,
+    },
+  }),
+  new ResendTransport({ apiKey: SECRET, headers: { Authorization: `Bearer ${SECRET}` } }),
+  new SendGridTransport({ apiKey: SECRET }),
+  new MailgunTransport({ apiKey: SECRET, domain: 'mg.example.com' }),
+  new MailtrapTransport({ apiToken: SECRET }),
+  new MailerooTransport({ apiKey: SECRET, headers: { 'X-API-Key': SECRET } }),
+  new LettermintTransport({ apiToken: SECRET }),
+  new PlunkTransport({ apiKey: SECRET }),
+  new JmapTransport({ sessionUrl: 'https://jmap.example.com/session', bearerToken: SECRET }),
+  new JmapTransport({
+    sessionUrl: 'https://jmap.example.com/session',
+    basicAuth: { username: 'alex', password: SECRET },
+  }),
+];
+
+test('Secrets: no transport shows its credentials to util.inspect() or JSON.stringify()', () => {
+  for (const transport of transports()) {
+    const inspected = inspect(transport, { depth: Infinity });
+    assert.ok(!inspected.includes(SECRET), inspected);
+    assert.ok(inspected.startsWith(`${transport.constructor.name} `), inspected);
+    assert.match(inspected, /\[REDACTED\]/);
+    const json = JSON.stringify(transport);
+    assert.ok(!json.includes(SECRET), json);
+  }
+});
+
+test('Secrets: the configuration itself keeps its credentials', () => {
+  const transport = new ResendTransport({ apiKey: SECRET });
+  assert.strictEqual(transport.config.apiKey, SECRET);
+  assert.strictEqual(inspect(transport.config).includes(SECRET), true);
+});
+
+test('Secrets: a decorator does not show the credentials of what it wraps', () => {
+  const wrapped = [
+    new RetryTransport(new ResendTransport({ apiKey: SECRET })),
+    new PoolTransport({
+      strategy: 'round-robin',
+      transports: [{ transport: new SendGridTransport({ apiKey: SECRET }) }],
+    }),
+  ];
+  for (const transport of wrapped) {
+    assert.ok(!inspect(transport, { depth: Infinity }).includes(SECRET));
+    assert.ok(!JSON.stringify(transport).includes(SECRET));
+  }
+});
+
+test('Secrets: redaction copies arrays and records, keeps built-in values, names emitters', () => {
+  const date = new Date(0);
+  const headers = new Map([['Authorization', 'kept, as a Map is not walked']]);
+  const record = { list: [{ token: SECRET }, 1], date, headers, socket: new Socket(), empty: null };
+  record.self = record;
+  const copy = redactSecrets(record);
+  assert.deepStrictEqual(copy.list, [{ token: '[REDACTED]' }, 1]);
+  assert.strictEqual(copy.date, date);
+  assert.strictEqual(copy.headers, headers);
+  assert.strictEqual(copy.socket, '[Socket]');
+  assert.strictEqual(copy.self, '[Circular]');
+  assert.strictEqual(copy.empty, null);
+  assert.deepStrictEqual(redactSecrets({ password: undefined }), { password: undefined });
+});

From 3d03f0460a8e4d3afd3849a604aa0a807ffd0682 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:22:06 +0300
Subject: [PATCH 027/158] fix(otel,logger): keep addresses out of exported
 error text by default

./otel left error.message out of span attributes unless recordSensitiveData
was on, but the span status, the exception event and the email.send_failed
event carried the raw error text anyway, and ./logger wrote failures with
their raw error text and the provider's raw response. SMTP names the
recipient in its rejections ("RCPT TO failed for bob@example.com: ..."), so
recipient addresses reached telemetry and logs by default, contrary to
SECURITY.md. ./plunk also put the start of the recipient's local part into
its synthetic message IDs.

src/internal/redact-addresses.js replaces every address in a text with
[REDACTED], scanning from each "@" to the separators around it (with a
bounded look for a quoted local part or a domain literal), so it runs in
linear time on any input. ./otel applies it to the status and events unless
recordSensitiveData is on; ./logger applies it to errorMessages, errors and
receipt and leaves providerDetails out unless recordMessage is on. A receipt
returned to the application keeps its full text. SECURITY.md and the otel
and logger guides now say what is redacted and when.

Upstream bugs, recorded in CLAUDE.md. The otel size budget goes from 4 to
5 KB min+gzip for the helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml           |  2 +-
 CHANGELOG.md                       |  6 +++
 CLAUDE.md                          |  5 +++
 SECURITY.md                        |  8 +++-
 docs/transports/logger.md          |  8 +++-
 docs/transports/otel.md            | 10 +++++
 src/internal/redact-addresses.js   | 68 ++++++++++++++++++++++++++++++
 src/logger/logger-transport.js     | 34 ++++++++++++---
 src/otel/attributes.js             | 10 +++++
 src/otel/tracing.js                | 14 ++++--
 src/plunk/plunk-transport.js       |  9 ++--
 tests/unit/logger.test.js          | 35 +++++++++++++++
 tests/unit/otel.test.js            | 26 ++++++++++++
 tests/unit/plunk-transport.test.js |  5 ++-
 tests/unit/privacy.test.js         | 29 +++++++++++++
 15 files changed, 248 insertions(+), 21 deletions(-)
 create mode 100644 src/internal/redact-addresses.js
 create mode 100644 tests/unit/privacy.test.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0c6fc00..eebf068 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 18 --max-gzip-jmap 9 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 3 --max-gzip-mailtrap 4 --max-gzip-maileroo 4 --max-gzip-lettermint 4 --max-gzip-plunk 3 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 4 --max-gzip-logger 2
+      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 18 --max-gzip-jmap 9 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 3 --max-gzip-mailtrap 4 --max-gzip-maileroo 4 --max-gzip-lettermint 4 --max-gzip-plunk 3 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 27327b5..8a02b13 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -74,6 +74,12 @@ listed in CLAUDE.md, to be fixed one by one.
   API key, password, tokens or DKIM key, also through `./retry` and `./pool`. They now show
   `[REDACTED]`, as do credential headers such as `Authorization`; `transport.config` keeps the
   values.
+- **`./otel` and `./logger` keep addresses out of error text by default** (an upstream bug): the
+  status and events of a span carried the raw error text whatever `recordSensitiveData` said, and
+  the logger wrote it with the provider's raw response, so the recipient of an SMTP rejection
+  reached telemetry and logs. Without `recordSensitiveData` (otel) or `recordMessage` (logger),
+  every address in that text is now `[REDACTED]`, and the logger leaves `providerDetails` out.
+  `./plunk` no longer puts the start of the recipient's address into a synthetic message ID.
 
 ### Fixed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index b5bfc5c..285cd7e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -172,6 +172,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     time), so `util.inspect`, `console.log` and `JSON.stringify` of a transport printed API keys,
     passwords, tokens and DKIM keys. `src/internal/redact.js` backs `toJSON()` and
     `[util.inspect.custom]` on the ten transports that hold them; `config` keeps its values.
+20. otel, logger, plunk: span status and events carried raw error text whatever
+    `recordSensitiveData` said, the logger wrote failures with `providerDetails`, and plunk's
+    synthetic message ID held the recipient's local part. `src/internal/redact-addresses.js`
+    (`redactAddresses`, linear time) scrubs the text unless `recordSensitiveData` (otel) or
+    `recordMessage` (logger) is set.
 
 ## Repository layout
 
diff --git a/SECURITY.md b/SECURITY.md
index 8046e87..8cd1765 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -42,8 +42,12 @@ is designed around:
 - **Attachments do not read the machine by default.** Reading a file path or fetching a URL for an
   attachment is off unless the application turns it on; fetching a URL is limited in size and
   refuses private and link-local addresses.
-- **Credentials and personal data stay out of logs.** SMTP passwords, OAuth2 tokens, provider keys
-  and DKIM private keys are never logged, and addresses in logs and telemetry are redacted.
+- **Credentials and personal data stay out of logs.** A transport shows `[REDACTED]` in place of
+  its SMTP password, OAuth2 tokens, provider key and DKIM private key when it is inspected,
+  logged or serialized. `./otel` and `./logger` record addresses only when told to
+  (`recordSensitiveData`, `recordMessage`); otherwise the addresses that error text names, such
+  as the recipient of an SMTP rejection, are redacted. A receipt returned to the application
+  keeps its full error text: logging it is the application's to scrub.
 - **Webhooks are verified.** A delivery event from a provider is accepted only with a valid
   signature and within a replay window.
 - **The audit log can forget a person.** Recipients are stored as a keyed hash and an encrypted
diff --git a/docs/transports/logger.md b/docs/transports/logger.md
index 3676972..26376d8 100644
--- a/docs/transports/logger.md
+++ b/docs/transports/logger.md
@@ -126,8 +126,12 @@ bindings you want (`logger.child({ component: 'mail' })`).
 
 ## Recording message content
 
-Messages are excluded from logs by default. The `recordMessage` option has two
-modes:
+Messages are excluded from logs by default, and so are the addresses that the
+error text of a failure names: with `recordMessage` off, `errorMessages`,
+`errors` and `receipt` are logged with every address replaced by `[REDACTED]`
+(`RCPT TO failed for [REDACTED]: 550 No such user`), and without the
+provider's raw response (`providerDetails`). The `recordMessage` option has two
+modes, both of which log the failure as it is:
 
 - `"properties"`: Adds the complete `Message` object to the structured properties
   of every lifecycle event. The log message itself remains on one line.
diff --git a/docs/transports/otel.md b/docs/transports/otel.md
index 2bab62c..b05c66d 100644
--- a/docs/transports/otel.md
+++ b/docs/transports/otel.md
@@ -370,6 +370,16 @@ These metrics are exported to your configured observability backend
 (Prometheus, DataDog, etc.) where you can create dashboards and alerts
 to monitor your email system's health.
 
+## Sensitive data
+
+With `tracing.recordSensitiveData` off, the default, a span records the sender's
+domain rather than its address, and the error text it records, in its status
+and in its `exception` and `email.send_failed` events, has every address
+replaced by `[REDACTED]`. An SMTP rejection such as
+`RCPT TO failed for bob@example.com: 550 No such user` is recorded as
+`RCPT TO failed for [REDACTED]: 550 No such user`. Turn the option on only for
+a backend where personal data is allowed.
+
 ## Error classification and analysis
 
 The OpenTelemetry transport includes intelligent error classification that
diff --git a/src/internal/redact-addresses.js b/src/internal/redact-addresses.js
new file mode 100644
index 0000000..91d4e44
--- /dev/null
+++ b/src/internal/redact-addresses.js
@@ -0,0 +1,68 @@
+// Not ported from upyo: keeps email addresses out of error text that goes to
+// telemetry and logs, such as an SMTP rejection naming its recipient.
+
+const REDACTED = '[REDACTED]';
+
+// The characters that end an address in free text: whitespace and controls,
+// quotes, brackets, and the separators of address lists and SMTP replies.
+const SEPARATOR = new Uint8Array(128);
+for (let code = 0; code <= 0x20; code++) SEPARATOR[code] = 1;
+for (const symbol of '"\'(),:;<>[\\]') SEPARATOR[symbol.charCodeAt(0)] = 1;
+SEPARATOR[0x7f] = 1;
+
+// How far a quoted local part or a domain literal is looked for: a local part
+// is at most 64 octets (RFC 5321 §4.5.3.1.1), plus its quotes or brackets.
+const MAX_BRACKETED_LENGTH = 66;
+
+const isAddressCharacter = (code) => code > 0x7f || SEPARATOR[code] !== 1;
+
+// The index where a quoted local part ending right before `at` opens, or `at`.
+const findQuotedStart = (text, at, floor) => {
+  if (text.charCodeAt(at - 1) !== 0x22) return at;
+  const limit = Math.max(floor, at - MAX_BRACKETED_LENGTH);
+  for (let i = at - 2; i >= limit; i--) {
+    if (text.charCodeAt(i) === 0x22) return i;
+  }
+  return at;
+};
+
+// The index after a domain literal starting right after `at`, or `at + 1`.
+const findLiteralEnd = (text, at) => {
+  if (text.charCodeAt(at + 1) !== 0x5b) return at + 1;
+  const limit = Math.min(text.length, at + MAX_BRACKETED_LENGTH);
+  for (let i = at + 2; i < limit; i++) {
+    if (text.charCodeAt(i) === 0x5d) return i + 1;
+  }
+  return at + 1;
+};
+
+/**
+ * Replaces every email address in a text with `[REDACTED]`.  It scans from
+ * each "@" to the separators around it, so it runs in linear time on any
+ * input, unlike a pattern that backtracks over a long run without an "@".
+ *
+ * @param text Free text, such as an error message.
+ * @returns The text without its addresses.
+ * @internal
+ */
+const redactAddresses = (text) => {
+  let result = '';
+  let copied = 0;
+  let at = text.indexOf('@');
+  while (at !== -1) {
+    let start = at;
+    while (start > copied && isAddressCharacter(text.charCodeAt(start - 1))) start--;
+    if (start === at) start = findQuotedStart(text, at, copied);
+    let end = at + 1;
+    while (end < text.length && isAddressCharacter(text.charCodeAt(end))) end++;
+    if (end === at + 1) end = findLiteralEnd(text, at);
+    if (start < at && end > at + 1) {
+      result += text.slice(copied, start) + REDACTED;
+      copied = end;
+    }
+    at = text.indexOf('@', end);
+  }
+  return copied === 0 ? text : result + text.slice(copied);
+};
+
+module.exports = { redactAddresses };
diff --git a/src/logger/logger-transport.js b/src/logger/logger-transport.js
index e3a3a73..6d0271d 100644
--- a/src/logger/logger-transport.js
+++ b/src/logger/logger-transport.js
@@ -3,6 +3,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { inspect } = require('node:util');
+const { redactAddresses } = require('../internal/redact-addresses.js');
 const { resolveLoggerTransportOptions } = require('./config.js');
 const { PendingQueue } = require('./pending-queue.js');
 
@@ -195,6 +196,7 @@ class LoggerTransport {
       return;
     }
 
+    const failure = this.config.recordMessage === false ? redactFailure(receipt) : receipt;
     this.log(
       this.config.levels.failed,
       this.getMessageText('Failed to send email.', pendingMessage?.message),
@@ -204,12 +206,12 @@ class LoggerTransport {
         operation,
         transportId: this.id,
         durationMilliseconds,
-        errorMessages: receipt.errorMessages,
-        errors: receipt.errors,
-        retryable: receipt.retryable,
-        provider: receipt.provider ?? this.id,
-        attempts: receipt.attempts,
-        receipt,
+        errorMessages: failure.errorMessages,
+        errors: failure.errors,
+        retryable: failure.retryable,
+        provider: failure.provider ?? this.id,
+        attempts: failure.attempts,
+        receipt: failure,
       },
     );
   }
@@ -286,6 +288,26 @@ class LoggerTransport {
   }
 }
 
+// Unless the message itself is logged, a failure is logged without the
+// addresses its error text names, such as the recipient of an SMTP rejection,
+// and without the provider's raw response.
+const redactFailure = (receipt) => {
+  const errorMessages = [];
+  for (const text of receipt.errorMessages) errorMessages.push(redactAddresses(text));
+  let errors = receipt.errors;
+  if (errors != null) {
+    errors = [];
+    for (const error of receipt.errors) {
+      errors.push({
+        ...error,
+        message: redactAddresses(error.message),
+        providerDetails: undefined,
+      });
+    }
+  }
+  return { ...receipt, errorMessages, errors };
+};
+
 const isAsyncDisposable = (value) => {
   return Symbol.asyncDispose in value && typeof value[Symbol.asyncDispose] === 'function';
 };
diff --git a/src/otel/attributes.js b/src/otel/attributes.js
index 56cf293..b00d9a3 100644
--- a/src/otel/attributes.js
+++ b/src/otel/attributes.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/opentelemetry/src/attributes.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { redactAddresses } = require('../internal/redact-addresses.js');
 const { estimateMessageSize } = require('./message-size.js');
 
 /**
@@ -167,6 +168,15 @@ class EmailAttributeExtractor {
     return attributes;
   }
 
+  /**
+   * Prepares error text for a span status or event: as it is when sensitive
+   * data is recorded, otherwise without the addresses it names, such as the
+   * recipient of an SMTP rejection.
+   */
+  describeError(text) {
+    return this.recordSensitiveData ? text : redactAddresses(text);
+  }
+
   detectContentType(message) {
     // If there are attachments, it's always multipart
     if (message.attachments.length > 0) {
diff --git a/src/otel/tracing.js b/src/otel/tracing.js
index cb8713f..ba03f56 100644
--- a/src/otel/tracing.js
+++ b/src/otel/tracing.js
@@ -104,9 +104,10 @@ class LiveEmailSpan {
 
   recordError(error, errorCategory) {
     // Set span status to error
+    const extractor = this.attributeExtractor;
     this.span.setStatus({
       code: SPAN_STATUS_ERROR,
-      message: error instanceof Error ? error.message : 'Unknown error',
+      message: error instanceof Error ? extractor.describeError(error.message) : 'Unknown error',
     });
 
     // Record error attributes
@@ -116,7 +117,9 @@ class LiveEmailSpan {
     // Add error event
     this.span.addEvent('exception', {
       'exception.type': error instanceof Error ? error.constructor.name : 'unknown',
-      'exception.message': error instanceof Error ? error.message : String(error),
+      'exception.message': extractor.describeError(
+        error instanceof Error ? error.message : String(error),
+      ),
     });
   }
 
@@ -149,9 +152,12 @@ class LiveEmailSpan {
   }
 
   recordFailure(errorMessages) {
+    const extractor = this.attributeExtractor;
+    const described = [];
+    for (const errorMessage of errorMessages) described.push(extractor.describeError(errorMessage));
     this.span.setStatus({
       code: SPAN_STATUS_ERROR,
-      message: errorMessages[0] || 'Send failed',
+      message: described[0] || 'Send failed',
     });
 
     this.span.setAttributes({
@@ -160,7 +166,7 @@ class LiveEmailSpan {
 
     this.span.addEvent('email.send_failed', {
       'error.count': errorMessages.length,
-      'error.messages': JSON.stringify(errorMessages),
+      'error.messages': JSON.stringify(described),
     });
   }
 
diff --git a/src/plunk/plunk-transport.js b/src/plunk/plunk-transport.js
index 6d8e72a..8e15b3f 100644
--- a/src/plunk/plunk-transport.js
+++ b/src/plunk/plunk-transport.js
@@ -212,18 +212,19 @@ class PlunkTransport {
    * @param message The original message for fallback ID generation.
    * @returns A message ID string.
    */
-  extractMessageId(response, message) {
+  extractMessageId(response, _message) {
     const emailId = response.emails?.[0]?.email;
     if (emailId) {
       return emailId;
     }
 
-    // Fallback: generate synthetic message ID
+    // Fallback: generate synthetic message ID.  Upstream put the first eight
+    // characters of the recipient's local part into it, personal data that
+    // receipts carry into logs.
     const timestamp = Date.now();
-    const recipientHash = message.recipients[0]?.address.split('@')[0].substring(0, 8) ?? 'unknown';
     const random = Math.random().toString(36).substring(2, 8);
 
-    return `plunk-${timestamp}-${recipientHash}-${random}`;
+    return `plunk-${timestamp}-${random}`;
   }
 }
 
diff --git a/tests/unit/logger.test.js b/tests/unit/logger.test.js
index 7701446..6a2754b 100644
--- a/tests/unit/logger.test.js
+++ b/tests/unit/logger.test.js
@@ -64,3 +64,38 @@ test('Logger: a pino logger records the lifecycle, with the error serialized', a
   assert.match(lines[1].err.stack, /TypeError: Connection refused\./);
   assert.strictEqual(lines[1].transportId, 'base');
 });
+
+test('Logger: unless the message is recorded, a failure is logged without addresses', async () => {
+  const failure = {
+    successful: false,
+    errorMessages: ['RCPT TO failed for bob@example.com: 550 No such user'],
+    errors: [
+      {
+        message: 'RCPT TO failed for bob@example.com: 550 No such user',
+        category: 'rejected',
+        retryable: false,
+        providerDetails: { response: '550 <bob@example.com> No such user' },
+      },
+    ],
+    retryable: false,
+  };
+  const transport = { id: 'smtp', send: async () => failure, async *sendMany() {} };
+  for (const recordMessage of [undefined, 'properties']) {
+    const calls = [];
+    const logger = {
+      debug: () => {},
+      info: () => {},
+      error: (properties) => calls.push(properties),
+    };
+    await new LoggerTransport({ logger, transport, recordMessage }).send(message());
+    const logged = JSON.stringify(calls[0]);
+    assert.strictEqual(logged.includes('bob@example.com'), recordMessage !== undefined, logged);
+    if (recordMessage === undefined) {
+      assert.deepStrictEqual(calls[0].errorMessages, [
+        'RCPT TO failed for [REDACTED]: 550 No such user',
+      ]);
+      assert.strictEqual(calls[0].errors[0].providerDetails, undefined);
+      assert.strictEqual(calls[0].errors[0].category, 'rejected');
+    }
+  }
+});
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index bbf753d..ca23755 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -110,3 +110,29 @@ test('OTel: a batch gets the custom attributes and records its failures', async
   assert.strictEqual(span.attributes['app.count'], 2);
   assert.strictEqual(span.status.code, 2);
 });
+
+test('OTel: without sensitive data, error text in spans names no address', async () => {
+  const rejection = 'RCPT TO failed for bob@example.com: 550 No such user';
+  const failure = { successful: false, errorMessages: [rejection], errors: [] };
+  const thrown = plain({});
+  thrown.send = async () => {
+    throw new Error(rejection);
+  };
+  for (const [transport, recordSensitiveData] of [
+    [plain({}, failure), false],
+    [thrown, false],
+    [plain({}, failure), true],
+  ]) {
+    const { tracerProvider, meterProvider } = providers();
+    const otel = new OpenTelemetryTransport(transport, {
+      tracerProvider,
+      meterProvider,
+      tracing: { recordSensitiveData },
+    });
+    await otel.send(createTestMessage()).catch(() => {});
+    const [span] = tracerProvider.getAllSpans();
+    const recorded = JSON.stringify({ status: span.status, events: span.events });
+    assert.strictEqual(recorded.includes('bob@example.com'), recordSensitiveData, recorded);
+    if (!recordSensitiveData) assert.match(recorded, /RCPT TO failed for \[REDACTED\]: 550/);
+  }
+});
diff --git a/tests/unit/plunk-transport.test.js b/tests/unit/plunk-transport.test.js
index 9e1c3ce..95fab0d 100644
--- a/tests/unit/plunk-transport.test.js
+++ b/tests/unit/plunk-transport.test.js
@@ -282,8 +282,9 @@ describe('PlunkTransport - fallback message ID', () => {
 
         assert.equal(receipt.successful, true);
         if (receipt.successful) {
-          assert.match(receipt.messageId, /^plunk-/);
-          assert.ok(receipt.messageId.includes('to'));
+          // Changed after the port: upstream put the start of the recipient's
+          // local part ("to") into the ID; it carries no personal data now.
+          assert.match(receipt.messageId, /^plunk-\d+-[a-z0-9]+$/);
         }
       },
     );
diff --git a/tests/unit/privacy.test.js b/tests/unit/privacy.test.js
new file mode 100644
index 0000000..78726e6
--- /dev/null
+++ b/tests/unit/privacy.test.js
@@ -0,0 +1,29 @@
+// Addresses stay out of the error text that ./otel and ./logger export by
+// default, such as an SMTP rejection naming its recipient.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { redactAddresses } = require('../../src/internal/redact-addresses.js');
+
+test('Privacy: every address in a text is redacted, and nothing else', () => {
+  assert.strictEqual(
+    redactAddresses('RCPT TO failed for bob@example.com: 550 5.1.1 <bob@example.com> unknown'),
+    'RCPT TO failed for [REDACTED]: 550 5.1.1 <[REDACTED]> unknown',
+  );
+  assert.strictEqual(
+    redactAddresses('a@b, "c d"@x.org; f@[192.0.2.1]'),
+    '[REDACTED], [REDACTED]; [REDACTED]',
+  );
+  assert.strictEqual(redactAddresses('user@пример.рф'), '[REDACTED]');
+  for (const text of ['Connection timeout', 'a lone @ sign', 'trailing@', '@leading', '']) {
+    assert.strictEqual(redactAddresses(text), text);
+  }
+});
+
+test('Privacy: redaction runs in linear time on a long text without an address', () => {
+  const long = `${'a'.repeat(200_000)}@`;
+  const started = performance.now();
+  assert.strictEqual(redactAddresses(long), long);
+  assert.strictEqual(redactAddresses('a@'.repeat(100_000)), '[REDACTED]');
+  assert.strictEqual(redactAddresses('"@['.repeat(100_000)).length, 300_000);
+  assert.ok(performance.now() - started < 1000);
+});

From aa0f94b7cda5bc821061424764eee62d74c70004 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:28:53 +0300
Subject: [PATCH 028/158] feat(core)!: mark a failed receipt whose delivery is
 unknown

A failed receipt can now carry `deliveryUnknown: true` (createFailedReceipt
option `deliveryUnknown`): the request or the message data went out but no
answer came back, so the message may have been accepted and sending it
again may deliver it twice. Such a receipt, and the errors made for it, are
never retryable. It is the `delivery_unknown` state of the roadmap's event
model, to be reconciled from delivery events rather than retried.

./retry does not retry it unless shouldRetry says so. ./pool stops failing
over at it and at an error of category validation or rejected, which every
provider would share; upstream failed over on any failed receipt, sending a
refused message to each transport in turn. The pool's own timeout now
produces an unknown delivery: upstream failed over after it, so the slow
transport and the next one could both deliver. Errors of the transport
itself (auth, rate limit, outage) still fail over.

Both decorators pin one Message-ID per message before the first attempt
(pinMessageId, with a WeakMap of copies, so the caller's message is left as
it is): each attempt used to compose a new one, so a duplicate could not be
told apart. The sender-rooted generator moves from the MIME builder to
src/core/message-id.js for that.

BREAKING CHANGE: a timeout of ./pool no longer fails over and its receipt
is no longer retryable; a pool no longer fails over at a rejected message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                      |  9 ++++
 CLAUDE.md                         |  6 +++
 docs/transports/pool.md           | 17 +++++++
 docs/transports/retry.md          |  6 +++
 index.d.ts                        | 15 ++++++
 src/core/message-id.js            | 79 ++++++++++++++++++++++++++++++-
 src/core/receipt.js               | 17 +++++--
 src/mime/message.js               | 42 +---------------
 src/pool/pool-transport.js        | 36 ++++++++++++--
 src/retry/retry-transport.js      | 11 ++++-
 tests/types/index.test-d.ts       |  6 +++
 tests/unit/core.test.js           | 11 +++++
 tests/unit/pool-transport.test.js |  6 ++-
 tests/unit/pool.test.js           | 56 ++++++++++++++++++++++
 tests/unit/retry.test.js          | 51 ++++++++++++++++++++
 15 files changed, 317 insertions(+), 51 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8a02b13..9471b27 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -83,6 +83,15 @@ listed in CLAUDE.md, to be fixed one by one.
 
 ### Fixed
 
+- **`./pool` and `./retry` no longer send a message twice where they can avoid it** (upstream
+  bugs). A failed receipt can now say `deliveryUnknown: true`, which makes it not retryable:
+  `./retry` does not retry it unless `shouldRetry` says so, and `./pool` does not pass it to
+  another transport. The pool's own timeout produces it (upstream failed over, so a slow
+  provider and the next one could both deliver). The pool also stops failing over at an error of
+  category `validation` or `rejected`, which every provider would share (upstream sent a
+  refused message to each transport in turn). Both decorators give a message without a
+  Message-ID one before the first attempt, so all attempts carry the same one.
+
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
   any step or after DATA; the greeting waits for a complete line; and a UTF-8 character split
diff --git a/CLAUDE.md b/CLAUDE.md
index 285cd7e..68b2df8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -177,6 +177,12 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     synthetic message ID held the recipient's local part. `src/internal/redact-addresses.js`
     (`redactAddresses`, linear time) scrubs the text unless `recordSensitiveData` (otel) or
     `recordMessage` (logger) is set.
+21. pool, retry: the pool failed over on any failed receipt, sending a refused message
+    (`validation`, `rejected`) to every transport, and on its own timeout, after which the slow
+    transport and the next could both deliver; each attempt of either decorator composed a new
+    Message-ID. A failed receipt may carry `deliveryUnknown: true` (never retryable); the pool
+    stops failover at it and at a message rejection, retry does not retry it, and both pin one
+    Message-ID per message (`pinMessageId`, `src/core/message-id.js`).
 
 ## Repository layout
 
diff --git a/docs/transports/pool.md b/docs/transports/pool.md
index b6e4d46..7fc8ef2 100644
--- a/docs/transports/pool.md
+++ b/docs/transports/pool.md
@@ -240,6 +240,23 @@ attempts, giving you complete visibility into what went wrong across all
 providers.  Structured errors use each child transport's provider `id`, so
 fallback failures remain tied to the transport that produced them.
 
+Failover moves on after a failure of the transport, such as an authentication
+error, a rate limit or an outage, and stops in two cases where another
+transport could not help:
+
+- **The message itself was refused**, an error of category `validation` or
+  `rejected`: another provider would refuse it too.  The receipt is not
+  retryable.
+- **The delivery is unknown** (`receipt.deliveryUnknown`): the transport timed
+  out, or lost its connection, after the message went out, so it may have
+  been accepted.  The pool's own `timeout` counts as such.  Another provider
+  could deliver the message a second time; reconcile it from the provider's
+  delivery events instead.
+
+Every attempt of one `send()` carries the same `Message-ID`: a message without
+one gets a generated one before the first attempt, so a recipient's server can
+tell a duplicate apart.
+
 ## Custom strategies
 
 For advanced use cases, you can implement custom routing strategies by
diff --git a/docs/transports/retry.md b/docs/transports/retry.md
index a2d88cf..1411cfc 100644
--- a/docs/transports/retry.md
+++ b/docs/transports/retry.md
@@ -80,6 +80,12 @@ its structured errors is marked retryable.  This includes common transient
 HTTP statuses such as `429`, `408`, and `5xx` when transports expose them as
 structured receipt errors.
 
+A receipt whose delivery is unknown (`receipt.deliveryUnknown`) is not
+retried: the message may have been accepted before the timeout or the lost
+connection, and another attempt could deliver it twice.  Every attempt carries
+the same `Message-ID`, generated before the first one when the message has
+none, so that a duplicate can be told apart.
+
 If a wrapped transport throws a transient error instead of returning a failed
 receipt, retry transport retries it using the same classifier used by
 *@alexify/mailer*.  After all attempts are exhausted, thrown delivery failures are
diff --git a/index.d.ts b/index.d.ts
index be7feec..6aba7c6 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -909,6 +909,16 @@ export type Receipt<TProviderId extends string = string> =
        * Whether retrying the same message may succeed.
        */
       readonly retryable?: boolean;
+      /**
+       * `true` when the transport cannot tell whether the message was
+       * accepted: the request or the message data went out, but no answer
+       * came back (a timeout or a closed connection after the end of `DATA`).
+       * Sending it again may deliver it twice, so such a receipt is never
+       * retryable, `./retry` does not retry it and `./pool` does not pass it
+       * to another transport; reconcile it from the provider's delivery
+       * events instead.
+       */
+      readonly deliveryUnknown?: boolean;
       /**
        * Provider or transport that produced this receipt.
        */
@@ -951,6 +961,11 @@ export interface CreateFailedReceiptOptions<
   readonly errors?: readonly ReceiptError<TProviderId>[];
   readonly attempts?: number;
   readonly timestamp?: string;
+  /**
+   * Marks the delivery as unknown; the receipt and the errors made for it are
+   * then not retryable.  See {@link Receipt}.
+   */
+  readonly deliveryUnknown?: boolean;
 }
 /**
  * Classifies an HTTP status code for delivery error handling.
diff --git a/src/core/message-id.js b/src/core/message-id.js
index 061368c..adb062c 100644
--- a/src/core/message-id.js
+++ b/src/core/message-id.js
@@ -297,4 +297,81 @@ const resolveThreadingHeaders = (message) => {
   return resolved;
 };
 
-module.exports = { generateMessageId, parseMessageId, formatMessageId, resolveThreadingHeaders };
+/**
+ * Generates an identifier rooted in the sender's domain.
+ *
+ * `parseAddress()` accepts spellings the identifier grammar does not, such as
+ * the trailing dot of a fully qualified name, which is dropped here.  A domain
+ * the grammar still refuses falls back to `localhost` rather than failing the
+ * send.  Uniqueness holds either way: the left half is a UUID.
+ *
+ * @param address The sender's address.
+ * @returns A bare message identifier.
+ * @internal
+ */
+const generateSenderMessageId = (address) => {
+  const domain = domainOf(address).replace(/\.$/, '');
+  try {
+    return generateMessageId(domain);
+  } catch {
+    return generateMessageId('localhost');
+  }
+};
+
+/**
+ * Extracts the domain of an address.
+ *
+ * The separator is the first at sign outside a quoted local part, since a
+ * quoted one may contain at signs of its own, as in `"a@b"@example.com`.
+ *
+ * @param address The address to read.
+ * @returns The domain, or the whole address when it carries no separator.
+ */
+const domainOf = (address) => {
+  let quoted = false;
+  for (let index = 0; index < address.length; index++) {
+    const character = address[index];
+    if (quoted && character === '\\') index++;
+    else if (character === '"') quoted = !quoted;
+    else if (!quoted && character === '@') return address.slice(index + 1);
+  }
+  return address;
+};
+
+// The copies of messages pinned to one Message-ID, keyed weakly: a copy lives
+// as long as the caller's message does.
+const pinnedMessages = new WeakMap();
+
+/**
+ * Gives a message one Message-ID for all of its attempts.  `./retry` and
+ * `./pool` send the same message more than once; without a fixed identifier
+ * each attempt would compose a new one, and a message delivered twice after
+ * an ambiguous failure would not read as one to its recipients' servers.
+ *
+ * @param message The message to send.
+ * @returns The message itself when it has a Message-ID, either as
+ * `messageId` or as a custom header; otherwise a copy carrying a generated
+ * one, the same copy on every call for the same message.
+ * @internal
+ */
+const pinMessageId = (message) => {
+  if (typeof message !== 'object' || message === null || message.sender == null) return message;
+  if (message.messageId !== undefined || message.headers?.get('Message-ID') != null) {
+    return message;
+  }
+  let pinned = pinnedMessages.get(message);
+  if (pinned === undefined) {
+    pinned = { ...message, messageId: generateSenderMessageId(message.sender.address) };
+    pinnedMessages.set(message, pinned);
+  }
+  return pinned;
+};
+
+module.exports = {
+  generateMessageId,
+  generateSenderMessageId,
+  parseMessageId,
+  pinMessageId,
+  formatMessageId,
+  resolveThreadingHeaders,
+};
diff --git a/src/core/receipt.js b/src/core/receipt.js
index 00a8a8e..e7ddbdc 100644
--- a/src/core/receipt.js
+++ b/src/core/receipt.js
@@ -179,12 +179,19 @@ const createReceiptError = (message, options = {}) => {
  * @returns A failed receipt.
  */
 const createFailedReceipt = (error, options = {}) => {
+  // When delivery is unknown, the message may have been accepted, so sending
+  // it again may deliver it twice: neither the receipt nor the errors made for
+  // it are retryable, whatever their classification says.
+  const deliveryUnknown = options.deliveryUnknown === true ? true : undefined;
+  const errorOptions = deliveryUnknown === true ? { ...options, retryable: false } : options;
   const errors =
     options.errors ??
     (typeof error === 'string'
-      ? [createReceiptError(error, options)]
+      ? [createReceiptError(error, errorOptions)]
       : Array.isArray(error)
-        ? error.map((item) => (typeof item === 'string' ? createReceiptError(item, options) : item))
+        ? error.map((item) =>
+            typeof item === 'string' ? createReceiptError(item, errorOptions) : item,
+          )
         : [error]);
   const errorMessages =
     typeof error === 'string'
@@ -192,7 +199,10 @@ const createFailedReceipt = (error, options = {}) => {
       : Array.isArray(error)
         ? error.map((item) => (typeof item === 'string' ? item : item.message))
         : errors.map((receiptError) => receiptError.message);
-  const retryable = options.retryable ?? errors.some((receiptError) => receiptError.retryable);
+  const retryable =
+    deliveryUnknown === true
+      ? false
+      : (options.retryable ?? errors.some((receiptError) => receiptError.retryable));
   const provider = options.provider ?? errors[0]?.provider;
 
   return omitUndefined({
@@ -200,6 +210,7 @@ const createFailedReceipt = (error, options = {}) => {
     errorMessages,
     errors,
     retryable,
+    deliveryUnknown,
     provider,
     attempts: options.attempts,
     timestamp: options.timestamp ?? new Date().toISOString(),
diff --git a/src/mime/message.js b/src/mime/message.js
index 293fd84..1a8342a 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -6,7 +6,7 @@ const { readAttachmentContent } = require('../core/attachment.js');
 const { checkAttachment } = require('../core/message.js');
 const {
   formatMessageId,
-  generateMessageId,
+  generateSenderMessageId,
   resolveThreadingHeaders,
 } = require('../core/message-id.js');
 const { resolveCalendarContent } = require('../core/calendar.js');
@@ -429,46 +429,6 @@ const resolveMessageId = (message) => {
   return formatMessageId(generateSenderMessageId(message.sender.address));
 };
 
-/**
- * Generates an identifier rooted in the sender's domain.
- *
- * `parseAddress()` accepts spellings the identifier grammar does not, such as
- * the trailing dot of a fully qualified name, which is dropped here.  A domain
- * the grammar still refuses falls back to `localhost` rather than failing the
- * send.  Uniqueness holds either way: the left half is a UUID.
- *
- * @param address The sender's address.
- * @returns A bare message identifier.
- */
-const generateSenderMessageId = (address) => {
-  const domain = domainOf(address).replace(/\.$/, '');
-  try {
-    return generateMessageId(domain);
-  } catch {
-    return generateMessageId('localhost');
-  }
-};
-
-/**
- * Extracts the domain of an address.
- *
- * The separator is the first at sign outside a quoted local part, since a
- * quoted one may contain at signs of its own, as in `"a@b"@example.com`.
- *
- * @param address The address to read.
- * @returns The domain, or the whole address when it carries no separator.
- */
-const domainOf = (address) => {
-  let quoted = false;
-  for (let index = 0; index < address.length; index++) {
-    const character = address[index];
-    if (quoted && character === '\\') index++;
-    else if (character === '"') quoted = !quoted;
-    else if (!quoted && character === '@') return address.slice(index + 1);
-  }
-  return address;
-};
-
 const dayNames = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
 
 const monthNames = [
diff --git a/src/pool/pool-transport.js b/src/pool/pool-transport.js
index fba7027..072862f 100644
--- a/src/pool/pool-transport.js
+++ b/src/pool/pool-transport.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { combineSignals } = require('../core/abort-signal.js');
+const { pinMessageId } = require('../core/message-id.js');
 const { createFailedReceipt, createReceiptError } = require('../core/receipt.js');
 const { createPoolConfig } = require('./config.js');
 const { RoundRobinStrategy } = require('./strategies/round-robin-strategy.js');
@@ -94,10 +95,16 @@ class PoolTransport {
    * @returns A promise that resolves to a receipt indicating success or failure.
    */
   async send(message, options) {
+    const pinned = pinMessageId(message);
     const attemptedIndices = new Set();
     const errorMessages = [];
     const errors = [];
     let checkCallerAbortBeforeFailure = false;
+    // Failover stops when another transport could only deliver the message a
+    // second time (delivery unknown) or would refuse it too (the message
+    // itself was rejected).
+    let deliveryUnknown = false;
+    let isRejected = false;
 
     for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
       // Check for cancellation
@@ -106,7 +113,7 @@ class PoolTransport {
       }
 
       // Select a transport
-      const selection = this.strategy.select(message, this.config.transports, attemptedIndices);
+      const selection = this.strategy.select(pinned, this.config.transports, attemptedIndices);
 
       if (!selection) {
         // No more transports available
@@ -122,7 +129,7 @@ class PoolTransport {
 
         let receipt;
         try {
-          receipt = await selection.entry.transport.send(message, sendOptions.options);
+          receipt = await selection.entry.transport.send(pinned, sendOptions.options);
         } catch (error) {
           if (sendOptions.abortedByCaller() && isCallerAbort(error, options?.signal)) {
             abortedByCaller = true;
@@ -140,6 +147,9 @@ class PoolTransport {
         errorMessages.push(...receipt.errorMessages);
         errors.push(...getReceiptErrors(receipt, selection.entry.transport.id));
         checkCallerAbortBeforeFailure = true;
+        deliveryUnknown = receipt.deliveryUnknown === true;
+        isRejected = hasMessageRejection(receipt.errors);
+        if (deliveryUnknown || isRejected) break;
       } catch (error) {
         // Handle transport errors
         if (abortedByCaller && isCallerAbort(error, options?.signal)) {
@@ -151,6 +161,8 @@ class PoolTransport {
           errorMessages.push(...thrownErrors.map((item) => item.message));
           errors.push(...thrownErrors);
           checkCallerAbortBeforeFailure = true;
+          isRejected = hasMessageRejection(thrownErrors);
+          if (isRejected) break;
           continue;
         }
 
@@ -166,10 +178,16 @@ class PoolTransport {
           createReceiptError(errorMessage, {
             provider: selection.entry.transport.id,
             category: abortError ? 'timeout' : undefined,
-            retryable: abortError ? true : undefined,
+            retryable: abortError ? false : undefined,
           }),
         );
         checkCallerAbortBeforeFailure ||= !abortError;
+        // A send cut short by the pool's timeout may already have been
+        // accepted: switching transports could deliver the message twice.
+        if (abortError) {
+          deliveryUnknown = true;
+          break;
+        }
       }
     }
 
@@ -184,6 +202,8 @@ class PoolTransport {
         provider: 'pool',
         errors: errors.length > 0 ? errors : undefined,
         attempts: attemptedIndices.size,
+        deliveryUnknown,
+        retryable: isRejected ? false : undefined,
       },
     );
   }
@@ -398,4 +418,14 @@ const isAbortError = (error) => {
   return error instanceof Error && error.name === 'AbortError';
 };
 
+// A rejection of the message itself, as opposed to one of the transport
+// (authentication, rate limit, outage), which another transport may not share.
+const hasMessageRejection = (errors) => {
+  if (errors == null) return false;
+  for (const error of errors) {
+    if (error.category === 'validation' || error.category === 'rejected') return true;
+  }
+  return false;
+};
+
 module.exports = { PoolTransport };
diff --git a/src/retry/retry-transport.js b/src/retry/retry-transport.js
index b6a3cdb..28b4b0d 100644
--- a/src/retry/retry-transport.js
+++ b/src/retry/retry-transport.js
@@ -7,6 +7,7 @@ const {
   createReceiptError,
 } = require('../core/receipt.js');
 const { combineSignals } = require('../core/abort-signal.js');
+const { pinMessageId } = require('../core/message-id.js');
 const { createRetryConfig } = require('./config.js');
 
 /**
@@ -46,13 +47,14 @@ class RetryTransport {
   async send(message, options) {
     options?.signal?.throwIfAborted();
 
+    const pinned = pinMessageId(message);
     let lastThrownError;
     for (let attempt = 1; attempt <= this.config.maxAttempts; attempt++) {
       options?.signal?.throwIfAborted();
 
       let receipt;
       try {
-        receipt = await this.wrappedTransport.send(message, options);
+        receipt = await this.wrappedTransport.send(pinned, options);
       } catch (error) {
         options?.signal?.throwIfAborted();
 
@@ -288,7 +290,10 @@ class RetryTransport {
     return {
       ...receipt,
       provider: receipt.provider ?? this.id,
-      retryable: receipt.retryable ?? this.hasRetryableError(receipt.errors),
+      retryable:
+        receipt.deliveryUnknown === true
+          ? false
+          : (receipt.retryable ?? this.hasRetryableError(receipt.errors)),
       attempts,
     };
   }
@@ -298,6 +303,8 @@ class RetryTransport {
     if (shouldRetry != null) {
       return shouldRetry({ kind: 'receipt', receipt });
     }
+    // The message may have been accepted: sending it again may deliver it twice.
+    if (receipt.deliveryUnknown === true) return false;
     if (receipt.retryable != null) return receipt.retryable;
     return this.hasRetryableError(receipt.errors);
   }
diff --git a/tests/types/index.test-d.ts b/tests/types/index.test-d.ts
index 4bae67e..bbe6048 100644
--- a/tests/types/index.test-d.ts
+++ b/tests/types/index.test-d.ts
@@ -50,6 +50,12 @@ const typedReceipt: Receipt<'sendgrid'> = createFailedReceipt('Too many requests
   statusCode: 429,
 });
 expectType<'sendgrid' | undefined>(typedReceipt.provider);
+const unknownDelivery = createFailedReceipt('Connection closed after DATA', {
+  deliveryUnknown: true,
+});
+if (!unknownDelivery.successful) {
+  expectType<boolean | undefined>(unknownDelivery.deliveryUnknown);
+}
 
 const transport: Transport<'smtp'> = {
   id: 'smtp',
diff --git a/tests/unit/core.test.js b/tests/unit/core.test.js
index b90a6d8..8fe8907 100644
--- a/tests/unit/core.test.js
+++ b/tests/unit/core.test.js
@@ -269,3 +269,14 @@ test('Raw message: a long message yields to the event loop while it is read', as
   for await (const chunk of iterateRawMessage(plan)) size += chunk.length;
   assert.strictEqual(size, text.length);
 });
+
+test('Receipt: an unknown delivery is never retryable, nor are the errors made for it', () => {
+  const receipt = createFailedReceipt('SMTP connection closed during DATA.', {
+    deliveryUnknown: true,
+    retryable: true,
+  });
+  assert.strictEqual(receipt.deliveryUnknown, true);
+  assert.strictEqual(receipt.retryable, false);
+  assert.strictEqual(receipt.errors[0].retryable, false);
+  assert.strictEqual('deliveryUnknown' in createFailedReceipt('Busy', { statusCode: 503 }), false);
+});
diff --git a/tests/unit/pool-transport.test.js b/tests/unit/pool-transport.test.js
index 4d7c994..416a367 100644
--- a/tests/unit/pool-transport.test.js
+++ b/tests/unit/pool-transport.test.js
@@ -652,7 +652,11 @@ describe('PoolTransport', () => {
       assert.ok(!receipt.successful);
       if (!receipt.successful) {
         assert.equal(receipt.errors?.[0]?.category, 'timeout');
-        assert.ok(receipt.retryable);
+        // Changed after the port: a send cut short by the pool's timeout may
+        // have been accepted, so its delivery is unknown and it is not
+        // retryable (upstream returned retryable: true).
+        assert.equal(receipt.deliveryUnknown, true);
+        assert.equal(receipt.retryable, false);
       }
     });
 
diff --git a/tests/unit/pool.test.js b/tests/unit/pool.test.js
index 6b8fb41..ebda8c5 100644
--- a/tests/unit/pool.test.js
+++ b/tests/unit/pool.test.js
@@ -67,3 +67,59 @@ test('Pool: a transport whose dispose throws does not fail the disposal', async
   });
   await pool[Symbol.asyncDispose]();
 });
+
+const failing = (receipt, sent = []) => ({
+  id: 'failing',
+  send: async (sentMessage) => {
+    sent.push(sentMessage);
+    return receipt;
+  },
+  async *sendMany() {},
+});
+const rejected = (category, extra = {}) => ({
+  successful: false,
+  errorMessages: [category],
+  errors: [{ message: category, category, code: category, retryable: category !== 'rejected' }],
+  ...extra,
+});
+
+test('Pool: failover stops at a rejected message or an unknown delivery, not at an auth failure', async () => {
+  for (const [first, isFailedOver] of [
+    [rejected('rejected'), false],
+    [rejected('validation'), false],
+    [rejected('timeout', { deliveryUnknown: true }), false],
+    [rejected('auth'), true],
+    [rejected('service-unavailable'), true],
+  ]) {
+    const second = [];
+    const pool = new PoolTransport({
+      strategy: 'priority',
+      transports: [
+        { transport: failing(first), priority: 2 },
+        { transport: failing({ successful: true, messageId: 'm2' }, second), priority: 1 },
+      ],
+    });
+    const receipt = await pool.send(message());
+    assert.strictEqual(second.length === 1, isFailedOver, first.errors[0].category);
+    assert.strictEqual(receipt.successful, isFailedOver);
+    if (!isFailedOver) {
+      assert.strictEqual(receipt.retryable, false);
+      assert.strictEqual(receipt.deliveryUnknown, first.deliveryUnknown);
+    }
+  }
+});
+
+test('Pool: every transport of a failover sends the same Message-ID', async () => {
+  const sent = [];
+  const pool = new PoolTransport({
+    strategy: 'priority',
+    transports: [
+      { transport: failing(rejected('auth'), sent), priority: 2 },
+      { transport: failing({ successful: true, messageId: 'm2' }, sent), priority: 1 },
+    ],
+  });
+  await pool.send(message());
+  assert.strictEqual(sent.length, 2);
+  assert.ok(sent[0].messageId);
+  assert.strictEqual(sent[0].messageId, sent[1].messageId);
+});
diff --git a/tests/unit/retry.test.js b/tests/unit/retry.test.js
index ac84e0b..bb0360b 100644
--- a/tests/unit/retry.test.js
+++ b/tests/unit/retry.test.js
@@ -97,3 +97,54 @@ test('Retry: the default wait rejects with an AbortError for a signal without a
   };
   await assert.rejects(wait({ delayMilliseconds: 10 }, signal), { name: 'AbortError' });
 });
+
+const unknownDelivery = {
+  successful: false,
+  errorMessages: ['Timed out after the request was sent'],
+  errors: [{ message: 'Timed out', category: 'timeout', code: 'timeout', retryable: true }],
+  deliveryUnknown: true,
+};
+
+test('Retry: a receipt of unknown delivery is not retried, unless shouldRetry says so', async () => {
+  const base = sequence(unknownDelivery, { successful: true, messageId: 'm1' });
+  const receipt = await new RetryTransport(base, { maxAttempts: 3 }).send(message());
+  assert.strictEqual(base.calls, 1);
+  assert.strictEqual(receipt.retryable, false);
+  assert.strictEqual(receipt.deliveryUnknown, true);
+
+  const opted = sequence(unknownDelivery, { successful: true, messageId: 'm1' });
+  const transport = new RetryTransport(opted, {
+    maxAttempts: 3,
+    shouldRetry: () => true,
+    wait: async () => {},
+  });
+  assert.strictEqual((await transport.send(message())).successful, true);
+  assert.strictEqual(opted.calls, 2);
+});
+
+test('Retry: every attempt sends the same Message-ID, without changing the message', async () => {
+  const ids = [];
+  const base = {
+    id: 'base',
+    send: async (sent) => {
+      ids.push(sent.messageId);
+      return ids.length < 3 ? failure(true) : { successful: true, messageId: 'm1' };
+    },
+    async *sendMany() {},
+  };
+  const original = message();
+  await new RetryTransport(base, { maxAttempts: 3, wait: async () => {} }).send(original);
+  assert.strictEqual(ids.length, 3);
+  assert.match(ids[0], /^[0-9a-f-]+@example\.com$/);
+  assert.deepStrictEqual(new Set(ids).size, 1);
+  assert.strictEqual(original.messageId, undefined);
+  const own = createMessage({
+    from: 'a@example.com',
+    to: 'b@example.com',
+    content: {},
+    messageId: 'own@example.com',
+  });
+  ids.length = 2;
+  await new RetryTransport(base, { maxAttempts: 1 }).send(own);
+  assert.strictEqual(ids[2], 'own@example.com');
+});

From 2c2a3b59437645dc0abe890e3280b4d57ad2980c Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:32:50 +0300
Subject: [PATCH 029/158] fix(smtp): report a failure after the end of DATA as
 of unknown delivery

A connection that closed, timed out or failed after the terminating dot of
DATA went out raised the same error as one before it ("SMTP connection
closed during DATA.", "SMTP DATA timeout."), which classifies as a
retryable network or timeout failure. The server may well have accepted the
message by then, so a retry, by ./retry or by the application, could deliver
it twice.

writeMessageData now wraps any failure after the dot is written in an
SmtpDeliveryUnknownError (with the failure as its cause), and
createSmtpFailure turns it into a receipt with deliveryUnknown, the code
smtp.delivery-unknown and the category of the cause. A failure before the
dot is unchanged and stays retryable. The flat test of a reply over 64 KiB
after the dot now expects it.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  4 +++
 CLAUDE.md                  |  3 ++
 docs/transports/smtp.md    |  6 ++++
 src/smtp/data-stream.js    | 27 +++++++++++++++--
 src/smtp/smtp-transport.js | 12 +++++++-
 tests/unit/smtp.test.js    | 61 ++++++++++++++++++++++++++++++++++++--
 6 files changed, 107 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9471b27..5df450c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -91,6 +91,10 @@ listed in CLAUDE.md, to be fixed one by one.
   category `validation` or `rejected`, which every provider would share (upstream sent a
   refused message to each transport in turn). Both decorators give a message without a
   Message-ID one before the first attempt, so all attempts carry the same one.
+- **`./smtp` marks a failure after the end of DATA as of unknown delivery** (an upstream bug): a
+  connection that closed or timed out after the terminating dot was a retryable network or
+  timeout failure, like one before it, so a retry could deliver the message twice. It is now
+  `deliveryUnknown` with the code `smtp.delivery-unknown`.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index 68b2df8..b13c971 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -183,6 +183,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     Message-ID. A failed receipt may carry `deliveryUnknown: true` (never retryable); the pool
     stops failover at it and at a message rejection, retry does not retry it, and both pin one
     Message-ID per message (`pinMessageId`, `src/core/message-id.js`).
+22. smtp: a connection that closed or timed out after the terminating dot of DATA failed with
+    the same retryable error as one before it. `writeMessageData` wraps a failure after the dot
+    in `SmtpDeliveryUnknownError`, which `createSmtpFailure` turns into `deliveryUnknown`.
 
 ## Repository layout
 
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index 80b9ad8..88399f7 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -231,6 +231,12 @@ network/routing statuses use `network`.  Other subjects retain the category
 derived from the traditional reply class.  A `4.x.x` code remains retryable and
 a `5.x.x` code remains non-retryable.
 
+A connection that closes, times out or fails after the end of the message data
+went out (the terminating dot) leaves it unknown whether the server accepted
+the message.  Such a failure has the code `smtp.delivery-unknown`, is marked
+`deliveryUnknown: true` and is not retryable, since sending it again could
+deliver it twice.  The same failure before the dot stays retryable.
+
 The enhanced code must appear at the start of the reply text, use fields of one
 to three digits without leading zeroes, and have the same class as the
 three-digit SMTP reply.  If any condition is not met, @alexify/mailer preserves the reply
diff --git a/src/smtp/data-stream.js b/src/smtp/data-stream.js
index f587514..01d0838 100644
--- a/src/smtp/data-stream.js
+++ b/src/smtp/data-stream.js
@@ -5,6 +5,25 @@ const { combineSignals } = require('../core/abort-signal.js');
 const { Buffer } = require('node:buffer');
 
 /** Races preparation against source inactivity and remote socket termination. */
+/**
+ * Error produced when the connection fails after the end of the message data
+ * went out: the server may have accepted the message, so whether it was
+ * delivered is unknown, and sending it again may deliver it twice.
+ */
+class SmtpDeliveryUnknownError extends Error {
+  /**
+   * @param cause The failure of the connection: a close, a timeout or a
+   * socket error.
+   */
+  constructor(cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    super(`${reason} The message data had been sent; the server may have accepted it.`, {
+      cause,
+    });
+    this.name = 'SmtpDeliveryUnknownError';
+  }
+}
+
 const prepareOnSocket = async (socket, timeoutMs, prepare, signal) => {
   const controller = new AbortController();
   const combined = combineSignals(controller.signal, signal);
@@ -60,8 +79,12 @@ const writeMessageData = async (socket, source, timeoutMs, checkSize, signal) =>
   const lines = [];
   let resolveReply;
   const reply = new Promise((resolve) => (resolveReply = resolve));
+  // Once the terminating dot is on its way, a failure of the connection can
+  // no longer tell whether the server accepted the message.
   const fail = (error) => {
-    if (!owned.aborted) controller.abort(error);
+    if (!owned.aborted) {
+      controller.abort(terminated ? new SmtpDeliveryUnknownError(error) : error);
+    }
     socket.destroy();
   };
   const close = () => fail(new TypeError('SMTP connection closed during DATA.'));
@@ -202,4 +225,4 @@ const writeMessageData = async (socket, source, timeoutMs, checkSize, signal) =>
   }
 };
 
-module.exports = { prepareOnSocket, writeMessageData };
+module.exports = { SmtpDeliveryUnknownError, prepareOnSocket, writeMessageData };
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index 8fa60bf..0f85d09 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -2,7 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { prepareRawSmtpMessage, Smtp8BitMimeUnsupportedError } = require('./raw-message.js');
-const { createFailedReceipt } = require('../core/receipt.js');
+const { classifyReceiptError, createFailedReceipt } = require('../core/receipt.js');
 const { createRawMessagePlan, RawMessageValidationError } = require('../core/raw-message.js');
 const {
   resolveSmtpDsn,
@@ -20,6 +20,7 @@ const { resolveSmtpEnvelope, SmtpEnvelopeValidationError } = require('./envelope
 const { OAuth2TokenManager } = require('./oauth2.js');
 const { prepareMessage } = require('./message-converter.js');
 const { SmtpAttachmentReplayError } = require('./message-stream.js');
+const { SmtpDeliveryUnknownError } = require('./data-stream.js');
 const { validateDkimBodyMode } = require('../mime/dkim/types.js');
 const { parseEnhancedSmtpStatusCode } = require('./smtp-status-code.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
@@ -768,6 +769,15 @@ class SmtpTransport {
 }
 
 const createSmtpFailure = (message, error) => {
+  if (error instanceof SmtpDeliveryUnknownError) {
+    return createFailedReceipt(message, {
+      provider: 'smtp',
+      code: 'smtp.delivery-unknown',
+      category: classifyReceiptError(error.cause).category,
+      deliveryUnknown: true,
+      attempts: 1,
+    });
+  }
   if (error instanceof RawMessageValidationError) {
     return createFailedReceipt(message, {
       provider: 'smtp',
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 8d78461..ff03f60 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -284,7 +284,7 @@ test('SMTP: message preparation fails on a socket that is already closed', async
   );
 });
 
-test('SMTP: the DATA writer refuses a reply over 64 KiB', async () => {
+test('SMTP: the DATA writer refuses a reply over 64 KiB, of unknown delivery', async () => {
   const socket = fakeSocket({
     write(chunk, callback) {
       if (chunk.toString() === '.\r\n') {
@@ -297,11 +297,66 @@ test('SMTP: the DATA writer refuses a reply over 64 KiB', async () => {
   const source = async function* () {
     yield Buffer.from('Subject: x\r\n\r\nbody\r\n');
   };
+  // The reply comes after the terminating dot, so the message may have been
+  // accepted before the server went wrong.
+  await assert.rejects(
+    writeMessageData(socket, source, 1000, () => {}),
+    (error) => {
+      assert.strictEqual(error.name, 'SmtpDeliveryUnknownError');
+      assert.strictEqual(error.cause.name, 'RangeError');
+      assert.strictEqual(error.cause.message, 'SMTP DATA reply exceeds 64 KiB.');
+      return true;
+    },
+  );
+});
+
+test('SMTP: a connection lost after the end of DATA is a receipt of unknown delivery', async () => {
+  for (const [onEnd, category] of [
+    [(socket) => socket.destroy(), 'network'],
+    [() => {}, 'timeout'],
+  ]) {
+    const reply = transaction(okReply);
+    const { server, port } = await scripted((line, socket) => {
+      if (line === '.') onEnd(socket);
+      else reply(line, socket);
+    });
+    try {
+      const transport = new SmtpTransport({
+        host: '127.0.0.1',
+        port,
+        pool: false,
+        socketTimeout: 300,
+      });
+      const receipt = await transport.send(message());
+      await transport.closeAllConnections();
+      assert.strictEqual(receipt.successful, false);
+      assert.strictEqual(receipt.deliveryUnknown, true, receipt.errorMessages.join(' | '));
+      assert.strictEqual(receipt.retryable, false);
+      assert.strictEqual(receipt.errors[0].category, category);
+      assert.strictEqual(receipt.errors[0].code, 'smtp.delivery-unknown');
+    } finally {
+      await stop(server);
+    }
+  }
+});
+
+test('SMTP: a connection lost before the end of DATA is a plain failure', async () => {
+  const socket = fakeSocket({
+    write(chunk, callback) {
+      callback?.();
+      return true;
+    },
+  });
+  const source = async function* () {
+    yield Buffer.from('Subject: x\r\n\r\n');
+    socket.emit('close');
+    await new Promise(() => {});
+  };
   await assert.rejects(
     writeMessageData(socket, source, 1000, () => {}),
     {
-      name: 'RangeError',
-      message: 'SMTP DATA reply exceeds 64 KiB.',
+      name: 'TypeError',
+      message: 'SMTP connection closed during DATA.',
     },
   );
 });

From 3d1cada2b45996cf9084bc168783da6db5e96847 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:37:33 +0300
Subject: [PATCH 030/158] fix(jmap): send the request that submits an email
 only once

send() and sendMany() went through a client built with replayable requests,
so a network failure or a timeout on the request that creates and submits
the email (Email/set with EmailSubmission/set) retried it, up to `retries`
times: a lost answer could submit the message twice. Only sendRaw() avoided
that.

That request now goes through a submission client with no retries, still
with a string body (a streamed one would turn a 401 into a network error on
Node 24, known bug 14). A failure without an answer from the server marks
the receipt deliveryUnknown, unless the connection was never made: JmapApiError
now keeps the failure as its cause, and src/internal/unsent.js finds a
refused connection, an unknown host or a rejected certificate in that chain,
after which the request certainly never left and stays retryable. The
session, mailbox and identity requests keep their retries.

An upstream bug, recorded in CLAUDE.md; the two ported tests that pinned
the retry now expect a single attempt of unknown delivery.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                           |  4 +++
 CLAUDE.md                              |  7 ++++-
 docs/transports/jmap.md                |  7 +++++
 src/internal/unsent.js                 | 39 ++++++++++++++++++++++++++
 src/jmap/errors.js                     | 12 ++++++--
 src/jmap/http-client.js                |  4 +++
 src/jmap/index.d.ts                    |  1 +
 src/jmap/jmap-transport.js             | 27 ++++++++++++++++--
 tests/unit/internal.test.js            | 26 +++++++++++++++++
 tests/unit/jmap-retry-attempts.test.js |  8 ++++--
 tests/unit/jmap-send-error.test.js     | 10 +++++--
 tests/unit/jmap.test.js                | 20 +++++++++++++
 12 files changed, 155 insertions(+), 10 deletions(-)
 create mode 100644 src/internal/unsent.js
 create mode 100644 tests/unit/internal.test.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5df450c..45d3de3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -95,6 +95,10 @@ listed in CLAUDE.md, to be fixed one by one.
   connection that closed or timed out after the terminating dot was a retryable network or
   timeout failure, like one before it, so a retry could deliver the message twice. It is now
   `deliveryUnknown` with the code `smtp.delivery-unknown`.
+- **`./jmap` no longer replays the request that submits an email** (an upstream bug): `send` and
+  `sendMany` retried `Email/set` with `EmailSubmission/set` after a network failure, which could
+  submit the message twice. That request is now sent once; a failure without an answer is
+  `deliveryUnknown`, unless the connection was never made. `JmapApiError` takes a `cause`.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index b13c971..a8b801a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -186,6 +186,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 22. smtp: a connection that closed or timed out after the terminating dot of DATA failed with
     the same retryable error as one before it. `writeMessageData` wraps a failure after the dot
     in `SmtpDeliveryUnknownError`, which `createSmtpFailure` turns into `deliveryUnknown`.
+23. jmap: `send` and `sendMany` retried the request that creates and submits emails, as only
+    `sendRaw` avoided. It goes through `submissionClient` (no retries); an unanswered failure is
+    `deliveryUnknown` unless `isUnsentRequestError` (`src/internal/unsent.js`) finds a connection
+    that was never made in its causes, which `JmapApiError` now keeps.
 
 ## Repository layout
 
@@ -195,7 +199,8 @@ src/
   index.js          public barrel (explicit named exports)
   version.js        the package name and version (OpenTelemetry scope), kept equal to package.json
   <subpath>/        one directory per subpath: index.js + index.d.ts + its modules
-  internal/         private modules shared by subpaths, not in the exports map (redact.js)
+  internal/         private modules shared by subpaths, not in the exports map (redact.js,
+                    redact-addresses.js, unsent.js)
 tests/
   unit/*.test.js    node:test suites, one per area (<subpath>-<module>.test.js for a subpath)
   helpers/<sub>/    shared test code of a subpath (fake servers, fixtures builders)
diff --git a/docs/transports/jmap.md b/docs/transports/jmap.md
index 660797b..6a99de8 100644
--- a/docs/transports/jmap.md
+++ b/docs/transports/jmap.md
@@ -258,6 +258,13 @@ The transport uses exponential backoff for retries, with delays of 1s,
 2s, 4s, etc. between attempts. Client errors (4xx responses) are not
 retried, as they typically indicate a problem with the request itself.
 
+The request that creates and submits the email (`Email/set` with
+`EmailSubmission/set`) is the exception: it is sent once, since a retry after a
+lost answer could submit the message twice.  If it fails without an answer
+from the server, the receipt is marked `deliveryUnknown: true` and is not
+retryable, unless the connection was never made (a refused connection, an
+unknown host, a rejected certificate), in which case it stays retryable.
+
 ### URL rewriting
 
 Some JMAP servers may return internal hostnames in session URLs that are
diff --git a/src/internal/unsent.js b/src/internal/unsent.js
new file mode 100644
index 0000000..af1e1cf
--- /dev/null
+++ b/src/internal/unsent.js
@@ -0,0 +1,39 @@
+// Not ported from upyo: tells a request that never left from one that may
+// have reached the server, for a request that must not be sent twice.
+
+// System error codes of a connection that was never made, so no request went
+// out: a refused connection, an unknown or unreachable host.  A certificate
+// rejected during the TLS handshake also ends the connection before it.
+const UNSENT_CODES = new Set([
+  'ECONNREFUSED',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+]);
+
+const isUnsentCode = (code) =>
+  typeof code === 'string' && (UNSENT_CODES.has(code) || code.includes('CERT'));
+
+/**
+ * Whether a failed request certainly never reached the server: somewhere in
+ * its chain of causes is the code of a connection that was never made, as
+ * `fetch` reports it (`TypeError: fetch failed`, caused by the socket error).
+ * Any other failure without a response, such as a timeout or a reset, may
+ * have come after the server received the request.
+ *
+ * @param error The failure of the request.
+ * @returns `true` when the request was never sent.
+ * @internal
+ */
+const isUnsentRequestError = (error) => {
+  let current = error;
+  for (let depth = 0; depth < 4 && current != null; depth++) {
+    if (isUnsentCode(current.code)) return true;
+    current = current.cause;
+  }
+  return false;
+};
+
+module.exports = { isUnsentRequestError };
diff --git a/src/jmap/errors.js b/src/jmap/errors.js
index 6f5c72b..a2aef7e 100644
--- a/src/jmap/errors.js
+++ b/src/jmap/errors.js
@@ -11,8 +11,16 @@ class JmapApiError extends Error {
   retryAfterMilliseconds;
   attempts;
 
-  constructor(message, statusCode, responseBody, jmapErrorType, retryAfterMilliseconds, attempts) {
-    super(message);
+  constructor(
+    message,
+    statusCode,
+    responseBody,
+    jmapErrorType,
+    retryAfterMilliseconds,
+    attempts,
+    options,
+  ) {
+    super(message, options);
     this.name = 'JmapApiError';
     this.statusCode = statusCode;
     this.responseBody = responseBody;
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index 50c1868..e555bce 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -121,6 +121,8 @@ class JmapHttpClient {
           if (error instanceof JmapApiError) {
             throw error;
           }
+          // The cause tells a request that never left (a refused connection)
+          // from one that may have reached the server.
           if (isAbortError(error)) {
             throw new JmapApiError(
               'JMAP request timed out.',
@@ -129,6 +131,7 @@ class JmapHttpClient {
               undefined,
               undefined,
               attempt + 1,
+              { cause: error },
             );
           }
           throw new JmapApiError(
@@ -138,6 +141,7 @@ class JmapHttpClient {
             undefined,
             undefined,
             attempt + 1,
+            { cause: error },
           );
         }
 
diff --git a/src/jmap/index.d.ts b/src/jmap/index.d.ts
index 1b83963..b4f53cb 100644
--- a/src/jmap/index.d.ts
+++ b/src/jmap/index.d.ts
@@ -173,6 +173,7 @@ export declare class JmapApiError extends Error {
     jmapErrorType?: string,
     retryAfterMilliseconds?: number,
     attempts?: number,
+    options?: { readonly cause?: unknown },
   );
 }
 /**
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index 6f3fec1..aefbb5e 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -11,6 +11,7 @@ const { uploadBlob } = require('./blob-uploader.js');
 const { createJmapConfig } = require('./config.js');
 const { JmapApiError } = require('./errors.js');
 const { JmapHttpClient } = require('./http-client.js');
+const { isUnsentRequestError } = require('../internal/unsent.js');
 const { convertMessage } = require('./message-converter.js');
 const { findMailAccount } = require('./session.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
@@ -41,6 +42,9 @@ class JmapTransport {
   constructor(config) {
     this.config = createJmapConfig(config);
     this.httpClient = new JmapHttpClient(this.config);
+    // The request that creates and submits the email is never replayed: a
+    // retry after a lost answer could submit the message twice.
+    this.submissionClient = new JmapHttpClient({ ...this.config, retries: 0 });
   }
 
   /**
@@ -207,7 +211,8 @@ class JmapTransport {
       const emailCreate = convertMessage(message, draftsMailboxId, uploadedBlobs);
 
       // Execute Email/set + EmailSubmission/set batch request
-      const response = await this.httpClient.executeRequest(
+      const response = await executeSubmission(
+        this.submissionClient,
         session.apiUrl,
         {
           using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.mail, JMAP_CAPABILITIES.submission],
@@ -434,7 +439,8 @@ class JmapTransport {
 
       // Execute batch request
       processingStage = 'batch request execution';
-      const response = await this.httpClient.executeRequest(
+      const response = await executeSubmission(
+        this.submissionClient,
         session.apiUrl,
         {
           using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.mail, JMAP_CAPABILITIES.submission],
@@ -869,6 +875,22 @@ class JmapTransport {
   }
 }
 
+// The submission errors after which the message may have been submitted.
+const unansweredSubmissions = new WeakSet();
+
+// Sends the request that creates and submits emails.  A failure without an
+// answer from the server, unless the connection was never made, leaves it
+// unknown whether the server submitted them.
+const executeSubmission = async (client, apiUrl, request, signal) => {
+  try {
+    return await client.executeRequest(apiUrl, request, signal);
+  } catch (error) {
+    const isUnanswered = error instanceof JmapApiError && error.statusCode === undefined;
+    if (isUnanswered && !isUnsentRequestError(error)) unansweredSubmissions.add(error);
+    throw error;
+  }
+};
+
 const createJmapFailure = (message, error, override = {}) => {
   const attempts = getAttemptCount(error);
 
@@ -885,6 +907,7 @@ const createJmapFailure = (message, error, override = {}) => {
       category: override.category,
       code: override.code,
       retryable: override.retryable,
+      deliveryUnknown: unansweredSubmissions.has(error),
     });
   }
 
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
new file mode 100644
index 0000000..c6116e7
--- /dev/null
+++ b/tests/unit/internal.test.js
@@ -0,0 +1,26 @@
+// The private modules of src/internal/ that the subpaths share.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { isUnsentRequestError } = require('../../src/internal/unsent.js');
+
+const fetchFailed = (code) =>
+  new TypeError('fetch failed', { cause: Object.assign(new Error(code), { code }) });
+
+test('Internal: a request whose connection was never made was not sent', () => {
+  for (const code of ['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'CERT_HAS_EXPIRED']) {
+    assert.strictEqual(isUnsentRequestError(fetchFailed(code)), true, code);
+  }
+  const wrapped = new Error('JMAP request failed', { cause: fetchFailed('ECONNREFUSED') });
+  assert.strictEqual(isUnsentRequestError(wrapped), true);
+});
+
+test('Internal: a reset, a timeout or a failure without a cause may have been sent', () => {
+  for (const error of [
+    fetchFailed('ECONNRESET'),
+    new DOMException('The operation timed out.', 'TimeoutError'),
+    new TypeError('fetch failed'),
+    null,
+  ]) {
+    assert.strictEqual(isUnsentRequestError(error), false);
+  }
+});
diff --git a/tests/unit/jmap-retry-attempts.test.js b/tests/unit/jmap-retry-attempts.test.js
index 727cbf6..1b18620 100644
--- a/tests/unit/jmap-retry-attempts.test.js
+++ b/tests/unit/jmap-retry-attempts.test.js
@@ -20,7 +20,10 @@ const baseMessage = {
 };
 
 describe('JmapTransport retry attempts', () => {
-  it('should preserve attempt counts from retried network failures', async () => {
+  // Changed after the port: the request that creates and submits the email is
+  // no longer retried, as a retry after a lost answer could submit it twice;
+  // upstream retried it (two attempts here).
+  it('should not retry a failed submission, whose delivery is unknown', async () => {
     const originalFetch = globalThis.fetch;
 
     try {
@@ -118,7 +121,8 @@ describe('JmapTransport retry attempts', () => {
       const receipt = await transport.send(baseMessage);
 
       assert.ok(!receipt.successful);
-      assert.equal(receipt.attempts, 2);
+      assert.equal(receipt.attempts, 1);
+      assert.equal(receipt.deliveryUnknown, true);
     } finally {
       globalThis.fetch = originalFetch;
     }
diff --git a/tests/unit/jmap-send-error.test.js b/tests/unit/jmap-send-error.test.js
index 07488c3..d68d3ca 100644
--- a/tests/unit/jmap-send-error.test.js
+++ b/tests/unit/jmap-send-error.test.js
@@ -53,7 +53,10 @@ describe('JmapTransport send error', () => {
     }
   });
 
-  it('should return retryable timeout receipts for request timeouts', async () => {
+  // Changed after the port: the submission request timed out after it went
+  // out, so the server may have submitted the message; upstream returned a
+  // retryable receipt.
+  it('should return unknown-delivery timeout receipts for request timeouts', async () => {
     const originalFetch = globalThis.fetch;
 
     try {
@@ -156,9 +159,10 @@ describe('JmapTransport send error', () => {
       assert.ok(!receipt.successful);
       if (!receipt.successful) {
         assert.equal(receipt.provider, 'jmap');
-        assert.equal(receipt.retryable, true);
+        assert.equal(receipt.retryable, false);
+        assert.equal(receipt.deliveryUnknown, true);
         assert.equal(receipt.errors?.[0]?.category, 'timeout');
-        assert.equal(receipt.errors?.[0]?.retryable, true);
+        assert.equal(receipt.errors?.[0]?.retryable, false);
         assert.equal(receipt.errors?.[0]?.code, 'timeout');
         assert.equal(receipt.errors?.[0]?.provider, 'jmap');
       }
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index 5a7a374..95ca643 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -165,3 +165,23 @@ test('JMAP: verification refuses a session without the submission capability', a
   serve(t, { session: session({ capabilities: { [CORE]: {}, [MAIL]: {} } }) });
   await assert.rejects(transport().verify(), /lacks core, mail, or submission capability/);
 });
+
+test('JMAP: a submission is sent once; it stays retryable only if it never left', async (t) => {
+  for (const [code, isUnknown] of [
+    ['ECONNREFUSED', false],
+    ['ECONNRESET', true],
+  ]) {
+    const calls = serve(t, {
+      'Email/set': () => {
+        const cause = Object.assign(new Error(code), { code });
+        throw new TypeError('fetch failed', { cause });
+      },
+    });
+    const receipt = await transport({ retries: 3 }).send(message());
+    assert.strictEqual(receipt.successful, false);
+    assert.strictEqual(calls.filter((call) => call === 'Email/set').length, 1);
+    assert.strictEqual(receipt.deliveryUnknown, isUnknown ? true : undefined, code);
+    assert.strictEqual(receipt.retryable, !isUnknown, code);
+    t.mock.restoreAll();
+  }
+});

From 1eb6bfe64cec7b79acd290a3c1936b42c13f7146 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:42:52 +0300
Subject: [PATCH 031/158] fix: never send a message again after a provider
 answered 2xx

Seven HTTP clients retried a request after the provider had answered it
with a 2xx: when the body of the response could not be read (a reset or a
timeout after the headers) or parsed, when SES or SendGrid answered a 2xx
other than the 200 or 202 they expect, and when Plunk answered
`success: false` in a 200. The provider had taken the request, so each
retry could deliver the message again.

Each client now notes the 2xx of an attempt and, if anything fails after
it, throws instead of retrying, with the failure marked through
src/internal/delivery-unknown.js (a WeakSet, so no public error class
changes); the transports report such a failure as deliveryUnknown, and so
does ./mailtrap for its existing MailtrapResponseError. Plunk's explicit
refusal is a PlunkApiError carrying the 200, a non-retryable failure rather
than an unknown delivery. ./jmap marks its unanswered submissions through
the same helper.

A timeout or a reset before any answer is still retried by these clients;
telling a request that never left from one that may have arrived needs the
shared HTTP client of Phase B. An upstream bug, recorded in CLAUDE.md; the
ported Maileroo test of a body timeout after a 200 now expects an unknown
delivery.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                           |  6 ++
 CLAUDE.md                              |  8 ++-
 src/internal/delivery-unknown.js       | 30 +++++++++
 src/jmap/jmap-transport.js             |  9 +--
 src/lettermint/http-client.js          |  7 +++
 src/lettermint/lettermint-transport.js |  4 ++
 src/maileroo/http-client.js            | 23 ++++---
 src/maileroo/maileroo-transport.js     |  4 ++
 src/mailgun/http-client.js             |  7 +++
 src/mailgun/mailgun-transport.js       |  3 +
 src/mailtrap/mailtrap-transport.js     |  1 +
 src/plunk/http-client.js               | 15 ++++-
 src/plunk/plunk-transport.js           |  3 +
 src/resend/http-client.js              |  7 +++
 src/resend/resend-transport.js         |  3 +
 src/sendgrid/http-client.js            |  7 +++
 src/sendgrid/sendgrid-transport.js     |  3 +
 src/ses/http-client.js                 |  7 +++
 src/ses/ses-transport.js               |  3 +
 tests/unit/delivery.test.js            | 84 ++++++++++++++++++++++++++
 tests/unit/maileroo-transport.test.js  |  6 +-
 21 files changed, 223 insertions(+), 17 deletions(-)
 create mode 100644 src/internal/delivery-unknown.js
 create mode 100644 tests/unit/delivery.test.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 45d3de3..67ada6f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -99,6 +99,12 @@ listed in CLAUDE.md, to be fixed one by one.
   `sendMany` retried `Email/set` with `EmailSubmission/set` after a network failure, which could
   submit the message twice. That request is now sent once; a failure without an answer is
   `deliveryUnknown`, unless the connection was never made. `JmapApiError` takes a `cause`.
+- **The HTTP providers no longer send a message again after a 2xx** (an upstream bug): `./ses`,
+  `./resend`, `./sendgrid`, `./mailgun`, `./maileroo`, `./lettermint` and `./plunk` retried when
+  the body of a successful response could not be read or parsed, or when SES or SendGrid answered
+  a 2xx other than the one they expect, though the provider had taken the request. Such a failure
+  is now `deliveryUnknown` (so is `./mailtrap`'s unreadable success); Plunk's `success: false` in a
+  200 is a non-retryable failure.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index a8b801a..df0c79f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -190,6 +190,12 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     `sendRaw` avoided. It goes through `submissionClient` (no retries); an unanswered failure is
     `deliveryUnknown` unless `isUnsentRequestError` (`src/internal/unsent.js`) finds a connection
     that was never made in its causes, which `JmapApiError` now keeps.
+24. ses, resend, sendgrid, mailgun, maileroo, lettermint, plunk: a failure after a 2xx (an
+    unreadable or unparsable body, a 2xx other than the expected one, Plunk's `success: false`)
+    was retried, re-sending a message the provider had taken. Each client notes the 2xx
+    (`isAccepted`) and throws `markDeliveryUnknown` (`src/internal/delivery-unknown.js`) instead
+    of retrying; the transports report `deliveryUnknown`. Telling an unsent request from a sent
+    one on a timeout or a reset waits for the shared HTTP client (Phase B).
 
 ## Repository layout
 
@@ -200,7 +206,7 @@ src/
   version.js        the package name and version (OpenTelemetry scope), kept equal to package.json
   <subpath>/        one directory per subpath: index.js + index.d.ts + its modules
   internal/         private modules shared by subpaths, not in the exports map (redact.js,
-                    redact-addresses.js, unsent.js)
+                    redact-addresses.js, unsent.js, delivery-unknown.js)
 tests/
   unit/*.test.js    node:test suites, one per area (<subpath>-<module>.test.js for a subpath)
   helpers/<sub>/    shared test code of a subpath (fake servers, fixtures builders)
diff --git a/src/internal/delivery-unknown.js b/src/internal/delivery-unknown.js
new file mode 100644
index 0000000..19091a6
--- /dev/null
+++ b/src/internal/delivery-unknown.js
@@ -0,0 +1,30 @@
+// Not ported from upyo: marks the failures after which a message may have
+// been accepted, so that a transport reports them as of unknown delivery
+// rather than as retryable, whatever class of error carries them.
+
+const unknownDeliveries = new WeakSet();
+
+/**
+ * Marks a failure that came after the provider took the request, such as an
+ * unreadable body of a 2xx response.
+ *
+ * @param error The failure.
+ * @returns The same failure, to throw.
+ * @internal
+ */
+const markDeliveryUnknown = (error) => {
+  unknownDeliveries.add(error);
+  return error;
+};
+
+/**
+ * Whether a failure was marked by {@link markDeliveryUnknown}.
+ *
+ * @param error The failure.
+ * @returns `true` when the message may have been accepted.
+ * @internal
+ */
+const isDeliveryUnknown = (error) =>
+  typeof error === 'object' && error !== null && unknownDeliveries.has(error);
+
+module.exports = { isDeliveryUnknown, markDeliveryUnknown };
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index aefbb5e..35db502 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -11,6 +11,7 @@ const { uploadBlob } = require('./blob-uploader.js');
 const { createJmapConfig } = require('./config.js');
 const { JmapApiError } = require('./errors.js');
 const { JmapHttpClient } = require('./http-client.js');
+const { isDeliveryUnknown, markDeliveryUnknown } = require('../internal/delivery-unknown.js');
 const { isUnsentRequestError } = require('../internal/unsent.js');
 const { convertMessage } = require('./message-converter.js');
 const { findMailAccount } = require('./session.js');
@@ -875,9 +876,6 @@ class JmapTransport {
   }
 }
 
-// The submission errors after which the message may have been submitted.
-const unansweredSubmissions = new WeakSet();
-
 // Sends the request that creates and submits emails.  A failure without an
 // answer from the server, unless the connection was never made, leaves it
 // unknown whether the server submitted them.
@@ -886,8 +884,7 @@ const executeSubmission = async (client, apiUrl, request, signal) => {
     return await client.executeRequest(apiUrl, request, signal);
   } catch (error) {
     const isUnanswered = error instanceof JmapApiError && error.statusCode === undefined;
-    if (isUnanswered && !isUnsentRequestError(error)) unansweredSubmissions.add(error);
-    throw error;
+    throw isUnanswered && !isUnsentRequestError(error) ? markDeliveryUnknown(error) : error;
   }
 };
 
@@ -907,7 +904,7 @@ const createJmapFailure = (message, error, override = {}) => {
       category: override.category,
       code: override.code,
       retryable: override.retryable,
-      deliveryUnknown: unansweredSubmissions.has(error),
+      deliveryUnknown: isDeliveryUnknown(error),
     });
   }
 
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index 560b7e5..56dcb30 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -3,6 +3,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
+const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * Lettermint API error class for API-specific failures.
@@ -104,8 +105,10 @@ class LettermintHttpClient {
     for (let attempt = 0; attempt <= this.config.retries; attempt++) {
       signal?.throwIfAborted();
 
+      let isAccepted = false;
       try {
         const response = await this.fetchWithAuth(url, body, signal, idempotencyKey);
+        isAccepted = response.ok;
         const text = await response.text();
 
         if (!response.ok) {
@@ -129,6 +132,10 @@ class LettermintHttpClient {
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
 
+        // A 2xx means the provider took the request: sending it again could
+        // deliver the message twice, so what fails after it is not retried.
+        if (isAccepted && !signal?.aborted) throw markDeliveryUnknown(lastError);
+
         if (error instanceof LettermintApiError && !isRetryable(error)) {
           throw error;
         }
diff --git a/src/lettermint/lettermint-transport.js b/src/lettermint/lettermint-transport.js
index 9124421..ab8accf 100644
--- a/src/lettermint/lettermint-transport.js
+++ b/src/lettermint/lettermint-transport.js
@@ -10,6 +10,7 @@ const {
 } = require('./http-client.js');
 const { convertMessage, generateIdempotencyKey } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
+const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 const MAX_BATCH_SIZE = 500;
 
@@ -226,6 +227,7 @@ const responseToReceipt = (response) => {
 const createLettermintFailure = (message, error) => {
   if (error instanceof LettermintApiError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'lettermint',
       statusCode: error.statusCode,
       retryAfterMilliseconds: error.retryAfterMilliseconds,
@@ -235,6 +237,7 @@ const createLettermintFailure = (message, error) => {
 
   if (error instanceof LettermintTimeoutError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'lettermint',
       category: 'timeout',
       code: 'timeout',
@@ -244,6 +247,7 @@ const createLettermintFailure = (message, error) => {
   }
 
   return createFailedReceipt(message, {
+    deliveryUnknown: isDeliveryUnknown(error),
     provider: 'lettermint',
     attempts: getErrorAttempts(error),
   });
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index 453e20c..f6457fa 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -3,6 +3,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
+const { isDeliveryUnknown, markDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 const maxErrorMessageLength = 500;
 
@@ -111,7 +112,7 @@ class MailerooHttpClient {
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
 
-        if (signal?.aborted) {
+        if (signal?.aborted || isDeliveryUnknown(error)) {
           throw error;
         }
 
@@ -127,7 +128,11 @@ class MailerooHttpClient {
         continue;
       }
 
-      return parseResponse(responseText);
+      try {
+        return parseResponse(responseText);
+      } catch (error) {
+        throw markDeliveryUnknown(error);
+      }
     }
 
     throw lastError ?? new Error('Request failed after all retry attempts.');
@@ -150,6 +155,7 @@ class MailerooHttpClient {
         : undefined;
     const requestSignal = combineSignals(timeoutController.signal, signal);
 
+    let isAccepted = false;
     try {
       const response = await globalThis.fetch(url, {
         method: 'POST',
@@ -157,18 +163,19 @@ class MailerooHttpClient {
         body: JSON.stringify(body),
         signal: requestSignal.signal,
       });
+      isAccepted = response.ok;
       const text = await response.text();
       return { response, text };
     } catch (error) {
-      if (
+      const isTimeout =
         error instanceof Error &&
         error.name === 'AbortError' &&
         timeoutController.signal.aborted &&
-        !signal?.aborted
-      ) {
-        throw new MailerooTimeoutError(this.config.timeout);
-      }
-      throw error;
+        !signal?.aborted;
+      const failure = isTimeout ? new MailerooTimeoutError(this.config.timeout) : error;
+      // A 2xx means Maileroo took the request: sending it again could
+      // deliver the message twice.
+      throw isAccepted && !signal?.aborted ? markDeliveryUnknown(failure) : failure;
     } finally {
       requestSignal.cleanup();
       if (timeoutId !== undefined) {
diff --git a/src/maileroo/maileroo-transport.js b/src/maileroo/maileroo-transport.js
index fe5a767..eded3e9 100644
--- a/src/maileroo/maileroo-transport.js
+++ b/src/maileroo/maileroo-transport.js
@@ -6,6 +6,7 @@ const { createMailerooConfig } = require('./config.js');
 const { MailerooApiError, MailerooHttpClient, MailerooTimeoutError } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
+const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * Maileroo transport implementation for sending emails via Maileroo API.
@@ -138,6 +139,7 @@ const responseToReceipt = (response) => {
 const createMailerooFailure = (message, error) => {
   if (error instanceof MailerooApiError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'maileroo',
       statusCode: error.statusCode,
       retryAfterMilliseconds: error.retryAfterMilliseconds,
@@ -147,6 +149,7 @@ const createMailerooFailure = (message, error) => {
 
   if (error instanceof MailerooTimeoutError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'maileroo',
       category: 'timeout',
       code: 'timeout',
@@ -156,6 +159,7 @@ const createMailerooFailure = (message, error) => {
   }
 
   return createFailedReceipt(message, {
+    deliveryUnknown: isDeliveryUnknown(error),
     provider: 'maileroo',
     attempts: getErrorAttempts(error),
   });
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index b9b5d59..baebe41 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -3,6 +3,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
+const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * HTTP client wrapper for Mailgun API requests.
@@ -47,8 +48,10 @@ class MailgunHttpClient {
     let lastError = null;
 
     for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      let isAccepted = false;
       try {
         const response = await this.fetchWithAuth(url, options);
+        isAccepted = response.ok;
         const text = await response.text();
 
         if (!response.ok) {
@@ -91,6 +94,10 @@ class MailgunHttpClient {
           throw createAbortError(options.signal);
         }
 
+        // A 2xx means the provider took the request: sending it again could
+        // deliver the message twice, so what fails after it is not retried.
+        if (isAccepted) throw markDeliveryUnknown(lastError);
+
         // Don't retry caller cancellation.
         if (isAbortError(error)) {
           throw error;
diff --git a/src/mailgun/mailgun-transport.js b/src/mailgun/mailgun-transport.js
index c09fc32..7560412 100644
--- a/src/mailgun/mailgun-transport.js
+++ b/src/mailgun/mailgun-transport.js
@@ -6,6 +6,7 @@ const { createMailgunConfig } = require('./config.js');
 const { MailgunApiError, MailgunHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
+const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * Mailgun transport implementation for sending emails via Mailgun API.
@@ -201,6 +202,7 @@ class MailgunTransport {
 const createMailgunFailure = (message, error) => {
   if (error instanceof MailgunApiError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'mailgun',
       statusCode: error.statusCode,
       retryAfterMilliseconds: error.retryAfterMilliseconds,
@@ -209,6 +211,7 @@ const createMailgunFailure = (message, error) => {
   }
 
   return createFailedReceipt(message, {
+    deliveryUnknown: isDeliveryUnknown(error),
     provider: 'mailgun',
   });
 };
diff --git a/src/mailtrap/mailtrap-transport.js b/src/mailtrap/mailtrap-transport.js
index 9d6cc8e..7e12f95 100644
--- a/src/mailtrap/mailtrap-transport.js
+++ b/src/mailtrap/mailtrap-transport.js
@@ -243,6 +243,7 @@ const toReceipt = (response, options) => {
 const createMailtrapFailure = (message, error) => {
   if (error instanceof MailtrapResponseError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: true,
       provider: 'mailtrap',
       ...(error.cause instanceof MailtrapTimeoutError
         ? { category: 'timeout', code: 'timeout' }
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index fdbbe2d..83f08de 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -3,6 +3,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
+const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * Error thrown when a Plunk API request fails.
@@ -77,8 +78,10 @@ class PlunkHttpClient {
     for (let attempt = 0; attempt <= this.config.retries; attempt++) {
       signal?.throwIfAborted();
 
+      let isAccepted = false;
       try {
         const response = await this.makeRequest(url, emailData, signal);
+        isAccepted = response.ok;
         return await this.parseResponse(response);
       } catch (error) {
         if (isCallerAbort(error, signal)) {
@@ -87,6 +90,13 @@ class PlunkHttpClient {
 
         lastError = error instanceof Error ? error : new Error(String(error));
 
+        // A 2xx means Plunk took the request: sending it again could deliver
+        // the message twice.  Its explicit refusal (success: false) is a
+        // failure of its own; anything else that fails after it is unknown.
+        if (isAccepted) {
+          throw lastError instanceof PlunkApiError ? lastError : markDeliveryUnknown(lastError);
+        }
+
         // Don't retry on client errors (4xx) or AbortError
         if (error instanceof Error && error.name === 'AbortError') {
           throw error;
@@ -211,7 +221,10 @@ class PlunkHttpClient {
       }
 
       if (!data.success) {
-        throw new Error(data.message ?? 'Send operation failed without error details');
+        throw new PlunkApiError(
+          data.message ?? 'Send operation failed without error details',
+          response.status,
+        );
       }
 
       const responseData = 'data' in data ? data.data : data;
diff --git a/src/plunk/plunk-transport.js b/src/plunk/plunk-transport.js
index 8e15b3f..1b00583 100644
--- a/src/plunk/plunk-transport.js
+++ b/src/plunk/plunk-transport.js
@@ -6,6 +6,7 @@ const { createPlunkConfig } = require('./config.js');
 const { PlunkApiError, PlunkHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
+const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * Plunk transport implementation for sending emails via Plunk API.
@@ -231,6 +232,7 @@ class PlunkTransport {
 const createPlunkFailure = (message, error) => {
   if (error instanceof PlunkApiError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'plunk',
       statusCode: error.statusCode,
       retryAfterMilliseconds: error.retryAfterMilliseconds,
@@ -239,6 +241,7 @@ const createPlunkFailure = (message, error) => {
   }
 
   return createFailedReceipt(message, {
+    deliveryUnknown: isDeliveryUnknown(error),
     provider: 'plunk',
   });
 };
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index b8d65fc..89722e6 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -3,6 +3,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
+const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * Error thrown when a Resend API request fails.
@@ -116,8 +117,10 @@ class ResendHttpClient {
     let lastError = null;
 
     for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      let isAccepted = false;
       try {
         const response = await this.fetchWithAuth(url, options);
+        isAccepted = response.ok;
         const text = await response.text();
 
         if (!response.ok) {
@@ -158,6 +161,10 @@ class ResendHttpClient {
 
         lastError = error instanceof Error ? error : new Error(String(error));
 
+        // A 2xx means the provider took the request: sending it again could
+        // deliver the message twice, so what fails after it is not retried.
+        if (isAccepted) throw markDeliveryUnknown(lastError);
+
         // Don't retry on client errors (4xx) or AbortError
         if (
           error instanceof ResendApiError &&
diff --git a/src/resend/resend-transport.js b/src/resend/resend-transport.js
index 010a5e6..54cc335 100644
--- a/src/resend/resend-transport.js
+++ b/src/resend/resend-transport.js
@@ -10,6 +10,7 @@ const {
   generateIdempotencyKey,
 } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
+const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * Resend transport implementation for sending emails via Resend API.
@@ -339,6 +340,7 @@ class ResendTransport {
 const createResendFailure = (message, error) => {
   if (error instanceof ResendApiError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'resend',
       statusCode: error.statusCode,
       retryAfterMilliseconds: error.retryAfterMilliseconds,
@@ -347,6 +349,7 @@ const createResendFailure = (message, error) => {
   }
 
   return createFailedReceipt(message, {
+    deliveryUnknown: isDeliveryUnknown(error),
     provider: 'resend',
   });
 };
diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
index 51fb0d1..9f65998 100644
--- a/src/sendgrid/http-client.js
+++ b/src/sendgrid/http-client.js
@@ -3,6 +3,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
+const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * HTTP client wrapper for SendGrid API requests.
@@ -51,8 +52,10 @@ class SendGridHttpClient {
     let lastError = null;
 
     for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      let isAccepted = false;
       try {
         const response = await this.fetchWithAuth(url, options);
+        isAccepted = response.ok;
 
         // Get response text
         const text = await response.text();
@@ -89,6 +92,10 @@ class SendGridHttpClient {
           throw error;
         }
 
+        // A 2xx means the provider took the request: sending it again could
+        // deliver the message twice, so what fails after it is not retried.
+        if (isAccepted) throw markDeliveryUnknown(lastError);
+
         // Don't retry on client errors (4xx) or if it's the last attempt
         if (
           error instanceof SendGridApiError &&
diff --git a/src/sendgrid/sendgrid-transport.js b/src/sendgrid/sendgrid-transport.js
index d9ed22d..6570bb4 100644
--- a/src/sendgrid/sendgrid-transport.js
+++ b/src/sendgrid/sendgrid-transport.js
@@ -6,6 +6,7 @@ const { createSendGridConfig } = require('./config.js');
 const { SendGridApiError, SendGridHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
+const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * SendGrid transport implementation for sending emails via SendGrid API.
@@ -231,6 +232,7 @@ class SendGridTransport {
 const createSendGridFailure = (message, error) => {
   if (error instanceof SendGridApiError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'sendgrid',
       statusCode: error.statusCode,
       retryAfterMilliseconds: error.retryAfterMilliseconds,
@@ -240,6 +242,7 @@ const createSendGridFailure = (message, error) => {
   }
 
   return createFailedReceipt(message, {
+    deliveryUnknown: isDeliveryUnknown(error),
     provider: 'sendgrid',
   });
 };
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index c3b0fb6..49d60ed 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -3,6 +3,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
+const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 class SesHttpClient {
   config;
@@ -39,8 +40,10 @@ class SesHttpClient {
     let lastError = null;
 
     for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      let isAccepted = false;
       try {
         const response = await this.fetchWithAuth(url, options);
+        isAccepted = response.ok;
         const text = await response.text();
 
         if (response.status === 200) {
@@ -72,6 +75,10 @@ class SesHttpClient {
           throw createAbortError(options.signal);
         }
 
+        // A 2xx means the provider took the request: sending it again could
+        // deliver the message twice, so what fails after it is not retried.
+        if (isAccepted) throw markDeliveryUnknown(lastError);
+
         if (isAbortError(error)) {
           throw error;
         }
diff --git a/src/ses/ses-transport.js b/src/ses/ses-transport.js
index 05a7d23..6c2dd5f 100644
--- a/src/ses/ses-transport.js
+++ b/src/ses/ses-transport.js
@@ -6,6 +6,7 @@ const { createSesConfig } = require('./config.js');
 const { SesApiError, SesHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
+const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 /**
  * Amazon SES email transport implementation.
@@ -228,6 +229,7 @@ class SesTransport {
 const createSesFailure = (message, error) => {
   if (error instanceof SesApiError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'ses',
       statusCode: error.statusCode,
       retryAfterMilliseconds: error.retryAfterMilliseconds,
@@ -237,6 +239,7 @@ const createSesFailure = (message, error) => {
   }
 
   return createFailedReceipt(message, {
+    deliveryUnknown: isDeliveryUnknown(error),
     provider: 'ses',
   });
 };
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
new file mode 100644
index 0000000..f2ebfba
--- /dev/null
+++ b/tests/unit/delivery.test.js
@@ -0,0 +1,84 @@
+// A provider that answered 2xx took the request: whatever fails after that,
+// such as reading the body, must not send the message again.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createMessage } = require('../../index.js');
+const { LettermintTransport } = require('../../src/lettermint/index.js');
+const { MailerooTransport } = require('../../src/maileroo/index.js');
+const { MailgunTransport } = require('../../src/mailgun/index.js');
+const { MailtrapTransport } = require('../../src/mailtrap/index.js');
+const { PlunkTransport } = require('../../src/plunk/index.js');
+const { ResendTransport } = require('../../src/resend/index.js');
+const { SendGridTransport } = require('../../src/sendgrid/index.js');
+const { SesTransport } = require('../../src/ses/index.js');
+
+const message = () =>
+  createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+
+const options = { retries: 3 };
+const providers = [
+  [
+    'SES',
+    200,
+    () =>
+      new SesTransport({
+        ...options,
+        authentication: { type: 'credentials', accessKeyId: 'a', secretAccessKey: 'b' },
+      }),
+  ],
+  ['Resend', 200, () => new ResendTransport({ ...options, apiKey: 'key' })],
+  ['SendGrid', 202, () => new SendGridTransport({ ...options, apiKey: 'key' })],
+  [
+    'Mailgun',
+    200,
+    () => new MailgunTransport({ ...options, apiKey: 'key', domain: 'mg.example.com' }),
+  ],
+  ['Mailtrap', 200, () => new MailtrapTransport({ ...options, apiToken: 'token' })],
+  ['Maileroo', 200, () => new MailerooTransport({ ...options, apiKey: 'key' })],
+  ['Lettermint', 200, () => new LettermintTransport({ ...options, apiToken: 'token' })],
+  ['Plunk', 200, () => new PlunkTransport({ ...options, apiKey: 'key' })],
+];
+
+// A 2xx whose body cannot be read: the connection broke after the headers.
+const unreadable = (status) => {
+  const response = new Response(null, { status });
+  const broken = () => Promise.reject(new Error('Connection reset while reading the body.'));
+  Object.defineProperty(response, 'text', { value: broken });
+  Object.defineProperty(response, 'json', { value: broken });
+  return response;
+};
+
+test('Delivery: a 2xx with an unreadable body is sent once, of unknown delivery', async (t) => {
+  for (const [name, status, create] of providers) {
+    let requests = 0;
+    t.mock.method(globalThis, 'fetch', async () => {
+      requests++;
+      return unreadable(status);
+    });
+    const receipt = await create().send(message());
+    t.mock.restoreAll();
+    assert.strictEqual(requests, 1, name);
+    assert.strictEqual(receipt.successful, false, name);
+    assert.strictEqual(receipt.deliveryUnknown, true, name);
+    assert.strictEqual(receipt.retryable, false, name);
+  }
+});
+
+test('Delivery: Plunk refusing in a 200 is sent once, a definite failure', async (t) => {
+  let requests = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    requests++;
+    return Response.json({ success: false, message: 'Sender not verified' });
+  });
+  const receipt = await new PlunkTransport({ ...options, apiKey: 'key' }).send(message());
+  assert.strictEqual(requests, 1);
+  assert.strictEqual(receipt.successful, false);
+  assert.strictEqual(receipt.deliveryUnknown, undefined);
+  assert.strictEqual(receipt.retryable, false);
+  assert.match(receipt.errorMessages[0], /Sender not verified/);
+});
diff --git a/tests/unit/maileroo-transport.test.js b/tests/unit/maileroo-transport.test.js
index da5d62b..d9d86c8 100644
--- a/tests/unit/maileroo-transport.test.js
+++ b/tests/unit/maileroo-transport.test.js
@@ -417,7 +417,11 @@ describe('MailerooTransport - send', { concurrency: false }, () => {
         assert.ok(!receipt.successful);
         if (!receipt.successful) {
           assert.equal(receipt.errors?.[0]?.category, 'timeout');
-          assert.ok(receipt.retryable);
+          // Changed after the port: the timeout came after a 200, so Maileroo
+          // took the request and a retry could deliver it twice; upstream
+          // returned a retryable receipt.
+          assert.equal(receipt.retryable, false);
+          assert.equal(receipt.deliveryUnknown, true);
         }
       },
     );

From c9617b045f93ff23d6984dbbb640e97fd4f63989 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 00:45:33 +0300
Subject: [PATCH 032/158] docs: say what is built and what is planned, and list
 the open issues

README presented the planned reliability layer, golden .eml messages, an
independent DKIM verifier and fuzzing as features; it now says which parts
are being designed or planned, and what the transport does today about
duplicates (deliveryUnknown, which ./retry and ./pool never resend). The
"Design" list of the guide says the same, and SECURITY.md marks the
attachment, webhook and audit-log principles as planned.

The open upstream bugs were listed only in CLAUDE.md, which is not
published; a "Known issues" page now lists them for users, and the
changelog points to it. CLAUDE.md no longer claims SigV4 on node:crypto (it
signs with WebCrypto) or REQUIRETLS (requireTls only requires STARTTLS),
and the JSDoc examples of the root helpers import from @alexify/mailer
rather than from subpaths that do not exist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  5 +++--
 CLAUDE.md                  |  4 ++--
 README.md                  | 16 ++++++++------
 SECURITY.md                | 16 +++++++-------
 docs/.vitepress/config.mts |  1 +
 docs/guide/known-issues.md | 44 ++++++++++++++++++++++++++++++++++++++
 docs/guide/why.md          | 11 +++++++---
 index.d.ts                 | 26 +++++++++++-----------
 src/core/address.js        | 12 +++++------
 src/core/calendar.js       |  4 ++--
 src/core/message-id.js     |  8 +++----
 src/core/priority.js       |  2 +-
 12 files changed, 101 insertions(+), 48 deletions(-)
 create mode 100644 docs/guide/known-issues.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 67ada6f..ecab22e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,8 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The transport layer, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0 (MIT, © 2025
 Hong Minhee): the code is upstream's, converted to CommonJS with hand-written types and no
-runtime dependency, one subpath per upstream package. Upstream's known bugs are kept for now and
-listed in CLAUDE.md, to be fixed one by one.
+runtime dependency, one subpath per upstream package. Upstream's known bugs are fixed one by one:
+the open ones are on the [Known issues](https://mailerat.vercel.app/guide/known-issues) page, the
+fixed ones below.
 
 ### Added
 
diff --git a/CLAUDE.md b/CLAUDE.md
index df0c79f..f800091 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -82,7 +82,7 @@ is no build step.
 There is no `dependencies` or `peerDependencies` key in `package.json`, and there won't be one.
 
 - **The transports are built on `node:*` and `fetch`:** SMTP on `node:net`/`node:tls`, DKIM and
-  the SES SigV4 signature on `node:crypto`, HTTP providers on the global `fetch`. No provider SDK.
+  the SES SigV4 signature on WebCrypto (`crypto.subtle`, a global of Node), HTTP providers on the global `fetch`. No provider SDK.
 - **Infrastructure drivers are injected.** An adapter for a queue or a store takes the client or
   module the application created (a BullMQ `Queue`, a `MongoClient` or `require('mongodb')`), the
   way `./mongodb` of `@alexify/metaschema` takes the driver module. The package never `require`s
@@ -263,7 +263,7 @@ model of states and events. `tenantId` is in the context from the start.
 **Phase 1, reliable sending (P0).**
 
 - **The transport of its own** (done, ported from upyo 0.7.0; its known bugs are on the list of
-  "Code ported from upyo"): the MIME builder; the SMTP client (pool, STARTTLS and REQUIRETLS,
+  "Code ported from upyo"): the MIME builder; the SMTP client (pool, STARTTLS with `requireTls`, not RFC 8689 REQUIRETLS,
   AUTH PLAIN/LOGIN/XOAUTH2, DSN, PIPELINING); DKIM (RSA-SHA256, Ed25519); SES v2 over `fetch` with
   SigV4; seven more HTTP providers and JMAP.
 - **A persistent queue:** the outbox in MongoDB (transactional outbox, no Redis needed) and a
diff --git a/README.md b/README.md
index 106191f..5138d65 100644
--- a/README.md
+++ b/README.md
@@ -25,14 +25,16 @@ idempotency. Zero runtime dependencies.
   MIME builder and DKIM (RSA-SHA256, Ed25519), and HTTP providers on `fetch`: Amazon SES v2,
   Resend, SendGrid, Mailgun, Mailtrap, Maileroo, Lettermint, Plunk, and JMAP. Secure by default:
   TLS certificates are verified, AUTH never goes over plain text, CRLF in a header is rejected.
-- **What happens after `send()`.** A persistent queue and outbox, an append-only audit log and one
-  model of delivery events (delivered, bounced, complained, failed). None of the
+- **What happens after `send()`** (being designed). A persistent queue and outbox, an append-only
+  audit log and one model of delivery events (delivered, bounced, complained, failed). None of the
   [fourteen libraries compared](https://mailerat.vercel.app/guide/comparison) has the three.
-- **Sent once, or known to be unknown.** Idempotency keys with deduplication, errors classified as
-  permanent or temporary, and a `delivery_unknown` state instead of a blind retry when a provider
-  has no idempotency key.
-- **Correct before broad.** Golden `.eml` messages, DKIM checked by an independent verifier, and
-  fuzzing of headers, `multipart/related`, dot-stuffing and internationalized addresses.
+- **Sent once, or known to be unknown.** Errors are classified as permanent or temporary, and a
+  failure after which the provider may have taken the message is marked `deliveryUnknown`:
+  `./retry` and `./pool` never send it again. Idempotency keys with deduplication come with the
+  outbox.
+- **Correct before broad.** The tests read the composed messages back with an independent parser;
+  golden `.eml` messages, DKIM checked by an independent verifier and fuzzing of headers,
+  `multipart/related`, dot-stuffing and internationalized addresses are planned.
 - **Zero dependencies.** Built on `node:*` modules and `fetch`. What a part needs from your
   application is passed in: the OpenTelemetry providers, a pino-like logger, and later the driver of
   a queue or a database (BullMQ, MongoDB). CommonJS with ESM named imports and hand-written
diff --git a/SECURITY.md b/SECURITY.md
index 8cd1765..45ef67f 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -39,20 +39,20 @@ is designed around:
   over a plain connection: when TLS is required and the server does not offer STARTTLS, or the
   upgrade fails, the send fails instead of falling back to plain text. Bcc recipients never appear
   in the headers of the message.
-- **Attachments do not read the machine by default.** Reading a file path or fetching a URL for an
-  attachment is off unless the application turns it on; fetching a URL is limited in size and
-  refuses private and link-local addresses.
+- **Attachments do not read the machine by default** (planned). Reading a file path or fetching a
+  URL for an attachment is off unless the application turns it on; fetching a URL is limited in size
+  and refuses private and link-local addresses.
 - **Credentials and personal data stay out of logs.** A transport shows `[REDACTED]` in place of
   its SMTP password, OAuth2 tokens, provider key and DKIM private key when it is inspected,
   logged or serialized. `./otel` and `./logger` record addresses only when told to
   (`recordSensitiveData`, `recordMessage`); otherwise the addresses that error text names, such
   as the recipient of an SMTP rejection, are redacted. A receipt returned to the application
   keeps its full error text: logging it is the application's to scrub.
-- **Webhooks are verified.** A delivery event from a provider is accepted only with a valid
-  signature and within a replay window.
-- **The audit log can forget a person.** Recipients are stored as a keyed hash and an encrypted
-  block whose key can be destroyed, so a request to erase someone's data does not require editing
-  an append-only log.
+- **Webhooks are verified** (planned). A delivery event from a provider is accepted only with a
+  valid signature and within a replay window.
+- **The audit log can forget a person** (planned). Recipients are stored as a keyed hash and an
+  encrypted block whose key can be destroyed, so a request to erase someone's data does not require
+  editing an append-only log.
 - **Drivers are the application's.** A queue or database driver passed in (BullMQ, MongoDB) is
   trusted the same as any other module the application `require`s; its connection security is the
   application's to configure.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index d6489f4..b6844bd 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -59,6 +59,7 @@ const guide = [
       { text: 'Why @alexify/mailer?', link: '/guide/why' },
       { text: 'Getting Started', link: '/guide/getting-started' },
       { text: 'Compared with alternatives', link: '/guide/comparison' },
+      { text: 'Known issues', link: '/guide/known-issues' },
     ],
   },
   {
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
new file mode 100644
index 0000000..2635f13
--- /dev/null
+++ b/docs/guide/known-issues.md
@@ -0,0 +1,44 @@
+# Known issues
+
+The transport layer is ported from [upyo](https://github.com/dahlia/upyo) 0.7.0 and keeps its
+behavior, bugs included, until each bug is fixed on its own with a test. This page lists the ones
+still open; the fixed ones are in the [changelog](https://github.com/Alexis-Technologies/mailer/blob/main/CHANGELOG.md).
+
+## Messages and MIME
+
+- Inline images (`contentId`) go into `multipart/mixed` rather than `multipart/related`, so some
+  clients show them as attachments.
+- The first encoded word of a header shares its line with the field name
+  (`Subject: =?UTF-8?B?…?=`), past the 76 characters that RFC 2047 allows such a line.
+- DKIM: a PKCS#1 key (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails; convert it to
+  PKCS#8 first.
+- DKIM: when signing fails and `send-unsigned` is set, the warning goes to `console.warn`.
+
+## SMTP
+
+- AUTH PLAIN and LOGIN fail on credentials outside Latin-1.
+- `cram-md5` is in the `SmtpAuth` type but not implemented.
+
+## HTTP providers and JMAP
+
+- `validateSsl` is accepted and never read (SES, Resend, SendGrid, Mailgun, Mailtrap, Plunk).
+- Basic authentication in JMAP and Mailgun fails on credentials outside Latin-1.
+- Mailgun sends an inline attachment under its file name rather than its `contentId`, so a
+  `cid:` in the HTML does not match it.
+- Resend and Plunk: the sleep between retries ignores the `AbortSignal`. SES, Resend, SendGrid,
+  Mailgun and Plunk parse `Retry-After` but do not wait for it.
+- Resend's `Idempotency-Key` comes from `Math.random`.
+- SES: custom and threading headers are not sent.
+- Plunk: an attachment that cannot be read is left out with a `console.warn`.
+- The HTTP providers retry a timeout or a reset that came before any answer, although the
+  request may have reached the provider; failures after a 2xx are already reported as
+  `deliveryUnknown` and not retried.
+- JMAP on Node 24: an authentication rejection (401) of a streamed request body (raw upload,
+  import, raw submission) becomes a retryable network error, as Node's `fetch` reports it so.
+
+## Decorators
+
+- `./pool`: `continueOnSuccess` is never read.
+- `./otel`: `durationBuckets` and `auto` are ignored, `recordRetry` is never called, `sendMany`
+  buffers its whole input, the active sends gauge drifts under sampling, and the default error
+  classifier matches `auth` and status codes as substrings of the message.
diff --git a/docs/guide/why.md b/docs/guide/why.md
index 6eb7016..08ab6bb 100644
--- a/docs/guide/why.md
+++ b/docs/guide/why.md
@@ -33,6 +33,10 @@ for a user who needs it, and the effort goes into what happens to a message afte
 
 ## Design
 
+The transport is built; the rest of this list is the design of the reliability layer, which is
+being built. A failure after which a provider may have taken the message is already marked
+`deliveryUnknown`, and `./retry` and `./pool` do not send it again.
+
 - **At least once, with deduplication.** Exactly-once delivery is not possible over SMTP or HTTP.
   A message carries an idempotency key, the outbox deduplicates by it, and a provider that has no
   idempotency key (SES) leads to a `delivery_unknown` state that is reconciled from delivery
@@ -47,9 +51,10 @@ for a user who needs it, and the effort goes into what happens to a message afte
 - **Secure by default.** TLS certificates are verified, AUTH never goes over plain text, CRLF in
   any header is rejected, the body is dot-stuffed, and reading files or URLs for attachments is
   off unless asked for.
-- **Correct before broad.** The transport is checked against a public set of golden `.eml`
-  messages, DKIM signatures verified by an independent verifier, and fuzzing of headers,
-  `multipart/related`, dot-stuffing and internationalized addresses.
+- **Correct before broad.** The tests read the composed messages back with an independent
+  parser; the transport is to be checked against a public set of golden `.eml` messages, DKIM
+  signatures verified by an independent verifier, and fuzzing of headers, `multipart/related`,
+  dot-stuffing and internationalized addresses.
 - **No dependencies.** The transports use `node:*` modules and `fetch`. The driver of a queue or a
   database (BullMQ on Valkey or Redis, MongoDB) is created by your application and passed in.
 
diff --git a/index.d.ts b/index.d.ts
index 6aba7c6..a3cfb0c 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -25,14 +25,14 @@ export interface Address {
  *
  * @example Formatting an address with a name
  * ```ts
- * import { type Address, formatAddress } from "@alexify/mailer/address";
+ * import { type Address, formatAddress } from "@alexify/mailer";
  * const address: Address = { name: "John Doe", address: "john@example.com" };
  * console.log(formatAddress(address)); // "John Doe <john@example.com>"
  * ```
  *
  * @example Formatting an address without a name
  * ```ts
- * import { type Address, formatAddress } from "@alexify/mailer/address";
+ * import { type Address, formatAddress } from "@alexify/mailer";
  * const address: Address = { address: "jane@examle.com" };
  * console.log(formatAddress(address)); // "jane@example.com"
  * ```
@@ -47,21 +47,21 @@ export declare function formatAddress(address: Address): string;
  *
  * @example Parsing an address with a name
  * ```ts
- * import { parseAddress } from "@alexify/mailer/address";
+ * import { parseAddress } from "@alexify/mailer";
  * const address = parseAddress("John Doe <john@example.com>");
  * console.log(address); // { name: "John Doe", address: "john@example.com" }
  * ```
  *
  * @example Parsing an address without a name
  * ```ts
- * import { parseAddress } from "@alexify/mailer/address";
+ * import { parseAddress } from "@alexify/mailer";
  * const address = parseAddress("jane@example.com");
  * console.log(address); // { address: "jane@example.com" }
  * ```
  *
  * @example Trying to parse an invalid address
  * ```ts
- * import { parseAddress } from "@alexify/mailer/address";
+ * import { parseAddress } from "@alexify/mailer";
  * const address = parseAddress("invalid-email");
  * console.log(address); // undefined
  * ```
@@ -76,7 +76,7 @@ export declare function parseAddress(address: string): Address | undefined;
  *
  * @example
  * ```ts
- * import { isEmailAddress } from "@alexify/mailer/address";
+ * import { isEmailAddress } from "@alexify/mailer";
  *
  * const userInput = "user@example.com";
  * if (isEmailAddress(userInput)) {
@@ -272,7 +272,7 @@ export interface CalendarConstructor {
  *
  * @example
  * ```ts
- * import { parseCalendarMethod } from "@alexify/mailer/calendar";
+ * import { parseCalendarMethod } from "@alexify/mailer";
  * parseCalendarMethod("BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR\r\n");
  * // "REQUEST"
  * ```
@@ -300,7 +300,7 @@ export declare function parseCalendarMethod(content: string): CalendarMethod | u
  *
  * @example
  * ```ts
- * import { resolveCalendarContent } from "@alexify/mailer/calendar";
+ * import { resolveCalendarContent } from "@alexify/mailer";
  * const calendar = resolveCalendarContent({ content: ics });
  * calendar.method;  // "REQUEST"
  * ```
@@ -692,7 +692,7 @@ export declare function createMessage(constructor: MessageConstructor): Message;
  *
  * @example
  * ```ts
- * import { generateMessageId } from "@alexify/mailer/message-id";
+ * import { generateMessageId } from "@alexify/mailer";
  * const messageId = generateMessageId("example.com");
  * // "1e2ee2e1-…-…@example.com"
  * ```
@@ -716,7 +716,7 @@ export declare function generateMessageId(domain: string): string;
  *
  * @example
  * ```ts
- * import { parseMessageId } from "@alexify/mailer/message-id";
+ * import { parseMessageId } from "@alexify/mailer";
  * parseMessageId("<abc@example.com>");  // "abc@example.com"
  * parseMessageId("not an identifier");  // undefined
  * ```
@@ -736,7 +736,7 @@ export declare function parseMessageId(value: string): string | undefined;
  *
  * @example
  * ```ts
- * import { formatMessageId } from "@alexify/mailer/message-id";
+ * import { formatMessageId } from "@alexify/mailer";
  * formatMessageId("abc@example.com");  // "<abc@example.com>"
  * ```
  *
@@ -765,7 +765,7 @@ export declare function formatMessageId(id: string): string;
  *
  * @example
  * ```ts
- * import { resolveThreadingHeaders } from "@alexify/mailer/message-id";
+ * import { resolveThreadingHeaders } from "@alexify/mailer";
  * // for a message replying to <122@example.com>:
  * // Map { "In-Reply-To" => "<122@example.com>" }
  * ```
@@ -788,7 +788,7 @@ export type Priority = 'high' | 'normal' | 'low';
  *
  * @example Sorting priorities
  * ```ts
- * import { comparePriority, type Priority } from "@alexify/mailer/priority";
+ * import { comparePriority, type Priority } from "@alexify/mailer";
  * const priorities: Priority[] = ["normal", "low", "high"];
  * priorities.sort(comparePriority);
  * console.log(priorities); // ["high", "normal", "low"]
diff --git a/src/core/address.js b/src/core/address.js
index f1122a3..0ea9d46 100644
--- a/src/core/address.js
+++ b/src/core/address.js
@@ -9,14 +9,14 @@ const net = require('node:net');
  *
  * @example Formatting an address with a name
  * ```ts
- * import { type Address, formatAddress } from "@alexify/mailer/address";
+ * import { type Address, formatAddress } from "@alexify/mailer";
  * const address: Address = { name: "John Doe", address: "john@example.com" };
  * console.log(formatAddress(address)); // "John Doe <john@example.com>"
  * ```
  *
  * @example Formatting an address without a name
  * ```ts
- * import { type Address, formatAddress } from "@alexify/mailer/address";
+ * import { type Address, formatAddress } from "@alexify/mailer";
  * const address: Address = { address: "jane@examle.com" };
  * console.log(formatAddress(address)); // "jane@example.com"
  * ```
@@ -108,21 +108,21 @@ const formatQuotedMailbox = (address) => {
  *
  * @example Parsing an address with a name
  * ```ts
- * import { parseAddress } from "@alexify/mailer/address";
+ * import { parseAddress } from "@alexify/mailer";
  * const address = parseAddress("John Doe <john@example.com>");
  * console.log(address); // { name: "John Doe", address: "john@example.com" }
  * ```
  *
  * @example Parsing an address without a name
  * ```ts
- * import { parseAddress } from "@alexify/mailer/address";
+ * import { parseAddress } from "@alexify/mailer";
  * const address = parseAddress("jane@example.com");
  * console.log(address); // { address: "jane@example.com" }
  * ```
  *
  * @example Trying to parse an invalid address
  * ```ts
- * import { parseAddress } from "@alexify/mailer/address";
+ * import { parseAddress } from "@alexify/mailer";
  * const address = parseAddress("invalid-email");
  * console.log(address); // undefined
  * ```
@@ -350,7 +350,7 @@ const isValidAddressLiteral = (literal) => {
  *
  * @example
  * ```ts
- * import { isEmailAddress } from "@alexify/mailer/address";
+ * import { isEmailAddress } from "@alexify/mailer";
  *
  * const userInput = "user@example.com";
  * if (isEmailAddress(userInput)) {
diff --git a/src/core/calendar.js b/src/core/calendar.js
index 2dea75e..13f2329 100644
--- a/src/core/calendar.js
+++ b/src/core/calendar.js
@@ -35,7 +35,7 @@ const calendarMethods = new Set([
  *
  * @example
  * ```ts
- * import { parseCalendarMethod } from "@alexify/mailer/calendar";
+ * import { parseCalendarMethod } from "@alexify/mailer";
  * parseCalendarMethod("BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nEND:VCALENDAR\r\n");
  * // "REQUEST"
  * ```
@@ -71,7 +71,7 @@ const parseCalendarMethod = (content) => {
  *
  * @example
  * ```ts
- * import { resolveCalendarContent } from "@alexify/mailer/calendar";
+ * import { resolveCalendarContent } from "@alexify/mailer";
  * const calendar = resolveCalendarContent({ content: ics });
  * calendar.method;  // "REQUEST"
  * ```
diff --git a/src/core/message-id.js b/src/core/message-id.js
index adb062c..a198a90 100644
--- a/src/core/message-id.js
+++ b/src/core/message-id.js
@@ -18,7 +18,7 @@
  *
  * @example
  * ```ts
- * import { generateMessageId } from "@alexify/mailer/message-id";
+ * import { generateMessageId } from "@alexify/mailer";
  * const messageId = generateMessageId("example.com");
  * // "1e2ee2e1-…-…@example.com"
  * ```
@@ -45,7 +45,7 @@ const generateMessageId = (domain) => {
  *
  * @example
  * ```ts
- * import { parseMessageId } from "@alexify/mailer/message-id";
+ * import { parseMessageId } from "@alexify/mailer";
  * parseMessageId("<abc@example.com>");  // "abc@example.com"
  * parseMessageId("not an identifier");  // undefined
  * ```
@@ -71,7 +71,7 @@ const parseMessageId = (value) => {
  *
  * @example
  * ```ts
- * import { formatMessageId } from "@alexify/mailer/message-id";
+ * import { formatMessageId } from "@alexify/mailer";
  * formatMessageId("abc@example.com");  // "<abc@example.com>"
  * ```
  *
@@ -275,7 +275,7 @@ const hasNonAscii = (value) => {
  *
  * @example
  * ```ts
- * import { resolveThreadingHeaders } from "@alexify/mailer/message-id";
+ * import { resolveThreadingHeaders } from "@alexify/mailer";
  * // for a message replying to <122@example.com>:
  * // Map { "In-Reply-To" => "<122@example.com>" }
  * ```
diff --git a/src/core/priority.js b/src/core/priority.js
index 0e63808..b741e92 100644
--- a/src/core/priority.js
+++ b/src/core/priority.js
@@ -7,7 +7,7 @@
  *
  * @example Sorting priorities
  * ```ts
- * import { comparePriority, type Priority } from "@alexify/mailer/priority";
+ * import { comparePriority, type Priority } from "@alexify/mailer";
  * const priorities: Priority[] = ["normal", "low", "high"];
  * priorities.sort(comparePriority);
  * console.log(priorities); // ["high", "normal", "low"]

From e36f3dbd908410deb8379143cb28434270ae19c5 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:47:04 +0300
Subject: [PATCH 033/158] refactor(ses): send through a shared request helper

Each of the nine HTTP clients carried its own copy of the retry loop, the
deadline of an attempt, the abortable sleep and, since the last fix, the
handling of a failure after a 2xx. src/internal/http.js now holds them once
as requestWithRetry: the provider passes in what is its own (one fetch, the
reading of a 2xx, the error of any other response, what it retries, the
delay, its timeout and final errors), and the helper owns the loop.

The providers still differ in how a timeout of 0 behaves, whether the
deadline covers the body and, for Resend and Plunk, a sleep that ignores
the signal; requestWithRetry takes those as options for now, so that each
provider moves over unchanged and each difference is then removed in its
own fix. ./ses moves first, with the same signing per attempt, timeout
message, retry rules and final SesApiError; its tests pass unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/internal/http.js        | 152 +++++++++++++++++++++++++++++++++
 src/ses/http-client.js      | 166 +++++++++++-------------------------
 tests/unit/internal.test.js | 123 ++++++++++++++++++++++++++
 3 files changed, 323 insertions(+), 118 deletions(-)
 create mode 100644 src/internal/http.js

diff --git a/src/internal/http.js b/src/internal/http.js
new file mode 100644
index 0000000..ed8de4f
--- /dev/null
+++ b/src/internal/http.js
@@ -0,0 +1,152 @@
+// Not ported from upyo: the retry loop that the HTTP providers carried as
+// copies.  A provider keeps what is its own (the request, its errors, what it
+// retries and how long it waits) and passes it in.
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { markDeliveryUnknown } = require('./delivery-unknown.js');
+
+const isAbortError = (error) => error instanceof Error && error.name === 'AbortError';
+
+/**
+ * The reason of an aborted signal, or an `AbortError` when it has none.
+ *
+ * @param signal The aborted signal.
+ * @returns The value to reject or throw with.
+ * @internal
+ */
+const abortReason = (signal) =>
+  signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+
+/**
+ * Waits, and stops waiting when the signal aborts, rejecting with its reason.
+ *
+ * @param milliseconds How long to wait.
+ * @param signal The caller's signal.
+ * @returns A promise settled when the wait ends.
+ * @internal
+ */
+const sleep = (milliseconds, signal) =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, milliseconds);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+
+/**
+ * The delay before retry `attempt` (from 0): one second, doubled each time.
+ *
+ * @param attempt The attempt that failed, from 0.
+ * @returns The delay in milliseconds.
+ * @internal
+ */
+const exponentialDelayMs = (attempt) => 1000 * 2 ** attempt;
+
+/**
+ * The exponential delay capped at ten seconds, then spread over its upper half
+ * so that clients that failed together do not retry together.
+ *
+ * @param attempt The attempt that failed, from 0.
+ * @returns The delay in milliseconds.
+ * @internal
+ */
+const jitteredDelayMs = (attempt) => {
+  const baseMs = Math.min(exponentialDelayMs(attempt), 10_000);
+  return Math.round(baseMs / 2 + Math.random() * (baseMs / 2));
+};
+
+// The deadline of one attempt, combined with the caller's signal.
+const startDeadline = (timeoutMs, isZeroTimeoutDisabled, signal) => {
+  const controller = new AbortController();
+  const timer =
+    isZeroTimeoutDisabled && !(timeoutMs > 0)
+      ? undefined
+      : setTimeout(() => controller.abort(), timeoutMs);
+  const combined = combineSignals(controller.signal, signal);
+  return {
+    signal: combined.signal,
+    get isExpired() {
+      return controller.signal.aborted;
+    },
+    stop() {
+      clearTimeout(timer);
+      combined.cleanup();
+    },
+  };
+};
+
+/**
+ * Sends a request with a deadline per attempt, retrying what the provider
+ * says to retry.  A failure after a 2xx response is never retried: the
+ * provider took the request, so it is thrown marked as of unknown delivery,
+ * unless the request is idempotent.
+ *
+ * @param request What the provider passes in:
+ * - `send(signal, attempt)`: one fetch, with the signal of the attempt;
+ * - `read(response, attempt)`: the result of a 2xx response;
+ * - `reject(response, attempt)`: the error of any other response;
+ * - `isRetryable(error)`, `retryDelayMs(attempt, error)`;
+ * - `retries`, `timeoutMs`, `signal`;
+ * - `createTimeoutError(error)`: the error of an expired deadline;
+ * - `finalError(error, attempts)`: the error thrown once retries are spent;
+ * - optional `wrapAccepted(error, attempts)`, `isIdempotent`, `sleep`, and
+ *   until they are unified, `isZeroTimeoutDisabled` (a timeout of 0 or less
+ *   means none) and `timeoutCoversBody` (the deadline lasts until `read`
+ *   returns, not only until the headers arrive).
+ * @returns What `read` returns.
+ * @internal
+ */
+const requestWithRetry = async (request) => {
+  const signal = request.signal;
+  const wait = request.sleep ?? sleep;
+  for (let attempt = 0; ; attempt++) {
+    signal?.throwIfAborted();
+    const deadline = startDeadline(
+      request.timeoutMs,
+      request.isZeroTimeoutDisabled === true,
+      signal,
+    );
+    let isAccepted = false;
+    let failure;
+    try {
+      const response = await request.send(deadline.signal, attempt);
+      isAccepted = response.ok;
+      if (request.timeoutCoversBody !== true) deadline.stop();
+      if (response.ok) return await request.read(response, attempt);
+      failure = await request.reject(response, attempt);
+    } catch (error) {
+      const isTimeout = deadline.isExpired && !signal?.aborted && isAbortError(error);
+      failure = isTimeout ? request.createTimeoutError(error) : error;
+    } finally {
+      deadline.stop();
+    }
+    if (!(failure instanceof Error)) failure = new Error(String(failure));
+
+    if (signal?.aborted) throw abortReason(signal);
+    if (isAccepted && request.isIdempotent !== true) {
+      const accepted = request.wrapAccepted?.(failure, attempt + 1) ?? failure;
+      throw markDeliveryUnknown(accepted);
+    }
+    if (!request.isRetryable(failure)) throw failure;
+    if (attempt >= request.retries) throw request.finalError(failure, attempt + 1);
+    await wait(request.retryDelayMs(attempt, failure), signal);
+  }
+};
+
+module.exports = {
+  abortReason,
+  exponentialDelayMs,
+  isAbortError,
+  jitteredDelayMs,
+  requestWithRetry,
+  sleep,
+};
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index 49d60ed..b32f675 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -1,9 +1,8 @@
 // Ported from upyo v0.7.0 (packages/ses/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
-const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
 
 class SesHttpClient {
   config;
@@ -36,75 +35,32 @@ class SesHttpClient {
    * @throws {SesApiError} If SES returns a client error or all retry attempts
    *                       are exhausted.
    */
-  async makeRequest(url, options) {
-    let lastError = null;
-
-    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
-      let isAccepted = false;
-      try {
-        const response = await this.fetchWithAuth(url, options);
-        isAccepted = response.ok;
+  makeRequest(url, options) {
+    return requestWithRetry({
+      signal: options.signal,
+      retries: this.config.retries,
+      timeoutMs: this.config.timeout,
+      send: (signal) => this.fetchWithAuth(url, options, signal),
+      read: async (response, attempt) => {
         const text = await response.text();
-
-        if (response.status === 200) {
-          return {
-            statusCode: response.status,
-            body: text,
-            headers: this.headersToRecord(response.headers),
-          };
-        }
-
-        let errorData;
-        try {
-          errorData = JSON.parse(text);
-        } catch {
-          errorData = { message: text || `HTTP ${response.status}` };
-        }
-
-        throw new SesApiError(
-          errorData.message || `HTTP ${response.status}`,
-          response.status,
-          errorData.errors,
-          parseRetryAfter(response.headers.get('Retry-After')),
-          attempt + 1,
-        );
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        if (options.signal?.aborted) {
-          throw createAbortError(options.signal);
-        }
-
-        // A 2xx means the provider took the request: sending it again could
-        // deliver the message twice, so what fails after it is not retried.
-        if (isAccepted) throw markDeliveryUnknown(lastError);
-
-        if (isAbortError(error)) {
-          throw error;
-        }
-
-        if (
-          error instanceof SesApiError &&
-          error.statusCode &&
-          error.statusCode >= 400 &&
-          error.statusCode < 500
-        ) {
-          throw error;
-        }
-
-        if (attempt === this.config.retries) {
-          if (lastError instanceof SesApiError) {
-            throw lastError;
-          }
-          throw new SesApiError(lastError.message, undefined, undefined, undefined, attempt + 1);
-        }
-
-        const delay = Math.pow(2, attempt) * 1000;
-        await sleep(delay, options.signal);
-      }
-    }
-
-    throw lastError || new Error('Request failed after all retries');
+        if (response.status !== 200) throw createSesApiError(response, text, attempt);
+        return {
+          statusCode: response.status,
+          body: text,
+          headers: this.headersToRecord(response.headers),
+        };
+      },
+      reject: async (response, attempt) =>
+        createSesApiError(response, await response.text(), attempt),
+      createTimeoutError: () =>
+        new Error(`SES API request timed out after ${this.config.timeout} ms.`),
+      isRetryable: (error) => !isClientError(error) && !isAbortError(error),
+      retryDelayMs: exponentialDelayMs,
+      finalError: (error, attempts) =>
+        error instanceof SesApiError
+          ? error
+          : new SesApiError(error.message, undefined, undefined, undefined, attempts),
+    });
   }
 
   /**
@@ -112,11 +68,10 @@ class SesHttpClient {
    *
    * @param url The URL to make the request to.
    * @param options Fetch options.
+   * @param signal The signal of the attempt, with its deadline.
    * @returns Promise that resolves to the fetch response.
-   * @throws {Error} If the configured request timeout is reached.
-   * @throws {DOMException} If the caller aborts the request.
    */
-  async fetchWithAuth(url, options) {
+  async fetchWithAuth(url, options, signal) {
     const credentials = await this.getCredentials();
     const headers = new Headers(options.headers);
 
@@ -133,27 +88,11 @@ class SesHttpClient {
       signedHeaders.set(key, value);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-
-    const combinedSignal = combineSignals(controller.signal, options.signal);
-
-    try {
-      return await globalThis.fetch(url, {
-        ...options,
-        headers: this.headersToRecord(signedHeaders),
-        signal: combinedSignal.signal,
-      });
-    } catch (error) {
-      if (isAbortError(error) && controller.signal.aborted && !options.signal?.aborted) {
-        // oxlint-disable-next-line preserve-caught-error -- upstream
-        throw new Error(`SES API request timed out after ${this.config.timeout} ms.`);
-      }
-      throw error;
-    } finally {
-      combinedSignal.cleanup();
-      clearTimeout(timeoutId);
-    }
+    return await globalThis.fetch(url, {
+      ...options,
+      headers: this.headersToRecord(signedHeaders),
+      signal,
+    });
   }
 
   async getCredentials() {
@@ -287,34 +226,25 @@ class SesHttpClient {
   }
 }
 
-const isAbortError = (error) => {
-  return error instanceof Error && error.name === 'AbortError';
-};
-
-const sleep = (milliseconds, signal) => {
-  if (signal?.aborted) {
-    return Promise.reject(createAbortError(signal));
+const createSesApiError = (response, text, attempt) => {
+  let errorData;
+  try {
+    errorData = JSON.parse(text);
+  } catch {
+    errorData = { message: text || `HTTP ${response.status}` };
   }
 
-  return new Promise((resolve, reject) => {
-    const abort = () => {
-      clearTimeout(timeoutId);
-      signal?.removeEventListener('abort', abort);
-      reject(createAbortError(signal));
-    };
-
-    const timeoutId = setTimeout(() => {
-      signal?.removeEventListener('abort', abort);
-      resolve();
-    }, milliseconds);
-
-    signal?.addEventListener('abort', abort, { once: true });
-  });
+  return new SesApiError(
+    errorData.message || `HTTP ${response.status}`,
+    response.status,
+    errorData.errors,
+    parseRetryAfter(response.headers.get('Retry-After')),
+    attempt + 1,
+  );
 };
 
-const createAbortError = (signal) => {
-  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
-};
+const isClientError = (error) =>
+  error instanceof SesApiError && error.statusCode >= 400 && error.statusCode < 500;
 
 class SesApiError extends Error {
   statusCode;
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index c6116e7..78d62d5 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -24,3 +24,126 @@ test('Internal: a reset, a timeout or a failure without a cause may have been se
     assert.strictEqual(isUnsentRequestError(error), false);
   }
 });
+
+const { isDeliveryUnknown } = require('../../src/internal/delivery-unknown.js');
+const {
+  exponentialDelayMs,
+  jitteredDelayMs,
+  requestWithRetry,
+} = require('../../src/internal/http.js');
+
+class RejectedError extends Error {}
+
+// A request whose fetches answer in turn with `responses` (a Response, an
+// error to throw, or a function of the attempt's signal).
+const scripted = (responses, overrides = {}) => {
+  const delays = [];
+  let sends = 0;
+  const request = {
+    retries: 2,
+    timeoutMs: 1000,
+    send: async (signal) => {
+      const next = responses[Math.min(sends++, responses.length - 1)];
+      if (typeof next === 'function') return next(signal);
+      if (next instanceof Error) throw next;
+      return next;
+    },
+    read: async (response) => response.text(),
+    reject: async (response) => new RejectedError(`HTTP ${response.status}`),
+    isRetryable: (error) => !(error instanceof RejectedError),
+    retryDelayMs: (attempt) => attempt + 1,
+    createTimeoutError: () => new Error('Timed out.'),
+    finalError: (error, attempts) => Object.assign(error, { attempts }),
+    sleep: async (milliseconds) => {
+      delays.push(milliseconds);
+    },
+    ...overrides,
+  };
+  return { request, delays, sends: () => sends };
+};
+
+test('Internal: a retryable failure is retried after its delay, then the read result returned', async () => {
+  const { request, delays, sends } = scripted([new TypeError('fetch failed'), new Response('ok')]);
+  assert.strictEqual(await requestWithRetry(request), 'ok');
+  assert.strictEqual(sends(), 2);
+  assert.deepStrictEqual(delays, [1]);
+});
+
+test('Internal: a failure that is not retryable is thrown at once, the last one with attempts', async () => {
+  const rejected = scripted([new Response('no', { status: 400 })]);
+  await assert.rejects(requestWithRetry(rejected.request), RejectedError);
+  assert.strictEqual(rejected.sends(), 1);
+
+  const spent = scripted([new TypeError('fetch failed')]);
+  await assert.rejects(requestWithRetry(spent.request), { message: 'fetch failed', attempts: 3 });
+  assert.deepStrictEqual(spent.delays, [1, 2]);
+});
+
+test('Internal: a failure after a 2xx is not retried and is of unknown delivery', async () => {
+  const unreadable = () => {
+    const response = new Response(null, { status: 200 });
+    Object.defineProperty(response, 'text', { value: () => Promise.reject(new Error('reset')) });
+    return response;
+  };
+  const { request, sends } = scripted([unreadable]);
+  const error = await requestWithRetry(request).catch((caught) => caught);
+  assert.strictEqual(sends(), 1);
+  assert.strictEqual(isDeliveryUnknown(error), true);
+
+  const wrapped = scripted([unreadable], {
+    wrapAccepted: (cause) => new Error('wrapped', { cause }),
+  });
+  const wrapping = await requestWithRetry(wrapped.request).catch((caught) => caught);
+  assert.strictEqual(wrapping.message, 'wrapped');
+  assert.strictEqual(isDeliveryUnknown(wrapping), true);
+
+  const idempotent = scripted([unreadable, new Response('ok')], { isIdempotent: true });
+  assert.strictEqual(await requestWithRetry(idempotent.request), 'ok');
+  assert.strictEqual(idempotent.sends(), 2);
+});
+
+test('Internal: an expired deadline gives the timeout error, over the body only if asked', async () => {
+  const hang = (signal) =>
+    new Promise((_resolve, reject) => {
+      signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+    });
+  const headers = scripted([hang], { timeoutMs: 5, retries: 0 });
+  await assert.rejects(requestWithRetry(headers.request), { message: 'Timed out.' });
+
+  const slowBody = (signal) => {
+    const response = new Response(null, { status: 200 });
+    Object.defineProperty(response, 'text', { value: () => hang(signal) });
+    return response;
+  };
+  const body = scripted([slowBody], { timeoutMs: 5, retries: 0, timeoutCoversBody: true });
+  const error = await requestWithRetry(body.request).catch((caught) => caught);
+  assert.strictEqual(error.message, 'Timed out.');
+  assert.strictEqual(isDeliveryUnknown(error), true);
+
+  const late = (signal) =>
+    new Promise((resolve) => setTimeout(() => resolve(new Response(String(signal.aborted))), 5));
+  const disabled = scripted([late], { timeoutMs: 0, isZeroTimeoutDisabled: true });
+  assert.strictEqual(await requestWithRetry(disabled.request), 'false');
+});
+
+test('Internal: an abort of the caller ends the retries with its reason', async () => {
+  const controller = new AbortController();
+  const reason = new Error('Stopped by the caller.');
+  const { request } = scripted([new TypeError('fetch failed')], {
+    signal: controller.signal,
+    sleep: undefined,
+    retryDelayMs: () => 60_000,
+  });
+  const pending = requestWithRetry(request);
+  setTimeout(() => controller.abort(reason), 5);
+  await assert.rejects(pending, (error) => error === reason);
+});
+
+test('Internal: delays double from one second, and the jittered one stays in its upper half', () => {
+  assert.deepStrictEqual([0, 1, 2, 3].map(exponentialDelayMs), [1000, 2000, 4000, 8000]);
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const baseMs = Math.min(1000 * 2 ** attempt, 10_000);
+    const delayMs = jitteredDelayMs(attempt);
+    assert.ok(delayMs >= baseMs / 2 && delayMs <= baseMs, String(delayMs));
+  }
+});

From c619758758c8329ac5bf6072c521d5e35c46daed Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:48:30 +0300
Subject: [PATCH 034/158] refactor(resend): send through the shared request
 helper

./resend moves its retry loop to requestWithRetry with the same request,
error parsing, timeout message, retry rules, capped backoff and final
ResendApiError. Its wait between attempts still ignores the signal, as
upstream's does (known bug 9), passed in as the helper's sleep until that
is fixed on its own. Its tests pass unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/resend/http-client.js | 144 ++++++++++++--------------------------
 1 file changed, 43 insertions(+), 101 deletions(-)

diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index 89722e6..b1166fd 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -1,9 +1,8 @@
 // Ported from upyo v0.7.0 (packages/resend/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
-const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
 
 /**
  * Error thrown when a Resend API request fails.
@@ -113,37 +112,14 @@ class ResendHttpClient {
    * @param options Fetch options.
    * @returns Promise that resolves to the parsed response.
    */
-  async makeRequest(url, options) {
-    let lastError = null;
-
-    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
-      let isAccepted = false;
-      try {
-        const response = await this.fetchWithAuth(url, options);
-        isAccepted = response.ok;
+  makeRequest(url, options) {
+    return requestWithRetry({
+      signal: options.signal,
+      retries: this.config.retries,
+      timeoutMs: this.config.timeout,
+      send: (signal) => this.fetchWithAuth(url, options, signal),
+      read: async (response) => {
         const text = await response.text();
-
-        if (!response.ok) {
-          let errorMessage;
-          try {
-            const errorBody = JSON.parse(text);
-            errorMessage = errorBody.message;
-          } catch {
-            // Ignore if JSON parsing fails, as the body may be non-JSON
-          }
-
-          const parsedErrorMessage = errorMessage === '' ? undefined : errorMessage;
-          const responseMessage = truncateErrorBody(text);
-          const fallbackMessage = responseMessage === '' ? undefined : responseMessage;
-
-          throw new ResendApiError(
-            parsedErrorMessage ?? fallbackMessage ?? `HTTP ${response.status}`,
-            response.status,
-            parseRetryAfter(response.headers.get('Retry-After')),
-            attempt + 1,
-          );
-        }
-
         try {
           return JSON.parse(text);
         } catch (parseError) {
@@ -154,46 +130,38 @@ class ResendHttpClient {
             }`,
           );
         }
-      } catch (error) {
-        if (isCallerAbort(error, options.signal)) {
-          throw error;
-        }
-
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        // A 2xx means the provider took the request: sending it again could
-        // deliver the message twice, so what fails after it is not retried.
-        if (isAccepted) throw markDeliveryUnknown(lastError);
-
-        // Don't retry on client errors (4xx) or AbortError
-        if (
-          error instanceof ResendApiError &&
-          error.statusCode !== undefined &&
-          error.statusCode >= 400 &&
-          error.statusCode < 500
-        ) {
-          throw error;
-        }
-
-        if (error instanceof Error && error.name === 'AbortError') {
-          throw error;
-        }
-
-        // If this is the last attempt, throw the error
-        if (attempt === this.config.retries) {
-          if (lastError instanceof ResendApiError) {
-            throw lastError;
-          }
-          throw new ResendApiError(lastError.message, undefined, undefined, attempt + 1);
+      },
+      reject: async (response, attempt) => {
+        const text = await response.text();
+        let errorMessage;
+        try {
+          errorMessage = JSON.parse(text).message;
+        } catch {
+          // Ignore if JSON parsing fails, as the body may be non-JSON
         }
 
-        // Wait before retrying with exponential backoff
-        const backoffMs = Math.min(1000 * Math.pow(2, attempt), 10000);
-        await new Promise((resolve) => setTimeout(resolve, backoffMs));
-      }
-    }
-
-    throw lastError || new Error('Request failed after all retry attempts');
+        const parsedErrorMessage = errorMessage === '' ? undefined : errorMessage;
+        const responseMessage = truncateErrorBody(text);
+        const fallbackMessage = responseMessage === '' ? undefined : responseMessage;
+
+        return new ResendApiError(
+          parsedErrorMessage ?? fallbackMessage ?? `HTTP ${response.status}`,
+          response.status,
+          parseRetryAfter(response.headers.get('Retry-After')),
+          attempt + 1,
+        );
+      },
+      createTimeoutError: () =>
+        new Error(`Resend API request timed out after ${this.config.timeout} ms.`),
+      isRetryable: (error) => !isClientError(error) && !isAbortError(error),
+      retryDelayMs: (attempt) => Math.min(exponentialDelayMs(attempt), 10000),
+      finalError: (error, attempts) =>
+        error instanceof ResendApiError
+          ? error
+          : new ResendApiError(error.message, undefined, undefined, attempts),
+      // Upstream's wait ignores the signal (CLAUDE.md, known upstream bugs).
+      sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+    });
   }
 
   /**
@@ -201,9 +169,10 @@ class ResendHttpClient {
    *
    * @param url The URL to fetch.
    * @param options Fetch options.
+   * @param signal The signal of the attempt, with its deadline.
    * @returns Promise that resolves to the Response.
    */
-  async fetchWithAuth(url, options) {
+  fetchWithAuth(url, options, signal) {
     const headers = new Headers(options.headers);
 
     // Add authentication
@@ -214,39 +183,12 @@ class ResendHttpClient {
       headers.set(key, value);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-
-    const combinedSignal = combineSignals(controller.signal, options.signal);
-
-    try {
-      const response = await fetch(url, {
-        ...options,
-        headers,
-        signal: combinedSignal.signal,
-      });
-
-      return response;
-    } catch (error) {
-      if (isAbortError(error) && controller.signal.aborted && !options.signal?.aborted) {
-        // oxlint-disable-next-line preserve-caught-error -- upstream
-        throw new Error(`Resend API request timed out after ${this.config.timeout} ms.`);
-      }
-      throw error;
-    } finally {
-      combinedSignal.cleanup();
-      clearTimeout(timeoutId);
-    }
+    return fetch(url, { ...options, headers, signal });
   }
 }
 
-const isAbortError = (error) => {
-  return error instanceof Error && error.name === 'AbortError';
-};
-
-const isCallerAbort = (error, signal) => {
-  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
-};
+const isClientError = (error) =>
+  error instanceof ResendApiError && error.statusCode >= 400 && error.statusCode < 500;
 
 const truncateErrorBody = (text) => {
   return text.length > 500 ? `${text.slice(0, 500)}...` : text;

From cbfffa764e24983e5c4b8a3801dd750bb5583196 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:49:18 +0300
Subject: [PATCH 035/158] refactor(sendgrid): send through the shared request
 helper

./sendgrid moves its retry loop to requestWithRetry with the same request,
202 as the only success, error parsing, timeout message, retry rules,
backoff and final SendGridApiError. Its tests pass unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/sendgrid/http-client.js | 174 +++++++++---------------------------
 1 file changed, 44 insertions(+), 130 deletions(-)

diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
index 9f65998..85474ad 100644
--- a/src/sendgrid/http-client.js
+++ b/src/sendgrid/http-client.js
@@ -1,9 +1,8 @@
 // Ported from upyo v0.7.0 (packages/sendgrid/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
-const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { exponentialDelayMs, requestWithRetry } = require('../internal/http.js');
 
 /**
  * HTTP client wrapper for SendGrid API requests.
@@ -48,84 +47,33 @@ class SendGridHttpClient {
    * @throws {SendGridApiError} If SendGrid returns a client error or all retry
    *                            attempts are exhausted.
    */
-  async makeRequest(url, options) {
-    let lastError = null;
-
-    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
-      let isAccepted = false;
-      try {
-        const response = await this.fetchWithAuth(url, options);
-        isAccepted = response.ok;
-
-        // Get response text
+  makeRequest(url, options) {
+    return requestWithRetry({
+      signal: options.signal,
+      retries: this.config.retries,
+      timeoutMs: this.config.timeout,
+      send: (signal) => this.fetchWithAuth(url, options, signal),
+      read: async (response, attempt) => {
         const text = await response.text();
-
         // SendGrid returns 202 for successful sends
-        if (response.status === 202) {
-          return {
-            statusCode: response.status,
-            body: text,
-            headers: this.headersToRecord(response.headers),
-          };
-        }
-
-        // Handle errors
-        let errorData;
-        try {
-          errorData = JSON.parse(text);
-        } catch {
-          errorData = { message: text || `HTTP ${response.status}` };
-        }
-
-        throw new SendGridApiError(
-          errorData.message || `HTTP ${response.status}`,
-          response.status,
-          errorData.errors,
-          parseRetryAfter(response.headers.get('Retry-After')),
-          attempt + 1,
-        );
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        // Don't retry caller cancellation.
-        if (isCallerAbort(error, options.signal)) {
-          throw error;
-        }
-
-        // A 2xx means the provider took the request: sending it again could
-        // deliver the message twice, so what fails after it is not retried.
-        if (isAccepted) throw markDeliveryUnknown(lastError);
-
-        // Don't retry on client errors (4xx) or if it's the last attempt
-        if (
-          error instanceof SendGridApiError &&
-          error.statusCode &&
-          error.statusCode >= 400 &&
-          error.statusCode < 500
-        ) {
-          throw error;
-        }
-
-        if (attempt === this.config.retries) {
-          if (lastError instanceof SendGridApiError) {
-            throw lastError;
-          }
-          throw new SendGridApiError(
-            lastError.message,
-            undefined,
-            undefined,
-            undefined,
-            attempt + 1,
-          );
-        }
-
-        // Wait before retrying (exponential backoff)
-        const delay = Math.pow(2, attempt) * 1000;
-        await sleep(delay, options.signal);
-      }
-    }
-
-    throw lastError || new Error('Request failed after all retries');
+        if (response.status !== 202) throw createSendGridApiError(response, text, attempt);
+        return {
+          statusCode: response.status,
+          body: text,
+          headers: this.headersToRecord(response.headers),
+        };
+      },
+      reject: async (response, attempt) =>
+        createSendGridApiError(response, await response.text(), attempt),
+      createTimeoutError: () =>
+        new Error(`SendGrid API request timed out after ${this.config.timeout} ms.`),
+      isRetryable: (error) => !isClientError(error),
+      retryDelayMs: exponentialDelayMs,
+      finalError: (error, attempts) =>
+        error instanceof SendGridApiError
+          ? error
+          : new SendGridApiError(error.message, undefined, undefined, undefined, attempts),
+    });
   }
 
   /**
@@ -133,11 +81,10 @@ class SendGridHttpClient {
    *
    * @param url The URL to make the request to.
    * @param options Fetch options.
+   * @param signal The signal of the attempt, with its deadline.
    * @returns Promise that resolves to the fetch response.
-   * @throws {Error} If the configured request timeout is reached.
-   * @throws {DOMException} If the caller aborts the request.
    */
-  async fetchWithAuth(url, options) {
+  fetchWithAuth(url, options, signal) {
     const headers = new Headers(options.headers);
 
     // Add authentication header
@@ -148,27 +95,7 @@ class SendGridHttpClient {
       headers.set(key, value);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-
-    const combinedSignal = combineSignals(controller.signal, options.signal);
-
-    try {
-      return await globalThis.fetch(url, {
-        ...options,
-        headers,
-        signal: combinedSignal.signal,
-      });
-    } catch (error) {
-      if (isAbortError(error) && controller.signal.aborted && !options.signal?.aborted) {
-        // oxlint-disable-next-line preserve-caught-error -- upstream
-        throw new Error(`SendGrid API request timed out after ${this.config.timeout} ms.`);
-      }
-      throw error;
-    } finally {
-      combinedSignal.cleanup();
-      clearTimeout(timeoutId);
-    }
+    return globalThis.fetch(url, { ...options, headers, signal });
   }
 
   /**
@@ -229,37 +156,24 @@ class SendGridApiError extends Error {
   }
 }
 
-const isAbortError = (error) => {
-  return error instanceof Error && error.name === 'AbortError';
-};
-
-const isCallerAbort = (error, signal) => {
-  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
-};
-
-const sleep = (milliseconds, signal) => {
-  if (signal?.aborted) {
-    return Promise.reject(createAbortError(signal));
+const createSendGridApiError = (response, text, attempt) => {
+  let errorData;
+  try {
+    errorData = JSON.parse(text);
+  } catch {
+    errorData = { message: text || `HTTP ${response.status}` };
   }
 
-  return new Promise((resolve, reject) => {
-    const abort = () => {
-      clearTimeout(timeoutId);
-      signal?.removeEventListener('abort', abort);
-      reject(createAbortError(signal));
-    };
-
-    const timeoutId = setTimeout(() => {
-      signal?.removeEventListener('abort', abort);
-      resolve();
-    }, milliseconds);
-
-    signal?.addEventListener('abort', abort, { once: true });
-  });
+  return new SendGridApiError(
+    errorData.message || `HTTP ${response.status}`,
+    response.status,
+    errorData.errors,
+    parseRetryAfter(response.headers.get('Retry-After')),
+    attempt + 1,
+  );
 };
 
-const createAbortError = (signal) => {
-  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
-};
+const isClientError = (error) =>
+  error instanceof SendGridApiError && error.statusCode >= 400 && error.statusCode < 500;
 
 module.exports = { SendGridHttpClient, SendGridApiError };

From 25362598324f6ab74ae3414dabbd8771776b74f4 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:50:17 +0300
Subject: [PATCH 036/158] refactor(mailgun): send through the shared request
 helper

./mailgun moves its retry loop to requestWithRetry with the same request
and Basic authentication, error parsing, timeout message, retry rules,
backoff and final MailgunApiError. Its tests pass unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mailgun/http-client.js | 168 ++++++++++---------------------------
 1 file changed, 44 insertions(+), 124 deletions(-)

diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index baebe41..00a819e 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -1,9 +1,8 @@
 // Ported from upyo v0.7.0 (packages/mailgun/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
-const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
 
 /**
  * HTTP client wrapper for Mailgun API requests.
@@ -44,39 +43,14 @@ class MailgunHttpClient {
    * @throws {MailgunApiError} If Mailgun returns an error response or all
    *                           retry attempts are exhausted.
    */
-  async makeRequest(url, options) {
-    let lastError = null;
-
-    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
-      let isAccepted = false;
-      try {
-        const response = await this.fetchWithAuth(url, options);
-        isAccepted = response.ok;
+  makeRequest(url, options) {
+    return requestWithRetry({
+      signal: options.signal,
+      retries: this.config.retries,
+      timeoutMs: this.config.timeout,
+      send: (signal) => this.fetchWithAuth(url, options, signal),
+      read: async (response) => {
         const text = await response.text();
-
-        if (!response.ok) {
-          let errorMessage;
-          try {
-            // Try to parse the error message from the JSON body
-            errorMessage = JSON.parse(text)?.message;
-          } catch {
-            // Ignore if JSON parsing fails, as the body may be non-JSON
-          }
-
-          // Fallback logic for creating a meaningful error message.
-          // 1. Use the parsed `errorMessage` if available.
-          // 2. Otherwise, use the raw `text` response.
-          // 3. If the raw `text` is also empty, fall back to the HTTP status.
-          // Using `||` is intentional here to treat empty strings as falsy
-          // and ensure a non-empty error message for the tests.
-          throw new MailgunApiError(
-            errorMessage || truncateErrorBody(text) || `HTTP ${response.status}`,
-            response.status,
-            parseRetryAfter(response.headers.get('Retry-After')),
-            attempt + 1,
-          );
-        }
-
         try {
           return JSON.parse(text);
         } catch (jsonError) {
@@ -87,46 +61,39 @@ class MailgunHttpClient {
             `Successfully received response but failed to parse JSON: ${jsonError.message}`,
           );
         }
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        if (options.signal?.aborted) {
-          throw createAbortError(options.signal);
-        }
-
-        // A 2xx means the provider took the request: sending it again could
-        // deliver the message twice, so what fails after it is not retried.
-        if (isAccepted) throw markDeliveryUnknown(lastError);
-
-        // Don't retry caller cancellation.
-        if (isAbortError(error)) {
-          throw error;
-        }
-
-        // Don't retry on client errors (4xx) or if it's the last attempt
-        if (
-          error instanceof MailgunApiError &&
-          error.statusCode &&
-          error.statusCode >= 400 &&
-          error.statusCode < 500
-        ) {
-          throw error;
-        }
-
-        if (attempt === this.config.retries) {
-          if (lastError instanceof MailgunApiError) {
-            throw lastError;
-          }
-          throw new MailgunApiError(lastError.message, undefined, undefined, attempt + 1);
+      },
+      reject: async (response, attempt) => {
+        const text = await response.text();
+        let errorMessage;
+        try {
+          // Try to parse the error message from the JSON body
+          errorMessage = JSON.parse(text)?.message;
+        } catch {
+          // Ignore if JSON parsing fails, as the body may be non-JSON
         }
 
-        // Wait before retrying (exponential backoff)
-        const delay = Math.pow(2, attempt) * 1000;
-        await sleep(delay, options.signal);
-      }
-    }
-
-    throw lastError || new Error('Request failed after all retries');
+        // Fallback logic for creating a meaningful error message.
+        // 1. Use the parsed `errorMessage` if available.
+        // 2. Otherwise, use the raw `text` response.
+        // 3. If the raw `text` is also empty, fall back to the HTTP status.
+        // Using `||` is intentional here to treat empty strings as falsy
+        // and ensure a non-empty error message for the tests.
+        return new MailgunApiError(
+          errorMessage || truncateErrorBody(text) || `HTTP ${response.status}`,
+          response.status,
+          parseRetryAfter(response.headers.get('Retry-After')),
+          attempt + 1,
+        );
+      },
+      createTimeoutError: () =>
+        new Error(`Mailgun API request timed out after ${this.config.timeout} ms.`),
+      isRetryable: (error) => !isClientError(error) && !isAbortError(error),
+      retryDelayMs: exponentialDelayMs,
+      finalError: (error, attempts) =>
+        error instanceof MailgunApiError
+          ? error
+          : new MailgunApiError(error.message, undefined, undefined, attempts),
+    });
   }
 
   /**
@@ -134,11 +101,10 @@ class MailgunHttpClient {
    *
    * @param url The URL to make the request to.
    * @param options Fetch options.
+   * @param signal The signal of the attempt, with its deadline.
    * @returns Promise that resolves to the fetch response.
-   * @throws {Error} If the configured request timeout is reached.
-   * @throws {DOMException} If the caller aborts the request.
    */
-  async fetchWithAuth(url, options) {
+  fetchWithAuth(url, options, signal) {
     const headers = new Headers(options.headers);
 
     // Add authentication header
@@ -150,27 +116,7 @@ class MailgunHttpClient {
       headers.set(key, value);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-
-    const combinedSignal = combineSignals(controller.signal, options.signal);
-
-    try {
-      return await globalThis.fetch(url, {
-        ...options,
-        headers,
-        signal: combinedSignal.signal,
-      });
-    } catch (error) {
-      if (isAbortError(error) && controller.signal.aborted && !options.signal?.aborted) {
-        // oxlint-disable-next-line preserve-caught-error -- upstream
-        throw new Error(`Mailgun API request timed out after ${this.config.timeout} ms.`);
-      }
-      throw error;
-    } finally {
-      combinedSignal.cleanup();
-      clearTimeout(timeoutId);
-    }
+    return globalThis.fetch(url, { ...options, headers, signal });
   }
 }
 
@@ -210,34 +156,8 @@ class MailgunApiError extends Error {
   }
 }
 
-const isAbortError = (error) => {
-  return error instanceof Error && error.name === 'AbortError';
-};
-
-const sleep = (milliseconds, signal) => {
-  if (signal?.aborted) {
-    return Promise.reject(createAbortError(signal));
-  }
-
-  return new Promise((resolve, reject) => {
-    const abort = () => {
-      clearTimeout(timeoutId);
-      signal?.removeEventListener('abort', abort);
-      reject(createAbortError(signal));
-    };
-
-    const timeoutId = setTimeout(() => {
-      signal?.removeEventListener('abort', abort);
-      resolve();
-    }, milliseconds);
-
-    signal?.addEventListener('abort', abort, { once: true });
-  });
-};
-
-const createAbortError = (signal) => {
-  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
-};
+const isClientError = (error) =>
+  error instanceof MailgunApiError && error.statusCode >= 400 && error.statusCode < 500;
 
 const truncateErrorBody = (text) => {
   return text.length > 500 ? `${text.slice(0, 500)}...` : text;

From 92de16b961fa0e7adfd1f3c4fcce7c4e74ac9fc0 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:51:22 +0300
Subject: [PATCH 037/158] refactor(mailtrap): send through the shared request
 helper

./mailtrap moves its retry loop to requestWithRetry with the same request,
error parsing, sandbox Retry-After inference, timeout error, retry rules,
jittered backoff and final errors. A timeout of 0 still means none and the
deadline still covers the body, as options of the helper for now.

One change, completing the fix of failures after a 2xx: a 200 whose body is
not JSON threw a plain SyntaxError, neither marked nor wrapped; like an
unreadable body, it is now a MailtrapResponseError of unknown delivery.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mailtrap/http-client.js | 173 +++++++++---------------------------
 tests/unit/mailtrap.test.js |  13 +++
 2 files changed, 56 insertions(+), 130 deletions(-)

diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index 67874f6..0144149 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/mailtrap/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { combineSignals } = require('../core/abort-signal.js');
+const { jitteredDelayMs, requestWithRetry } = require('../internal/http.js');
 
 const maxErrorMessageLength = 500;
 const sandboxRateLimitWindowMilliseconds = 10_000;
@@ -130,65 +130,46 @@ class MailtrapHttpClient {
     return `${baseUrl}/api/${kind}${suffix}`;
   }
 
-  async makeRequest(url, body, signal) {
-    let lastError = null;
-
-    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
-      signal?.throwIfAborted();
-
-      let responseText;
-      try {
-        const { response, text } = await this.fetchWithAuth(url, body, signal);
-        responseText = text;
-
-        if (!response.ok) {
-          const message = parseErrorMessage(responseText, response.status);
-          throw new MailtrapApiError(
-            message,
-            response.status,
-            parseRetryAfter(response.headers.get('Retry-After')) ??
-              inferSandboxRetryAfter(message, response.status, this.config.sandbox),
-            attempt + 1,
+  makeRequest(url, body, signal) {
+    return requestWithRetry({
+      signal,
+      retries: this.config.retries,
+      timeoutMs: this.config.timeout,
+      isZeroTimeoutDisabled: true,
+      timeoutCoversBody: true,
+      send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
+      read: async (response) => {
+        const text = await response.text();
+        try {
+          return JSON.parse(text);
+        } catch (error) {
+          throw new SyntaxError(
+            `Invalid JSON response from Mailtrap API: ${
+              error instanceof Error ? error.message : String(error)
+            }.`,
           );
         }
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        if (error instanceof MailtrapResponseError) {
-          throw new MailtrapResponseError(error.cause, attempt + 1);
-        }
-
-        if (error instanceof MailtrapApiError && !isRetryable(error)) {
-          throw error;
-        }
-
-        if (error instanceof Error && error.name === 'AbortError' && signal?.aborted) {
-          throw error;
-        }
-
-        if (attempt === this.config.retries) {
-          throw withAttempts(lastError, attempt + 1);
-        }
-
-        await sleep(calculateRetryDelay(attempt, lastError), signal);
-        continue;
-      }
-
-      try {
-        return JSON.parse(responseText);
-      } catch (error) {
-        throw new SyntaxError(
-          `Invalid JSON response from Mailtrap API: ${
-            error instanceof Error ? error.message : String(error)
-          }.`,
+      },
+      reject: async (response, attempt) => {
+        const message = parseErrorMessage(await response.text(), response.status);
+        return new MailtrapApiError(
+          message,
+          response.status,
+          parseRetryAfter(response.headers.get('Retry-After')) ??
+            inferSandboxRetryAfter(message, response.status, this.config.sandbox),
+          attempt + 1,
         );
-      }
-    }
-
-    throw lastError ?? new Error('Request failed after all retry attempts.');
+      },
+      createTimeoutError: () => new MailtrapTimeoutError(this.config.timeout),
+      // A 2xx response means Mailtrap may already have sent the message.
+      wrapAccepted: (error, attempts) => new MailtrapResponseError(error, attempts),
+      isRetryable: (error) => !(error instanceof MailtrapApiError) || isRetryable(error),
+      retryDelayMs: calculateRetryDelay,
+      finalError: withAttempts,
+    });
   }
 
-  async fetchWithAuth(url, body, signal) {
+  fetchWithAuth(url, body, signal) {
     const headers = new Headers({
       'Content-Type': 'application/json',
       'Api-Token': this.config.apiToken,
@@ -199,45 +180,12 @@ class MailtrapHttpClient {
       headers.set(key, value);
     }
 
-    const timeoutController = new AbortController();
-    const timeoutId =
-      this.config.timeout > 0
-        ? setTimeout(() => timeoutController.abort(), this.config.timeout)
-        : undefined;
-    const requestSignal = combineSignals(timeoutController.signal, signal);
-
-    let response;
-    try {
-      response = await globalThis.fetch(url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(body),
-        signal: requestSignal.signal,
-      });
-      const text = await response.text();
-      return { response, text };
-    } catch (error) {
-      signal?.throwIfAborted();
-      let cause = error;
-      if (
-        error instanceof Error &&
-        error.name === 'AbortError' &&
-        timeoutController.signal.aborted &&
-        !signal?.aborted
-      ) {
-        cause = new MailtrapTimeoutError(this.config.timeout);
-      }
-      // A 2xx response means Mailtrap may already have sent the message.
-      if (response?.ok) {
-        throw new MailtrapResponseError(cause);
-      }
-      throw cause;
-    } finally {
-      requestSignal.cleanup();
-      if (timeoutId !== undefined) {
-        clearTimeout(timeoutId);
-      }
-    }
+    return globalThis.fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal,
+    });
   }
 }
 
@@ -246,8 +194,7 @@ const isRetryable = (error) => {
 };
 
 const calculateRetryDelay = (attempt, error) => {
-  const baseDelay = Math.min(1000 * Math.pow(2, attempt), 10000);
-  const backoffDelay = Math.round(baseDelay / 2 + Math.random() * (baseDelay / 2));
+  const backoffDelay = jitteredDelayMs(attempt);
   if (error instanceof MailtrapApiError) {
     return Math.max(backoffDelay, error.retryAfterMilliseconds ?? 0);
   }
@@ -309,40 +256,6 @@ const truncateErrorMessage = (message) => {
     : message;
 };
 
-const abortReason = (signal) => {
-  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
-};
-
-const sleep = (ms, signal) => {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(abortReason(signal));
-      return;
-    }
-
-    const timeoutState = {};
-    const onAbort = () => {
-      if (timeoutState.id !== undefined) {
-        clearTimeout(timeoutState.id);
-      }
-      signal?.removeEventListener('abort', onAbort);
-      reject(abortReason(signal));
-    };
-
-    signal?.addEventListener('abort', onAbort, { once: true });
-
-    if (signal?.aborted) {
-      onAbort();
-      return;
-    }
-
-    timeoutState.id = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort);
-      resolve();
-    }, ms);
-  });
-};
-
 module.exports = {
   MailtrapApiError,
   MailtrapTimeoutError,
diff --git a/tests/unit/mailtrap.test.js b/tests/unit/mailtrap.test.js
index 648c1e1..0800c09 100644
--- a/tests/unit/mailtrap.test.js
+++ b/tests/unit/mailtrap.test.js
@@ -152,3 +152,16 @@ test('Mailtrap: batches that fail, partly or whole, fail their messages', async
   );
   assert.deepStrictEqual(allBroken[0].errorMessages, ['Cannot read attachment']);
 });
+
+test('Mailtrap: a 200 that is not JSON is sent once, of unknown delivery', async (t) => {
+  let requests = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    requests++;
+    return new Response('<html>accepted</html>', { status: 200 });
+  });
+  const receipt = await new MailtrapTransport({ ...config, retries: 3 }).send(message());
+  assert.strictEqual(requests, 1);
+  assert.strictEqual(receipt.successful, false);
+  assert.strictEqual(receipt.deliveryUnknown, true);
+  assert.strictEqual(receipt.retryable, false);
+});

From e69ff9e8729c81c65355d1a5ad2534f0afdb53d8 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:52:18 +0300
Subject: [PATCH 038/158] refactor(maileroo): send through the shared request
 helper

./maileroo moves its retry loop to requestWithRetry with the same request,
error parsing, timeout error, retry rules, jittered backoff honoring
Retry-After and final errors. A timeout of 0 still means none and the
deadline still covers the body, as options of the helper for now; the body
and its JSON are read in the helper's read step, which marks their failure
after a 2xx as before. Its tests pass unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/maileroo/http-client.js | 150 ++++++++----------------------------
 1 file changed, 30 insertions(+), 120 deletions(-)

diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index f6457fa..f84d4bd 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -1,9 +1,8 @@
 // Ported from upyo v0.7.0 (packages/maileroo/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
-const { isDeliveryUnknown, markDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { jitteredDelayMs, requestWithRetry } = require('../internal/http.js');
 
 const maxErrorMessageLength = 500;
 
@@ -89,56 +88,30 @@ class MailerooHttpClient {
     return this.makeRequest(url, messageData, signal);
   }
 
-  async makeRequest(url, body, signal) {
-    let lastError;
-
-    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
-      signal?.throwIfAborted();
-
-      let responseText;
-      try {
-        const { response, text } = await this.fetchWithAuth(url, body, signal);
-
-        if (!response.ok) {
-          throw new MailerooApiError(
-            parseErrorMessage(text, response.status),
-            response.status,
-            parseRetryAfter(response.headers.get('Retry-After')),
-            attempt + 1,
-          );
-        }
-
-        responseText = text;
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        if (signal?.aborted || isDeliveryUnknown(error)) {
-          throw error;
-        }
-
-        if (error instanceof MailerooApiError && !isRetryable(error)) {
-          throw error;
-        }
-
-        if (attempt === this.config.retries) {
-          throw withAttempts(lastError, attempt + 1);
-        }
-
-        await sleep(calculateRetryDelay(attempt, lastError), signal);
-        continue;
-      }
-
-      try {
-        return parseResponse(responseText);
-      } catch (error) {
-        throw markDeliveryUnknown(error);
-      }
-    }
-
-    throw lastError ?? new Error('Request failed after all retry attempts.');
+  makeRequest(url, body, signal) {
+    return requestWithRetry({
+      signal,
+      retries: this.config.retries,
+      timeoutMs: this.config.timeout,
+      isZeroTimeoutDisabled: true,
+      timeoutCoversBody: true,
+      send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
+      read: async (response) => parseResponse(await response.text()),
+      reject: async (response, attempt) =>
+        new MailerooApiError(
+          parseErrorMessage(await response.text(), response.status),
+          response.status,
+          parseRetryAfter(response.headers.get('Retry-After')),
+          attempt + 1,
+        ),
+      createTimeoutError: () => new MailerooTimeoutError(this.config.timeout),
+      isRetryable: (error) => !(error instanceof MailerooApiError) || isRetryable(error),
+      retryDelayMs: calculateRetryDelay,
+      finalError: withAttempts,
+    });
   }
 
-  async fetchWithAuth(url, body, signal) {
+  fetchWithAuth(url, body, signal) {
     const headers = new Headers({
       'Content-Type': 'application/json',
       'X-API-Key': this.config.apiKey,
@@ -148,40 +121,12 @@ class MailerooHttpClient {
       headers.set(key, value);
     }
 
-    const timeoutController = new AbortController();
-    const timeoutId =
-      this.config.timeout > 0
-        ? setTimeout(() => timeoutController.abort(), this.config.timeout)
-        : undefined;
-    const requestSignal = combineSignals(timeoutController.signal, signal);
-
-    let isAccepted = false;
-    try {
-      const response = await globalThis.fetch(url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(body),
-        signal: requestSignal.signal,
-      });
-      isAccepted = response.ok;
-      const text = await response.text();
-      return { response, text };
-    } catch (error) {
-      const isTimeout =
-        error instanceof Error &&
-        error.name === 'AbortError' &&
-        timeoutController.signal.aborted &&
-        !signal?.aborted;
-      const failure = isTimeout ? new MailerooTimeoutError(this.config.timeout) : error;
-      // A 2xx means Maileroo took the request: sending it again could
-      // deliver the message twice.
-      throw isAccepted && !signal?.aborted ? markDeliveryUnknown(failure) : failure;
-    } finally {
-      requestSignal.cleanup();
-      if (timeoutId !== undefined) {
-        clearTimeout(timeoutId);
-      }
-    }
+    return globalThis.fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal,
+    });
   }
 }
 
@@ -200,8 +145,7 @@ const isRetryable = (error) => {
 };
 
 const calculateRetryDelay = (attempt, error) => {
-  const baseDelay = Math.min(1000 * Math.pow(2, attempt), 10000);
-  const backoffDelay = Math.round(baseDelay / 2 + Math.random() * (baseDelay / 2));
+  const backoffDelay = jitteredDelayMs(attempt);
   if (error instanceof MailerooApiError) {
     return Math.max(backoffDelay, error.retryAfterMilliseconds ?? 0);
   }
@@ -252,38 +196,4 @@ const truncateErrorMessage = (message) => {
     : message;
 };
 
-const abortReason = (signal) => {
-  return signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
-};
-
-const sleep = (ms, signal) => {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(abortReason(signal));
-      return;
-    }
-
-    const timeoutState = {};
-    const onAbort = () => {
-      if (timeoutState.id !== undefined) {
-        clearTimeout(timeoutState.id);
-      }
-      signal?.removeEventListener('abort', onAbort);
-      reject(abortReason(signal));
-    };
-
-    signal?.addEventListener('abort', onAbort, { once: true });
-
-    if (signal?.aborted) {
-      onAbort();
-      return;
-    }
-
-    timeoutState.id = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort);
-      resolve();
-    }, ms);
-  });
-};
-
 module.exports = { MailerooApiError, MailerooTimeoutError, MailerooHttpClient };

From 59b137e9cda807580f14405a16ee955b3159e2b1 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:53:08 +0300
Subject: [PATCH 039/158] refactor(lettermint): send through the shared request
 helper

./lettermint moves its retry loop to requestWithRetry with the same request
and idempotency key, error parsing, timeout error, retry rules, jittered
backoff and final errors. A timeout of 0 still means none, as an option of
the helper for now, and its own wait, which rejects with an AbortError of
its own instead of the caller's reason, is passed in until that is fixed.
Its tests pass unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/lettermint/http-client.js | 114 ++++++++++------------------------
 1 file changed, 32 insertions(+), 82 deletions(-)

diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index 56dcb30..b9e8486 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -1,9 +1,8 @@
 // Ported from upyo v0.7.0 (packages/lettermint/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
-const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { jitteredDelayMs, requestWithRetry } = require('../internal/http.js');
 
 /**
  * Lettermint API error class for API-specific failures.
@@ -99,27 +98,15 @@ class LettermintHttpClient {
     return this.makeRequest(url, messagesData, signal, idempotencyKey);
   }
 
-  async makeRequest(url, body, signal, idempotencyKey) {
-    let lastError = null;
-
-    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
-      signal?.throwIfAborted();
-
-      let isAccepted = false;
-      try {
-        const response = await this.fetchWithAuth(url, body, signal, idempotencyKey);
-        isAccepted = response.ok;
+  makeRequest(url, body, signal, idempotencyKey) {
+    return requestWithRetry({
+      signal,
+      retries: this.config.retries,
+      timeoutMs: this.config.timeout,
+      isZeroTimeoutDisabled: true,
+      send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal, idempotencyKey),
+      read: async (response) => {
         const text = await response.text();
-
-        if (!response.ok) {
-          throw new LettermintApiError(
-            parseErrorMessage(text, response.status),
-            response.status,
-            parseRetryAfter(response.headers.get('Retry-After')),
-            attempt + 1,
-          );
-        }
-
         try {
           return JSON.parse(text);
         } catch (error) {
@@ -129,33 +116,25 @@ class LettermintHttpClient {
             }.`,
           );
         }
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        // A 2xx means the provider took the request: sending it again could
-        // deliver the message twice, so what fails after it is not retried.
-        if (isAccepted && !signal?.aborted) throw markDeliveryUnknown(lastError);
-
-        if (error instanceof LettermintApiError && !isRetryable(error)) {
-          throw error;
-        }
-
-        if (error instanceof Error && error.name === 'AbortError' && signal?.aborted) {
-          throw error;
-        }
-
-        if (attempt === this.config.retries) {
-          throw withAttempts(lastError, attempt + 1);
-        }
-
-        await sleep(calculateRetryDelay(attempt), signal);
-      }
-    }
-
-    throw lastError ?? new Error('Request failed after all retry attempts.');
+      },
+      reject: async (response, attempt) =>
+        new LettermintApiError(
+          parseErrorMessage(await response.text(), response.status),
+          response.status,
+          parseRetryAfter(response.headers.get('Retry-After')),
+          attempt + 1,
+        ),
+      createTimeoutError: () => new LettermintTimeoutError(this.config.timeout),
+      isRetryable: (error) => !(error instanceof LettermintApiError) || isRetryable(error),
+      retryDelayMs: jitteredDelayMs,
+      finalError: withAttempts,
+      // Upstream's wait rejects with an AbortError of its own rather than the
+      // caller's reason.
+      sleep,
+    });
   }
 
-  async fetchWithAuth(url, body, signal, idempotencyKey) {
+  fetchWithAuth(url, body, signal, idempotencyKey) {
     const headers = new Headers({
       'Content-Type': 'application/json',
       'x-lettermint-token': this.config.apiToken,
@@ -169,36 +148,12 @@ class LettermintHttpClient {
       headers.set(key, value);
     }
 
-    const timeoutController = new AbortController();
-    const timeoutId =
-      this.config.timeout > 0
-        ? setTimeout(() => timeoutController.abort(), this.config.timeout)
-        : undefined;
-    const requestSignal = combineSignals(timeoutController.signal, signal);
-
-    try {
-      return await globalThis.fetch(url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(body),
-        signal: requestSignal.signal,
-      });
-    } catch (error) {
-      if (
-        error instanceof Error &&
-        error.name === 'AbortError' &&
-        timeoutController.signal.aborted &&
-        !signal?.aborted
-      ) {
-        throw new LettermintTimeoutError(this.config.timeout);
-      }
-      throw error;
-    } finally {
-      requestSignal.cleanup();
-      if (timeoutId !== undefined) {
-        clearTimeout(timeoutId);
-      }
-    }
+    return globalThis.fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal,
+    });
   }
 }
 
@@ -216,11 +171,6 @@ const isRetryable = (error) => {
   return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
 };
 
-const calculateRetryDelay = (attempt) => {
-  const baseDelay = Math.min(1000 * Math.pow(2, attempt), 10000);
-  return Math.round(baseDelay / 2 + Math.random() * (baseDelay / 2));
-};
-
 const parseErrorMessage = (text, statusCode) => {
   try {
     const errorBody = JSON.parse(text);

From 3d9752db414d3fb5248ac9ba1986e14850b43f8d Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:54:56 +0300
Subject: [PATCH 040/158] refactor(plunk): send through the shared request
 helper

./plunk moves its retry loop to requestWithRetry with the same request,
error message, timeout message, retry rules, capped backoff and final
PlunkApiError. A timeout of 0 still means none, and its wait still ignores
the signal (known bug 9), both passed in until they are fixed on their own.

Its refusal in a 200 (success: false) stays a definite failure rather than
an unknown delivery: requestWithRetry takes an isAnswer option for an error
that is the provider's own answer in a 2xx. Its tests pass unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/internal/http.js        |   6 +-
 src/plunk/http-client.js    | 167 +++++++++++-------------------------
 tests/unit/internal.test.js |  11 +++
 3 files changed, 65 insertions(+), 119 deletions(-)

diff --git a/src/internal/http.js b/src/internal/http.js
index ed8de4f..4b50a05 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -98,7 +98,10 @@ const startDeadline = (timeoutMs, isZeroTimeoutDisabled, signal) => {
  * - `retries`, `timeoutMs`, `signal`;
  * - `createTimeoutError(error)`: the error of an expired deadline;
  * - `finalError(error, attempts)`: the error thrown once retries are spent;
- * - optional `wrapAccepted(error, attempts)`, `isIdempotent`, `sleep`, and
+ * - optional `wrapAccepted(error, attempts)`, `isAnswer(error)` (an error that
+ *   is the provider's own answer in a 2xx, such as a refusal in its body,
+ *   thrown as it is rather than as of unknown delivery), `isIdempotent`,
+ *   `sleep`, and
  *   until they are unified, `isZeroTimeoutDisabled` (a timeout of 0 or less
  *   means none) and `timeoutCoversBody` (the deadline lasts until `read`
  *   returns, not only until the headers arrive).
@@ -133,6 +136,7 @@ const requestWithRetry = async (request) => {
 
     if (signal?.aborted) throw abortReason(signal);
     if (isAccepted && request.isIdempotent !== true) {
+      if (request.isAnswer?.(failure) === true) throw failure;
       const accepted = request.wrapAccepted?.(failure, attempt + 1) ?? failure;
       throw markDeliveryUnknown(accepted);
     }
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index 83f08de..3cd3e6a 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -1,9 +1,8 @@
 // Ported from upyo v0.7.0 (packages/plunk/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
-const { markDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
 
 /**
  * Error thrown when a Plunk API request fails.
@@ -70,74 +69,49 @@ class PlunkHttpClient {
    * @returns Promise that resolves to Plunk API response
    * @throws PlunkError if the request fails after all retries
    */
-  async sendMessage(emailData, signal) {
+  sendMessage(emailData, signal) {
     const url = `${this.config.baseUrl}/v1/send`;
 
-    let lastError = null;
-
-    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
-      signal?.throwIfAborted();
-
-      let isAccepted = false;
-      try {
-        const response = await this.makeRequest(url, emailData, signal);
-        isAccepted = response.ok;
-        return await this.parseResponse(response);
-      } catch (error) {
-        if (isCallerAbort(error, signal)) {
-          throw error;
-        }
-
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        // A 2xx means Plunk took the request: sending it again could deliver
-        // the message twice.  Its explicit refusal (success: false) is a
-        // failure of its own; anything else that fails after it is unknown.
-        if (isAccepted) {
-          throw lastError instanceof PlunkApiError ? lastError : markDeliveryUnknown(lastError);
-        }
-
-        // Don't retry on client errors (4xx) or AbortError
-        if (error instanceof Error && error.name === 'AbortError') {
-          throw error;
-        }
-
-        if (
-          error instanceof PlunkApiError &&
-          error.statusCode !== undefined &&
-          error.statusCode >= 400 &&
-          error.statusCode < 500
-        ) {
-          throw new PlunkApiError(
-            error.message,
-            error.statusCode,
-            error.retryAfterMilliseconds,
-            attempt + 1,
-          );
+    return requestWithRetry({
+      signal,
+      retries: this.config.retries,
+      timeoutMs: this.config.timeout,
+      isZeroTimeoutDisabled: true,
+      send: (attemptSignal) => this.makeRequest(url, emailData, attemptSignal),
+      read: (response) => this.parseResponse(response),
+      reject: async (response, attempt) => {
+        let errorBody;
+        try {
+          errorBody = await response.text();
+        } catch {
+          errorBody = 'Failed to read error response';
         }
 
-        // If this was the last attempt, throw the error
-        if (attempt === this.config.retries) {
-          break;
-        }
-
-        // Wait before retrying (exponential backoff)
-        const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
-        await this.sleep(delay);
-      }
-    }
-
-    // All retries failed
-    const errorMessage = lastError?.message ?? 'Unknown error occurred';
-    if (lastError instanceof PlunkApiError) {
-      throw new PlunkApiError(
-        lastError.message,
-        lastError.statusCode,
-        lastError.retryAfterMilliseconds,
-        this.config.retries + 1,
-      );
-    }
-    throw new PlunkApiError(errorMessage, undefined, undefined, this.config.retries + 1);
+        return new PlunkApiError(
+          `HTTP ${response.status}: ${response.statusText}. ${truncateErrorBody(errorBody)}`,
+          response.status,
+          parseRetryAfter(response.headers.get('Retry-After')),
+          attempt + 1,
+        );
+      },
+      createTimeoutError: () =>
+        new Error(`Plunk API request timed out after ${this.config.timeout} ms.`),
+      // Plunk refusing in a 200 (success: false) is a failure of its own.
+      isAnswer: (error) => error instanceof PlunkApiError,
+      isRetryable: (error) => !isClientError(error) && !isAbortError(error),
+      retryDelayMs: (attempt) => Math.min(exponentialDelayMs(attempt), 10000),
+      finalError: (error, attempts) =>
+        error instanceof PlunkApiError
+          ? new PlunkApiError(
+              error.message,
+              error.statusCode,
+              error.retryAfterMilliseconds,
+              attempts,
+            )
+          : new PlunkApiError(error.message, undefined, undefined, attempts),
+      // Upstream's wait ignores the signal (CLAUDE.md, known upstream bugs).
+      sleep: (milliseconds) => this.sleep(milliseconds),
+    });
   }
 
   /**
@@ -148,57 +122,19 @@ class PlunkHttpClient {
    * @param signal - Optional AbortSignal for cancellation
    * @returns Promise that resolves to the Response object
    */
-  async makeRequest(url, emailData, signal) {
+  makeRequest(url, emailData, signal) {
     const headers = {
       Authorization: `Bearer ${this.config.apiKey}`,
       'Content-Type': 'application/json',
       ...this.config.headers,
     };
 
-    const timeoutController = new AbortController();
-    const timeoutId =
-      this.config.timeout > 0
-        ? setTimeout(() => timeoutController.abort(), this.config.timeout)
-        : undefined;
-    const combinedSignal = combineSignals(timeoutController.signal, signal);
-
-    let response;
-    try {
-      response = await fetch(url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(emailData),
-        signal: combinedSignal.signal,
-      });
-    } catch (error) {
-      if (isAbortError(error) && timeoutController.signal.aborted && !signal?.aborted) {
-        // oxlint-disable-next-line preserve-caught-error -- upstream
-        throw new Error(`Plunk API request timed out after ${this.config.timeout} ms.`);
-      }
-      throw error;
-    } finally {
-      combinedSignal.cleanup();
-      if (timeoutId !== undefined) {
-        clearTimeout(timeoutId);
-      }
-    }
-
-    if (!response.ok) {
-      let errorBody;
-      try {
-        errorBody = await response.text();
-      } catch {
-        errorBody = 'Failed to read error response';
-      }
-
-      throw new PlunkApiError(
-        `HTTP ${response.status}: ${response.statusText}. ${truncateErrorBody(errorBody)}`,
-        response.status,
-        parseRetryAfter(response.headers.get('Retry-After')),
-      );
-    }
-
-    return response;
+    return fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(emailData),
+      signal,
+    });
   }
 
   /**
@@ -257,13 +193,8 @@ class PlunkHttpClient {
   }
 }
 
-const isAbortError = (error) => {
-  return error instanceof Error && error.name === 'AbortError';
-};
-
-const isCallerAbort = (error, signal) => {
-  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
-};
+const isClientError = (error) =>
+  error instanceof PlunkApiError && error.statusCode >= 400 && error.statusCode < 500;
 
 const truncateErrorBody = (text) => {
   return text.length > 500 ? `${text.slice(0, 500)}...` : text;
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index 78d62d5..619c1ad 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -97,6 +97,17 @@ test('Internal: a failure after a 2xx is not retried and is of unknown delivery'
   assert.strictEqual(wrapping.message, 'wrapped');
   assert.strictEqual(isDeliveryUnknown(wrapping), true);
 
+  const refusal = new RejectedError('Refused in the body.');
+  const answered = scripted([new Response('{}')], {
+    read: async () => {
+      throw refusal;
+    },
+    isAnswer: (failure) => failure instanceof RejectedError,
+  });
+  const answer = await requestWithRetry(answered.request).catch((caught) => caught);
+  assert.strictEqual(answer, refusal);
+  assert.strictEqual(isDeliveryUnknown(answer), false);
+
   const idempotent = scripted([unreadable, new Response('ok')], { isIdempotent: true });
   assert.strictEqual(await requestWithRetry(idempotent.request), 'ok');
   assert.strictEqual(idempotent.sends(), 2);

From 5a3e90aeedc4b083dad4f9c4af9fba110fadd6ec Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:57:05 +0300
Subject: [PATCH 041/158] refactor(jmap): send through the shared request
 helper

The session fetch and executeRequest of ./jmap move to requestWithRetry
with the same authentication, bodies (a string, or a stream that cannot be
replayed), errors, retry rules, backoff and final JmapApiError with its
cause. Every JMAP request is idempotent to the helper, so a 2xx it cannot
read is retried as before; the submission of an email has no retries and is
judged by executeSubmission. The timeout and final errors of the helper are
now optional, the failure itself by default, as JMAP keeps the AbortError
of a timeout. Its tests pass unchanged.

All nine HTTP clients now share one retry loop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/internal/http.js    |  10 +-
 src/jmap/http-client.js | 204 ++++++++++++----------------------------
 2 files changed, 66 insertions(+), 148 deletions(-)

diff --git a/src/internal/http.js b/src/internal/http.js
index 4b50a05..afcf74c 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -96,8 +96,10 @@ const startDeadline = (timeoutMs, isZeroTimeoutDisabled, signal) => {
  * - `reject(response, attempt)`: the error of any other response;
  * - `isRetryable(error)`, `retryDelayMs(attempt, error)`;
  * - `retries`, `timeoutMs`, `signal`;
- * - `createTimeoutError(error)`: the error of an expired deadline;
- * - `finalError(error, attempts)`: the error thrown once retries are spent;
+ * - `createTimeoutError(error)`: the error of an expired deadline, by default
+ *   the `AbortError` itself;
+ * - `finalError(error, attempts)`: the error thrown once retries are spent,
+ *   by default the last failure;
  * - optional `wrapAccepted(error, attempts)`, `isAnswer(error)` (an error that
  *   is the provider's own answer in a 2xx, such as a refusal in its body,
  *   thrown as it is rather than as of unknown delivery), `isIdempotent`,
@@ -128,7 +130,7 @@ const requestWithRetry = async (request) => {
       failure = await request.reject(response, attempt);
     } catch (error) {
       const isTimeout = deadline.isExpired && !signal?.aborted && isAbortError(error);
-      failure = isTimeout ? request.createTimeoutError(error) : error;
+      failure = isTimeout ? (request.createTimeoutError?.(error) ?? error) : error;
     } finally {
       deadline.stop();
     }
@@ -141,7 +143,7 @@ const requestWithRetry = async (request) => {
       throw markDeliveryUnknown(accepted);
     }
     if (!request.isRetryable(failure)) throw failure;
-    if (attempt >= request.retries) throw request.finalError(failure, attempt + 1);
+    if (attempt >= request.retries) throw request.finalError?.(failure, attempt + 1) ?? failure;
     await wait(request.retryDelayMs(attempt, failure), signal);
   }
 };
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index e555bce..4ccd754 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { JmapApiError } = require('./errors.js');
+const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
 
 /**
  * HTTP client for JMAP API requests.
@@ -25,24 +26,29 @@ class JmapHttpClient {
    * @param signal Optional abort signal.
    * @returns The JMAP session response.
    */
-  async fetchSession(signal) {
+  fetchSession(signal) {
     signal?.throwIfAborted();
 
-    const response = await this.fetchWithAuth(this.config.sessionUrl, { method: 'GET' }, signal);
-
-    if (!response.ok) {
-      const text = await response.text();
-      throw new JmapApiError(
-        `Session fetch failed: ${response.status}`,
-        response.status,
-        text,
-        undefined,
-        parseRetryAfter(response.headers.get('Retry-After')),
-        1,
-      );
-    }
-
-    return await response.json();
+    return requestWithRetry({
+      signal,
+      retries: 0,
+      timeoutMs: this.config.timeout,
+      isIdempotent: true,
+      send: (attemptSignal) =>
+        this.fetchWithAuth(this.config.sessionUrl, { method: 'GET' }, attemptSignal),
+      read: (response) => response.json(),
+      reject: async (response) =>
+        new JmapApiError(
+          `Session fetch failed: ${response.status}`,
+          response.status,
+          await response.text(),
+          undefined,
+          parseRetryAfter(response.headers.get('Retry-After')),
+          1,
+        ),
+      isRetryable: () => true,
+      retryDelayMs: exponentialDelayMs,
+    });
   }
 
   /**
@@ -52,17 +58,18 @@ class JmapHttpClient {
    * @param signal Optional abort signal.
    * @returns The JMAP response.
    */
-  async executeRequest(apiUrl, request, signal) {
+  executeRequest(apiUrl, request, signal) {
     signal?.throwIfAborted();
 
-    let lastError = null;
-
-    const retries = this.replayableRequests ? this.config.retries : 0;
-    for (let attempt = 0; attempt <= retries; attempt++) {
-      signal?.throwIfAborted();
-
-      try {
-        const response = await this.fetchWithAuth(
+    return requestWithRetry({
+      signal,
+      retries: this.replayableRequests ? this.config.retries : 0,
+      timeoutMs: this.config.timeout,
+      // A JMAP request is retried after a 2xx it could not read, as upstream
+      // did; the submission of an email has no retries (`submissionClient`).
+      isIdempotent: true,
+      send: (attemptSignal) =>
+        this.fetchWithAuth(
           apiUrl,
           {
             method: 'POST',
@@ -79,107 +86,42 @@ class JmapHttpClient {
                 }),
             ...(this.replayableRequests ? {} : { duplex: 'half', redirect: 'error' }),
           },
-          signal,
-        );
-
-        if (!response.ok) {
-          const text = await response.text();
-          const error = new JmapApiError(
-            `JMAP request failed: ${response.status}`,
-            response.status,
-            text,
-            undefined,
-            parseRetryAfter(response.headers.get('Retry-After')),
-            attempt + 1,
-          );
-
-          // Don't retry on 4xx errors (client errors)
-          if (response.status >= 400 && response.status < 500) {
-            throw error;
-          }
-
-          throw error;
-        }
-
-        return await response.json();
-      } catch (error) {
-        // Don't retry if aborted
-        if (isCallerAbort(error, signal)) {
-          throw error;
-        }
-
-        // Don't retry on 4xx errors
-        if (error instanceof JmapApiError && error.statusCode !== undefined) {
-          if (error.statusCode >= 400 && error.statusCode < 500) {
-            throw error;
-          }
-        }
-
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        if (attempt === retries) {
-          if (error instanceof JmapApiError) {
-            throw error;
-          }
-          // The cause tells a request that never left (a refused connection)
-          // from one that may have reached the server.
-          if (isAbortError(error)) {
-            throw new JmapApiError(
-              'JMAP request timed out.',
-              undefined,
-              undefined,
-              undefined,
-              undefined,
-              attempt + 1,
-              { cause: error },
-            );
-          }
-          throw new JmapApiError(
-            lastError.message,
-            undefined,
-            undefined,
-            undefined,
-            undefined,
-            attempt + 1,
-            { cause: error },
-          );
-        }
-
-        // Exponential backoff
-        const delay = Math.pow(2, attempt) * 1000;
-        await new Promise((resolve, reject) => {
-          const cleanup = () => {
-            clearTimeout(timer);
-            signal?.removeEventListener('abort', onAbort);
-          };
-          const onAbort = () => {
-            cleanup();
-            reject(signal?.reason);
-          };
-          const timer = setTimeout(() => {
-            cleanup();
-            resolve();
-          }, delay);
-          signal?.addEventListener('abort', onAbort, { once: true });
-          if (signal?.aborted) onAbort();
+          attemptSignal,
+        ),
+      read: (response) => response.json(),
+      reject: async (response, attempt) =>
+        new JmapApiError(
+          `JMAP request failed: ${response.status}`,
+          response.status,
+          await response.text(),
+          undefined,
+          parseRetryAfter(response.headers.get('Retry-After')),
+          attempt + 1,
+        ),
+      // Don't retry on 4xx errors (client errors)
+      isRetryable: (error) =>
+        !(error instanceof JmapApiError && error.statusCode >= 400 && error.statusCode < 500),
+      retryDelayMs: exponentialDelayMs,
+      // The cause tells a request that never left (a refused connection) from
+      // one that may have reached the server.
+      finalError: (error, attempts) => {
+        if (error instanceof JmapApiError) return error;
+        const message = isAbortError(error) ? 'JMAP request timed out.' : error.message;
+        return new JmapApiError(message, undefined, undefined, undefined, undefined, attempts, {
+          cause: error,
         });
-      }
-    }
-
-    if (lastError != null) {
-      throw lastError;
-    }
-    throw new Error('Request failed after all retries');
+      },
+    });
   }
 
   /**
    * Makes an authenticated fetch request.
    * @param url The URL to fetch.
    * @param options Fetch options.
-   * @param signal Optional abort signal.
+   * @param signal The signal of the attempt, with its deadline.
    * @returns The fetch response.
    */
-  async fetchWithAuth(url, options, signal) {
+  fetchWithAuth(url, options, signal) {
     const headers = new Headers(options.headers);
     if (this.config.bearerToken) {
       headers.set('Authorization', `Bearer ${this.config.bearerToken}`);
@@ -195,34 +137,8 @@ class JmapHttpClient {
       headers.set(key, value);
     }
 
-    // Setup timeout
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
-
-    // Combine with external signal if provided
-    let combinedSignal = controller.signal;
-    if (signal) {
-      combinedSignal = AbortSignal.any([signal, controller.signal]);
-    }
-
-    try {
-      return await globalThis.fetch(url, {
-        ...options,
-        headers,
-        signal: combinedSignal,
-      });
-    } finally {
-      clearTimeout(timeoutId);
-    }
+    return globalThis.fetch(url, { ...options, headers, signal });
   }
 }
 
-const isCallerAbort = (error, signal) => {
-  return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
-};
-
-const isAbortError = (error) => {
-  return error instanceof Error && error.name === 'AbortError';
-};
-
 module.exports = { JmapHttpClient };

From 6b41b51fdc14891ddb6cb601c312801f9280c683 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:58:55 +0300
Subject: [PATCH 042/158] fix(resend,plunk): stop waiting between retries when
 the caller aborts

The wait between two attempts of ./resend and ./plunk was a bare
setTimeout, so an abort of the caller took effect only once the backoff
was over, up to ten seconds later. They now use the abortable sleep of the
shared request helper, which rejects at once with the signal's reason, as
the other providers did.

Known upstream bug 9 (its first half); recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  2 ++
 CLAUDE.md                  |  6 ++++--
 docs/guide/known-issues.md |  3 +--
 src/plunk/http-client.js   | 12 ------------
 src/resend/http-client.js  |  2 --
 tests/unit/plunk.test.js   | 15 +++++++++++++++
 tests/unit/resend.test.js  | 15 +++++++++++++++
 7 files changed, 37 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ecab22e..2104d62 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -106,6 +106,8 @@ fixed ones below.
   a 2xx other than the one they expect, though the provider had taken the request. Such a failure
   is now `deliveryUnknown` (so is `./mailtrap`'s unreadable success); Plunk's `success: false` in a
   200 is a non-retryable failure.
+- **`./resend` and `./plunk` stop at once when the caller aborts during the wait between retries**
+  (known upstream bug 9): the abort took effect only after the backoff, up to ten seconds.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index f800091..b443918 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -136,8 +136,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 8. otel: `_active_sends` is not decremented after `sendMany` and drifts under sampling;
    `durationBuckets` and `auto` are ignored; `recordRetry` is never called; `sendMany` buffers
    its whole input; `defaultErrorClassifier` matches `"auth"` as a substring.
-9. resend, plunk: the sleep between retries ignores the `AbortSignal`; ses, resend, sendgrid,
-   mailgun and plunk parse `Retry-After` but do not wait for it.
+9. ses, resend, sendgrid, mailgun and plunk parse `Retry-After` but do not wait for it (the
+   sleep of resend and plunk that ignored the `AbortSignal` is fixed, see 25).
 10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
 11. resend: the `Idempotency-Key` comes from `Math.random`.
 12. `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of `process.emitWarning` or
@@ -196,6 +196,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     (`isAccepted`) and throws `markDeliveryUnknown` (`src/internal/delivery-unknown.js`) instead
     of retrying; the transports report `deliveryUnknown`. Telling an unsent request from a sent
     one on a timeout or a reset waits for the shared HTTP client (Phase B).
+25. resend, plunk (known bug 9): the wait between retries ignored the `AbortSignal`, so an abort
+    took effect only after the backoff. They use the abortable `sleep` of `src/internal/http.js`.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 2635f13..2cabccb 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -25,8 +25,7 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 - Basic authentication in JMAP and Mailgun fails on credentials outside Latin-1.
 - Mailgun sends an inline attachment under its file name rather than its `contentId`, so a
   `cid:` in the HTML does not match it.
-- Resend and Plunk: the sleep between retries ignores the `AbortSignal`. SES, Resend, SendGrid,
-  Mailgun and Plunk parse `Retry-After` but do not wait for it.
+- SES, Resend, SendGrid, Mailgun and Plunk parse `Retry-After` but do not wait for it.
 - Resend's `Idempotency-Key` comes from `Math.random`.
 - SES: custom and threading headers are not sent.
 - Plunk: an attachment that cannot be read is left out with a `console.warn`.
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index 3cd3e6a..c8d03e5 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -109,8 +109,6 @@ class PlunkHttpClient {
               attempts,
             )
           : new PlunkApiError(error.message, undefined, undefined, attempts),
-      // Upstream's wait ignores the signal (CLAUDE.md, known upstream bugs).
-      sleep: (milliseconds) => this.sleep(milliseconds),
     });
   }
 
@@ -181,16 +179,6 @@ class PlunkHttpClient {
       throw error;
     }
   }
-
-  /**
-   * Sleeps for the specified number of milliseconds.
-   *
-   * @param ms - Milliseconds to sleep
-   * @returns Promise that resolves after the delay
-   */
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
 }
 
 const isClientError = (error) =>
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index b1166fd..bbeaf9c 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -159,8 +159,6 @@ class ResendHttpClient {
         error instanceof ResendApiError
           ? error
           : new ResendApiError(error.message, undefined, undefined, attempts),
-      // Upstream's wait ignores the signal (CLAUDE.md, known upstream bugs).
-      sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
     });
   }
 
diff --git a/tests/unit/plunk.test.js b/tests/unit/plunk.test.js
index 4ab4526..fa04c84 100644
--- a/tests/unit/plunk.test.js
+++ b/tests/unit/plunk.test.js
@@ -101,3 +101,18 @@ test('Plunk: an attachment that cannot be read is left out with a warning', asyn
   assert.strictEqual(warn.mock.callCount(), 1);
   assert.strictEqual(body.attachments, undefined);
 });
+
+test('Plunk: an abort during the wait between attempts ends the send at once', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => new Response('busy', { status: 503 }));
+  const controller = new AbortController();
+  const reason = new Error('Stopped by the caller.');
+  setTimeout(() => controller.abort(reason), 20);
+  const started = performance.now();
+  await assert.rejects(
+    new PlunkTransport({ apiKey: 'key', retries: 3 }).send(message(), {
+      signal: controller.signal,
+    }),
+    (error) => error === reason,
+  );
+  assert.ok(performance.now() - started < 500);
+});
diff --git a/tests/unit/resend.test.js b/tests/unit/resend.test.js
index 3a10ded..abbfb55 100644
--- a/tests/unit/resend.test.js
+++ b/tests/unit/resend.test.js
@@ -101,3 +101,18 @@ test('Resend: a display name with "<", "," or "@" stays a single mailbox', async
   });
   assert.deepStrictEqual(parsed.to, [{ address: 'bob@example.com', name }]);
 });
+
+test('Resend: an abort during the wait between attempts ends the send at once', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => new Response('busy', { status: 503 }));
+  const controller = new AbortController();
+  const reason = new Error('Stopped by the caller.');
+  setTimeout(() => controller.abort(reason), 20);
+  const started = performance.now();
+  await assert.rejects(
+    new ResendTransport({ apiKey: 'key', retries: 3 }).send(message(), {
+      signal: controller.signal,
+    }),
+    (error) => error === reason,
+  );
+  assert.ok(performance.now() - started < 500);
+});

From fb8b6c8f384c24218ea33d19a73191940b10568d Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 15:59:40 +0300
Subject: [PATCH 043/158] fix(lettermint): keep the caller's reason when it
 aborts a wait

An abort of the caller during the wait between two attempts of
./lettermint rejected with a new AbortError rather than the signal's
reason, so a caller that aborted with a reason of its own could not tell it
apart. It now uses the shared sleep, which rejects with the reason, as the
other providers do.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                  |  2 ++
 CLAUDE.md                     |  2 ++
 src/lettermint/http-client.js | 30 ------------------------------
 tests/unit/lettermint.test.js | 12 ++++++++++++
 4 files changed, 16 insertions(+), 30 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2104d62..26ff541 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -108,6 +108,8 @@ fixed ones below.
   200 is a non-retryable failure.
 - **`./resend` and `./plunk` stop at once when the caller aborts during the wait between retries**
   (known upstream bug 9): the abort took effect only after the backoff, up to ten seconds.
+- **`./lettermint` rejects with the caller's abort reason** (an upstream bug): an abort during the
+  wait between retries rejected with an `AbortError` of its own.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index b443918..60a8044 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -198,6 +198,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     one on a timeout or a reset waits for the shared HTTP client (Phase B).
 25. resend, plunk (known bug 9): the wait between retries ignored the `AbortSignal`, so an abort
     took effect only after the backoff. They use the abortable `sleep` of `src/internal/http.js`.
+26. lettermint: an abort during the wait between retries rejected with a new `AbortError`
+    instead of the caller's reason. It uses the shared `sleep`, which keeps the reason.
 
 ## Repository layout
 
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index b9e8486..014e866 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -128,9 +128,6 @@ class LettermintHttpClient {
       isRetryable: (error) => !(error instanceof LettermintApiError) || isRetryable(error),
       retryDelayMs: jitteredDelayMs,
       finalError: withAttempts,
-      // Upstream's wait rejects with an AbortError of its own rather than the
-      // caller's reason.
-      sleep,
     });
   }
 
@@ -190,31 +187,4 @@ const parseErrorMessage = (text, statusCode) => {
   return text || `HTTP ${statusCode}`;
 };
 
-const sleep = (ms, signal) => {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(new DOMException('The operation was aborted.', 'AbortError'));
-      return;
-    }
-
-    const onAbort = () => {
-      clearTimeout(timeoutId);
-      signal?.removeEventListener('abort', onAbort);
-      reject(new DOMException('The operation was aborted.', 'AbortError'));
-    };
-
-    const timeoutId = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort);
-      resolve();
-    }, ms);
-
-    if (signal?.aborted) {
-      onAbort();
-      return;
-    }
-
-    signal?.addEventListener('abort', onAbort, { once: true });
-  });
-};
-
 module.exports = { LettermintApiError, LettermintTimeoutError, LettermintHttpClient };
diff --git a/tests/unit/lettermint.test.js b/tests/unit/lettermint.test.js
index 9d87789..2c58a9b 100644
--- a/tests/unit/lettermint.test.js
+++ b/tests/unit/lettermint.test.js
@@ -92,3 +92,15 @@ test('Lettermint: a batch whose every message fails to convert sends nothing', a
   assert.strictEqual(calls, 0);
   assert.deepStrictEqual(receipts[0].errorMessages, ['Cannot read attachment']);
 });
+
+test('Lettermint: an abort during the wait between attempts keeps the caller reason', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => new Response('busy', { status: 503 }));
+  const controller = new AbortController();
+  const reason = new Error('Stopped by the caller.');
+  setTimeout(() => controller.abort(reason), 20);
+  const transport = new LettermintTransport({ apiToken: 'token', retries: 3 });
+  await assert.rejects(
+    transport.send(message(), { signal: controller.signal }),
+    (error) => error === reason,
+  );
+});

From 45aaaaa2689b389b0137fd08934bc5ac4789cdfe Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:02:16 +0300
Subject: [PATCH 044/158] fix: let the timeout of an HTTP provider cover the
 response body

Seven clients cleared their timeout once the headers of the response
arrived, so a provider, a proxy or a broken connection that kept the body
open held the send forever: a Resend transport with a 200 ms timeout was
still pending seconds later. The deadline of requestWithRetry now lasts
until the response is read, body included, as it did for ./mailtrap and
./maileroo, whose option for it goes away. A body cut short after a 2xx is
of unknown delivery, like any failure after one.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  4 +++
 CLAUDE.md                   |  3 +++
 src/internal/http.js        |  9 +++----
 src/maileroo/http-client.js |  1 -
 src/mailtrap/http-client.js |  1 -
 tests/unit/delivery.test.js | 51 +++++++++++++++++++++++++++++++------
 tests/unit/internal.test.js |  4 +--
 7 files changed, 56 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26ff541..ea6099a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -110,6 +110,10 @@ fixed ones below.
   (known upstream bug 9): the abort took effect only after the backoff, up to ten seconds.
 - **`./lettermint` rejects with the caller's abort reason** (an upstream bug): an abort during the
   wait between retries rejected with an `AbortError` of its own.
+- **The timeout of an HTTP provider covers the body of the response** (an upstream bug): it ended
+  when the headers arrived in `./ses`, `./resend`, `./sendgrid`, `./mailgun`, `./lettermint`,
+  `./plunk` and `./jmap`, so a body that never ended held the send forever. A body cut short
+  after a 2xx is of unknown delivery.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index 60a8044..328609e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -200,6 +200,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     took effect only after the backoff. They use the abortable `sleep` of `src/internal/http.js`.
 26. lettermint: an abort during the wait between retries rejected with a new `AbortError`
     instead of the caller's reason. It uses the shared `sleep`, which keeps the reason.
+27. ses, resend, sendgrid, mailgun, lettermint, plunk, jmap: the timeout was cleared once the
+    headers arrived, so a body that never ended held a send forever. The deadline of
+    `requestWithRetry` lasts until the response is read, as mailtrap and maileroo had it.
 
 ## Repository layout
 
diff --git a/src/internal/http.js b/src/internal/http.js
index afcf74c..2f2ea55 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -103,10 +103,10 @@ const startDeadline = (timeoutMs, isZeroTimeoutDisabled, signal) => {
  * - optional `wrapAccepted(error, attempts)`, `isAnswer(error)` (an error that
  *   is the provider's own answer in a 2xx, such as a refusal in its body,
  *   thrown as it is rather than as of unknown delivery), `isIdempotent`,
- *   `sleep`, and
- *   until they are unified, `isZeroTimeoutDisabled` (a timeout of 0 or less
- *   means none) and `timeoutCoversBody` (the deadline lasts until `read`
- *   returns, not only until the headers arrive).
+ *   `sleep`, and until it is unified, `isZeroTimeoutDisabled` (a timeout of
+ *   0 or less means none).
+ * The deadline of an attempt lasts until its response is read, body
+ * included, so a body that never ends cannot hold a send.
  * @returns What `read` returns.
  * @internal
  */
@@ -125,7 +125,6 @@ const requestWithRetry = async (request) => {
     try {
       const response = await request.send(deadline.signal, attempt);
       isAccepted = response.ok;
-      if (request.timeoutCoversBody !== true) deadline.stop();
       if (response.ok) return await request.read(response, attempt);
       failure = await request.reject(response, attempt);
     } catch (error) {
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index f84d4bd..a097cd6 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -94,7 +94,6 @@ class MailerooHttpClient {
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       isZeroTimeoutDisabled: true,
-      timeoutCoversBody: true,
       send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
       read: async (response) => parseResponse(await response.text()),
       reject: async (response, attempt) =>
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index 0144149..9713399 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -136,7 +136,6 @@ class MailtrapHttpClient {
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       isZeroTimeoutDisabled: true,
-      timeoutCoversBody: true,
       send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
       read: async (response) => {
         const text = await response.text();
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index f2ebfba..23cd2c8 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -25,23 +25,29 @@ const providers = [
   [
     'SES',
     200,
-    () =>
+    (extra) =>
       new SesTransport({
         ...options,
+        ...extra,
         authentication: { type: 'credentials', accessKeyId: 'a', secretAccessKey: 'b' },
       }),
   ],
-  ['Resend', 200, () => new ResendTransport({ ...options, apiKey: 'key' })],
-  ['SendGrid', 202, () => new SendGridTransport({ ...options, apiKey: 'key' })],
+  ['Resend', 200, (extra) => new ResendTransport({ ...options, ...extra, apiKey: 'key' })],
+  ['SendGrid', 202, (extra) => new SendGridTransport({ ...options, ...extra, apiKey: 'key' })],
   [
     'Mailgun',
     200,
-    () => new MailgunTransport({ ...options, apiKey: 'key', domain: 'mg.example.com' }),
+    (extra) =>
+      new MailgunTransport({ ...options, ...extra, apiKey: 'key', domain: 'mg.example.com' }),
   ],
-  ['Mailtrap', 200, () => new MailtrapTransport({ ...options, apiToken: 'token' })],
-  ['Maileroo', 200, () => new MailerooTransport({ ...options, apiKey: 'key' })],
-  ['Lettermint', 200, () => new LettermintTransport({ ...options, apiToken: 'token' })],
-  ['Plunk', 200, () => new PlunkTransport({ ...options, apiKey: 'key' })],
+  ['Mailtrap', 200, (extra) => new MailtrapTransport({ ...options, ...extra, apiToken: 'token' })],
+  ['Maileroo', 200, (extra) => new MailerooTransport({ ...options, ...extra, apiKey: 'key' })],
+  [
+    'Lettermint',
+    200,
+    (extra) => new LettermintTransport({ ...options, ...extra, apiToken: 'token' }),
+  ],
+  ['Plunk', 200, (extra) => new PlunkTransport({ ...options, ...extra, apiKey: 'key' })],
 ];
 
 // A 2xx whose body cannot be read: the connection broke after the headers.
@@ -82,3 +88,32 @@ test('Delivery: Plunk refusing in a 200 is sent once, a definite failure', async
   assert.strictEqual(receipt.retryable, false);
   assert.match(receipt.errorMessages[0], /Sender not verified/);
 });
+
+// A 2xx whose body never ends, until the signal of the request aborts.
+const stalled = (status, signal) => {
+  const response = new Response(null, { status });
+  const hang = () =>
+    new Promise((_resolve, reject) => {
+      signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+    });
+  Object.defineProperty(response, 'text', { value: hang });
+  Object.defineProperty(response, 'json', { value: hang });
+  return response;
+};
+
+test(
+  'Delivery: the timeout covers a body that never ends, of unknown delivery',
+  { timeout: 5000 },
+  async (t) => {
+    for (const [name, status, create] of providers) {
+      t.mock.method(globalThis, 'fetch', async (_url, init) => stalled(status, init.signal));
+      const transport = create({ timeout: 20 });
+      const started = performance.now();
+      const receipt = await transport.send(message());
+      t.mock.restoreAll();
+      assert.ok(performance.now() - started < 1000, name);
+      assert.strictEqual(receipt.successful, false, name);
+      assert.strictEqual(receipt.deliveryUnknown, true, name);
+    }
+  },
+);
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index 619c1ad..893590c 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -113,7 +113,7 @@ test('Internal: a failure after a 2xx is not retried and is of unknown delivery'
   assert.strictEqual(idempotent.sends(), 2);
 });
 
-test('Internal: an expired deadline gives the timeout error, over the body only if asked', async () => {
+test('Internal: an expired deadline gives the timeout error, over the body too', async () => {
   const hang = (signal) =>
     new Promise((_resolve, reject) => {
       signal.addEventListener('abort', () => reject(signal.reason), { once: true });
@@ -126,7 +126,7 @@ test('Internal: an expired deadline gives the timeout error, over the body only
     Object.defineProperty(response, 'text', { value: () => hang(signal) });
     return response;
   };
-  const body = scripted([slowBody], { timeoutMs: 5, retries: 0, timeoutCoversBody: true });
+  const body = scripted([slowBody], { timeoutMs: 5, retries: 0 });
   const error = await requestWithRetry(body.request).catch((caught) => caught);
   assert.strictEqual(error.message, 'Timed out.');
   assert.strictEqual(isDeliveryUnknown(error), true);

From 971f09ce0f0391ca9a27c6684ff52cef222e5d5a Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:06:35 +0300
Subject: [PATCH 045/158] perf(ses): sign requests with node:crypto, deriving
 the key once a day

SigV4 went through WebCrypto: five importKey and sign round trips per
request, a TextEncoder per hash and a hex string built with Array.from,
map and join. It now uses createHash and createHmac of node:crypto, which
CLAUDE.md already said it did, and keeps the signing key, which depends
only on the secret and the scope (day, region, service), until either
changes. The signing is synchronous, and the shared request helper fits
the ./ses bundle within its budget again.

Nothing tested the signature before; a new test signs "get-vanilla" of the
AWS Signature Version 4 test suite and expects its published Authorization
header, twice, the second time from the cached key. signRequest takes the
service as a parameter for that, 'ses' by default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md              |  2 +-
 src/ses/http-client.js | 96 +++++++++++++++---------------------------
 tests/unit/ses.test.js | 26 ++++++++++++
 3 files changed, 60 insertions(+), 64 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 328609e..bf18544 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -82,7 +82,7 @@ is no build step.
 There is no `dependencies` or `peerDependencies` key in `package.json`, and there won't be one.
 
 - **The transports are built on `node:*` and `fetch`:** SMTP on `node:net`/`node:tls`, DKIM and
-  the SES SigV4 signature on WebCrypto (`crypto.subtle`, a global of Node), HTTP providers on the global `fetch`. No provider SDK.
+  the SES SigV4 signature on `node:crypto`, HTTP providers on the global `fetch`. No provider SDK.
 - **Infrastructure drivers are injected.** An adapter for a queue or a store takes the client or
   module the application created (a BullMQ `Queue`, a `MongoClient` or `require('mongodb')`), the
   way `./mongodb` of `@alexify/metaschema` takes the driver module. The package never `require`s
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index b32f675..dab4901 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -1,11 +1,13 @@
 // Ported from upyo v0.7.0 (packages/ses/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { createHash, createHmac } = require('node:crypto');
 const { parseRetryAfter } = require('../core/receipt.js');
 const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
 
 class SesHttpClient {
   config;
+  #signingKey = null;
 
   constructor(config) {
     this.config = config;
@@ -75,7 +77,7 @@ class SesHttpClient {
     const credentials = await this.getCredentials();
     const headers = new Headers(options.headers);
 
-    const signedHeaders = await this.signRequest(
+    const signedHeaders = this.signRequest(
       url,
       {
         ...options,
@@ -117,14 +119,22 @@ class SesHttpClient {
     }
   }
 
-  async signRequest(url, options, credentials) {
+  /**
+   * Signs a request with AWS Signature Version 4.
+   *
+   * @param url The URL of the request.
+   * @param options The method, headers and body of the request.
+   * @param credentials The access key, secret key and session token.
+   * @param service The AWS service the request goes to.
+   * @returns The headers of the request, with the signature.
+   */
+  signRequest(url, options, credentials, service = 'ses') {
     const parsedUrl = new URL(url);
     const method = options.method || 'GET';
     const headers = new Headers(options.headers);
 
     const host = parsedUrl.host;
     const path = parsedUrl.pathname + parsedUrl.search;
-    const service = 'ses';
     const region = this.config.region;
 
     const now = new Date();
@@ -144,22 +154,15 @@ class SesHttpClient {
       `host:${host}\nx-amz-date:${amzDate}\n` +
       (credentials.sessionToken ? `x-amz-security-token:${credentials.sessionToken}\n` : '');
 
-    const payloadHash = await this.sha256(options.body || '');
+    const payloadHash = sha256Hex(options.body || '');
     const canonicalRequest = `${method}\n${path}\n\n${canonicalHeaders}\n${signedHeaders}\n${payloadHash}`;
 
     const algorithm = 'AWS4-HMAC-SHA256';
     const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
-    const stringToSign = `${algorithm}\n${amzDate}\n${credentialScope}\n${await this.sha256(
-      canonicalRequest,
-    )}`;
-
-    const signingKey = await this.getSignatureKey(
-      credentials.secretAccessKey,
-      dateStamp,
-      region,
-      service,
-    );
-    const signature = await this.hmacSha256(signingKey, stringToSign);
+    const stringToSign = `${algorithm}\n${amzDate}\n${credentialScope}\n${sha256Hex(canonicalRequest)}`;
+
+    const signingKey = this.getSigningKey(credentials.secretAccessKey, credentialScope);
+    const signature = createHmac('sha256', signingKey).update(stringToSign).digest('hex');
 
     const authorizationHeader = `${algorithm} Credential=${credentials.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
     headers.set('Authorization', authorizationHeader);
@@ -167,54 +170,19 @@ class SesHttpClient {
     return headers;
   }
 
-  async sha256(data) {
-    const encoder = new TextEncoder();
-    const dataBuffer = encoder.encode(data);
-    const hashBuffer = await crypto.subtle.digest('SHA-256', dataBuffer);
-    return Array.from(new Uint8Array(hashBuffer))
-      .map((b) => b.toString(16).padStart(2, '0'))
-      .join('');
-  }
-
-  async hmacSha256(key, data) {
-    const encoder = new TextEncoder();
-    const dataBuffer = encoder.encode(data);
-    const cryptoKey = await crypto.subtle.importKey(
-      'raw',
-      key,
-      { name: 'HMAC', hash: 'SHA-256' },
-      false,
-      ['sign'],
-    );
-    const signature = await crypto.subtle.sign('HMAC', cryptoKey, dataBuffer);
-    return Array.from(new Uint8Array(signature))
-      .map((b) => b.toString(16).padStart(2, '0'))
-      .join('');
-  }
-
-  async getSignatureKey(key, dateStamp, regionName, serviceName) {
-    const encoder = new TextEncoder();
-
-    let keyBuffer = new Uint8Array(encoder.encode('AWS4' + key)).buffer;
-    keyBuffer = await this.hmacSha256Buffer(keyBuffer, dateStamp);
-    keyBuffer = await this.hmacSha256Buffer(keyBuffer, regionName);
-    keyBuffer = await this.hmacSha256Buffer(keyBuffer, serviceName);
-    keyBuffer = await this.hmacSha256Buffer(keyBuffer, 'aws4_request');
-
-    return keyBuffer;
-  }
-
-  async hmacSha256Buffer(key, data) {
-    const encoder = new TextEncoder();
-    const dataBuffer = encoder.encode(data);
-    const cryptoKey = await crypto.subtle.importKey(
-      'raw',
-      key,
-      { name: 'HMAC', hash: 'SHA-256' },
-      false,
-      ['sign'],
-    );
-    return await crypto.subtle.sign('HMAC', cryptoKey, dataBuffer);
+  // The signing key depends only on the secret and the scope (a day, a
+  // region, a service), so it is derived once a day rather than per request.
+  getSigningKey(secretAccessKey, credentialScope) {
+    const cached = this.#signingKey;
+    if (cached?.scope === credentialScope && cached.secretAccessKey === secretAccessKey) {
+      return cached.key;
+    }
+    let key = `AWS4${secretAccessKey}`;
+    for (const part of credentialScope.split('/')) {
+      key = createHmac('sha256', key).update(part).digest();
+    }
+    this.#signingKey = { scope: credentialScope, secretAccessKey, key };
+    return key;
   }
 
   headersToRecord(headers) {
@@ -226,6 +194,8 @@ class SesHttpClient {
   }
 }
 
+const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
+
 const createSesApiError = (response, text, attempt) => {
   let errorData;
   try {
diff --git a/tests/unit/ses.test.js b/tests/unit/ses.test.js
index d988d61..d47b920 100644
--- a/tests/unit/ses.test.js
+++ b/tests/unit/ses.test.js
@@ -5,6 +5,7 @@ const { test } = require('node:test');
 const assert = require('node:assert');
 const { createMessage } = require('../../index.js');
 const { SesTransport } = require('../../src/ses/index.js');
+const { SesHttpClient } = require('../../src/ses/http-client.js');
 const PostalMime = require('postal-mime');
 const { createSesConfig } = require('../../src/ses/config.js');
 const { convertMessage } = require('../../src/ses/message-converter.js');
@@ -166,3 +167,28 @@ test('SES: a display name with "<", "," or "@" stays a single mailbox', async ()
   });
   assert.deepStrictEqual(parsed.to, [{ address: 'bob@example.com', name }]);
 });
+
+test('SES: a request is signed as the SigV4 test suite of AWS expects', (t) => {
+  // "get-vanilla" of the AWS Signature Version 4 test suite.
+  t.mock.timers.enable({ apis: ['Date'], now: Date.parse('2015-08-30T12:36:00Z') });
+  const client = new SesHttpClient(createSesConfig({ region: 'us-east-1' }));
+  const credentials = {
+    accessKeyId: 'AKIDEXAMPLE',
+    secretAccessKey: 'wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY',
+  };
+  for (let call = 0; call < 2; call++) {
+    const headers = client.signRequest(
+      'https://example.amazonaws.com/',
+      { method: 'GET' },
+      credentials,
+      'service',
+    );
+    assert.strictEqual(headers.get('X-Amz-Date'), '20150830T123600Z');
+    assert.strictEqual(
+      headers.get('Authorization'),
+      'AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20150830/us-east-1/service/aws4_request, ' +
+        'SignedHeaders=host;x-amz-date, ' +
+        'Signature=5fa00fa31553b73ebf1942676e86291e8372ff2a2260956d9b8aae1d763fbf31',
+    );
+  }
+});

From 74d71cedb1a87b36a662a0a5d7156531a6c88f95 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:07:13 +0300
Subject: [PATCH 046/158] fix: give timeout 0 one meaning and check timeout and
 retries

A timeout of 0 aborted every request at once in ./ses, ./resend,
./sendgrid, ./mailgun and ./jmap, which passed it to setTimeout, and meant
no timeout in ./mailtrap, ./maileroo, ./lettermint and ./plunk; Infinity
became the 1 ms that setTimeout clamps it to; and neither option was
checked, so a typo surfaced as odd timing at the first send.

0 and Infinity now set no deadline in every provider, and the helper's
isZeroTimeoutDisabled option goes away. checkRequestOptions refuses a
negative or non-numeric timeout, and retries that are not a non-negative
whole number, with a RangeError when the config is made. The typings say
what 0 and Infinity mean and that the timeout covers the body.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                  |  5 +++++
 CLAUDE.md                     |  4 ++++
 src/internal/http.js          | 41 +++++++++++++++++++++++++----------
 src/jmap/config.js            |  6 ++++-
 src/jmap/index.d.ts           |  3 ++-
 src/lettermint/config.js      |  6 ++++-
 src/lettermint/http-client.js |  1 -
 src/lettermint/index.d.ts     |  3 ++-
 src/maileroo/config.js        |  6 ++++-
 src/maileroo/http-client.js   |  1 -
 src/maileroo/index.d.ts       |  2 +-
 src/mailgun/config.js         |  6 ++++-
 src/mailgun/index.d.ts        |  3 ++-
 src/mailtrap/config.js        |  6 ++++-
 src/mailtrap/http-client.js   |  1 -
 src/mailtrap/index.d.ts       |  3 ++-
 src/plunk/config.js           |  6 ++++-
 src/plunk/http-client.js      |  1 -
 src/plunk/index.d.ts          |  3 ++-
 src/resend/config.js          |  6 ++++-
 src/resend/index.d.ts         |  3 ++-
 src/sendgrid/config.js        |  6 ++++-
 src/sendgrid/index.d.ts       |  3 ++-
 src/ses/config.js             |  6 ++++-
 src/ses/index.d.ts            |  1 +
 tests/unit/delivery.test.js   | 16 ++++++++++++++
 tests/unit/internal.test.js   | 11 ++++++++++
 27 files changed, 126 insertions(+), 33 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ea6099a..9fe6acf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -114,6 +114,11 @@ fixed ones below.
   when the headers arrived in `./ses`, `./resend`, `./sendgrid`, `./mailgun`, `./lettermint`,
   `./plunk` and `./jmap`, so a body that never ended held the send forever. A body cut short
   after a 2xx is of unknown delivery.
+- **`timeout: 0` and `timeout: Infinity` mean no timeout in every HTTP provider** (an upstream
+  bug): 0 aborted every request at once in `./ses`, `./resend`, `./sendgrid`, `./mailgun` and
+  `./jmap` while it meant none in the others, and `Infinity` became 1 ms. A negative or
+  non-numeric `timeout`, and `retries` that are not a non-negative whole number, are refused
+  with a `RangeError` when the transport is made.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index bf18544..3e7b0bb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -203,6 +203,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 27. ses, resend, sendgrid, mailgun, lettermint, plunk, jmap: the timeout was cleared once the
     headers arrived, so a body that never ended held a send forever. The deadline of
     `requestWithRetry` lasts until the response is read, as mailtrap and maileroo had it.
+28. every HTTP provider and jmap: `timeout: 0` aborted at once in five clients and meant none in
+    four, `Infinity` became 1 ms, and neither `timeout` nor `retries` was checked. 0 and
+    `Infinity` now mean none everywhere, and `checkRequestOptions` refuses anything else that is
+    not a non-negative number, or retries that are not a whole number, when the config is made.
 
 ## Repository layout
 
diff --git a/src/internal/http.js b/src/internal/http.js
index 2f2ea55..cc1b455 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -64,13 +64,34 @@ const jitteredDelayMs = (attempt) => {
   return Math.round(baseMs / 2 + Math.random() * (baseMs / 2));
 };
 
-// The deadline of one attempt, combined with the caller's signal.
-const startDeadline = (timeoutMs, isZeroTimeoutDisabled, signal) => {
+/**
+ * Checks the timeout and the retries of a provider's configuration.
+ *
+ * @param timeoutMs The timeout of an attempt in milliseconds, 0 or `Infinity`
+ * for none.
+ * @param retries How many times a failed attempt is retried.
+ * @throws {RangeError} If either is not a number of that kind.
+ * @internal
+ */
+const checkRequestOptions = (timeoutMs, retries) => {
+  if (typeof timeoutMs !== 'number' || !(timeoutMs >= 0)) {
+    throw new RangeError(
+      '`timeout` must be a number of milliseconds, 0 or Infinity for none: ' + String(timeoutMs),
+    );
+  }
+  if (!Number.isInteger(retries) || retries < 0) {
+    throw new RangeError('`retries` must be a non-negative integer: ' + String(retries));
+  }
+};
+
+// The deadline of one attempt, combined with the caller's signal.  A timeout
+// of 0 or Infinity sets none: setTimeout() would fire at once for either.
+const startDeadline = (timeoutMs, signal) => {
   const controller = new AbortController();
   const timer =
-    isZeroTimeoutDisabled && !(timeoutMs > 0)
-      ? undefined
-      : setTimeout(() => controller.abort(), timeoutMs);
+    timeoutMs > 0 && Number.isFinite(timeoutMs)
+      ? setTimeout(() => controller.abort(), timeoutMs)
+      : undefined;
   const combined = combineSignals(controller.signal, signal);
   return {
     signal: combined.signal,
@@ -103,8 +124,7 @@ const startDeadline = (timeoutMs, isZeroTimeoutDisabled, signal) => {
  * - optional `wrapAccepted(error, attempts)`, `isAnswer(error)` (an error that
  *   is the provider's own answer in a 2xx, such as a refusal in its body,
  *   thrown as it is rather than as of unknown delivery), `isIdempotent`,
- *   `sleep`, and until it is unified, `isZeroTimeoutDisabled` (a timeout of
- *   0 or less means none).
+ *   `sleep`.
  * The deadline of an attempt lasts until its response is read, body
  * included, so a body that never ends cannot hold a send.
  * @returns What `read` returns.
@@ -115,11 +135,7 @@ const requestWithRetry = async (request) => {
   const wait = request.sleep ?? sleep;
   for (let attempt = 0; ; attempt++) {
     signal?.throwIfAborted();
-    const deadline = startDeadline(
-      request.timeoutMs,
-      request.isZeroTimeoutDisabled === true,
-      signal,
-    );
+    const deadline = startDeadline(request.timeoutMs, signal);
     let isAccepted = false;
     let failure;
     try {
@@ -149,6 +165,7 @@ const requestWithRetry = async (request) => {
 
 module.exports = {
   abortReason,
+  checkRequestOptions,
   exponentialDelayMs,
   isAbortError,
   jitteredDelayMs,
diff --git a/src/jmap/config.js b/src/jmap/config.js
index 150a69b..45477a9 100644
--- a/src/jmap/config.js
+++ b/src/jmap/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/jmap/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { checkRequestOptions } = require('../internal/http.js');
+
 /**
  * Creates a resolved JMAP configuration with default values applied.
  * @param config The user-provided configuration.
@@ -11,7 +13,7 @@ const createJmapConfig = (config) => {
   if (!config.bearerToken && !config.basicAuth) {
     throw new Error('Either bearerToken or basicAuth must be provided');
   }
-  return {
+  const resolved = {
     sessionUrl: config.sessionUrl,
     bearerToken: config.bearerToken ?? null,
     basicAuth: config.basicAuth ?? null,
@@ -23,6 +25,8 @@ const createJmapConfig = (config) => {
     sessionCacheTtl: config.sessionCacheTtl ?? 300000,
     baseUrl: config.baseUrl ?? null,
   };
+  checkRequestOptions(resolved.timeout, resolved.retries);
+  return resolved;
 };
 
 module.exports = { createJmapConfig };
diff --git a/src/jmap/index.d.ts b/src/jmap/index.d.ts
index b4f53cb..e0334ab 100644
--- a/src/jmap/index.d.ts
+++ b/src/jmap/index.d.ts
@@ -46,7 +46,8 @@ export interface JmapConfig {
    */
   readonly identityId?: string;
   /**
-   * HTTP request timeout in milliseconds.
+   * HTTP request timeout in milliseconds, response body included; 0 or
+   * `Infinity` for none.
    * @default 30000
    */
   readonly timeout?: number;
diff --git a/src/lettermint/config.js b/src/lettermint/config.js
index 1e080db..182dec6 100644
--- a/src/lettermint/config.js
+++ b/src/lettermint/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/lettermint/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { checkRequestOptions } = require('../internal/http.js');
+
 /**
  * Creates a resolved Lettermint configuration by applying default values.
  *
@@ -8,7 +10,7 @@
  * @returns A resolved configuration with all defaults applied.
  */
 const createLettermintConfig = (config) => {
-  return {
+  const resolved = {
     apiToken: config.apiToken,
     baseUrl: normalizeBaseUrl(config.baseUrl ?? 'https://api.lettermint.co'),
     timeout: config.timeout ?? 30000,
@@ -19,6 +21,8 @@ const createLettermintConfig = (config) => {
     metadata: config.metadata == null ? undefined : { ...config.metadata },
     settings: config.settings == null ? undefined : { ...config.settings },
   };
+  checkRequestOptions(resolved.timeout, resolved.retries);
+  return resolved;
 };
 
 const normalizeBaseUrl = (baseUrl) => {
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index 014e866..be45ab6 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -103,7 +103,6 @@ class LettermintHttpClient {
       signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
-      isZeroTimeoutDisabled: true,
       send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal, idempotencyKey),
       read: async (response) => {
         const text = await response.text();
diff --git a/src/lettermint/index.d.ts b/src/lettermint/index.d.ts
index 5b7ea3a..d16890d 100644
--- a/src/lettermint/index.d.ts
+++ b/src/lettermint/index.d.ts
@@ -47,7 +47,8 @@ export interface LettermintConfig {
    */
   readonly baseUrl?: string;
   /**
-   * HTTP request timeout in milliseconds.
+   * HTTP request timeout in milliseconds, response body included; 0 or
+   * `Infinity` for none.
    *
    * @default 30000
    */
diff --git a/src/maileroo/config.js b/src/maileroo/config.js
index 836e2cd..7b6f81d 100644
--- a/src/maileroo/config.js
+++ b/src/maileroo/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/maileroo/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { checkRequestOptions } = require('../internal/http.js');
+
 /**
  * Creates a resolved Maileroo configuration by applying default values.
  *
@@ -8,7 +10,7 @@
  * @returns A resolved configuration with all defaults applied.
  */
 const createMailerooConfig = (config) => {
-  return {
+  const resolved = {
     apiKey: config.apiKey,
     baseUrl: normalizeBaseUrl(config.baseUrl ?? 'https://smtp.maileroo.com/api/v2'),
     timeout: config.timeout ?? 30000,
@@ -17,6 +19,8 @@ const createMailerooConfig = (config) => {
     tracking: config.tracking,
     tags: config.tags == null ? undefined : { ...config.tags },
   };
+  checkRequestOptions(resolved.timeout, resolved.retries);
+  return resolved;
 };
 
 const normalizeBaseUrl = (baseUrl) => {
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index a097cd6..5337d52 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -93,7 +93,6 @@ class MailerooHttpClient {
       signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
-      isZeroTimeoutDisabled: true,
       send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
       read: async (response) => parseResponse(await response.text()),
       reject: async (response, attempt) =>
diff --git a/src/maileroo/index.d.ts b/src/maileroo/index.d.ts
index 668a43f..da50658 100644
--- a/src/maileroo/index.d.ts
+++ b/src/maileroo/index.d.ts
@@ -31,7 +31,7 @@ export interface MailerooConfig {
   /**
    * HTTP request timeout in milliseconds.
    *
-   * Set to `0` to disable request timeouts.
+   * Set to `0` or `Infinity` to disable request timeouts.
    *
    * @default 30000
    */
diff --git a/src/mailgun/config.js b/src/mailgun/config.js
index 312d9ea..2cd4888 100644
--- a/src/mailgun/config.js
+++ b/src/mailgun/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/mailgun/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { checkRequestOptions } = require('../internal/http.js');
+
 /**
  * Creates a resolved Mailgun configuration by applying default values to optional fields.
  *
@@ -16,7 +18,7 @@ const createMailgunConfig = (config) => {
   const region = config.region ?? 'us';
   const baseUrl = config.baseUrl ?? getDefaultBaseUrl(region);
 
-  return {
+  const resolved = {
     apiKey: config.apiKey,
     domain: config.domain,
     region,
@@ -29,6 +31,8 @@ const createMailgunConfig = (config) => {
     clickTracking: config.clickTracking ?? true,
     openTracking: config.openTracking ?? true,
   };
+  checkRequestOptions(resolved.timeout, resolved.retries);
+  return resolved;
 };
 
 /**
diff --git a/src/mailgun/index.d.ts b/src/mailgun/index.d.ts
index 7534647..651a75a 100644
--- a/src/mailgun/index.d.ts
+++ b/src/mailgun/index.d.ts
@@ -49,7 +49,8 @@ export interface MailgunConfig {
    */
   readonly baseUrl?: string;
   /**
-   * HTTP request timeout in milliseconds.
+   * HTTP request timeout in milliseconds, response body included; 0 or
+   * `Infinity` for none.
    *
    * @default 30000
    */
diff --git a/src/mailtrap/config.js b/src/mailtrap/config.js
index 6291c0f..5f11e6d 100644
--- a/src/mailtrap/config.js
+++ b/src/mailtrap/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/mailtrap/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { checkRequestOptions } = require('../internal/http.js');
+
 const DEFAULT_SEND_BASE_URL = 'https://send.api.mailtrap.io';
 const DEFAULT_SANDBOX_BASE_URL = 'https://sandbox.api.mailtrap.io';
 const DEFAULT_CATEGORY = 'transactional';
@@ -20,7 +22,7 @@ const createMailtrapConfig = (config) => {
     throw new RangeError('`inboxId` is required when Mailtrap sandbox mode is enabled.');
   }
 
-  return {
+  const resolved = {
     apiToken: config.apiToken,
     sandbox,
     inboxId: config.inboxId,
@@ -34,6 +36,8 @@ const createMailtrapConfig = (config) => {
     validateSsl: config.validateSsl ?? true,
     headers: config.headers == null ? {} : { ...config.headers },
   };
+  checkRequestOptions(resolved.timeout, resolved.retries);
+  return resolved;
 };
 
 const isValidInboxId = (inboxId) => {
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index 9713399..41702b0 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -135,7 +135,6 @@ class MailtrapHttpClient {
       signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
-      isZeroTimeoutDisabled: true,
       send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
       read: async (response) => {
         const text = await response.text();
diff --git a/src/mailtrap/index.d.ts b/src/mailtrap/index.d.ts
index fd7cf37..3b1373a 100644
--- a/src/mailtrap/index.d.ts
+++ b/src/mailtrap/index.d.ts
@@ -68,7 +68,8 @@ export interface MailtrapConfig {
    */
   readonly userAgent?: string;
   /**
-   * HTTP request timeout in milliseconds.
+   * HTTP request timeout in milliseconds, response body included; 0 or
+   * `Infinity` for none.
    *
    * @default 30000
    */
diff --git a/src/plunk/config.js b/src/plunk/config.js
index 744ec96..968fec2 100644
--- a/src/plunk/config.js
+++ b/src/plunk/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/plunk/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { checkRequestOptions } = require('../internal/http.js');
+
 /**
  * Creates a resolved Plunk configuration by applying default values to optional fields.
  *
@@ -13,7 +15,7 @@
  * @internal
  */
 const createPlunkConfig = (config) => {
-  return {
+  const resolved = {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? 'https://next-api.useplunk.com',
     timeout: config.timeout ?? 30000,
@@ -21,6 +23,8 @@ const createPlunkConfig = (config) => {
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
   };
+  checkRequestOptions(resolved.timeout, resolved.retries);
+  return resolved;
 };
 
 module.exports = { createPlunkConfig };
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index c8d03e5..29c073c 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -76,7 +76,6 @@ class PlunkHttpClient {
       signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
-      isZeroTimeoutDisabled: true,
       send: (attemptSignal) => this.makeRequest(url, emailData, attemptSignal),
       read: (response) => this.parseResponse(response),
       reject: async (response, attempt) => {
diff --git a/src/plunk/index.d.ts b/src/plunk/index.d.ts
index a861a0a..466efc9 100644
--- a/src/plunk/index.d.ts
+++ b/src/plunk/index.d.ts
@@ -39,7 +39,8 @@ export interface PlunkConfig {
    */
   readonly baseUrl?: string;
   /**
-   * HTTP request timeout in milliseconds.
+   * HTTP request timeout in milliseconds, response body included; 0 or
+   * `Infinity` for none.
    *
    * @default 30000
    */
diff --git a/src/resend/config.js b/src/resend/config.js
index 02d7853..850543b 100644
--- a/src/resend/config.js
+++ b/src/resend/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/resend/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { checkRequestOptions } = require('../internal/http.js');
+
 /**
  * Creates a resolved Resend configuration by applying default values to optional fields.
  *
@@ -13,7 +15,7 @@
  * @internal
  */
 const createResendConfig = (config) => {
-  return {
+  const resolved = {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? 'https://api.resend.com',
     timeout: config.timeout ?? 30000,
@@ -21,6 +23,8 @@ const createResendConfig = (config) => {
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
   };
+  checkRequestOptions(resolved.timeout, resolved.retries);
+  return resolved;
 };
 
 module.exports = { createResendConfig };
diff --git a/src/resend/index.d.ts b/src/resend/index.d.ts
index 87767ef..1da6481 100644
--- a/src/resend/index.d.ts
+++ b/src/resend/index.d.ts
@@ -33,7 +33,8 @@ export interface ResendConfig {
    */
   readonly baseUrl?: string;
   /**
-   * HTTP request timeout in milliseconds.
+   * HTTP request timeout in milliseconds, response body included; 0 or
+   * `Infinity` for none.
    *
    * @default 30000
    */
diff --git a/src/sendgrid/config.js b/src/sendgrid/config.js
index b0107bf..690cb0b 100644
--- a/src/sendgrid/config.js
+++ b/src/sendgrid/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/sendgrid/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { checkRequestOptions } = require('../internal/http.js');
+
 /**
  * Creates a resolved SendGrid configuration by applying default values to optional fields.
  *
@@ -13,7 +15,7 @@
  * @internal
  */
 const createSendGridConfig = (config) => {
-  return {
+  const resolved = {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? 'https://api.sendgrid.com/v3',
     timeout: config.timeout ?? 30000,
@@ -25,6 +27,8 @@ const createSendGridConfig = (config) => {
     subscriptionTracking: config.subscriptionTracking ?? false,
     googleAnalytics: config.googleAnalytics ?? false,
   };
+  checkRequestOptions(resolved.timeout, resolved.retries);
+  return resolved;
 };
 
 module.exports = { createSendGridConfig };
diff --git a/src/sendgrid/index.d.ts b/src/sendgrid/index.d.ts
index 8c7b074..9852433 100644
--- a/src/sendgrid/index.d.ts
+++ b/src/sendgrid/index.d.ts
@@ -34,7 +34,8 @@ export interface SendGridConfig {
    */
   readonly baseUrl?: string;
   /**
-   * HTTP request timeout in milliseconds.
+   * HTTP request timeout in milliseconds, response body included; 0 or
+   * `Infinity` for none.
    *
    * @default 30000
    */
diff --git a/src/ses/config.js b/src/ses/config.js
index 482a664..5fdbb7e 100644
--- a/src/ses/config.js
+++ b/src/ses/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/ses/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { checkRequestOptions } = require('../internal/http.js');
+
 /**
  * Creates a resolved SES configuration with default values applied.
  *
@@ -27,7 +29,7 @@
  * @returns A resolved configuration with all defaults applied.
  */
 const createSesConfig = (config) => {
-  return {
+  const resolved = {
     authentication: config.authentication,
     region: config.region ?? 'us-east-1',
     timeout: config.timeout ?? 30000,
@@ -38,6 +40,8 @@ const createSesConfig = (config) => {
     defaultTags: config.defaultTags ?? {},
     batchSize: config.batchSize ?? 50,
   };
+  checkRequestOptions(resolved.timeout, resolved.retries);
+  return resolved;
 };
 
 module.exports = { createSesConfig };
diff --git a/src/ses/index.d.ts b/src/ses/index.d.ts
index 4fefc8b..14ed062 100644
--- a/src/ses/index.d.ts
+++ b/src/ses/index.d.ts
@@ -85,6 +85,7 @@ export interface SesConfig {
   readonly region?: string;
   /**
    * Request timeout in milliseconds.
+   * The response body is included; 0 or `Infinity` for none.
    * @default 30000
    */
   readonly timeout?: number;
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index 23cd2c8..b699216 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -117,3 +117,19 @@ test(
     }
   },
 );
+
+test('Delivery: a timeout of 0 or Infinity sets none, a bad one is refused', async (t) => {
+  for (const [name, , create] of providers) {
+    for (const timeout of [0, Infinity]) {
+      t.mock.method(globalThis, 'fetch', async (_url, init) => {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        return new Response(JSON.stringify({ aborted: init.signal.aborted }), { status: 400 });
+      });
+      const receipt = await create({ timeout, retries: 0 }).send(message());
+      t.mock.restoreAll();
+      assert.strictEqual(receipt.errors[0].statusCode, 400, `${name} ${timeout}`);
+    }
+    assert.throws(() => create({ timeout: -1 }), RangeError, name);
+    assert.throws(() => create({ retries: 1.5 }), RangeError, name);
+  }
+});
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index 893590c..bcd9202 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -27,6 +27,7 @@ test('Internal: a reset, a timeout or a failure without a cause may have been se
 
 const { isDeliveryUnknown } = require('../../src/internal/delivery-unknown.js');
 const {
+  checkRequestOptions,
   exponentialDelayMs,
   jitteredDelayMs,
   requestWithRetry,
@@ -158,3 +159,13 @@ test('Internal: delays double from one second, and the jittered one stays in its
     assert.ok(delayMs >= baseMs / 2 && delayMs <= baseMs, String(delayMs));
   }
 });
+
+test('Internal: a timeout is a number of milliseconds or none, retries a whole number', () => {
+  for (const timeoutMs of [0, 1, 30_000, Infinity]) checkRequestOptions(timeoutMs, 0);
+  for (const timeoutMs of [-1, Number.NaN, '30000', undefined]) {
+    assert.throws(() => checkRequestOptions(timeoutMs, 3), RangeError);
+  }
+  for (const retries of [-1, 1.5, Infinity, '3']) {
+    assert.throws(() => checkRequestOptions(30_000, retries), RangeError);
+  }
+});

From 01d40da57ab3060b1e0e78b92408c1782603b1e4 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:08:32 +0300
Subject: [PATCH 047/158] fix(core): read a Retry-After longer than a day as a
 day

parseRetryAfter turned any number of seconds into milliseconds, so a server
answering `Retry-After: 99999999999` asked for about 3,170 years, and a far
HTTP date for as long. A delay longer than a day is now read as a day, both
as seconds and as a date; no sender waits longer within a send.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  2 ++
 CLAUDE.md               |  2 ++
 index.d.ts              |  3 ++-
 src/core/receipt.js     | 12 ++++++++----
 tests/unit/core.test.js | 10 ++++++++++
 5 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9fe6acf..4b363b1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -119,6 +119,8 @@ fixed ones below.
   `./jmap` while it meant none in the others, and `Infinity` became 1 ms. A negative or
   non-numeric `timeout`, and `retries` that are not a non-negative whole number, are refused
   with a `RangeError` when the transport is made.
+- **`parseRetryAfter` reads a delay longer than a day as a day** (an upstream bug): a value such as
+  `99999999999` meant about 3,170 years.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index 3e7b0bb..3ccb110 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -207,6 +207,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     four, `Infinity` became 1 ms, and neither `timeout` nor `retries` was checked. 0 and
     `Infinity` now mean none everywhere, and `checkRequestOptions` refuses anything else that is
     not a non-negative number, or retries that are not a whole number, when the config is made.
+29. core: `parseRetryAfter` had no upper bound (`99999999999` gave about 3,170 years); a delay
+    longer than a day is read as a day.
 
 ## Repository layout
 
diff --git a/index.d.ts b/index.d.ts
index a3cfb0c..c909419 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -1006,7 +1006,8 @@ export declare function createFailedReceipt<TProviderId extends string = string>
   readonly successful: false;
 };
 /**
- * Parses an HTTP `Retry-After` header value into milliseconds.
+ * Parses an HTTP `Retry-After` header value into milliseconds.  A delay
+ * longer than a day is read as a day.
  *
  * @param value Header value to parse.
  * @param now Current time used when parsing HTTP dates.
diff --git a/src/core/receipt.js b/src/core/receipt.js
index e7ddbdc..ce3357f 100644
--- a/src/core/receipt.js
+++ b/src/core/receipt.js
@@ -220,6 +220,9 @@ const createFailedReceipt = (error, options = {}) => {
 /**
  * Parses an HTTP `Retry-After` header value into milliseconds.
  *
+ * A delay longer than a day is read as a day: no sender waits longer within a
+ * send, and a value such as `99999999999` would otherwise mean centuries.
+ *
  * @param value Header value to parse.
  * @param now Current time used when parsing HTTP dates.
  * @returns Retry delay in milliseconds, or `undefined` if invalid.
@@ -229,17 +232,18 @@ const parseRetryAfter = (value, now = new Date()) => {
 
   const trimmed = value.trim();
   if (/^\d+$/.test(trimmed)) {
-    const delay = Number(trimmed) * 1000;
-    return delay;
+    return Math.min(Number(trimmed) * 1000, MAX_RETRY_AFTER_MS);
   }
 
   const timestamp = Date.parse(trimmed);
   if (Number.isNaN(timestamp)) return undefined;
 
-  const delay = timestamp - now.getTime();
-  return delay > 0 ? delay : undefined;
+  const delayMs = timestamp - now.getTime();
+  return delayMs > 0 ? Math.min(delayMs, MAX_RETRY_AFTER_MS) : undefined;
 };
 
+const MAX_RETRY_AFTER_MS = 24 * 60 * 60 * 1000;
+
 const getStringProperty = (value, property) => {
   if (value instanceof Error) {
     return value[property];
diff --git a/tests/unit/core.test.js b/tests/unit/core.test.js
index 8fe8907..d45a534 100644
--- a/tests/unit/core.test.js
+++ b/tests/unit/core.test.js
@@ -15,6 +15,7 @@ const {
   iterateAttachmentContent,
   iterateRawMessage,
   parseAddress,
+  parseRetryAfter,
   RawMessageValidationError,
   readAttachmentContent,
   resolveCalendarContent,
@@ -280,3 +281,12 @@ test('Receipt: an unknown delivery is never retryable, nor are the errors made f
   assert.strictEqual(receipt.errors[0].retryable, false);
   assert.strictEqual('deliveryUnknown' in createFailedReceipt('Busy', { statusCode: 503 }), false);
 });
+
+test('Receipt: a Retry-After longer than a day is read as a day', () => {
+  const now = new Date('2026-10-16T00:00:00Z');
+  const dayMs = 24 * 60 * 60 * 1000;
+  assert.strictEqual(parseRetryAfter('120', now), 120_000);
+  assert.strictEqual(parseRetryAfter('99999999999', now), dayMs);
+  assert.strictEqual(parseRetryAfter('Wed, 21 Oct 2099 07:28:00 GMT', now), dayMs);
+  assert.strictEqual(parseRetryAfter('Fri, 16 Oct 2026 00:01:00 GMT', now), 60_000);
+});

From 80e7a80013ee629647223bf4059565b89463255e Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:10:14 +0300
Subject: [PATCH 048/158] fix: wait for Retry-After in every HTTP provider, up
 to 30 seconds

Seven clients parsed the Retry-After of a response into the error's
retryAfterMilliseconds and then retried after their own backoff, so a
provider that asked for two minutes was asked again after one second;
./mailtrap and ./maileroo waited for it, however long it was, inside the
send.

requestWithRetry now waits at least retryAfterMilliseconds between two
attempts, for every provider, so the two that did it themselves no longer
do. When the server asks for more than 30 seconds the send does not wait or
retry: the failure is thrown at once with its delay, which the receipt
carries, for ./retry or a queue to schedule.

Known upstream bug 9, now fixed in full; recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  5 +++++
 CLAUDE.md                   |  8 ++++++--
 docs/guide/known-issues.md  |  1 -
 src/internal/http.js        | 17 ++++++++++++++---
 src/maileroo/http-client.js | 10 +---------
 src/mailtrap/http-client.js | 10 +---------
 tests/unit/delivery.test.js | 18 ++++++++++++++++++
 tests/unit/internal.test.js | 13 +++++++++++++
 8 files changed, 58 insertions(+), 24 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4b363b1..ebb0be1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -121,6 +121,11 @@ fixed ones below.
   with a `RangeError` when the transport is made.
 - **`parseRetryAfter` reads a delay longer than a day as a day** (an upstream bug): a value such as
   `99999999999` meant about 3,170 years.
+- **Every HTTP provider waits for `Retry-After`, up to 30 seconds** (known upstream bug 9):
+  `./ses`, `./resend`, `./sendgrid`, `./mailgun`, `./plunk`, `./lettermint` and `./jmap` parsed it
+  and retried after their own backoff anyway, while `./mailtrap` and `./maileroo` waited for it
+  however long it was. A longer one is no longer waited for within the send: the failure is
+  returned at once with its `retryAfterMilliseconds`.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index 3ccb110..15cf286 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -136,8 +136,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 8. otel: `_active_sends` is not decremented after `sendMany` and drifts under sampling;
    `durationBuckets` and `auto` are ignored; `recordRetry` is never called; `sendMany` buffers
    its whole input; `defaultErrorClassifier` matches `"auth"` as a substring.
-9. ses, resend, sendgrid, mailgun and plunk parse `Retry-After` but do not wait for it (the
-   sleep of resend and plunk that ignored the `AbortSignal` is fixed, see 25).
+9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
+   ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
 10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
 11. resend: the `Idempotency-Key` comes from `Math.random`.
 12. `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of `process.emitWarning` or
@@ -209,6 +209,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     not a non-negative number, or retries that are not a whole number, when the config is made.
 29. core: `parseRetryAfter` had no upper bound (`99999999999` gave about 3,170 years); a delay
     longer than a day is read as a day.
+30. every HTTP provider and jmap (known bug 9): `Retry-After` was parsed and ignored by seven
+    clients, and waited for without a bound by mailtrap and maileroo. `requestWithRetry` waits
+    at least `retryAfterMilliseconds` between attempts, and when it is over 30 seconds throws
+    the failure with it instead, for the caller or a queue to schedule.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 2cabccb..937b8e6 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -25,7 +25,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 - Basic authentication in JMAP and Mailgun fails on credentials outside Latin-1.
 - Mailgun sends an inline attachment under its file name rather than its `contentId`, so a
   `cid:` in the HTML does not match it.
-- SES, Resend, SendGrid, Mailgun and Plunk parse `Retry-After` but do not wait for it.
 - Resend's `Idempotency-Key` comes from `Math.random`.
 - SES: custom and threading headers are not sent.
 - Plunk: an attachment that cannot be read is left out with a `console.warn`.
diff --git a/src/internal/http.js b/src/internal/http.js
index cc1b455..0869997 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -84,6 +84,10 @@ const checkRequestOptions = (timeoutMs, retries) => {
   }
 };
 
+// The longest Retry-After a send waits for between two attempts; beyond it the
+// failure is thrown with its delay, for the caller or a queue to schedule.
+const MAX_RETRY_AFTER_WAIT_MS = 30_000;
+
 // The deadline of one attempt, combined with the caller's signal.  A timeout
 // of 0 or Infinity sets none: setTimeout() would fire at once for either.
 const startDeadline = (timeoutMs, signal) => {
@@ -126,7 +130,9 @@ const startDeadline = (timeoutMs, signal) => {
  *   thrown as it is rather than as of unknown delivery), `isIdempotent`,
  *   `sleep`.
  * The deadline of an attempt lasts until its response is read, body
- * included, so a body that never ends cannot hold a send.
+ * included, so a body that never ends cannot hold a send.  Between attempts
+ * it waits at least the failure's `retryAfterMilliseconds`, the server's
+ * `Retry-After`, and does not retry when that is longer than 30 seconds.
  * @returns What `read` returns.
  * @internal
  */
@@ -158,8 +164,13 @@ const requestWithRetry = async (request) => {
       throw markDeliveryUnknown(accepted);
     }
     if (!request.isRetryable(failure)) throw failure;
-    if (attempt >= request.retries) throw request.finalError?.(failure, attempt + 1) ?? failure;
-    await wait(request.retryDelayMs(attempt, failure), signal);
+    const retryAfterMs = Number.isFinite(failure.retryAfterMilliseconds)
+      ? failure.retryAfterMilliseconds
+      : 0;
+    if (attempt >= request.retries || retryAfterMs > MAX_RETRY_AFTER_WAIT_MS) {
+      throw request.finalError?.(failure, attempt + 1) ?? failure;
+    }
+    await wait(Math.max(request.retryDelayMs(attempt, failure), retryAfterMs), signal);
   }
 };
 
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index 5337d52..0cfd834 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -104,7 +104,7 @@ class MailerooHttpClient {
         ),
       createTimeoutError: () => new MailerooTimeoutError(this.config.timeout),
       isRetryable: (error) => !(error instanceof MailerooApiError) || isRetryable(error),
-      retryDelayMs: calculateRetryDelay,
+      retryDelayMs: jitteredDelayMs,
       finalError: withAttempts,
     });
   }
@@ -142,14 +142,6 @@ const isRetryable = (error) => {
   return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
 };
 
-const calculateRetryDelay = (attempt, error) => {
-  const backoffDelay = jitteredDelayMs(attempt);
-  if (error instanceof MailerooApiError) {
-    return Math.max(backoffDelay, error.retryAfterMilliseconds ?? 0);
-  }
-  return backoffDelay;
-};
-
 const parseErrorMessage = (text, statusCode) => {
   try {
     const errorBody = JSON.parse(text);
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index 41702b0..9dc4230 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -162,7 +162,7 @@ class MailtrapHttpClient {
       // A 2xx response means Mailtrap may already have sent the message.
       wrapAccepted: (error, attempts) => new MailtrapResponseError(error, attempts),
       isRetryable: (error) => !(error instanceof MailtrapApiError) || isRetryable(error),
-      retryDelayMs: calculateRetryDelay,
+      retryDelayMs: jitteredDelayMs,
       finalError: withAttempts,
     });
   }
@@ -191,14 +191,6 @@ const isRetryable = (error) => {
   return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
 };
 
-const calculateRetryDelay = (attempt, error) => {
-  const backoffDelay = jitteredDelayMs(attempt);
-  if (error instanceof MailtrapApiError) {
-    return Math.max(backoffDelay, error.retryAfterMilliseconds ?? 0);
-  }
-  return backoffDelay;
-};
-
 const withAttempts = (error, attempts) => {
   if (error instanceof MailtrapTimeoutError) {
     return new MailtrapTimeoutError(error.timeout, attempts);
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index b699216..1cd4e20 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -133,3 +133,21 @@ test('Delivery: a timeout of 0 or Infinity sets none, a bad one is refused', asy
     assert.throws(() => create({ retries: 1.5 }), RangeError, name);
   }
 });
+
+test(
+  'Delivery: a Retry-After of two minutes is not waited for but returned',
+  { timeout: 5000 },
+  async (t) => {
+    for (const [name, , create] of providers) {
+      let requests = 0;
+      t.mock.method(globalThis, 'fetch', async () => {
+        requests++;
+        return new Response('busy', { status: 503, headers: { 'Retry-After': '120' } });
+      });
+      const receipt = await create().send(message());
+      t.mock.restoreAll();
+      assert.strictEqual(requests, 1, name);
+      assert.strictEqual(receipt.errors[0].retryAfterMilliseconds, 120_000, name);
+    }
+  },
+);
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index bcd9202..2e7ac9b 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -169,3 +169,16 @@ test('Internal: a timeout is a number of milliseconds or none, retries a whole n
     assert.throws(() => checkRequestOptions(30_000, retries), RangeError);
   }
 });
+
+test('Internal: a Retry-After is waited for, and not when it is longer than half a minute', async () => {
+  const busy = (retryAfterMilliseconds) =>
+    Object.assign(new Error('Busy'), { retryAfterMilliseconds });
+  const soon = scripted([busy(1500), new Response('ok')]);
+  assert.strictEqual(await requestWithRetry(soon.request), 'ok');
+  assert.deepStrictEqual(soon.delays, [1500]);
+
+  const later = scripted([busy(60_000), new Response('ok')]);
+  await assert.rejects(requestWithRetry(later.request), { message: 'Busy', attempts: 1 });
+  assert.strictEqual(later.sends(), 1);
+  assert.deepStrictEqual(later.delays, []);
+});

From d96068afdc1df9ff4c16d9f354e8e5a7f4e92de4 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:11:44 +0300
Subject: [PATCH 049/158] fix(retry): return a Retry-After beyond the maximum
 delay

./retry cut a provider's Retry-After to maxDelayMilliseconds and retried
then, so a server that asked for two minutes was asked again after 30
seconds and most likely refused again, spending an attempt. A failure whose
Retry-After is longer than the maximum delay is now returned at once, with
its delay, for the caller or a queue to schedule; a shorter one is still
waited for before the computed backoff.

An upstream bug, recorded in CLAUDE.md; the ported test that pinned the cut
delay now expects the receipt back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                       |  3 +++
 CLAUDE.md                          |  3 +++
 docs/transports/retry.md           |  6 +++--
 src/retry/index.d.ts               |  3 ++-
 src/retry/retry-transport.js       | 23 +++++++++++++++++--
 tests/unit/retry-transport.test.js | 37 +++++++++++++++++++++++++++---
 6 files changed, 67 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ebb0be1..e81e39d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -126,6 +126,9 @@ fixed ones below.
   and retried after their own backoff anyway, while `./mailtrap` and `./maileroo` waited for it
   however long it was. A longer one is no longer waited for within the send: the failure is
   returned at once with its `retryAfterMilliseconds`.
+- **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
+  longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
+  limit. The failed receipt is returned at once, with its delay.
 
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
diff --git a/CLAUDE.md b/CLAUDE.md
index 15cf286..83cd96f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -213,6 +213,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     clients, and waited for without a bound by mailtrap and maileroo. `requestWithRetry` waits
     at least `retryAfterMilliseconds` between attempts, and when it is over 30 seconds throws
     the failure with it instead, for the caller or a queue to schedule.
+31. retry: a `Retry-After` longer than `maxDelayMilliseconds` was cut to it, so the retry came
+    sooner than the server asked and most likely met the same 429. The receipt is returned at
+    once instead.
 
 ## Repository layout
 
diff --git a/docs/transports/retry.md b/docs/transports/retry.md
index 1411cfc..4ef6c22 100644
--- a/docs/transports/retry.md
+++ b/docs/transports/retry.md
@@ -120,8 +120,10 @@ Computed retry delays use exponential backoff:
   computed delays.
 
 - `Retry-After`: When a structured receipt error includes `retryAfterMilliseconds`, retry
-  transport uses that provider-supplied delay before computed backoff.  The
-  delay is still capped by `maxDelayMilliseconds`.
+  transport uses that provider-supplied delay before computed backoff.  When it
+  is longer than `maxDelayMilliseconds`, the transport does not retry sooner,
+  where the provider would most likely refuse again: it returns the failed
+  receipt at once, with its delay, for the caller or a queue to schedule.
 
 Tests or host environments can replace waiting by passing a custom `wait`
 function:
diff --git a/src/retry/index.d.ts b/src/retry/index.d.ts
index 2ac248a..e35feea 100644
--- a/src/retry/index.d.ts
+++ b/src/retry/index.d.ts
@@ -20,7 +20,8 @@ export interface BackoffConfig {
    */
   readonly baseDelayMilliseconds?: number;
   /**
-   * Maximum computed delay, in milliseconds.
+   * Maximum computed delay, in milliseconds.  A `Retry-After` longer than it
+   * is not retried sooner: the failure is returned with its delay.
    *
    * @default 30000
    */
diff --git a/src/retry/retry-transport.js b/src/retry/retry-transport.js
index 28b4b0d..cbab977 100644
--- a/src/retry/retry-transport.js
+++ b/src/retry/retry-transport.js
@@ -59,7 +59,11 @@ class RetryTransport {
         options?.signal?.throwIfAborted();
 
         lastThrownError = error;
-        if (attempt >= this.config.maxAttempts || !this.shouldRetryError(error)) {
+        if (
+          attempt >= this.config.maxAttempts ||
+          !this.shouldRetryError(error) ||
+          this.isRetryAfterBeyondMaxDelay(toReceiptError(error))
+        ) {
           return this.createThrownFailure(error, attempt);
         }
 
@@ -84,7 +88,11 @@ class RetryTransport {
       }
 
       const failedReceipt = this.withFailureMetadata(receipt, attempt);
-      if (attempt >= this.config.maxAttempts || !this.shouldRetryReceipt(failedReceipt)) {
+      if (
+        attempt >= this.config.maxAttempts ||
+        !this.shouldRetryReceipt(failedReceipt) ||
+        this.isRetryAfterBeyondMaxDelay(failedReceipt)
+      ) {
         return failedReceipt;
       }
 
@@ -328,6 +336,17 @@ class RetryTransport {
     return errors?.some((error) => error.retryable) ?? false;
   }
 
+  // A server that asks to wait longer than the longest delay is not asked
+  // again sooner, where it would most likely refuse again: the failure goes
+  // back with its delay, for the caller or a queue to schedule.
+  isRetryAfterBeyondMaxDelay(failure) {
+    const retryAfterMilliseconds = getRetryAfterMilliseconds(failure);
+    return (
+      Number.isFinite(retryAfterMilliseconds) &&
+      retryAfterMilliseconds > this.config.backoff.maxDelayMilliseconds
+    );
+  }
+
   calculateDelay(attempt, failure) {
     const retryAfterMilliseconds = getRetryAfterMilliseconds(failure);
     const cappedRetryAfter =
diff --git a/tests/unit/retry-transport.test.js b/tests/unit/retry-transport.test.js
index 287edd6..d5ea6ef 100644
--- a/tests/unit/retry-transport.test.js
+++ b/tests/unit/retry-transport.test.js
@@ -68,7 +68,7 @@ describe('RetryTransport', () => {
     assert.equal(waits.length, 0);
   });
 
-  it('uses capped Retry-After metadata before computed backoff', async () => {
+  it('returns a Retry-After beyond the maximum delay rather than retrying early', async () => {
     const delays = [];
     const base = new SequenceTransport([
       createFailedReceipt(
@@ -93,9 +93,40 @@ describe('RetryTransport', () => {
       },
     });
 
-    await transport.send(message());
+    const receipt = await transport.send(message());
+
+    // Changed after the port: upstream capped the 5 s Retry-After at the
+    // 2 s maximum delay and retried early; the receipt now goes back with it.
+    assert.deepEqual(delays, []);
+    assert.equal(receipt.successful, false);
+    assert.equal(receipt.attempts, 1);
+    assert.equal(receipt.errors?.[0]?.retryAfterMilliseconds, 5_000);
+  });
+
+  it('uses Retry-After metadata within the maximum delay before computed backoff', async () => {
+    const delays = [];
+    const base = new SequenceTransport([
+      createFailedReceipt(
+        createReceiptError('Rate limited', {
+          provider: 'base',
+          statusCode: 429,
+          retryAfterMilliseconds: 1_500,
+        }),
+      ),
+      { successful: true, messageId: 'delivered' },
+    ]);
+    const transport = createRetryTransport(base, {
+      maxAttempts: 2,
+      backoff: { baseDelayMilliseconds: 100, maxDelayMilliseconds: 2_000 },
+      jitter: false,
+      wait: (context) => {
+        delays.push(context.delayMilliseconds);
+        return Promise.resolve();
+      },
+    });
 
-    assert.deepEqual(delays, [2_000]);
+    assert.equal((await transport.send(message())).successful, true);
+    assert.deepEqual(delays, [1_500]);
   });
 
   it('preserves zero Retry-After metadata', async () => {

From 40e2cbccd3f05025fed764ff4aa22ce0a488b472 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:14:18 +0300
Subject: [PATCH 050/158] fix: one retry policy for every HTTP provider

The providers decided differently what to retry and how long to wait: ./ses,
./resend, ./sendgrid, ./mailgun, ./plunk and ./jmap retried no 4xx, not even
a 429 that asks to come back later, and waited 1, 2, 4... seconds without
jitter, the first three without a cap, so clients that failed together came
back together; ./mailtrap, ./maileroo and ./lettermint retried 408, 429 and
5xx with jitter.

requestWithRetry now owns the policy, from the statusCode every provider
error carries: a request timeout (408), a rate limit (429), a server error
(5xx) and a failure without a response are retried, after an exponential
backoff capped at ten seconds and spread over its upper half, or after
Retry-After. The providers drop their own rules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                  |  8 ++++++++
 docs/transports/jmap.md       |  7 ++++---
 src/internal/http.js          | 27 ++++++++++++++++++++++++---
 src/jmap/http-client.js       |  8 +-------
 src/lettermint/http-client.js |  8 +-------
 src/maileroo/http-client.js   |  8 +-------
 src/mailgun/http-client.js    |  7 +------
 src/mailtrap/http-client.js   |  8 +-------
 src/plunk/http-client.js      |  7 +------
 src/resend/http-client.js     |  7 +------
 src/sendgrid/http-client.js   |  7 +------
 src/ses/http-client.js        |  7 +------
 tests/unit/internal.test.js   | 27 +++++++++++++++++++++++++++
 tests/unit/ses.test.js        | 11 +++++++++++
 14 files changed, 83 insertions(+), 64 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e81e39d..a5b40cc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -130,6 +130,14 @@ fixed ones below.
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
 
+### Changed
+
+- **One retry policy for every HTTP provider.** A request timeout (408), a rate limit (429), a
+  server error (5xx) and a failure without a response are retried, after an exponential backoff
+  capped at ten seconds and spread over its upper half (jitter), or after `Retry-After`. `./ses`,
+  `./resend`, `./sendgrid`, `./mailgun`, `./plunk` and `./jmap` used to retry no 4xx at all, and
+  waited without jitter, the first three without a cap.
+
 - **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
   (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
   any step or after DATA; the greeting waits for a complete line; and a UTF-8 character split
diff --git a/docs/transports/jmap.md b/docs/transports/jmap.md
index 6a99de8..91721f0 100644
--- a/docs/transports/jmap.md
+++ b/docs/transports/jmap.md
@@ -254,9 +254,10 @@ const transport = new JmapTransport({
 });
 ```
 
-The transport uses exponential backoff for retries, with delays of 1s,
-2s, 4s, etc. between attempts. Client errors (4xx responses) are not
-retried, as they typically indicate a problem with the request itself.
+The transport retries a request timeout (408), a rate limit (429), a server
+error (5xx) and a failure without a response, after an exponential backoff
+capped at ten seconds with jitter, or after `Retry-After`. Other client errors
+are not retried, as they indicate a problem with the request itself.
 
 The request that creates and submits the email (`Email/set` with
 `EmailSubmission/set`) is the exception: it is sent once, since a retry after a
diff --git a/src/internal/http.js b/src/internal/http.js
index 0869997..692494a 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -84,6 +84,22 @@ const checkRequestOptions = (timeoutMs, retries) => {
   }
 };
 
+/**
+ * Whether a response status may succeed when the request is sent again: a
+ * request timeout (408), too many requests (429) or a server error (5xx).
+ *
+ * @param statusCode The HTTP status of the response.
+ * @returns `true` when a retry may succeed.
+ * @internal
+ */
+const isRetryableStatus = (statusCode) =>
+  statusCode === 408 || statusCode === 429 || statusCode >= 500;
+
+// A failure without a status (the network, a timeout) may pass on a retry;
+// one with a status, only as isRetryableStatus() says.
+const isRetryableFailure = (error) =>
+  error.statusCode === undefined || isRetryableStatus(error.statusCode);
+
 // The longest Retry-After a send waits for between two attempts; beyond it the
 // failure is thrown with its delay, for the caller or a queue to schedule.
 const MAX_RETRY_AFTER_WAIT_MS = 30_000;
@@ -119,8 +135,11 @@ const startDeadline = (timeoutMs, signal) => {
  * - `send(signal, attempt)`: one fetch, with the signal of the attempt;
  * - `read(response, attempt)`: the result of a 2xx response;
  * - `reject(response, attempt)`: the error of any other response;
- * - `isRetryable(error)`, `retryDelayMs(attempt, error)`;
  * - `retries`, `timeoutMs`, `signal`;
+ * - `isRetryable(error)`: by default, a failure without a status or with a
+ *   retryable one (`isRetryableStatus`), from the `statusCode` that every
+ *   provider error carries;
+ * - `retryDelayMs(attempt, error)`: by default `jitteredDelayMs`;
  * - `createTimeoutError(error)`: the error of an expired deadline, by default
  *   the `AbortError` itself;
  * - `finalError(error, attempts)`: the error thrown once retries are spent,
@@ -163,14 +182,15 @@ const requestWithRetry = async (request) => {
       const accepted = request.wrapAccepted?.(failure, attempt + 1) ?? failure;
       throw markDeliveryUnknown(accepted);
     }
-    if (!request.isRetryable(failure)) throw failure;
+    if (!(request.isRetryable ?? isRetryableFailure)(failure)) throw failure;
     const retryAfterMs = Number.isFinite(failure.retryAfterMilliseconds)
       ? failure.retryAfterMilliseconds
       : 0;
     if (attempt >= request.retries || retryAfterMs > MAX_RETRY_AFTER_WAIT_MS) {
       throw request.finalError?.(failure, attempt + 1) ?? failure;
     }
-    await wait(Math.max(request.retryDelayMs(attempt, failure), retryAfterMs), signal);
+    const delayMs = (request.retryDelayMs ?? jitteredDelayMs)(attempt, failure);
+    await wait(Math.max(delayMs, retryAfterMs), signal);
   }
 };
 
@@ -179,6 +199,7 @@ module.exports = {
   checkRequestOptions,
   exponentialDelayMs,
   isAbortError,
+  isRetryableStatus,
   jitteredDelayMs,
   requestWithRetry,
   sleep,
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index 4ccd754..67c2ad0 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -3,7 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { JmapApiError } = require('./errors.js');
-const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
+const { isAbortError, requestWithRetry } = require('../internal/http.js');
 
 /**
  * HTTP client for JMAP API requests.
@@ -46,8 +46,6 @@ class JmapHttpClient {
           parseRetryAfter(response.headers.get('Retry-After')),
           1,
         ),
-      isRetryable: () => true,
-      retryDelayMs: exponentialDelayMs,
     });
   }
 
@@ -98,10 +96,6 @@ class JmapHttpClient {
           parseRetryAfter(response.headers.get('Retry-After')),
           attempt + 1,
         ),
-      // Don't retry on 4xx errors (client errors)
-      isRetryable: (error) =>
-        !(error instanceof JmapApiError && error.statusCode >= 400 && error.statusCode < 500),
-      retryDelayMs: exponentialDelayMs,
       // The cause tells a request that never left (a refused connection) from
       // one that may have reached the server.
       finalError: (error, attempts) => {
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index be45ab6..98a534b 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -2,7 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { parseRetryAfter } = require('../core/receipt.js');
-const { jitteredDelayMs, requestWithRetry } = require('../internal/http.js');
+const { requestWithRetry } = require('../internal/http.js');
 
 /**
  * Lettermint API error class for API-specific failures.
@@ -124,8 +124,6 @@ class LettermintHttpClient {
           attempt + 1,
         ),
       createTimeoutError: () => new LettermintTimeoutError(this.config.timeout),
-      isRetryable: (error) => !(error instanceof LettermintApiError) || isRetryable(error),
-      retryDelayMs: jitteredDelayMs,
       finalError: withAttempts,
     });
   }
@@ -163,10 +161,6 @@ const withAttempts = (error, attempts) => {
   return Object.assign(error, { attempts });
 };
 
-const isRetryable = (error) => {
-  return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
-};
-
 const parseErrorMessage = (text, statusCode) => {
   try {
     const errorBody = JSON.parse(text);
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index 0cfd834..ebcb284 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -2,7 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { parseRetryAfter } = require('../core/receipt.js');
-const { jitteredDelayMs, requestWithRetry } = require('../internal/http.js');
+const { requestWithRetry } = require('../internal/http.js');
 
 const maxErrorMessageLength = 500;
 
@@ -103,8 +103,6 @@ class MailerooHttpClient {
           attempt + 1,
         ),
       createTimeoutError: () => new MailerooTimeoutError(this.config.timeout),
-      isRetryable: (error) => !(error instanceof MailerooApiError) || isRetryable(error),
-      retryDelayMs: jitteredDelayMs,
       finalError: withAttempts,
     });
   }
@@ -138,10 +136,6 @@ const withAttempts = (error, attempts) => {
   return Object.assign(error, { attempts });
 };
 
-const isRetryable = (error) => {
-  return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
-};
-
 const parseErrorMessage = (text, statusCode) => {
   try {
     const errorBody = JSON.parse(text);
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index 00a819e..85210ed 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -2,7 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { parseRetryAfter } = require('../core/receipt.js');
-const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
+const { requestWithRetry } = require('../internal/http.js');
 
 /**
  * HTTP client wrapper for Mailgun API requests.
@@ -87,8 +87,6 @@ class MailgunHttpClient {
       },
       createTimeoutError: () =>
         new Error(`Mailgun API request timed out after ${this.config.timeout} ms.`),
-      isRetryable: (error) => !isClientError(error) && !isAbortError(error),
-      retryDelayMs: exponentialDelayMs,
       finalError: (error, attempts) =>
         error instanceof MailgunApiError
           ? error
@@ -156,9 +154,6 @@ class MailgunApiError extends Error {
   }
 }
 
-const isClientError = (error) =>
-  error instanceof MailgunApiError && error.statusCode >= 400 && error.statusCode < 500;
-
 const truncateErrorBody = (text) => {
   return text.length > 500 ? `${text.slice(0, 500)}...` : text;
 };
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index 9dc4230..f6c2a19 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/mailtrap/src/http-client.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { jitteredDelayMs, requestWithRetry } = require('../internal/http.js');
+const { requestWithRetry } = require('../internal/http.js');
 
 const maxErrorMessageLength = 500;
 const sandboxRateLimitWindowMilliseconds = 10_000;
@@ -161,8 +161,6 @@ class MailtrapHttpClient {
       createTimeoutError: () => new MailtrapTimeoutError(this.config.timeout),
       // A 2xx response means Mailtrap may already have sent the message.
       wrapAccepted: (error, attempts) => new MailtrapResponseError(error, attempts),
-      isRetryable: (error) => !(error instanceof MailtrapApiError) || isRetryable(error),
-      retryDelayMs: jitteredDelayMs,
       finalError: withAttempts,
     });
   }
@@ -187,10 +185,6 @@ class MailtrapHttpClient {
   }
 }
 
-const isRetryable = (error) => {
-  return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
-};
-
 const withAttempts = (error, attempts) => {
   if (error instanceof MailtrapTimeoutError) {
     return new MailtrapTimeoutError(error.timeout, attempts);
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index 29c073c..2d78e90 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -2,7 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { parseRetryAfter } = require('../core/receipt.js');
-const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
+const { requestWithRetry } = require('../internal/http.js');
 
 /**
  * Error thrown when a Plunk API request fails.
@@ -97,8 +97,6 @@ class PlunkHttpClient {
         new Error(`Plunk API request timed out after ${this.config.timeout} ms.`),
       // Plunk refusing in a 200 (success: false) is a failure of its own.
       isAnswer: (error) => error instanceof PlunkApiError,
-      isRetryable: (error) => !isClientError(error) && !isAbortError(error),
-      retryDelayMs: (attempt) => Math.min(exponentialDelayMs(attempt), 10000),
       finalError: (error, attempts) =>
         error instanceof PlunkApiError
           ? new PlunkApiError(
@@ -180,9 +178,6 @@ class PlunkHttpClient {
   }
 }
 
-const isClientError = (error) =>
-  error instanceof PlunkApiError && error.statusCode >= 400 && error.statusCode < 500;
-
 const truncateErrorBody = (text) => {
   return text.length > 500 ? `${text.slice(0, 500)}...` : text;
 };
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index bbeaf9c..582d7bc 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -2,7 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { parseRetryAfter } = require('../core/receipt.js');
-const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
+const { requestWithRetry } = require('../internal/http.js');
 
 /**
  * Error thrown when a Resend API request fails.
@@ -153,8 +153,6 @@ class ResendHttpClient {
       },
       createTimeoutError: () =>
         new Error(`Resend API request timed out after ${this.config.timeout} ms.`),
-      isRetryable: (error) => !isClientError(error) && !isAbortError(error),
-      retryDelayMs: (attempt) => Math.min(exponentialDelayMs(attempt), 10000),
       finalError: (error, attempts) =>
         error instanceof ResendApiError
           ? error
@@ -185,9 +183,6 @@ class ResendHttpClient {
   }
 }
 
-const isClientError = (error) =>
-  error instanceof ResendApiError && error.statusCode >= 400 && error.statusCode < 500;
-
 const truncateErrorBody = (text) => {
   return text.length > 500 ? `${text.slice(0, 500)}...` : text;
 };
diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
index 85474ad..b477b6b 100644
--- a/src/sendgrid/http-client.js
+++ b/src/sendgrid/http-client.js
@@ -2,7 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { parseRetryAfter } = require('../core/receipt.js');
-const { exponentialDelayMs, requestWithRetry } = require('../internal/http.js');
+const { requestWithRetry } = require('../internal/http.js');
 
 /**
  * HTTP client wrapper for SendGrid API requests.
@@ -67,8 +67,6 @@ class SendGridHttpClient {
         createSendGridApiError(response, await response.text(), attempt),
       createTimeoutError: () =>
         new Error(`SendGrid API request timed out after ${this.config.timeout} ms.`),
-      isRetryable: (error) => !isClientError(error),
-      retryDelayMs: exponentialDelayMs,
       finalError: (error, attempts) =>
         error instanceof SendGridApiError
           ? error
@@ -173,7 +171,4 @@ const createSendGridApiError = (response, text, attempt) => {
   );
 };
 
-const isClientError = (error) =>
-  error instanceof SendGridApiError && error.statusCode >= 400 && error.statusCode < 500;
-
 module.exports = { SendGridHttpClient, SendGridApiError };
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index dab4901..1c9358b 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -3,7 +3,7 @@
 
 const { createHash, createHmac } = require('node:crypto');
 const { parseRetryAfter } = require('../core/receipt.js');
-const { exponentialDelayMs, isAbortError, requestWithRetry } = require('../internal/http.js');
+const { requestWithRetry } = require('../internal/http.js');
 
 class SesHttpClient {
   config;
@@ -56,8 +56,6 @@ class SesHttpClient {
         createSesApiError(response, await response.text(), attempt),
       createTimeoutError: () =>
         new Error(`SES API request timed out after ${this.config.timeout} ms.`),
-      isRetryable: (error) => !isClientError(error) && !isAbortError(error),
-      retryDelayMs: exponentialDelayMs,
       finalError: (error, attempts) =>
         error instanceof SesApiError
           ? error
@@ -213,9 +211,6 @@ const createSesApiError = (response, text, attempt) => {
   );
 };
 
-const isClientError = (error) =>
-  error instanceof SesApiError && error.statusCode >= 400 && error.statusCode < 500;
-
 class SesApiError extends Error {
   statusCode;
   errors;
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index 2e7ac9b..7818f63 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -29,6 +29,7 @@ const { isDeliveryUnknown } = require('../../src/internal/delivery-unknown.js');
 const {
   checkRequestOptions,
   exponentialDelayMs,
+  isRetryableStatus,
   jitteredDelayMs,
   requestWithRetry,
 } = require('../../src/internal/http.js');
@@ -182,3 +183,29 @@ test('Internal: a Retry-After is waited for, and not when it is longer than half
   assert.strictEqual(later.sends(), 1);
   assert.deepStrictEqual(later.delays, []);
 });
+
+test('Internal: a timeout, a rate limit and a server error are retried by default', async () => {
+  assert.deepStrictEqual([400, 401, 404, 408, 422, 429, 500, 503, 301].map(isRetryableStatus), [
+    false,
+    false,
+    false,
+    true,
+    false,
+    true,
+    true,
+    true,
+    false,
+  ]);
+  const reject = async (response) =>
+    Object.assign(new Error('HTTP'), { statusCode: response.status });
+  const limited = scripted([new Response('', { status: 429 }), new Response('ok')], {
+    reject,
+    isRetryable: undefined,
+    retryDelayMs: undefined,
+  });
+  assert.strictEqual(await requestWithRetry(limited.request), 'ok');
+  assert.ok(limited.delays[0] >= 500 && limited.delays[0] <= 1000, String(limited.delays[0]));
+  const refused = scripted([new Response('', { status: 400 })], { reject, isRetryable: undefined });
+  await assert.rejects(requestWithRetry(refused.request), { statusCode: 400 });
+  assert.strictEqual(refused.sends(), 1);
+});
diff --git a/tests/unit/ses.test.js b/tests/unit/ses.test.js
index d47b920..c8e5da5 100644
--- a/tests/unit/ses.test.js
+++ b/tests/unit/ses.test.js
@@ -192,3 +192,14 @@ test('SES: a request is signed as the SigV4 test suite of AWS expects', (t) => {
     );
   }
 });
+
+test('SES: a rate limit (429) is retried, a refusal (400) is not', async (t) => {
+  let requests = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    requests++;
+    return new Response('{"message":"x"}', { status: requests === 1 ? 429 : 400 });
+  });
+  const receipt = await new SesTransport({ authentication, retries: 3 }).send(message());
+  assert.strictEqual(requests, 2);
+  assert.strictEqual(receipt.errors[0].statusCode, 400);
+});

From da08d079525f7a624c50ed67627c18b25a43e41c Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:16:28 +0300
Subject: [PATCH 051/158] fix: never follow a redirect with credentials

fetch follows redirects by default, and undici drops only the
Authorization header when one crosses origins: Maileroo's X-API-Key,
Mailtrap's Api-Token, Lettermint's x-lettermint-token, any custom header of
the config, and the body of the OAuth2 token request (client secret and
refresh token) went to wherever a redirect pointed (checked against a local
server: the key reached the other origin).

Every request of the HTTP providers, of ./jmap (blob uploads included) and
the token refresh of ./smtp now asks for redirect: 'manual', so a 3xx comes
back as a response: an error the provider reports, which the retry policy
does not retry. The raw JMAP requests keep redirect: 'error'.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                  |  5 +++++
 CLAUDE.md                     |  5 +++++
 src/jmap/blob-uploader.js     |  3 +++
 src/jmap/http-client.js       |  4 +++-
 src/lettermint/http-client.js |  3 +++
 src/maileroo/http-client.js   |  3 +++
 src/mailgun/http-client.js    |  4 +++-
 src/mailtrap/http-client.js   |  3 +++
 src/plunk/http-client.js      |  3 +++
 src/resend/http-client.js     |  4 +++-
 src/sendgrid/http-client.js   |  4 +++-
 src/ses/http-client.js        |  3 +++
 src/smtp/oauth2.js            |  3 +++
 tests/unit/delivery.test.js   | 15 +++++++++++++++
 tests/unit/jmap.test.js       | 27 +++++++++++++++++++++++++++
 tests/unit/smtp.test.js       | 21 +++++++++++++++++++++
 16 files changed, 106 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a5b40cc..b28db05 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -126,6 +126,11 @@ fixed ones below.
   and retried after their own backoff anyway, while `./mailtrap` and `./maileroo` waited for it
   however long it was. A longer one is no longer waited for within the send: the failure is
   returned at once with its `retryAfterMilliseconds`.
+- **No request follows a redirect** (an upstream bug): `fetch` followed them and strips only
+  `Authorization` on a cross-origin one, so Maileroo's `X-API-Key`, Mailtrap's `Api-Token`,
+  Lettermint's token, custom `headers` and the body of the OAuth2 token request (client secret,
+  refresh token) went wherever a redirect pointed. Every request of the HTTP providers, `./jmap`
+  and the OAuth2 refresh of `./smtp` now gets a 3xx back as a failure, which is not retried.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 83cd96f..469992a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -216,6 +216,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 31. retry: a `Retry-After` longer than `maxDelayMilliseconds` was cut to it, so the retry came
     sooner than the server asked and most likely met the same 429. The receipt is returned at
     once instead.
+32. every HTTP provider, jmap and the OAuth2 token request of smtp: `fetch` followed redirects,
+    and undici strips only `Authorization` on a cross-origin one, so `X-API-Key`, `Api-Token`,
+    `x-lettermint-token`, custom headers and the token request's body went wherever a redirect
+    pointed. Every request is sent with `redirect: 'manual'` (or `'error'`), and a 3xx is a
+    failure that is not retried.
 
 ## Repository layout
 
diff --git a/src/jmap/blob-uploader.js b/src/jmap/blob-uploader.js
index ccddf53..0812017 100644
--- a/src/jmap/blob-uploader.js
+++ b/src/jmap/blob-uploader.js
@@ -46,11 +46,14 @@ const uploadBlob = async (config, uploadUrl, accountId, blob, signal) => {
   const combinedSignal = combineSignals(controller.signal, signal);
 
   try {
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
     const response = await fetch(url, {
       method: 'POST',
       headers,
       body: blob,
       signal: combinedSignal.signal,
+      redirect: 'manual',
     });
 
     if (!response.ok) {
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index 67c2ad0..6d56b77 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -131,7 +131,9 @@ class JmapHttpClient {
       headers.set(key, value);
     }
 
-    return globalThis.fetch(url, { ...options, headers, signal });
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
+    return globalThis.fetch(url, { redirect: 'manual', ...options, headers, signal });
   }
 }
 
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index 98a534b..864cf09 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -142,11 +142,14 @@ class LettermintHttpClient {
       headers.set(key, value);
     }
 
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
     return globalThis.fetch(url, {
       method: 'POST',
       headers,
       body: JSON.stringify(body),
       signal,
+      redirect: 'manual',
     });
   }
 }
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index ebcb284..c9e2807 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -117,11 +117,14 @@ class MailerooHttpClient {
       headers.set(key, value);
     }
 
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
     return globalThis.fetch(url, {
       method: 'POST',
       headers,
       body: JSON.stringify(body),
       signal,
+      redirect: 'manual',
     });
   }
 }
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index 85210ed..2b5cd06 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -114,7 +114,9 @@ class MailgunHttpClient {
       headers.set(key, value);
     }
 
-    return globalThis.fetch(url, { ...options, headers, signal });
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
+    return globalThis.fetch(url, { ...options, headers, signal, redirect: 'manual' });
   }
 }
 
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index f6c2a19..61a38e8 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -176,11 +176,14 @@ class MailtrapHttpClient {
       headers.set(key, value);
     }
 
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
     return globalThis.fetch(url, {
       method: 'POST',
       headers,
       body: JSON.stringify(body),
       signal,
+      redirect: 'manual',
     });
   }
 }
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index 2d78e90..0a50442 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -124,11 +124,14 @@ class PlunkHttpClient {
       ...this.config.headers,
     };
 
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
     return fetch(url, {
       method: 'POST',
       headers,
       body: JSON.stringify(emailData),
       signal,
+      redirect: 'manual',
     });
   }
 
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index 582d7bc..56c9128 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -179,7 +179,9 @@ class ResendHttpClient {
       headers.set(key, value);
     }
 
-    return fetch(url, { ...options, headers, signal });
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
+    return fetch(url, { ...options, headers, signal, redirect: 'manual' });
   }
 }
 
diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
index b477b6b..582d7a8 100644
--- a/src/sendgrid/http-client.js
+++ b/src/sendgrid/http-client.js
@@ -93,7 +93,9 @@ class SendGridHttpClient {
       headers.set(key, value);
     }
 
-    return globalThis.fetch(url, { ...options, headers, signal });
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
+    return globalThis.fetch(url, { ...options, headers, signal, redirect: 'manual' });
   }
 
   /**
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index 1c9358b..c7f193f 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -88,10 +88,13 @@ class SesHttpClient {
       signedHeaders.set(key, value);
     }
 
+    // A redirect comes back as a response rather than being followed, so the
+    // credentials in the headers never reach another origin.
     return await globalThis.fetch(url, {
       ...options,
       headers: this.headersToRecord(signedHeaders),
       signal,
+      redirect: 'manual',
     });
   }
 
diff --git a/src/smtp/oauth2.js b/src/smtp/oauth2.js
index fd7ffb4..1c630c1 100644
--- a/src/smtp/oauth2.js
+++ b/src/smtp/oauth2.js
@@ -339,6 +339,9 @@ class OAuth2TokenManager {
         },
         body,
         signal: controller.signal,
+        // A redirect is not followed: it would send the client secret and the
+        // refresh token in the body to wherever it points.
+        redirect: 'manual',
       });
       // Read the body under the same timeout: an endpoint that returns headers
       // but stalls on the body must not leave `pending` unresolved forever.
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index 1cd4e20..5fda60b 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -151,3 +151,18 @@ test(
     }
   },
 );
+
+test('Delivery: a redirect is not followed, nor retried', async (t) => {
+  for (const [name, , create] of providers) {
+    const redirects = [];
+    t.mock.method(globalThis, 'fetch', async (_url, init) => {
+      redirects.push(init.redirect);
+      return new Response(null, { status: 307, headers: { Location: 'https://evil.example/' } });
+    });
+    const receipt = await create().send(message());
+    t.mock.restoreAll();
+    assert.deepStrictEqual(redirects, ['manual'], name);
+    assert.strictEqual(receipt.successful, false, name);
+    assert.strictEqual(receipt.errors[0].statusCode, 307, name);
+  }
+});
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index 95ca643..8e6fcb1 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -6,6 +6,8 @@ const { test } = require('node:test');
 const assert = require('node:assert');
 const { createMessage } = require('../../index.js');
 const { JmapTransport } = require('../../src/jmap/index.js');
+const { uploadBlob } = require('../../src/jmap/blob-uploader.js');
+const { createJmapConfig } = require('../../src/jmap/config.js');
 
 const CORE = 'urn:ietf:params:jmap:core';
 const MAIL = 'urn:ietf:params:jmap:mail';
@@ -185,3 +187,28 @@ test('JMAP: a submission is sent once; it stays retryable only if it never left'
     t.mock.restoreAll();
   }
 });
+
+test('JMAP: no request follows a redirect', async (t) => {
+  const redirects = new Set();
+  const calls = serve(t);
+  const original = globalThis.fetch;
+  t.mock.method(globalThis, 'fetch', (input, init) => {
+    redirects.add(init.redirect);
+    return original(input, init);
+  });
+  const receipt = await transport().send(message());
+  assert.ok(calls.length > 0);
+  assert.strictEqual(receipt.successful, true, receipt.errorMessages?.join(' | '));
+  assert.deepStrictEqual([...redirects], ['manual']);
+});
+
+test('JMAP: a blob upload does not follow a redirect', async (t) => {
+  const redirects = [];
+  t.mock.method(globalThis, 'fetch', async (_url, init) => {
+    redirects.push(init.redirect);
+    return Response.json({ blobId: 'b1' });
+  });
+  const config = createJmapConfig({ sessionUrl: 'https://jmap.example.com/s', bearerToken: 't' });
+  await uploadBlob(config, 'https://jmap.example.com/upload/{accountId}', 'a1', new Blob(['a']));
+  assert.deepStrictEqual(redirects, ['manual']);
+});
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index ff03f60..a6ff975 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -9,6 +9,7 @@ const { createMessage } = require('../../index.js');
 const { SmtpTransport } = require('../../src/smtp/index.js');
 const { prepareOnSocket, writeMessageData } = require('../../src/smtp/data-stream.js');
 const { checkSmtpPath } = require('../../src/smtp/envelope.js');
+const { OAuth2TokenManager } = require('../../src/smtp/oauth2.js');
 const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
 
 const message = () =>
@@ -383,3 +384,23 @@ test('SMTP: a connection reset in the middle of the envelope fails the send', as
     await stop(server);
   }
 });
+
+test('SMTP: the OAuth2 token request does not follow a redirect', async () => {
+  const redirects = [];
+  const fetchFn = async (_url, init) => {
+    redirects.push(init.redirect);
+    return Response.json({ access_token: 'token', expires_in: 3600 });
+  };
+  const manager = new OAuth2TokenManager(
+    {
+      user: 'alex@example.com',
+      clientId: 'client',
+      clientSecret: 'secret',
+      refreshToken: 'refresh',
+      tokenEndpoint: 'https://auth.example.com/token',
+    },
+    fetchFn,
+  );
+  assert.strictEqual(await manager.getAccessToken(), 'token');
+  assert.deepStrictEqual(redirects, ['manual']);
+});

From fc35c95a1012e39502b49370093fc7ec650b49c4 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:19:48 +0300
Subject: [PATCH 052/158] fix: refuse to send provider credentials over plain
 HTTP

No URL of a provider's configuration had to use HTTPS: a baseUrl, a
Mailtrap send or sandbox base URL, or a JMAP session or base URL starting
with http:// sent the API key or token in clear on every request. Only the
OAuth 2.0 token endpoint of ./smtp checked it.

checkSecureUrl now refuses, with a TypeError when the config is made, any
URL that is not HTTPS, except plain HTTP to a loopback host (localhost,
*.localhost, 127.0.0.0/8, ::1), so local fake servers keep working. It
lives with checkRequestOptions in src/internal/config.js, apart from the
request loop of src/internal/http.js; src/internal/loopback.js holds the
loopback check, for the SMTP checks to share later.

The shared modules have grown with the fixes of this phase, so the size
budgets of ./ses and ./jmap go up by 1 KB min+gzip. An upstream bug,
recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml    |  2 +-
 CHANGELOG.md                |  4 +++
 CLAUDE.md                   |  3 +++
 src/internal/config.js      | 50 +++++++++++++++++++++++++++++++++++++
 src/internal/http.js        | 21 ----------------
 src/internal/loopback.js    | 23 +++++++++++++++++
 src/jmap/config.js          |  4 ++-
 src/lettermint/config.js    |  3 ++-
 src/maileroo/config.js      |  3 ++-
 src/mailgun/config.js       |  3 ++-
 src/mailtrap/config.js      |  4 ++-
 src/plunk/config.js         |  3 ++-
 src/resend/config.js        |  3 ++-
 src/sendgrid/config.js      |  3 ++-
 src/ses/config.js           |  2 +-
 tests/unit/delivery.test.js | 18 +++++++++++++
 tests/unit/internal.test.js | 17 ++++++++++++-
 17 files changed, 134 insertions(+), 32 deletions(-)
 create mode 100644 src/internal/config.js
 create mode 100644 src/internal/loopback.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index eebf068..d7c6b08 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 18 --max-gzip-jmap 9 --max-gzip-ses 4 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 3 --max-gzip-mailtrap 4 --max-gzip-maileroo 4 --max-gzip-lettermint 4 --max-gzip-plunk 3 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2
+      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 18 --max-gzip-jmap 10 --max-gzip-ses 5 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 3 --max-gzip-mailtrap 4 --max-gzip-maileroo 4 --max-gzip-lettermint 4 --max-gzip-plunk 3 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2
 
   types:
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b28db05..44c020c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -131,6 +131,10 @@ fixed ones below.
   Lettermint's token, custom `headers` and the body of the OAuth2 token request (client secret,
   refresh token) went wherever a redirect pointed. Every request of the HTTP providers, `./jmap`
   and the OAuth2 refresh of `./smtp` now gets a 3xx back as a failure, which is not retried.
+- **A provider no longer sends its credentials over plain HTTP** (an upstream bug): a `baseUrl`,
+  a Mailtrap base URL or a JMAP `sessionUrl` starting with `http://` sent the API key or token in
+  clear. They must use HTTPS, or plain HTTP only to a loopback host such as a local fake server;
+  anything else is refused with a `TypeError` when the transport is made.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 469992a..69c58ca 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -221,6 +221,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     `x-lettermint-token`, custom headers and the token request's body went wherever a redirect
     pointed. Every request is sent with `redirect: 'manual'` (or `'error'`), and a 3xx is a
     failure that is not retried.
+33. every HTTP provider and jmap: no URL of a config had to be HTTPS, so `http://` sent the key
+    in clear. `checkSecureUrl` (`src/internal/http.js`, with `src/internal/loopback.js`) refuses
+    anything but HTTPS or plain HTTP to a loopback host when the config is made.
 
 ## Repository layout
 
diff --git a/src/internal/config.js b/src/internal/config.js
new file mode 100644
index 0000000..ebfad7a
--- /dev/null
+++ b/src/internal/config.js
@@ -0,0 +1,50 @@
+// Not ported from upyo: the checks of the options that every HTTP provider
+// shares, made once, when its configuration is made.
+
+const { isLoopbackHostname } = require('./loopback.js');
+
+/**
+ * Checks the timeout and the retries of a provider's configuration.
+ *
+ * @param timeoutMs The timeout of an attempt in milliseconds, 0 or `Infinity`
+ * for none.
+ * @param retries How many times a failed attempt is retried.
+ * @throws {RangeError} If either is not a number of that kind.
+ * @internal
+ */
+const checkRequestOptions = (timeoutMs, retries) => {
+  if (typeof timeoutMs !== 'number' || !(timeoutMs >= 0)) {
+    throw new RangeError(
+      '`timeout` must be a number of milliseconds, 0 or Infinity for none: ' + String(timeoutMs),
+    );
+  }
+  if (!Number.isInteger(retries) || retries < 0) {
+    throw new RangeError('`retries` must be a non-negative integer: ' + String(retries));
+  }
+};
+
+/**
+ * Checks that a URL of a provider's configuration keeps credentials off the
+ * network in clear: HTTPS, or plain HTTP only to a loopback host.
+ *
+ * @param value The URL, as configured.
+ * @param name The option it comes from, for the error.
+ * @throws {TypeError} If it is not a URL, or neither HTTPS nor loopback HTTP.
+ * @internal
+ */
+const checkSecureUrl = (value, name) => {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TypeError(`\`${name}\` must be a URL: ${String(value)}`);
+  }
+  if (url.protocol === 'https:') return;
+  if (url.protocol === 'http:' && isLoopbackHostname(url.hostname)) return;
+  throw new TypeError(
+    `\`${name}\` must use HTTPS, or plain HTTP only to a loopback host, ` +
+      `so that credentials are not sent in clear: ${value}`,
+  );
+};
+
+module.exports = { checkRequestOptions, checkSecureUrl };
diff --git a/src/internal/http.js b/src/internal/http.js
index 692494a..e3db8ed 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -64,26 +64,6 @@ const jitteredDelayMs = (attempt) => {
   return Math.round(baseMs / 2 + Math.random() * (baseMs / 2));
 };
 
-/**
- * Checks the timeout and the retries of a provider's configuration.
- *
- * @param timeoutMs The timeout of an attempt in milliseconds, 0 or `Infinity`
- * for none.
- * @param retries How many times a failed attempt is retried.
- * @throws {RangeError} If either is not a number of that kind.
- * @internal
- */
-const checkRequestOptions = (timeoutMs, retries) => {
-  if (typeof timeoutMs !== 'number' || !(timeoutMs >= 0)) {
-    throw new RangeError(
-      '`timeout` must be a number of milliseconds, 0 or Infinity for none: ' + String(timeoutMs),
-    );
-  }
-  if (!Number.isInteger(retries) || retries < 0) {
-    throw new RangeError('`retries` must be a non-negative integer: ' + String(retries));
-  }
-};
-
 /**
  * Whether a response status may succeed when the request is sent again: a
  * request timeout (408), too many requests (429) or a server error (5xx).
@@ -196,7 +176,6 @@ const requestWithRetry = async (request) => {
 
 module.exports = {
   abortReason,
-  checkRequestOptions,
   exponentialDelayMs,
   isAbortError,
   isRetryableStatus,
diff --git a/src/internal/loopback.js b/src/internal/loopback.js
new file mode 100644
index 0000000..5971660
--- /dev/null
+++ b/src/internal/loopback.js
@@ -0,0 +1,23 @@
+// Not ported from upyo: whether a host name of a URL is this machine, the one
+// place where credentials may go over plain HTTP, to a local fake server.
+
+const net = require('node:net');
+
+/**
+ * Whether the host name of a parsed URL is a loopback host: `localhost`, a
+ * name under `.localhost`, an address of 127.0.0.0/8, or `::1` (also as an
+ * IPv4-mapped 127 address).  `URL` has already put the name in its canonical
+ * form, so `127.1` reads `127.0.0.1` and an IPv6 address is bracketed.
+ *
+ * @param hostname The `hostname` of a `URL`.
+ * @returns `true` for a loopback host.
+ * @internal
+ */
+const isLoopbackHostname = (hostname) => {
+  const name = hostname.toLowerCase().replace(/\.$/, '');
+  if (name === 'localhost' || name.endsWith('.localhost')) return true;
+  if (net.isIPv4(name)) return name.startsWith('127.');
+  return name === '[::1]' || name.startsWith('[::ffff:7f');
+};
+
+module.exports = { isLoopbackHostname };
diff --git a/src/jmap/config.js b/src/jmap/config.js
index 45477a9..300000c 100644
--- a/src/jmap/config.js
+++ b/src/jmap/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/jmap/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions } = require('../internal/http.js');
+const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved JMAP configuration with default values applied.
@@ -26,6 +26,8 @@ const createJmapConfig = (config) => {
     baseUrl: config.baseUrl ?? null,
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkSecureUrl(resolved.sessionUrl, 'sessionUrl');
+  if (resolved.baseUrl != null) checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
 
diff --git a/src/lettermint/config.js b/src/lettermint/config.js
index 182dec6..2664d4b 100644
--- a/src/lettermint/config.js
+++ b/src/lettermint/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/lettermint/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions } = require('../internal/http.js');
+const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved Lettermint configuration by applying default values.
@@ -22,6 +22,7 @@ const createLettermintConfig = (config) => {
     settings: config.settings == null ? undefined : { ...config.settings },
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
 
diff --git a/src/maileroo/config.js b/src/maileroo/config.js
index 7b6f81d..9d8b4ed 100644
--- a/src/maileroo/config.js
+++ b/src/maileroo/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/maileroo/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions } = require('../internal/http.js');
+const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved Maileroo configuration by applying default values.
@@ -20,6 +20,7 @@ const createMailerooConfig = (config) => {
     tags: config.tags == null ? undefined : { ...config.tags },
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
 
diff --git a/src/mailgun/config.js b/src/mailgun/config.js
index 2cd4888..de915b7 100644
--- a/src/mailgun/config.js
+++ b/src/mailgun/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/mailgun/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions } = require('../internal/http.js');
+const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved Mailgun configuration by applying default values to optional fields.
@@ -32,6 +32,7 @@ const createMailgunConfig = (config) => {
     openTracking: config.openTracking ?? true,
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
 
diff --git a/src/mailtrap/config.js b/src/mailtrap/config.js
index 5f11e6d..94924af 100644
--- a/src/mailtrap/config.js
+++ b/src/mailtrap/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/mailtrap/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions } = require('../internal/http.js');
+const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 const DEFAULT_SEND_BASE_URL = 'https://send.api.mailtrap.io';
 const DEFAULT_SANDBOX_BASE_URL = 'https://sandbox.api.mailtrap.io';
@@ -37,6 +37,8 @@ const createMailtrapConfig = (config) => {
     headers: config.headers == null ? {} : { ...config.headers },
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkSecureUrl(resolved.sendBaseUrl, 'sendBaseUrl');
+  checkSecureUrl(resolved.sandboxBaseUrl, 'sandboxBaseUrl');
   return resolved;
 };
 
diff --git a/src/plunk/config.js b/src/plunk/config.js
index 968fec2..a436599 100644
--- a/src/plunk/config.js
+++ b/src/plunk/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/plunk/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions } = require('../internal/http.js');
+const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved Plunk configuration by applying default values to optional fields.
@@ -24,6 +24,7 @@ const createPlunkConfig = (config) => {
     headers: config.headers ?? {},
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
 
diff --git a/src/resend/config.js b/src/resend/config.js
index 850543b..b70846b 100644
--- a/src/resend/config.js
+++ b/src/resend/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/resend/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions } = require('../internal/http.js');
+const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved Resend configuration by applying default values to optional fields.
@@ -24,6 +24,7 @@ const createResendConfig = (config) => {
     headers: config.headers ?? {},
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
 
diff --git a/src/sendgrid/config.js b/src/sendgrid/config.js
index 690cb0b..0715386 100644
--- a/src/sendgrid/config.js
+++ b/src/sendgrid/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/sendgrid/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions } = require('../internal/http.js');
+const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved SendGrid configuration by applying default values to optional fields.
@@ -28,6 +28,7 @@ const createSendGridConfig = (config) => {
     googleAnalytics: config.googleAnalytics ?? false,
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
 
diff --git a/src/ses/config.js b/src/ses/config.js
index 5fdbb7e..03fa0f8 100644
--- a/src/ses/config.js
+++ b/src/ses/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/ses/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions } = require('../internal/http.js');
+const { checkRequestOptions } = require('../internal/config.js');
 
 /**
  * Creates a resolved SES configuration with default values applied.
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index 5fda60b..aea2e1e 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -11,6 +11,7 @@ const { PlunkTransport } = require('../../src/plunk/index.js');
 const { ResendTransport } = require('../../src/resend/index.js');
 const { SendGridTransport } = require('../../src/sendgrid/index.js');
 const { SesTransport } = require('../../src/ses/index.js');
+const { JmapTransport } = require('../../src/jmap/index.js');
 
 const message = () =>
   createMessage({
@@ -166,3 +167,20 @@ test('Delivery: a redirect is not followed, nor retried', async (t) => {
     assert.strictEqual(receipt.errors[0].statusCode, 307, name);
   }
 });
+
+test('Delivery: a provider refuses to send its credentials over plain HTTP', () => {
+  const insecure = 'http://api.example.com';
+  const configs = [
+    () => new ResendTransport({ apiKey: 'key', baseUrl: insecure }),
+    () => new SendGridTransport({ apiKey: 'key', baseUrl: insecure }),
+    () => new MailgunTransport({ apiKey: 'key', domain: 'mg.example.com', baseUrl: insecure }),
+    () => new MailtrapTransport({ apiToken: 'token', sendBaseUrl: insecure }),
+    () => new MailerooTransport({ apiKey: 'key', baseUrl: insecure }),
+    () => new LettermintTransport({ apiToken: 'token', baseUrl: insecure }),
+    () => new PlunkTransport({ apiKey: 'key', baseUrl: insecure }),
+    () => new JmapTransport({ sessionUrl: `${insecure}/session`, bearerToken: 'token' }),
+  ];
+  for (const create of configs) assert.throws(create, TypeError);
+  const local = new ResendTransport({ apiKey: 'key', baseUrl: 'http://localhost:8080' });
+  assert.strictEqual(local.config.baseUrl, 'http://localhost:8080');
+});
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index 7818f63..81598a4 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -26,8 +26,8 @@ test('Internal: a reset, a timeout or a failure without a cause may have been se
 });
 
 const { isDeliveryUnknown } = require('../../src/internal/delivery-unknown.js');
+const { checkRequestOptions, checkSecureUrl } = require('../../src/internal/config.js');
 const {
-  checkRequestOptions,
   exponentialDelayMs,
   isRetryableStatus,
   jitteredDelayMs,
@@ -209,3 +209,18 @@ test('Internal: a timeout, a rate limit and a server error are retried by defaul
   await assert.rejects(requestWithRetry(refused.request), { statusCode: 400 });
   assert.strictEqual(refused.sends(), 1);
 });
+
+test('Internal: a provider URL is HTTPS, or plain HTTP only to a loopback host', () => {
+  const allowed = [
+    'https://api.example.com/v1',
+    'http://localhost:8080',
+    'http://mail.localhost/',
+    'http://127.0.0.1:3000',
+    'http://127.1/',
+    'http://[::1]:8080/',
+  ];
+  for (const url of allowed) checkSecureUrl(url, 'baseUrl');
+  for (const url of ['http://api.example.com', 'http://10.0.0.1/', 'ftp://a.example', 'nope']) {
+    assert.throws(() => checkSecureUrl(url, 'baseUrl'), TypeError, url);
+  }
+});

From 6fe5b1f45cc7f5bab95b90b5ab7ccc8655460e7e Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:22:53 +0300
Subject: [PATCH 053/158] fix: read a response body within 4 MiB

Every HTTP provider, ./jmap (blob and raw uploads included) and the OAuth2
token request of ./smtp read a response with response.text() or .json(),
whole, before looking at it, so a broken or hostile endpoint that sent an
endless body could fill the memory of the sending process.

readText and readJson in src/internal/body.js read the body from its
stream and refuse, with a RangeError, one longer than 4 MiB, by its
Content-Length before reading or as it streams, cancelling the rest; the
bound is far above any answer of a provider. After a 2xx, such a refusal is
an unknown delivery, like any failure after one. Three tests that stubbed
response.text() now stall or break the body stream itself.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                          |  4 ++
 CLAUDE.md                             |  6 ++-
 src/internal/body.js                  | 53 ++++++++++++++++++++++++
 src/jmap/blob-uploader.js             |  5 ++-
 src/jmap/http-client.js               |  9 +++--
 src/jmap/raw-upload.js                |  5 ++-
 src/lettermint/http-client.js         |  5 ++-
 src/maileroo/http-client.js           |  5 ++-
 src/mailgun/http-client.js            |  5 ++-
 src/mailtrap/http-client.js           |  5 ++-
 src/plunk/http-client.js              |  5 ++-
 src/resend/http-client.js             |  5 ++-
 src/sendgrid/http-client.js           |  5 ++-
 src/ses/http-client.js                |  5 ++-
 src/smtp/oauth2.js                    |  4 +-
 tests/unit/delivery.test.js           | 58 ++++++++++++++++++---------
 tests/unit/internal.test.js           | 38 ++++++++++++++++++
 tests/unit/jmap-http-client.test.js   | 19 ++++-----
 tests/unit/maileroo-transport.test.js | 37 +++++++++--------
 19 files changed, 204 insertions(+), 74 deletions(-)
 create mode 100644 src/internal/body.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 44c020c..231840d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -135,6 +135,10 @@ fixed ones below.
   a Mailtrap base URL or a JMAP `sessionUrl` starting with `http://` sent the API key or token in
   clear. They must use HTTPS, or plain HTTP only to a loopback host such as a local fake server;
   anything else is refused with a `TypeError` when the transport is made.
+- **A response body is read within 4 MiB** (an upstream bug): every HTTP provider, `./jmap` and
+  the OAuth2 token request of `./smtp` read a response whole, however long, so a broken or
+  hostile endpoint could fill the memory of the sender. A longer body is refused, by its
+  `Content-Length` or as it streams; after a 2xx, that is an unknown delivery.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 69c58ca..3ebf4d4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -224,6 +224,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 33. every HTTP provider and jmap: no URL of a config had to be HTTPS, so `http://` sent the key
     in clear. `checkSecureUrl` (`src/internal/http.js`, with `src/internal/loopback.js`) refuses
     anything but HTTPS or plain HTTP to a loopback host when the config is made.
+34. every HTTP provider, jmap and the OAuth2 token request: a response body was read whole,
+    however long, before anything looked at it. `readText`/`readJson` (`src/internal/body.js`)
+    read it from its stream and refuse one over 4 MiB, by its `Content-Length` or as it comes.
 
 ## Repository layout
 
@@ -234,7 +237,8 @@ src/
   version.js        the package name and version (OpenTelemetry scope), kept equal to package.json
   <subpath>/        one directory per subpath: index.js + index.d.ts + its modules
   internal/         private modules shared by subpaths, not in the exports map (redact.js,
-                    redact-addresses.js, unsent.js, delivery-unknown.js)
+                    redact-addresses.js, unsent.js, delivery-unknown.js, http.js,
+                    config.js, loopback.js, body.js)
 tests/
   unit/*.test.js    node:test suites, one per area (<subpath>-<module>.test.js for a subpath)
   helpers/<sub>/    shared test code of a subpath (fake servers, fixtures builders)
diff --git a/src/internal/body.js b/src/internal/body.js
new file mode 100644
index 0000000..8b14e85
--- /dev/null
+++ b/src/internal/body.js
@@ -0,0 +1,53 @@
+// Not ported from upyo: reads the body of a response within a bound, so that
+// a broken or hostile server cannot fill the memory of a sender.
+
+// Far above any answer of a provider (a batch of receipts, a JMAP session or
+// mailbox list), far below what would hurt a process.
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Reads the body of a response as text, refusing one longer than the bound:
+ * from its `Content-Length` before reading, or while it streams.
+ *
+ * @param response The response to read.
+ * @param maxBytes The longest body accepted, in bytes.
+ * @returns The body, decoded as UTF-8.
+ * @throws {RangeError} If the body is longer than `maxBytes`.
+ * @internal
+ */
+const readText = async (response, maxBytes = MAX_RESPONSE_BYTES) => {
+  const tooLong = () => new RangeError(`The response body exceeds ${maxBytes} bytes.`);
+  if (Number(response.headers.get('content-length')) > maxBytes) {
+    await response.body?.cancel();
+    throw tooLong();
+  }
+  if (response.body == null) return '';
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let text = '';
+  let sizeBytes = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    sizeBytes += value.byteLength;
+    if (sizeBytes > maxBytes) {
+      await reader.cancel();
+      throw tooLong();
+    }
+    text += decoder.decode(value, { stream: true });
+  }
+  return text + decoder.decode();
+};
+
+/**
+ * Reads the body of a response as JSON, within the bound of {@link readText}.
+ *
+ * @param response The response to read.
+ * @returns The parsed body.
+ * @throws {SyntaxError} If the body is not JSON.
+ * @throws {RangeError} If the body is too long.
+ * @internal
+ */
+const readJson = async (response) => JSON.parse(await readText(response));
+
+module.exports = { readJson, readText };
diff --git a/src/jmap/blob-uploader.js b/src/jmap/blob-uploader.js
index 0812017..51ae44d 100644
--- a/src/jmap/blob-uploader.js
+++ b/src/jmap/blob-uploader.js
@@ -3,6 +3,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { JmapApiError } = require('./errors.js');
+const { readJson, readText } = require('../internal/body.js');
 
 /**
  * Upload a blob to the JMAP server.
@@ -57,7 +58,7 @@ const uploadBlob = async (config, uploadUrl, accountId, blob, signal) => {
     });
 
     if (!response.ok) {
-      const body = await response.text();
+      const body = await readText(response);
       throw new JmapApiError(
         `Blob upload failed: ${response.status} ${response.statusText}`,
         response.status,
@@ -65,7 +66,7 @@ const uploadBlob = async (config, uploadUrl, accountId, blob, signal) => {
       );
     }
 
-    const result = await response.json();
+    const result = await readJson(response);
     return result;
   } finally {
     combinedSignal.cleanup();
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index 6d56b77..9ec088e 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -4,6 +4,7 @@
 const { parseRetryAfter } = require('../core/receipt.js');
 const { JmapApiError } = require('./errors.js');
 const { isAbortError, requestWithRetry } = require('../internal/http.js');
+const { readJson, readText } = require('../internal/body.js');
 
 /**
  * HTTP client for JMAP API requests.
@@ -36,12 +37,12 @@ class JmapHttpClient {
       isIdempotent: true,
       send: (attemptSignal) =>
         this.fetchWithAuth(this.config.sessionUrl, { method: 'GET' }, attemptSignal),
-      read: (response) => response.json(),
+      read: (response) => readJson(response),
       reject: async (response) =>
         new JmapApiError(
           `Session fetch failed: ${response.status}`,
           response.status,
-          await response.text(),
+          await readText(response),
           undefined,
           parseRetryAfter(response.headers.get('Retry-After')),
           1,
@@ -86,12 +87,12 @@ class JmapHttpClient {
           },
           attemptSignal,
         ),
-      read: (response) => response.json(),
+      read: (response) => readJson(response),
       reject: async (response, attempt) =>
         new JmapApiError(
           `JMAP request failed: ${response.status}`,
           response.status,
-          await response.text(),
+          await readText(response),
           undefined,
           parseRetryAfter(response.headers.get('Retry-After')),
           attempt + 1,
diff --git a/src/jmap/raw-upload.js b/src/jmap/raw-upload.js
index 6fec3e9..d9ee80d 100644
--- a/src/jmap/raw-upload.js
+++ b/src/jmap/raw-upload.js
@@ -5,6 +5,7 @@ const { analyzeRawMessage, iterateRawMessage } = require('../core/raw-message.js
 const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
 const { JmapApiError } = require('./errors.js');
+const { readJson, readText } = require('../internal/body.js');
 
 /** Runs a raw operation with a progress-resettable deadline through response parsing. @internal */
 const rawOperation = async (timeout, operation, signal) => {
@@ -163,7 +164,7 @@ const uploadRawMessage = async (config, uploadUrl, accountId, plan, signal) => {
           throw new JmapApiError(
             `Raw upload failed: ${response.status}`,
             response.status,
-            await response.text(),
+            await readText(response),
             undefined,
             parseRetryAfter(response.headers.get('Retry-After')),
           );
@@ -171,7 +172,7 @@ const uploadRawMessage = async (config, uploadUrl, accountId, plan, signal) => {
         if (!eof) {
           throw new JmapApiError('Raw upload responded before validated EOF.');
         }
-        const result = await response.json();
+        const result = await readJson(response);
         outerSignal.throwIfAborted();
         if (
           !isRecord(result) ||
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index 864cf09..fbfb741 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { readText } = require('../internal/body.js');
 
 /**
  * Lettermint API error class for API-specific failures.
@@ -105,7 +106,7 @@ class LettermintHttpClient {
       timeoutMs: this.config.timeout,
       send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal, idempotencyKey),
       read: async (response) => {
-        const text = await response.text();
+        const text = await readText(response);
         try {
           return JSON.parse(text);
         } catch (error) {
@@ -118,7 +119,7 @@ class LettermintHttpClient {
       },
       reject: async (response, attempt) =>
         new LettermintApiError(
-          parseErrorMessage(await response.text(), response.status),
+          parseErrorMessage(await readText(response), response.status),
           response.status,
           parseRetryAfter(response.headers.get('Retry-After')),
           attempt + 1,
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index c9e2807..cfa21cf 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { readText } = require('../internal/body.js');
 
 const maxErrorMessageLength = 500;
 
@@ -94,10 +95,10 @@ class MailerooHttpClient {
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
-      read: async (response) => parseResponse(await response.text()),
+      read: async (response) => parseResponse(await readText(response)),
       reject: async (response, attempt) =>
         new MailerooApiError(
-          parseErrorMessage(await response.text(), response.status),
+          parseErrorMessage(await readText(response), response.status),
           response.status,
           parseRetryAfter(response.headers.get('Retry-After')),
           attempt + 1,
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index 2b5cd06..9192393 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { readText } = require('../internal/body.js');
 
 /**
  * HTTP client wrapper for Mailgun API requests.
@@ -50,7 +51,7 @@ class MailgunHttpClient {
       timeoutMs: this.config.timeout,
       send: (signal) => this.fetchWithAuth(url, options, signal),
       read: async (response) => {
-        const text = await response.text();
+        const text = await readText(response);
         try {
           return JSON.parse(text);
         } catch (jsonError) {
@@ -63,7 +64,7 @@ class MailgunHttpClient {
         }
       },
       reject: async (response, attempt) => {
-        const text = await response.text();
+        const text = await readText(response);
         let errorMessage;
         try {
           // Try to parse the error message from the JSON body
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index 61a38e8..64e54fb 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { requestWithRetry } = require('../internal/http.js');
+const { readText } = require('../internal/body.js');
 
 const maxErrorMessageLength = 500;
 const sandboxRateLimitWindowMilliseconds = 10_000;
@@ -137,7 +138,7 @@ class MailtrapHttpClient {
       timeoutMs: this.config.timeout,
       send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
       read: async (response) => {
-        const text = await response.text();
+        const text = await readText(response);
         try {
           return JSON.parse(text);
         } catch (error) {
@@ -149,7 +150,7 @@ class MailtrapHttpClient {
         }
       },
       reject: async (response, attempt) => {
-        const message = parseErrorMessage(await response.text(), response.status);
+        const message = parseErrorMessage(await readText(response), response.status);
         return new MailtrapApiError(
           message,
           response.status,
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index 0a50442..71a9b02 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { readJson, readText } = require('../internal/body.js');
 
 /**
  * Error thrown when a Plunk API request fails.
@@ -81,7 +82,7 @@ class PlunkHttpClient {
       reject: async (response, attempt) => {
         let errorBody;
         try {
-          errorBody = await response.text();
+          errorBody = await readText(response);
         } catch {
           errorBody = 'Failed to read error response';
         }
@@ -143,7 +144,7 @@ class PlunkHttpClient {
    */
   async parseResponse(response) {
     try {
-      const data = await response.json();
+      const data = await readJson(response);
 
       // Validate response structure
       if (typeof data !== 'object' || data === null) {
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index 56c9128..b81d403 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { readText } = require('../internal/body.js');
 
 /**
  * Error thrown when a Resend API request fails.
@@ -119,7 +120,7 @@ class ResendHttpClient {
       timeoutMs: this.config.timeout,
       send: (signal) => this.fetchWithAuth(url, options, signal),
       read: async (response) => {
-        const text = await response.text();
+        const text = await readText(response);
         try {
           return JSON.parse(text);
         } catch (parseError) {
@@ -132,7 +133,7 @@ class ResendHttpClient {
         }
       },
       reject: async (response, attempt) => {
-        const text = await response.text();
+        const text = await readText(response);
         let errorMessage;
         try {
           errorMessage = JSON.parse(text).message;
diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
index 582d7a8..abaaf28 100644
--- a/src/sendgrid/http-client.js
+++ b/src/sendgrid/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { readText } = require('../internal/body.js');
 
 /**
  * HTTP client wrapper for SendGrid API requests.
@@ -54,7 +55,7 @@ class SendGridHttpClient {
       timeoutMs: this.config.timeout,
       send: (signal) => this.fetchWithAuth(url, options, signal),
       read: async (response, attempt) => {
-        const text = await response.text();
+        const text = await readText(response);
         // SendGrid returns 202 for successful sends
         if (response.status !== 202) throw createSendGridApiError(response, text, attempt);
         return {
@@ -64,7 +65,7 @@ class SendGridHttpClient {
         };
       },
       reject: async (response, attempt) =>
-        createSendGridApiError(response, await response.text(), attempt),
+        createSendGridApiError(response, await readText(response), attempt),
       createTimeoutError: () =>
         new Error(`SendGrid API request timed out after ${this.config.timeout} ms.`),
       finalError: (error, attempts) =>
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index c7f193f..6add011 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -4,6 +4,7 @@
 const { createHash, createHmac } = require('node:crypto');
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { readText } = require('../internal/body.js');
 
 class SesHttpClient {
   config;
@@ -44,7 +45,7 @@ class SesHttpClient {
       timeoutMs: this.config.timeout,
       send: (signal) => this.fetchWithAuth(url, options, signal),
       read: async (response, attempt) => {
-        const text = await response.text();
+        const text = await readText(response);
         if (response.status !== 200) throw createSesApiError(response, text, attempt);
         return {
           statusCode: response.status,
@@ -53,7 +54,7 @@ class SesHttpClient {
         };
       },
       reject: async (response, attempt) =>
-        createSesApiError(response, await response.text(), attempt),
+        createSesApiError(response, await readText(response), attempt),
       createTimeoutError: () =>
         new Error(`SES API request timed out after ${this.config.timeout} ms.`),
       finalError: (error, attempts) =>
diff --git a/src/smtp/oauth2.js b/src/smtp/oauth2.js
index 1c630c1..3fef173 100644
--- a/src/smtp/oauth2.js
+++ b/src/smtp/oauth2.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/smtp/src/oauth2.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { readText } = require('../internal/body.js');
+
 /**
  * An error thrown when SMTP authentication fails, including OAuth 2.0 token
  * acquisition and SASL exchange failures.
@@ -345,7 +347,7 @@ class OAuth2TokenManager {
       });
       // Read the body under the same timeout: an endpoint that returns headers
       // but stalls on the body must not leave `pending` unresolved forever.
-      text = await response.text();
+      text = await readText(response);
     } catch (cause) {
       throw new SmtpAuthError(
         `Failed to request an OAuth 2.0 access token from ` +
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index aea2e1e..9dc4b56 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -52,13 +52,15 @@ const providers = [
 ];
 
 // A 2xx whose body cannot be read: the connection broke after the headers.
-const unreadable = (status) => {
-  const response = new Response(null, { status });
-  const broken = () => Promise.reject(new Error('Connection reset while reading the body.'));
-  Object.defineProperty(response, 'text', { value: broken });
-  Object.defineProperty(response, 'json', { value: broken });
-  return response;
-};
+const unreadable = (status) =>
+  new Response(
+    new ReadableStream({
+      pull(controller) {
+        controller.error(new Error('Connection reset while reading the body.'));
+      },
+    }),
+    { status },
+  );
 
 test('Delivery: a 2xx with an unreadable body is sent once, of unknown delivery', async (t) => {
   for (const [name, status, create] of providers) {
@@ -90,17 +92,17 @@ test('Delivery: Plunk refusing in a 200 is sent once, a definite failure', async
   assert.match(receipt.errorMessages[0], /Sender not verified/);
 });
 
-// A 2xx whose body never ends, until the signal of the request aborts.
-const stalled = (status, signal) => {
-  const response = new Response(null, { status });
-  const hang = () =>
-    new Promise((_resolve, reject) => {
-      signal.addEventListener('abort', () => reject(signal.reason), { once: true });
-    });
-  Object.defineProperty(response, 'text', { value: hang });
-  Object.defineProperty(response, 'json', { value: hang });
-  return response;
-};
+// A 2xx whose body never ends, until the signal of the request aborts, as
+// fetch errors the body of an aborted request.
+const stalled = (status, signal) =>
+  new Response(
+    new ReadableStream({
+      start(controller) {
+        signal.addEventListener('abort', () => controller.error(signal.reason), { once: true });
+      },
+    }),
+    { status },
+  );
 
 test(
   'Delivery: the timeout covers a body that never ends, of unknown delivery',
@@ -184,3 +186,23 @@ test('Delivery: a provider refuses to send its credentials over plain HTTP', ()
   const local = new ResendTransport({ apiKey: 'key', baseUrl: 'http://localhost:8080' });
   assert.strictEqual(local.config.baseUrl, 'http://localhost:8080');
 });
+
+test('Delivery: a 2xx body longer than 4 MiB is refused, of unknown delivery', async (t) => {
+  for (const [name, status, create] of providers) {
+    t.mock.method(globalThis, 'fetch', async () => {
+      let sentBytes = 0;
+      const body = new ReadableStream({
+        pull(controller) {
+          if (sentBytes > 5 * 1024 * 1024) controller.close();
+          else controller.enqueue(new Uint8Array(65536).fill(0x20));
+          sentBytes += 65536;
+        },
+      });
+      return new Response(body, { status });
+    });
+    const receipt = await create().send(message());
+    t.mock.restoreAll();
+    assert.strictEqual(receipt.deliveryUnknown, true, name);
+    assert.match(receipt.errorMessages[0], /exceeds 4194304 bytes/, name);
+  }
+});
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index 81598a4..001fe33 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -224,3 +224,41 @@ test('Internal: a provider URL is HTTPS, or plain HTTP only to a loopback host',
     assert.throws(() => checkSecureUrl(url, 'baseUrl'), TypeError, url);
   }
 });
+
+const { readJson, readText } = require('../../src/internal/body.js');
+
+// A body of `chunks` chunks of `size` bytes, counting how many were pulled.
+const counted = (chunks, size) => {
+  let pulled = 0;
+  const stream = new ReadableStream({
+    pull(controller) {
+      if (pulled === chunks) {
+        controller.close();
+        return;
+      }
+      pulled++;
+      controller.enqueue(new Uint8Array(size).fill(0x61));
+    },
+  });
+  return { stream, pulled: () => pulled };
+};
+
+test('Internal: a body is read within its bound, as text or JSON', async () => {
+  const split = new TextEncoder().encode('{"name":"Дуже"}');
+  const body = new ReadableStream({
+    start(controller) {
+      controller.enqueue(split.subarray(0, 11));
+      controller.enqueue(split.subarray(11));
+      controller.close();
+    },
+  });
+  assert.deepStrictEqual(await readJson(new Response(body)), { name: 'Дуже' });
+  assert.strictEqual(await readText(new Response(null)), '');
+
+  const long = counted(100, 1024);
+  await assert.rejects(readText(new Response(long.stream), 10 * 1024), RangeError);
+  assert.ok(long.pulled() < 20, String(long.pulled()));
+
+  const declared = new Response('small', { headers: { 'Content-Length': '999999999' } });
+  await assert.rejects(readText(declared), RangeError);
+});
diff --git a/tests/unit/jmap-http-client.test.js b/tests/unit/jmap-http-client.test.js
index 0701f82..4595607 100644
--- a/tests/unit/jmap-http-client.test.js
+++ b/tests/unit/jmap-http-client.test.js
@@ -240,19 +240,16 @@ test('caller cancellation clears the retry backoff', async () => {
   const controller = new AbortController();
   let calls = 0;
   let abortedAt = 0;
+  // Changed after the port: the body is read from its stream rather than
+  // through response.text(), so the abort is scheduled from fetch, to land
+  // in the backoff that follows the 503.
   globalThis.fetch = () => {
     calls++;
-    const response = new Response('Unavailable.', { status: 503 });
-    const text = response.text.bind(response);
-    response.text = async () => {
-      const body = await text();
-      setTimeout(() => {
-        abortedAt = Date.now();
-        controller.abort('stop retry');
-      }, 0);
-      return body;
-    };
-    return Promise.resolve(response);
+    setTimeout(() => {
+      abortedAt = Date.now();
+      controller.abort('stop retry');
+    }, 20);
+    return Promise.resolve(new Response('Unavailable.', { status: 503 }));
   };
   try {
     const client = new JmapHttpClient(
diff --git a/tests/unit/maileroo-transport.test.js b/tests/unit/maileroo-transport.test.js
index d9d86c8..35628a1 100644
--- a/tests/unit/maileroo-transport.test.js
+++ b/tests/unit/maileroo-transport.test.js
@@ -385,26 +385,25 @@ describe('MailerooTransport - send', { concurrency: false }, () => {
   it('keeps request timeouts active while reading response bodies', async () => {
     await withMockedFetch(
       (_url, init) => {
-        const response = new Response(null, {
-          status: 200,
-          headers: { 'Content-Type': 'application/json' },
-        });
-        Object.defineProperty(response, 'text', {
-          value: () =>
-            new Promise((_resolve, reject) => {
-              init?.signal?.addEventListener(
-                'abort',
-                () => {
-                  reject(new DOMException('The operation was aborted.', 'AbortError'));
-                },
-                { once: true },
-              );
-              setTimeout(() => {
-                reject(new Error('Body read was not aborted.'));
-              }, 50);
-            }),
+        // Changed after the port: the body is read from its stream rather
+        // than through response.text(), so the stream is what stalls.
+        const body = new ReadableStream({
+          start(controller) {
+            init?.signal?.addEventListener(
+              'abort',
+              () => {
+                controller.error(new DOMException('The operation was aborted.', 'AbortError'));
+              },
+              { once: true },
+            );
+            setTimeout(() => {
+              controller.error(new Error('Body read was not aborted.'));
+            }, 50);
+          },
         });
-        return Promise.resolve(response);
+        return Promise.resolve(
+          new Response(body, { status: 200, headers: { 'Content-Type': 'application/json' } }),
+        );
       },
       async () => {
         const transport = new MailerooTransport({

From 9e05ce2823363a9af7e0cea0d4de7ad3b9532e31 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:24:44 +0300
Subject: [PATCH 054/158] fix: keep the cause of a provider error

Once retries were spent, ./ses, ./resend, ./sendgrid, ./mailgun and
./plunk rewrapped the last failure in their API error with its message
only, and the errors for a body that was not JSON did the same, under
`// oxlint-disable-next-line preserve-caught-error -- upstream`. A
`TypeError: fetch failed` so lost the refused connection or the rejected
certificate behind it, which tells a configuration error from an outage,
and a request that never left from one that may have arrived.

The provider errors take an options argument, passed to Error, and every
rewrap keeps the failure as its cause; the four suppressions go away.
JmapApiError already did.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                  |  5 +++++
 CLAUDE.md                     |  4 ++++
 src/lettermint/http-client.js |  1 +
 src/maileroo/http-client.js   |  1 +
 src/mailgun/http-client.js    |  9 +++++----
 src/mailgun/index.d.ts        |  1 +
 src/mailtrap/http-client.js   |  1 +
 src/plunk/http-client.js      | 10 +++++-----
 src/resend/http-client.js     |  9 +++++----
 src/resend/index.d.ts         |  1 +
 src/sendgrid/http-client.js   |  9 ++++++---
 src/sendgrid/index.d.ts       |  1 +
 src/ses/http-client.js        |  8 +++++---
 tests/unit/delivery.test.js   | 19 +++++++++++++++++++
 14 files changed, 60 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 231840d..7631884 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -139,6 +139,11 @@ fixed ones below.
   the OAuth2 token request of `./smtp` read a response whole, however long, so a broken or
   hostile endpoint could fill the memory of the sender. A longer body is refused, by its
   `Content-Length` or as it streams; after a 2xx, that is an unknown delivery.
+- **Provider errors keep their cause** (an upstream bug): once retries were spent, `SesApiError`,
+  `ResendApiError`, `SendGridApiError`, `MailgunApiError` and `PlunkApiError` rewrapped the last
+  failure without it, so `fetch failed` lost the refused connection or the certificate error
+  behind it, and so did the errors for a body that was not JSON. They keep it as `cause`, and
+  their constructors take an `options` argument with it.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 3ebf4d4..a4f2e5f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -227,6 +227,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 34. every HTTP provider, jmap and the OAuth2 token request: a response body was read whole,
     however long, before anything looked at it. `readText`/`readJson` (`src/internal/body.js`)
     read it from its stream and refuse one over 4 MiB, by its `Content-Length` or as it comes.
+35. ses, resend, sendgrid, mailgun, plunk, mailtrap, maileroo, lettermint: errors rewrapped once
+    retries were spent, or for a body that was not JSON, dropped their cause, so `fetch failed`
+    lost the ECONNREFUSED or certificate error behind it. Each keeps it as `cause`; the provider
+    errors take an `options` argument for it.
 
 ## Repository layout
 
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index fbfb741..8ec3729 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -114,6 +114,7 @@ class LettermintHttpClient {
             `Invalid JSON response from Lettermint API: ${
               error instanceof Error ? error.message : String(error)
             }.`,
+            { cause: error },
           );
         }
       },
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index cfa21cf..463ee19 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -174,6 +174,7 @@ const parseResponse = (text) => {
       `Invalid JSON response from Maileroo API: ${
         error instanceof Error ? error.message : String(error)
       }.`,
+      { cause: error },
     );
   }
 };
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index 9192393..41de0f4 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -57,9 +57,9 @@ class MailgunHttpClient {
         } catch (jsonError) {
           // This handles cases where the request was successful (e.g., 2xx status)
           // but the response body is not valid JSON.
-          // oxlint-disable-next-line preserve-caught-error -- upstream
           throw new Error(
             `Successfully received response but failed to parse JSON: ${jsonError.message}`,
+            { cause: jsonError },
           );
         }
       },
@@ -91,7 +91,7 @@ class MailgunHttpClient {
       finalError: (error, attempts) =>
         error instanceof MailgunApiError
           ? error
-          : new MailgunApiError(error.message, undefined, undefined, attempts),
+          : new MailgunApiError(error.message, undefined, undefined, attempts, { cause: error }),
     });
   }
 
@@ -147,9 +147,10 @@ class MailgunApiError extends Error {
    * @param statusCode HTTP status code returned by Mailgun.
    * @param retryAfterMilliseconds Retry delay from the response.
    * @param attempts Number of attempts made before this error.
+   * @param options The cause of the error, such as the failure of `fetch`.
    */
-  constructor(message, statusCode, retryAfterMilliseconds, attempts) {
-    super(message);
+  constructor(message, statusCode, retryAfterMilliseconds, attempts, options) {
+    super(message, options);
     this.name = 'MailgunApiError';
     this.statusCode = statusCode;
     this.retryAfterMilliseconds = retryAfterMilliseconds;
diff --git a/src/mailgun/index.d.ts b/src/mailgun/index.d.ts
index 651a75a..e941698 100644
--- a/src/mailgun/index.d.ts
+++ b/src/mailgun/index.d.ts
@@ -266,5 +266,6 @@ export declare class MailgunApiError extends Error {
     statusCode?: number,
     retryAfterMilliseconds?: number,
     attempts?: number,
+    options?: { readonly cause?: unknown },
   );
 }
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index 64e54fb..7cd5a7c 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -146,6 +146,7 @@ class MailtrapHttpClient {
             `Invalid JSON response from Mailtrap API: ${
               error instanceof Error ? error.message : String(error)
             }.`,
+            { cause: error },
           );
         }
       },
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index 71a9b02..a7d3be3 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -32,8 +32,8 @@ class PlunkApiError extends Error {
    * @param retryAfterMilliseconds Retry delay from the response.
    * @param attempts Number of attempts made before this error.
    */
-  constructor(message, statusCode, retryAfterMilliseconds, attempts) {
-    super(message);
+  constructor(message, statusCode, retryAfterMilliseconds, attempts, options) {
+    super(message, options);
     this.name = 'PlunkApiError';
     this.statusCode = statusCode;
     this.retryAfterMilliseconds = retryAfterMilliseconds;
@@ -105,8 +105,9 @@ class PlunkHttpClient {
               error.statusCode,
               error.retryAfterMilliseconds,
               attempts,
+              { cause: error.cause },
             )
-          : new PlunkApiError(error.message, undefined, undefined, attempts),
+          : new PlunkApiError(error.message, undefined, undefined, attempts, { cause: error }),
     });
   }
 
@@ -174,8 +175,7 @@ class PlunkHttpClient {
       };
     } catch (error) {
       if (error instanceof SyntaxError) {
-        // oxlint-disable-next-line preserve-caught-error -- upstream
-        throw new Error('Invalid JSON response from Plunk API');
+        throw new Error('Invalid JSON response from Plunk API', { cause: error });
       }
       throw error;
     }
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index b81d403..99a1216 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -31,9 +31,10 @@ class ResendApiError extends Error {
    * @param statusCode HTTP status code returned by Resend.
    * @param retryAfterMilliseconds Retry delay from the response.
    * @param attempts Number of attempts made before this error.
+   * @param options The cause of the error, such as the failure of `fetch`.
    */
-  constructor(message, statusCode, retryAfterMilliseconds, attempts) {
-    super(message);
+  constructor(message, statusCode, retryAfterMilliseconds, attempts, options) {
+    super(message, options);
     this.name = 'ResendApiError';
     this.statusCode = statusCode;
     this.retryAfterMilliseconds = retryAfterMilliseconds;
@@ -124,11 +125,11 @@ class ResendHttpClient {
         try {
           return JSON.parse(text);
         } catch (parseError) {
-          // oxlint-disable-next-line preserve-caught-error -- upstream
           throw new Error(
             `Invalid JSON response from Resend API: ${
               parseError instanceof Error ? parseError.message : String(parseError)
             }`,
+            { cause: parseError },
           );
         }
       },
@@ -157,7 +158,7 @@ class ResendHttpClient {
       finalError: (error, attempts) =>
         error instanceof ResendApiError
           ? error
-          : new ResendApiError(error.message, undefined, undefined, attempts),
+          : new ResendApiError(error.message, undefined, undefined, attempts, { cause: error }),
     });
   }
 
diff --git a/src/resend/index.d.ts b/src/resend/index.d.ts
index 1da6481..9b59484 100644
--- a/src/resend/index.d.ts
+++ b/src/resend/index.d.ts
@@ -270,6 +270,7 @@ declare class ResendApiError extends Error {
     statusCode?: number,
     retryAfterMilliseconds?: number,
     attempts?: number,
+    options?: { readonly cause?: unknown },
   );
 }
 /**
diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
index abaaf28..3c304b4 100644
--- a/src/sendgrid/http-client.js
+++ b/src/sendgrid/http-client.js
@@ -71,7 +71,9 @@ class SendGridHttpClient {
       finalError: (error, attempts) =>
         error instanceof SendGridApiError
           ? error
-          : new SendGridApiError(error.message, undefined, undefined, undefined, attempts),
+          : new SendGridApiError(error.message, undefined, undefined, undefined, attempts, {
+              cause: error,
+            }),
     });
   }
 
@@ -146,9 +148,10 @@ class SendGridApiError extends Error {
    * @param errors Provider-supplied SendGrid error details.
    * @param retryAfterMilliseconds Retry delay from the response.
    * @param attempts Number of attempts made before this error.
+   * @param options The cause of the error, such as the failure of `fetch`.
    */
-  constructor(message, statusCode, errors, retryAfterMilliseconds, attempts) {
-    super(message);
+  constructor(message, statusCode, errors, retryAfterMilliseconds, attempts, options) {
+    super(message, options);
     this.name = 'SendGridApiError';
     this.statusCode = statusCode;
     this.errors = errors;
diff --git a/src/sendgrid/index.d.ts b/src/sendgrid/index.d.ts
index 9852433..b138761 100644
--- a/src/sendgrid/index.d.ts
+++ b/src/sendgrid/index.d.ts
@@ -271,5 +271,6 @@ export declare class SendGridApiError extends Error {
     }>,
     retryAfterMilliseconds?: number,
     attempts?: number,
+    options?: { readonly cause?: unknown },
   );
 }
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index 6add011..575d352 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -60,7 +60,9 @@ class SesHttpClient {
       finalError: (error, attempts) =>
         error instanceof SesApiError
           ? error
-          : new SesApiError(error.message, undefined, undefined, undefined, attempts),
+          : new SesApiError(error.message, undefined, undefined, undefined, attempts, {
+              cause: error,
+            }),
     });
   }
 
@@ -221,8 +223,8 @@ class SesApiError extends Error {
   retryAfterMilliseconds;
   attempts;
 
-  constructor(message, statusCode, errors, retryAfterMilliseconds, attempts) {
-    super(message);
+  constructor(message, statusCode, errors, retryAfterMilliseconds, attempts, options) {
+    super(message, options);
     this.name = 'SesApiError';
     this.statusCode = statusCode;
     this.errors = errors;
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index 9dc4b56..b98dc0c 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -206,3 +206,22 @@ test('Delivery: a 2xx body longer than 4 MiB is refused, of unknown delivery', a
     assert.match(receipt.errorMessages[0], /exceeds 4194304 bytes/, name);
   }
 });
+
+test('Delivery: the failure of fetch stays the cause of the provider error', async (t) => {
+  const refused = new TypeError('fetch failed', {
+    cause: Object.assign(new Error('connect ECONNREFUSED'), { code: 'ECONNREFUSED' }),
+  });
+  t.mock.method(globalThis, 'fetch', async () => {
+    throw refused;
+  });
+  for (const [name, , create] of providers) {
+    const body = name === 'Mailgun' ? new FormData() : {};
+    const error = await create({ retries: 0 })
+      .httpClient.sendMessage(body, undefined)
+      .catch((caught) => caught);
+    assert.ok(error instanceof Error, name);
+    let cause = error;
+    while (cause !== refused && cause?.cause != null) cause = cause.cause;
+    assert.strictEqual(cause, refused, `${name}: ${error.name}`);
+  }
+});

From 095fc6cd1fc2329b68a1ec2f85d963e34e5cc238 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:26:42 +0300
Subject: [PATCH 055/158] fix(core): classify a failure by its status and code
 before its words

classifyReceiptError looked for status codes as substrings of the message:
"Message size 4013 octets exceeds the limit" held a 401 and was an
authentication error, and "5000 ms" held a 500. It also ignored what an
error carries: the statusCode of an HTTP error, and the system code behind
`TypeError: fetch failed`, so a certificate rejected by TLS was a retryable
network error.

It now classifies by statusCode first (as classifyHttpStatus, with the code
http.<status>), then by the first code along the chain of causes (a refused
connection or an unknown host is network, ETIMEDOUT and undici's timeouts
are timeout, a certificate error is a configuration error that is not
retried), and only then by the words of the message, where a status code
counts as a whole number.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  6 ++++
 CLAUDE.md               |  4 +++
 index.d.ts              |  5 ++-
 src/core/receipt.js     | 72 +++++++++++++++++++++++++++++++++++------
 tests/unit/core.test.js | 22 +++++++++++++
 5 files changed, 98 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7631884..b079b5d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -144,6 +144,12 @@ fixed ones below.
   failure without it, so `fetch failed` lost the refused connection or the certificate error
   behind it, and so did the errors for a body that was not JSON. They keep it as `cause`, and
   their constructors take an `options` argument with it.
+- **`classifyReceiptError` classifies by structure before words** (an upstream bug): it looked
+  for status codes anywhere in the message, so `Message size 4013 octets exceeds` was an
+  authentication error, and it ignored the `statusCode` of an HTTP error and the system code
+  behind `fetch failed`. It now classifies by `statusCode`, then by the code along the causes
+  (a refused connection or a timeout retryable, a rejected TLS certificate a configuration
+  error that is not), and only then by the words of the message, status codes as whole numbers.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index a4f2e5f..5a0a1a5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -231,6 +231,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     retries were spent, or for a body that was not JSON, dropped their cause, so `fetch failed`
     lost the ECONNREFUSED or certificate error behind it. Each keeps it as `cause`; the provider
     errors take an `options` argument for it.
+36. core: `classifyReceiptError` read status codes as substrings of the message ("4013 octets"
+    was `auth`, "5000 ms" a server error) and ignored the `statusCode` and the system `code` of
+    the error. It classifies by `statusCode`, then by the code along the causes (a rejected
+    certificate is a non-retryable configuration error), then by words, numbers as whole words.
 
 ## Repository layout
 
diff --git a/index.d.ts b/index.d.ts
index c909419..fab9c83 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -975,7 +975,10 @@ export interface CreateFailedReceiptOptions<
  */
 export declare function classifyHttpStatus(statusCode: number): ReceiptErrorClassification;
 /**
- * Classifies an arbitrary delivery failure.
+ * Classifies an arbitrary delivery failure: by the HTTP `statusCode` it
+ * carries, then by the system `code` along its causes (a refused connection,
+ * a timeout, a rejected certificate), and only then by the words of its
+ * message, where a status code counts as a whole number only.
  *
  * @param error The error to classify.
  * @returns The receipt error category, retryability, and default code.
diff --git a/src/core/receipt.js b/src/core/receipt.js
index ce3357f..8a2f3ec 100644
--- a/src/core/receipt.js
+++ b/src/core/receipt.js
@@ -29,13 +29,68 @@ const classifyHttpStatus = (statusCode) => {
   return { category: 'unknown', retryable: false };
 };
 
+// System and undici codes of a failure without a response.
+const TIMEOUT_CODES = new Set([
+  'ETIMEDOUT',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_HEADERS_TIMEOUT',
+  'UND_ERR_BODY_TIMEOUT',
+]);
+const NETWORK_CODES = new Set([
+  'ECONNREFUSED',
+  'ECONNRESET',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'EPIPE',
+  'UND_ERR_SOCKET',
+]);
+
+// Status codes in a message count as whole numbers only: "4013 octets" holds
+// no 401, nor "5000 ms" a 500.
+const hasNumber = (text, pattern) => pattern.test(text);
+const AUTH_STATUS = /\b(?:401|403)\b/;
+const RATE_LIMIT_STATUS = /\b429\b/;
+const VALIDATION_STATUS = /\b(?:400|422)\b/;
+const UNAVAILABLE_STATUS = /\b503\b/;
+const SERVER_ERROR_STATUS = /\b(?:500|502)\b/;
+
+// The first `code` along the chain of causes, as `fetch failed` keeps the
+// socket error behind it.
+const findErrorCode = (error) => {
+  let current = error;
+  for (let depth = 0; depth < 4 && current != null && typeof current === 'object'; depth++) {
+    if (typeof current.code === 'string') return current.code;
+    current = current.cause;
+  }
+  return undefined;
+};
+
 /**
- * Classifies an arbitrary delivery failure.
+ * Classifies a failure: by the HTTP status it carries, then by the system
+ * code along its causes, and only then by the words of its message.
  *
  * @param error The error to classify.
- * @returns The receipt error category, retryability, and default code.
+ * @returns The category, retryability and default code.
  */
 const classifyReceiptError = (error) => {
+  const statusCode = error != null && typeof error === 'object' ? error.statusCode : undefined;
+  if (Number.isInteger(statusCode)) {
+    return { ...classifyHttpStatus(statusCode), code: `http.${statusCode}` };
+  }
+  const errorCode = findErrorCode(error);
+  if (TIMEOUT_CODES.has(errorCode)) {
+    return { category: 'timeout', retryable: true, code: 'timeout' };
+  }
+  if (NETWORK_CODES.has(errorCode)) {
+    return { category: 'network', retryable: true, code: 'network' };
+  }
+  // A certificate refused during the TLS handshake will not pass on a retry.
+  if (typeof errorCode === 'string' && errorCode.includes('CERT')) {
+    return { category: 'configuration', retryable: false, code: 'configuration' };
+  }
+
   const message = getStringProperty(error, 'message') ?? String(error);
   const name = getStringProperty(error, 'name') ?? '';
   const text = `${name} ${message}`.toLowerCase();
@@ -66,8 +121,7 @@ const classifyReceiptError = (error) => {
     text.includes('forbidden') ||
     text.includes('invalid api key') ||
     text.includes('invalid token') ||
-    text.includes('401') ||
-    text.includes('403')
+    hasNumber(text, AUTH_STATUS)
   ) {
     return { category: 'auth', retryable: false, code: 'auth' };
   }
@@ -77,7 +131,7 @@ const classifyReceiptError = (error) => {
     text.includes('too many requests') ||
     text.includes('quota') ||
     text.includes('throttle') ||
-    text.includes('429')
+    hasNumber(text, RATE_LIMIT_STATUS)
   ) {
     return {
       category: 'rate-limit',
@@ -90,8 +144,7 @@ const classifyReceiptError = (error) => {
     text.includes('malformed') ||
     text.includes('validation') ||
     text.includes('bad request') ||
-    text.includes('400') ||
-    text.includes('422')
+    hasNumber(text, VALIDATION_STATUS)
   ) {
     return { category: 'validation', retryable: false, code: 'validation' };
   }
@@ -107,7 +160,7 @@ const classifyReceiptError = (error) => {
   if (
     text.includes('service unavailable') ||
     text.includes('temporarily unavailable') ||
-    text.includes('503')
+    hasNumber(text, UNAVAILABLE_STATUS)
   ) {
     return {
       category: 'service-unavailable',
@@ -118,8 +171,7 @@ const classifyReceiptError = (error) => {
   if (
     text.includes('internal server error') ||
     text.includes('bad gateway') ||
-    text.includes('500') ||
-    text.includes('502')
+    hasNumber(text, SERVER_ERROR_STATUS)
   ) {
     return {
       category: 'server-error',
diff --git a/tests/unit/core.test.js b/tests/unit/core.test.js
index d45a534..f711e49 100644
--- a/tests/unit/core.test.js
+++ b/tests/unit/core.test.js
@@ -290,3 +290,25 @@ test('Receipt: a Retry-After longer than a day is read as a day', () => {
   assert.strictEqual(parseRetryAfter('Wed, 21 Oct 2099 07:28:00 GMT', now), dayMs);
   assert.strictEqual(parseRetryAfter('Fri, 16 Oct 2026 00:01:00 GMT', now), 60_000);
 });
+
+test('Receipt: a failure is classified by its status, then its code, then its words', () => {
+  const classify = (error) => classifyReceiptError(error).category;
+  assert.strictEqual(classify(new Error('Message size 4013 octets exceeds the limit')), 'unknown');
+  assert.strictEqual(classify(new Error('Server answered 401')), 'auth');
+  assert.strictEqual(classify(new Error('Waited 5000 ms')), 'unknown');
+  const limited = Object.assign(new Error('Something went wrong'), { statusCode: 429 });
+  assert.deepStrictEqual(classifyReceiptError(limited), {
+    category: 'rate-limit',
+    retryable: true,
+    code: 'http.429',
+  });
+  const caused = (code) =>
+    new TypeError('fetch failed', { cause: Object.assign(new Error(code), { code }) });
+  assert.strictEqual(classify(caused('ECONNREFUSED')), 'network');
+  assert.strictEqual(classify(caused('ETIMEDOUT')), 'timeout');
+  assert.deepStrictEqual(classifyReceiptError(caused('CERT_HAS_EXPIRED')), {
+    category: 'configuration',
+    retryable: false,
+    code: 'configuration',
+  });
+});

From d2ade95116ff60f53084e0ceb3575fd3fd454cec Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:28:29 +0300
Subject: [PATCH 056/158] fix(ses): refuse a wrong authentication when the
 transport is made

An authentication of an unknown type, without its access key or secret
key, or a session without its token, was found only by getCredentials at
the first send, inside the retry loop, so it was retried like an outage,
with backoff, before the send failed. SesTransport now refuses it with a
TypeError when it is made; the flat test of an unknown type expects that.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md             |  3 +++
 CLAUDE.md                |  2 ++
 src/ses/ses-transport.js | 17 +++++++++++++++++
 tests/unit/ses.test.js   | 18 +++++++++++++-----
 4 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b079b5d..708db98 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -150,6 +150,9 @@ fixed ones below.
   behind `fetch failed`. It now classifies by `statusCode`, then by the code along the causes
   (a refused connection or a timeout retryable, a rejected TLS certificate a configuration
   error that is not), and only then by the words of the message, status codes as whole numbers.
+- **`./ses` refuses a wrong `authentication` when the transport is made** (an upstream bug): an
+  unknown type, a missing key or a session without its token failed only at the first send,
+  after the retries and their backoff.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 5a0a1a5..5f5f4a4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -235,6 +235,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     was `auth`, "5000 ms" a server error) and ignored the `statusCode` and the system `code` of
     the error. It classifies by `statusCode`, then by the code along the causes (a rejected
     certificate is a non-retryable configuration error), then by words, numbers as whole words.
+37. ses: an unsupported authentication type or missing keys surfaced at the first send, inside
+    the retry loop, which retried it like an outage. `SesTransport` refuses them when made.
 
 ## Repository layout
 
diff --git a/src/ses/ses-transport.js b/src/ses/ses-transport.js
index 6c2dd5f..8b4b027 100644
--- a/src/ses/ses-transport.js
+++ b/src/ses/ses-transport.js
@@ -58,6 +58,7 @@ class SesTransport {
    */
   constructor(config) {
     this.config = createSesConfig(config);
+    checkAuthentication(this.config.authentication);
     this.httpClient = new SesHttpClient(this.config);
   }
 
@@ -226,6 +227,22 @@ class SesTransport {
   }
 }
 
+// A wrong authentication is refused when the transport is made: found at the
+// first send, it was retried like an outage before it failed.
+const checkAuthentication = (authentication) => {
+  const type = authentication?.type;
+  if (type !== 'credentials' && type !== 'session') {
+    throw new TypeError(`Unsupported authentication type: ${type}`);
+  }
+  const isFilled = (value) => typeof value === 'string' && value !== '';
+  if (!isFilled(authentication.accessKeyId) || !isFilled(authentication.secretAccessKey)) {
+    throw new TypeError('SES authentication needs an accessKeyId and a secretAccessKey.');
+  }
+  if (type === 'session' && !isFilled(authentication.sessionToken)) {
+    throw new TypeError('SES session authentication needs its sessionToken.');
+  }
+};
+
 const createSesFailure = (message, error) => {
   if (error instanceof SesApiError) {
     return createFailedReceipt(message, {
diff --git a/tests/unit/ses.test.js b/tests/unit/ses.test.js
index c8e5da5..3403f30 100644
--- a/tests/unit/ses.test.js
+++ b/tests/unit/ses.test.js
@@ -45,11 +45,19 @@ test('SES: session credentials and custom headers are signed', async (t) => {
   assert.match(request.get('authorization'), /SignedHeaders=host;x-amz-date;x-amz-security-token/);
 });
 
-test('SES: an unknown authentication type fails the send', async () => {
-  const transport = new SesTransport({ authentication: { type: 'role' }, retries: 0 });
-  const receipt = await transport.send(message());
-  assert.strictEqual(receipt.successful, false);
-  assert.deepStrictEqual(receipt.errorMessages, ['Unsupported authentication type: role']);
+test('SES: a wrong authentication is refused when the transport is made', () => {
+  const wrong = [
+    { type: 'role' },
+    { type: 'credentials', accessKeyId: 'AKID' },
+    { type: 'session', accessKeyId: 'AKID', secretAccessKey: 'secret' },
+    undefined,
+  ];
+  for (const candidate of wrong) {
+    assert.throws(() => new SesTransport({ authentication: candidate }), TypeError);
+  }
+  assert.throws(() => new SesTransport({ authentication: { type: 'role' } }), {
+    message: 'Unsupported authentication type: role',
+  });
 });
 
 test('SES: HTTP and network failures become failed receipts', async (t) => {

From c6acb773389b5d63cf218122fd9be5ee64229fda Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:30:04 +0300
Subject: [PATCH 057/158] fix: encode credentials outside Latin-1 as UTF-8

SMTP AUTH PLAIN and LOGIN, and the Basic authentication of ./jmap (its
client, blob and raw uploads) and ./mailgun, encoded credentials with btoa,
which throws an InvalidCharacterError on any character outside Latin-1, so
a Cyrillic or Greek user name or password could never authenticate; in the
HTTP clients the error was even retried. They are now encoded as UTF-8 with
Buffer, as RFC 4616 (PLAIN) and RFC 7617 (Basic, charset UTF-8) expect.

Known upstream bug 4, recorded in CLAUDE.md and removed from the known
issues page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  3 +++
 CLAUDE.md                   |  7 +++++--
 docs/guide/known-issues.md  |  2 --
 src/jmap/blob-uploader.js   |  4 +++-
 src/jmap/http-client.js     |  6 +++---
 src/jmap/raw-upload.js      |  3 ++-
 src/mailgun/http-client.js  |  3 ++-
 src/smtp/smtp-connection.js |  6 +++---
 tests/unit/jmap.test.js     | 17 +++++++++++++++
 tests/unit/smtp.test.js     | 41 +++++++++++++++++++++++++++++++++++++
 10 files changed, 79 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 708db98..47b7c74 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -153,6 +153,9 @@ fixed ones below.
 - **`./ses` refuses a wrong `authentication` when the transport is made** (an upstream bug): an
   unknown type, a missing key or a session without its token failed only at the first send,
   after the retries and their backoff.
+- **Credentials outside Latin-1 work** (known upstream bug 4): SMTP AUTH PLAIN and LOGIN and the
+  Basic authentication of `./jmap` and `./mailgun` encoded them with `btoa`, which throws on a
+  Cyrillic or accented character. They are encoded as UTF-8.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 5f5f4a4..20338fd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -128,8 +128,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 2. mailgun: an inline attachment is sent under its `filename`, not its `contentId`
    (`message-converter.js`), so a `cid:` in the HTML does not match it.
 3. `validateSsl` is accepted and never read (ses, resend, sendgrid, mailgun, mailtrap, plunk).
-4. SMTP AUTH PLAIN and LOGIN encode with `btoa`, which fails on non-Latin-1 credentials; so does
-   Basic auth in jmap and mailgun.
+4. (fixed, see 38) SMTP AUTH PLAIN and LOGIN encoded with `btoa`, which fails on non-Latin-1
+   credentials; so did Basic auth in jmap and mailgun.
 5. `cram-md5` is in the `SmtpAuth` type but not implemented.
 6. DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails.
 7. pool: `continueOnSuccess` is never read.
@@ -237,6 +237,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     certificate is a non-retryable configuration error), then by words, numbers as whole words.
 37. ses: an unsupported authentication type or missing keys surfaced at the first send, inside
     the retry loop, which retried it like an outage. `SesTransport` refuses them when made.
+38. smtp, jmap, mailgun (known bug 4): credentials went through `btoa`, which throws on any
+    character outside Latin-1, inside the retry loop for the HTTP ones. They are encoded as
+    UTF-8 with `Buffer`.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 937b8e6..5b6cb6b 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -16,13 +16,11 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 
 ## SMTP
 
-- AUTH PLAIN and LOGIN fail on credentials outside Latin-1.
 - `cram-md5` is in the `SmtpAuth` type but not implemented.
 
 ## HTTP providers and JMAP
 
 - `validateSsl` is accepted and never read (SES, Resend, SendGrid, Mailgun, Mailtrap, Plunk).
-- Basic authentication in JMAP and Mailgun fails on credentials outside Latin-1.
 - Mailgun sends an inline attachment under its file name rather than its `contentId`, so a
   `cid:` in the HTML does not match it.
 - Resend's `Idempotency-Key` comes from `Math.random`.
diff --git a/src/jmap/blob-uploader.js b/src/jmap/blob-uploader.js
index 51ae44d..9a1763b 100644
--- a/src/jmap/blob-uploader.js
+++ b/src/jmap/blob-uploader.js
@@ -4,6 +4,7 @@
 const { combineSignals } = require('../core/abort-signal.js');
 const { JmapApiError } = require('./errors.js');
 const { readJson, readText } = require('../internal/body.js');
+const { Buffer } = require('node:buffer');
 
 /**
  * Upload a blob to the JMAP server.
@@ -24,7 +25,8 @@ const uploadBlob = async (config, uploadUrl, accountId, blob, signal) => {
   if (config.bearerToken) {
     authHeader = `Bearer ${config.bearerToken}`;
   } else if (config.basicAuth) {
-    const credentials = btoa(`${config.basicAuth.username}:${config.basicAuth.password}`);
+    const { username, password } = config.basicAuth;
+    const credentials = Buffer.from(`${username}:${password}`).toString('base64');
     authHeader = `Basic ${credentials}`;
   } else {
     throw new Error('No authentication method configured');
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index 9ec088e..3663959 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -5,6 +5,7 @@ const { parseRetryAfter } = require('../core/receipt.js');
 const { JmapApiError } = require('./errors.js');
 const { isAbortError, requestWithRetry } = require('../internal/http.js');
 const { readJson, readText } = require('../internal/body.js');
+const { Buffer } = require('node:buffer');
 
 /**
  * HTTP client for JMAP API requests.
@@ -121,9 +122,8 @@ class JmapHttpClient {
     if (this.config.bearerToken) {
       headers.set('Authorization', `Bearer ${this.config.bearerToken}`);
     } else if (this.config.basicAuth) {
-      const credentials = btoa(
-        `${this.config.basicAuth.username}:${this.config.basicAuth.password}`,
-      );
+      const { username, password } = this.config.basicAuth;
+      const credentials = Buffer.from(`${username}:${password}`).toString('base64');
       headers.set('Authorization', `Basic ${credentials}`);
     }
 
diff --git a/src/jmap/raw-upload.js b/src/jmap/raw-upload.js
index d9ee80d..b3d1135 100644
--- a/src/jmap/raw-upload.js
+++ b/src/jmap/raw-upload.js
@@ -6,6 +6,7 @@ const { combineSignals } = require('../core/abort-signal.js');
 const { parseRetryAfter } = require('../core/receipt.js');
 const { JmapApiError } = require('./errors.js');
 const { readJson, readText } = require('../internal/body.js');
+const { Buffer } = require('node:buffer');
 
 /** Runs a raw operation with a progress-resettable deadline through response parsing. @internal */
 const rawOperation = async (timeout, operation, signal) => {
@@ -139,7 +140,7 @@ const uploadRawMessage = async (config, uploadUrl, accountId, plan, signal) => {
         } else if (config.basicAuth) {
           headers.set(
             'Authorization',
-            `Basic ${btoa(`${config.basicAuth.username}:${config.basicAuth.password}`)}`,
+            `Basic ${Buffer.from(`${config.basicAuth.username}:${config.basicAuth.password}`).toString('base64')}`,
           );
         }
       }
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index 41de0f4..ffada34 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -4,6 +4,7 @@
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
 const { readText } = require('../internal/body.js');
+const { Buffer } = require('node:buffer');
 
 /**
  * HTTP client wrapper for Mailgun API requests.
@@ -107,7 +108,7 @@ class MailgunHttpClient {
     const headers = new Headers(options.headers);
 
     // Add authentication header
-    const auth = btoa(`api:${this.config.apiKey}`);
+    const auth = Buffer.from(`api:${this.config.apiKey}`).toString('base64');
     headers.set('Authorization', `Basic ${auth}`);
 
     // Add custom headers from config
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index 5be9c73..9530e1c 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -808,7 +808,7 @@ class SmtpConnection {
 
   async authPlain(auth, signal) {
     const { user, pass } = auth;
-    const credentials = btoa(`\0${user}\0${pass}`);
+    const credentials = Buffer.from(`\0${user}\0${pass}`).toString('base64');
     const response = await this.sendCommand(`AUTH PLAIN ${credentials}`, signal);
 
     if (response.code !== 235) {
@@ -834,7 +834,7 @@ class SmtpConnection {
       );
     }
 
-    response = await this.sendCommand(btoa(user), signal);
+    response = await this.sendCommand(Buffer.from(user).toString('base64'), signal);
     if (response.code !== 334) {
       throw new SmtpAuthResponseError(
         `Username authentication failed: ${response.message}`,
@@ -844,7 +844,7 @@ class SmtpConnection {
       );
     }
 
-    response = await this.sendCommand(btoa(pass), signal);
+    response = await this.sendCommand(Buffer.from(pass).toString('base64'), signal);
     if (response.code !== 235) {
       throw new SmtpAuthResponseError(
         `Password authentication failed: ${response.message}`,
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index 8e6fcb1..9ed99ab 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -212,3 +212,20 @@ test('JMAP: a blob upload does not follow a redirect', async (t) => {
   await uploadBlob(config, 'https://jmap.example.com/upload/{accountId}', 'a1', new Blob(['a']));
   assert.deepStrictEqual(redirects, ['manual']);
 });
+
+test('JMAP: Basic authentication encodes credentials outside Latin-1 as UTF-8', async (t) => {
+  const authorizations = new Set();
+  serve(t);
+  const original = globalThis.fetch;
+  t.mock.method(globalThis, 'fetch', (input, init) => {
+    authorizations.add(new Headers(init.headers).get('Authorization'));
+    return original(input, init);
+  });
+  const receipt = await transport({
+    bearerToken: undefined,
+    basicAuth: { username: 'алекс', password: 'пароль-✓' },
+  }).send(message());
+  assert.strictEqual(receipt.successful, true, receipt.errorMessages?.join(' | '));
+  const expected = `Basic ${Buffer.from('алекс:пароль-✓').toString('base64')}`;
+  assert.deepStrictEqual([...authorizations], [expected]);
+});
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index a6ff975..9df54f8 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -404,3 +404,44 @@ test('SMTP: the OAuth2 token request does not follow a redirect', async () => {
   assert.strictEqual(await manager.getAccessToken(), 'token');
   assert.deepStrictEqual(redirects, ['manual']);
 });
+
+test('SMTP: AUTH PLAIN and LOGIN encode credentials outside Latin-1 as UTF-8', async () => {
+  const user = 'алекс@example.com';
+  const pass = 'пароль-ü-✓';
+  for (const method of ['plain', 'login']) {
+    const lines = [];
+    const reply = transaction((verb) =>
+      verb === 'EHLO' ? '250-localhost\r\n250 AUTH PLAIN LOGIN\r\n' : okReply(verb),
+    );
+    let loginStep = 0;
+    const { server, port } = await scripted((line, socket) => {
+      if (line.startsWith('AUTH PLAIN ')) {
+        lines.push(line.slice('AUTH PLAIN '.length));
+        socket.write('235 ok\r\n');
+      } else if (line === 'AUTH LOGIN') {
+        socket.write('334 VXNlcm5hbWU6\r\n');
+        loginStep = 1;
+      } else if (loginStep > 0) {
+        lines.push(line);
+        socket.write(loginStep++ === 1 ? '334 UGFzc3dvcmQ6\r\n' : '235 ok\r\n');
+        if (loginStep > 2) loginStep = 0;
+      } else {
+        reply(line, socket);
+      }
+    });
+    try {
+      const transport = new SmtpTransport({
+        host: '127.0.0.1',
+        port,
+        pool: false,
+        auth: { user, pass, method },
+      });
+      const receipt = await transport.send(message());
+      assert.strictEqual(receipt.successful, true, receipt.errorMessages?.join(' | '));
+      const decoded = lines.map((line) => Buffer.from(line, 'base64').toString('utf8'));
+      assert.deepStrictEqual(decoded, method === 'plain' ? [`\0${user}\0${pass}`] : [user, pass]);
+    } finally {
+      await stop(server);
+    }
+  }
+});

From a354c1b848a70698102e6cc68c093eb2fd0ec555 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:38:40 +0300
Subject: [PATCH 058/158] fix: do not resend an HTTP request that may have
 arrived

A timeout, a lost connection or a gateway timeout (504) before any usable
answer was retried by every HTTP provider, though the provider may already
have taken the request, so the message could be delivered once per
attempt. The roadmap's rule is that a provider without an idempotency key
leads to an unknown delivery, reconciled from events, never to a blind
retry.

requestWithRetry now treats such a failure as ambiguous, unless its causes
show that the connection was never made (a refused connection, an unknown
host, a rejected certificate, through isUnsentRequestError), and so does a
failure after a 2xx. An ambiguous failure of a plain send is thrown at once,
marked as of unknown delivery. A send with an idempotency key, which the
provider deduplicates (hasIdempotencyKey: ./resend and ./lettermint, which
always send one), is retried, and its last failure is marked if any attempt
was ambiguous. A read (isIdempotent: the JMAP queries) is retried and never
marked. ./mailtrap and ./jmap report the mark on every kind of failure.

Ported tests that pinned the retry of a network failure or a timeout, or a
retryable receipt for one, now expect an unknown delivery. An upstream bug,
recorded in CLAUDE.md and removed from the known issues page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                          |  7 ++++
 CLAUDE.md                             |  8 ++++-
 docs/guide/known-issues.md            |  3 --
 index.d.ts                            |  6 ++--
 src/internal/http.js                  | 44 ++++++++++++++++++------
 src/jmap/jmap-transport.js            |  1 +
 src/lettermint/http-client.js         |  2 ++
 src/mailtrap/mailtrap-transport.js    |  4 +++
 src/resend/http-client.js             |  2 ++
 tests/unit/delivery.test.js           | 31 +++++++++++++++--
 tests/unit/internal.test.js           | 48 +++++++++++++++++++++++++--
 tests/unit/maileroo-transport.test.js |  7 ++--
 tests/unit/mailgun-transport.test.js  | 11 ++++--
 tests/unit/mailtrap-transport.test.js |  8 +++++
 tests/unit/resend-transport.test.js   | 10 ++++--
 tests/unit/sendgrid-transport.test.js |  6 +++-
 16 files changed, 170 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 47b7c74..1151307 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -156,6 +156,13 @@ fixed ones below.
 - **Credentials outside Latin-1 work** (known upstream bug 4): SMTP AUTH PLAIN and LOGIN and the
   Basic authentication of `./jmap` and `./mailgun` encoded them with `btoa`, which throws on a
   Cyrillic or accented character. They are encoded as UTF-8.
+- **An HTTP provider no longer resends a request that may have arrived** (an upstream bug): a
+  timeout, a lost connection or a gateway timeout (504) before any usable answer was retried,
+  though the provider may have taken the request. Unless the failure shows that the connection
+  was never made (a refused connection, an unknown host, a rejected certificate), it is now an
+  unknown delivery, not retried, for `./ses`, `./sendgrid`, `./mailgun`, `./mailtrap`,
+  `./maileroo` and `./plunk`. `./resend` and `./lettermint`, which send an idempotency key that
+  the provider deduplicates, still retry, and report the last failure as of unknown delivery.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 20338fd..57ead7c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -195,7 +195,7 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     was retried, re-sending a message the provider had taken. Each client notes the 2xx
     (`isAccepted`) and throws `markDeliveryUnknown` (`src/internal/delivery-unknown.js`) instead
     of retrying; the transports report `deliveryUnknown`. Telling an unsent request from a sent
-    one on a timeout or a reset waits for the shared HTTP client (Phase B).
+    one on a timeout or a reset is 39.
 25. resend, plunk (known bug 9): the wait between retries ignored the `AbortSignal`, so an abort
     took effect only after the backoff. They use the abortable `sleep` of `src/internal/http.js`.
 26. lettermint: an abort during the wait between retries rejected with a new `AbortError`
@@ -240,6 +240,12 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 38. smtp, jmap, mailgun (known bug 4): credentials went through `btoa`, which throws on any
     character outside Latin-1, inside the retry loop for the HTTP ones. They are encoded as
     UTF-8 with `Buffer`.
+39. every HTTP provider: a timeout, a reset or a 504 before any usable answer was retried, and
+    the provider may already have taken the request. `requestWithRetry` treats such a failure as
+    ambiguous: unless the causes show a connection that was never made (`isUnsentRequestError`),
+    it is thrown as `deliveryUnknown` without a retry; a request with an idempotency key
+    (`hasIdempotencyKey`: resend, lettermint) is retried and only its last failure is marked; a
+    read (`isIdempotent`: jmap queries) is retried and never marked.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 5b6cb6b..3219397 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -26,9 +26,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 - Resend's `Idempotency-Key` comes from `Math.random`.
 - SES: custom and threading headers are not sent.
 - Plunk: an attachment that cannot be read is left out with a `console.warn`.
-- The HTTP providers retry a timeout or a reset that came before any answer, although the
-  request may have reached the provider; failures after a 2xx are already reported as
-  `deliveryUnknown` and not retried.
 - JMAP on Node 24: an authentication rejection (401) of a streamed request body (raw upload,
   import, raw submission) becomes a retryable network error, as Node's `fetch` reports it so.
 
diff --git a/index.d.ts b/index.d.ts
index fab9c83..547ae93 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -911,8 +911,10 @@ export type Receipt<TProviderId extends string = string> =
       readonly retryable?: boolean;
       /**
        * `true` when the transport cannot tell whether the message was
-       * accepted: the request or the message data went out, but no answer
-       * came back (a timeout or a closed connection after the end of `DATA`).
+       * accepted: the request or the message data went out, but no usable
+       * answer came back (a timeout or a lost connection after the request
+       * went out or after the end of `DATA`, a 2xx that could not be read, a
+       * gateway timeout).
        * Sending it again may deliver it twice, so such a receipt is never
        * retryable, `./retry` does not retry it and `./pool` does not pass it
        * to another transport; reconcile it from the provider's delivery
diff --git a/src/internal/http.js b/src/internal/http.js
index e3db8ed..9d522da 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -4,6 +4,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { markDeliveryUnknown } = require('./delivery-unknown.js');
+const { isUnsentRequestError } = require('./unsent.js');
 
 const isAbortError = (error) => error instanceof Error && error.name === 'AbortError';
 
@@ -107,9 +108,17 @@ const startDeadline = (timeoutMs, signal) => {
 
 /**
  * Sends a request with a deadline per attempt, retrying what the provider
- * says to retry.  A failure after a 2xx response is never retried: the
- * provider took the request, so it is thrown marked as of unknown delivery,
- * unless the request is idempotent.
+ * says to retry.
+ *
+ * A failure that leaves it unknown whether the provider took the request is
+ * ambiguous: a failure after a 2xx, a gateway timeout (504), and a failure
+ * without any response, unless its causes show that the connection was never
+ * made.  Sending the request again after one could deliver the message twice,
+ * so an ambiguous failure is thrown at once, marked as of unknown delivery.
+ * A request with an idempotency key (`hasIdempotencyKey`), which the provider
+ * deduplicates, is retried after one instead, and its last failure is marked
+ * if any attempt was ambiguous.  A read (`isIdempotent`) is retried with no
+ * marking at all.
  *
  * @param request What the provider passes in:
  * - `send(signal, attempt)`: one fetch, with the signal of the attempt;
@@ -126,8 +135,8 @@ const startDeadline = (timeoutMs, signal) => {
  *   by default the last failure;
  * - optional `wrapAccepted(error, attempts)`, `isAnswer(error)` (an error that
  *   is the provider's own answer in a 2xx, such as a refusal in its body,
- *   thrown as it is rather than as of unknown delivery), `isIdempotent`,
- *   `sleep`.
+ *   thrown as it is rather than as of unknown delivery), `hasIdempotencyKey`,
+ *   `isIdempotent`, `sleep`.
  * The deadline of an attempt lasts until its response is read, body
  * included, so a body that never ends cannot hold a send.  Between attempts
  * it waits at least the failure's `retryAfterMilliseconds`, the server's
@@ -138,13 +147,20 @@ const startDeadline = (timeoutMs, signal) => {
 const requestWithRetry = async (request) => {
   const signal = request.signal;
   const wait = request.sleep ?? sleep;
+  const isRead = request.isIdempotent === true;
+  const hasKey = request.hasIdempotencyKey === true;
+  let wasAmbiguous = false;
+  // The last failure, marked when an attempt left the delivery unknown.
+  const settle = (error) => (wasAmbiguous && !isRead ? markDeliveryUnknown(error) : error);
   for (let attempt = 0; ; attempt++) {
     signal?.throwIfAborted();
     const deadline = startDeadline(request.timeoutMs, signal);
+    let hasResponse = false;
     let isAccepted = false;
     let failure;
     try {
       const response = await request.send(deadline.signal, attempt);
+      hasResponse = true;
       isAccepted = response.ok;
       if (response.ok) return await request.read(response, attempt);
       failure = await request.reject(response, attempt);
@@ -157,17 +173,23 @@ const requestWithRetry = async (request) => {
     if (!(failure instanceof Error)) failure = new Error(String(failure));
 
     if (signal?.aborted) throw abortReason(signal);
-    if (isAccepted && request.isIdempotent !== true) {
-      if (request.isAnswer?.(failure) === true) throw failure;
-      const accepted = request.wrapAccepted?.(failure, attempt + 1) ?? failure;
-      throw markDeliveryUnknown(accepted);
+    if (isAccepted && request.isAnswer?.(failure) === true) throw settle(failure);
+    const isAmbiguous =
+      isAccepted || (hasResponse ? failure.statusCode === 504 : !isUnsentRequestError(failure));
+    if (isAmbiguous && !isRead) {
+      wasAmbiguous = true;
+      if (!hasKey) {
+        const wrapped = isAccepted ? request.wrapAccepted?.(failure, attempt + 1) : undefined;
+        throw markDeliveryUnknown(wrapped ?? request.finalError?.(failure, attempt + 1) ?? failure);
+      }
     }
-    if (!(request.isRetryable ?? isRetryableFailure)(failure)) throw failure;
+    const isRetryable = isAccepted || (request.isRetryable ?? isRetryableFailure)(failure);
+    if (!isRetryable) throw settle(failure);
     const retryAfterMs = Number.isFinite(failure.retryAfterMilliseconds)
       ? failure.retryAfterMilliseconds
       : 0;
     if (attempt >= request.retries || retryAfterMs > MAX_RETRY_AFTER_WAIT_MS) {
-      throw request.finalError?.(failure, attempt + 1) ?? failure;
+      throw settle(request.finalError?.(failure, attempt + 1) ?? failure);
     }
     const delayMs = (request.retryDelayMs ?? jitteredDelayMs)(attempt, failure);
     await wait(Math.max(delayMs, retryAfterMs), signal);
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index 35db502..f18667d 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -914,6 +914,7 @@ const createJmapFailure = (message, error, override = {}) => {
     category: override.category,
     code: override.code,
     retryable: override.retryable,
+    deliveryUnknown: isDeliveryUnknown(error),
   });
 };
 
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index 8ec3729..f56879c 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -104,6 +104,8 @@ class LettermintHttpClient {
       signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
+      // Lettermint deduplicates a repeated Idempotency-Key.
+      hasIdempotencyKey: idempotencyKey != null && idempotencyKey !== '',
       send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal, idempotencyKey),
       read: async (response) => {
         const text = await readText(response);
diff --git a/src/mailtrap/mailtrap-transport.js b/src/mailtrap/mailtrap-transport.js
index 7e12f95..6288780 100644
--- a/src/mailtrap/mailtrap-transport.js
+++ b/src/mailtrap/mailtrap-transport.js
@@ -11,6 +11,7 @@ const {
 } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
+const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
 
 const MAX_BATCH_SIZE = 500;
 
@@ -255,6 +256,7 @@ const createMailtrapFailure = (message, error) => {
 
   if (error instanceof MailtrapApiError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'mailtrap',
       statusCode: error.statusCode,
       retryAfterMilliseconds: error.retryAfterMilliseconds,
@@ -264,6 +266,7 @@ const createMailtrapFailure = (message, error) => {
 
   if (error instanceof MailtrapTimeoutError) {
     return createFailedReceipt(message, {
+      deliveryUnknown: isDeliveryUnknown(error),
       provider: 'mailtrap',
       category: 'timeout',
       code: 'timeout',
@@ -273,6 +276,7 @@ const createMailtrapFailure = (message, error) => {
   }
 
   return createFailedReceipt(message, {
+    deliveryUnknown: isDeliveryUnknown(error),
     provider: 'mailtrap',
     attempts: getErrorAttempts(error),
   });
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index 99a1216..c37ad3d 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -119,6 +119,8 @@ class ResendHttpClient {
       signal: options.signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
+      // Resend answers a repeated Idempotency-Key with its first answer.
+      hasIdempotencyKey: options.headers?.['Idempotency-Key'] != null,
       send: (signal) => this.fetchWithAuth(url, options, signal),
       read: async (response) => {
         const text = await readText(response);
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index b98dc0c..54074c1 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -21,7 +21,10 @@ const message = () =>
     content: { text: 'Hi' },
   });
 
-const options = { retries: 3 };
+// One retry: a provider that resends shows two requests, as Resend and Lettermint do with
+// the idempotency key they always send.
+const options = { retries: 1 };
+const expectedRequests = (name) => (name === 'Resend' || name === 'Lettermint' ? 2 : 1);
 const providers = [
   [
     'SES',
@@ -71,7 +74,7 @@ test('Delivery: a 2xx with an unreadable body is sent once, of unknown delivery'
     });
     const receipt = await create().send(message());
     t.mock.restoreAll();
-    assert.strictEqual(requests, 1, name);
+    assert.strictEqual(requests, expectedRequests(name), name);
     assert.strictEqual(receipt.successful, false, name);
     assert.strictEqual(receipt.deliveryUnknown, true, name);
     assert.strictEqual(receipt.retryable, false, name);
@@ -225,3 +228,27 @@ test('Delivery: the failure of fetch stays the cause of the provider error', asy
     assert.strictEqual(cause, refused, `${name}: ${error.name}`);
   }
 });
+
+test('Delivery: a lost request is not sent again without a key; a refused one is', async (t) => {
+  const failed = (code) =>
+    new TypeError('fetch failed', { cause: Object.assign(new Error(code), { code }) });
+  for (const [name, , create] of providers) {
+    for (const code of ['ECONNRESET', 'ECONNREFUSED']) {
+      let requests = 0;
+      t.mock.method(globalThis, 'fetch', async () => {
+        requests++;
+        throw failed(code);
+      });
+      const receipt = await create().send(message());
+      t.mock.restoreAll();
+      if (code === 'ECONNREFUSED') {
+        assert.strictEqual(requests, 2, `${name} ${code}`);
+        assert.strictEqual(receipt.deliveryUnknown, undefined, `${name} ${code}`);
+        assert.strictEqual(receipt.retryable, true, `${name} ${code}`);
+      } else {
+        assert.strictEqual(requests, expectedRequests(name), `${name} ${code}`);
+        assert.strictEqual(receipt.deliveryUnknown, true, `${name} ${code}`);
+      }
+    }
+  }
+});
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index 001fe33..bb4fa4d 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -44,6 +44,8 @@ const scripted = (responses, overrides = {}) => {
   const request = {
     retries: 2,
     timeoutMs: 1000,
+    // The retry mechanics, apart from the rules of an ambiguous failure.
+    isIdempotent: true,
     send: async (signal) => {
       const next = responses[Math.min(sends++, responses.length - 1)];
       if (typeof next === 'function') return next(signal);
@@ -87,12 +89,13 @@ test('Internal: a failure after a 2xx is not retried and is of unknown delivery'
     Object.defineProperty(response, 'text', { value: () => Promise.reject(new Error('reset')) });
     return response;
   };
-  const { request, sends } = scripted([unreadable]);
+  const { request, sends } = scripted([unreadable], { isIdempotent: false });
   const error = await requestWithRetry(request).catch((caught) => caught);
   assert.strictEqual(sends(), 1);
   assert.strictEqual(isDeliveryUnknown(error), true);
 
   const wrapped = scripted([unreadable], {
+    isIdempotent: false,
     wrapAccepted: (cause) => new Error('wrapped', { cause }),
   });
   const wrapping = await requestWithRetry(wrapped.request).catch((caught) => caught);
@@ -101,6 +104,7 @@ test('Internal: a failure after a 2xx is not retried and is of unknown delivery'
 
   const refusal = new RejectedError('Refused in the body.');
   const answered = scripted([new Response('{}')], {
+    isIdempotent: false,
     read: async () => {
       throw refusal;
     },
@@ -128,7 +132,7 @@ test('Internal: an expired deadline gives the timeout error, over the body too',
     Object.defineProperty(response, 'text', { value: () => hang(signal) });
     return response;
   };
-  const body = scripted([slowBody], { timeoutMs: 5, retries: 0 });
+  const body = scripted([slowBody], { timeoutMs: 5, retries: 0, isIdempotent: false });
   const error = await requestWithRetry(body.request).catch((caught) => caught);
   assert.strictEqual(error.message, 'Timed out.');
   assert.strictEqual(isDeliveryUnknown(error), true);
@@ -262,3 +266,43 @@ test('Internal: a body is read within its bound, as text or JSON', async () => {
   const declared = new Response('small', { headers: { 'Content-Length': '999999999' } });
   await assert.rejects(readText(declared), RangeError);
 });
+
+test('Internal: an ambiguous failure of a send is not retried, unless it has a key', async () => {
+  const refused = new TypeError('fetch failed', {
+    cause: Object.assign(new Error('refused'), { code: 'ECONNREFUSED' }),
+  });
+  const reset = new TypeError('fetch failed', {
+    cause: Object.assign(new Error('reset'), { code: 'ECONNRESET' }),
+  });
+  const reject = async (response) =>
+    Object.assign(new Error('HTTP'), { statusCode: response.status });
+  const plain = { isIdempotent: false, reject };
+
+  const lost = scripted([reset, new Response('ok')], plain);
+  const lostError = await requestWithRetry(lost.request).catch((caught) => caught);
+  assert.strictEqual(lost.sends(), 1);
+  assert.strictEqual(isDeliveryUnknown(lostError), true);
+
+  const gateway = scripted([new Response('', { status: 504 }), new Response('ok')], plain);
+  const gatewayError = await requestWithRetry(gateway.request).catch((caught) => caught);
+  assert.strictEqual(gateway.sends(), 1);
+  assert.strictEqual(isDeliveryUnknown(gatewayError), true);
+
+  const never = scripted([refused, new Response('ok')], plain);
+  assert.strictEqual(await requestWithRetry(never.request), 'ok');
+  assert.strictEqual(never.sends(), 2);
+
+  const keyed = scripted([reset, new Response('', { status: 503 })], {
+    ...plain,
+    hasIdempotencyKey: true,
+    retries: 1,
+  });
+  const keyedError = await requestWithRetry(keyed.request).catch((caught) => caught);
+  assert.strictEqual(keyed.sends(), 2);
+  assert.strictEqual(isDeliveryUnknown(keyedError), true);
+
+  const read = scripted([reset, new Response('', { status: 503 })], { reject, retries: 1 });
+  const readError = await requestWithRetry(read.request).catch((caught) => caught);
+  assert.strictEqual(read.sends(), 2);
+  assert.strictEqual(isDeliveryUnknown(readError), false);
+});
diff --git a/tests/unit/maileroo-transport.test.js b/tests/unit/maileroo-transport.test.js
index 35628a1..5ddee34 100644
--- a/tests/unit/maileroo-transport.test.js
+++ b/tests/unit/maileroo-transport.test.js
@@ -461,8 +461,11 @@ describe('MailerooTransport - send', { concurrency: false }, () => {
         });
         const receipt = await transport.send(createMessage());
 
-        assert.equal(calls, 2);
-        assert.ok(receipt.successful);
+        // Changed after the port: the timeout came before any response, so
+        // Maileroo may have taken the request; it is not retried but of
+        // unknown delivery (upstream retried it and succeeded).
+        assert.equal(calls, 1);
+        assert.equal(receipt.deliveryUnknown, true);
       },
     );
   });
diff --git a/tests/unit/mailgun-transport.test.js b/tests/unit/mailgun-transport.test.js
index 77fe6e0..1a9e2f0 100644
--- a/tests/unit/mailgun-transport.test.js
+++ b/tests/unit/mailgun-transport.test.js
@@ -283,7 +283,11 @@ describe('MailgunTransport - Network Errors', () => {
         assert.equal(receipt.errorMessages.length, 1);
         assert.equal(receipt.errorMessages[0], 'Network error');
         assert.equal(receipt.provider, 'mailgun');
-        assert.equal(receipt.retryable, true);
+        // Changed after the port: a failure without a response may have
+        // reached Mailgun, which has no idempotency key, so its delivery is
+        // unknown and it is not retryable (upstream: retryable).
+        assert.equal(receipt.retryable, false);
+        assert.equal(receipt.deliveryUnknown, true);
         assert.equal(receipt.attempts, 1);
         assert.equal(receipt.errors?.[0]?.category, 'network');
       }
@@ -788,7 +792,10 @@ describe('MailgunTransport - Connection Timeouts', () => {
       if (!receipt.successful) {
         assert.equal(receipt.errorMessages.length, 1);
         assert.equal(receipt.errors?.[0]?.category, 'timeout');
-        assert.ok(receipt.retryable);
+        // Changed after the port: a timeout before any response may have come
+        // after Mailgun took the request (upstream: retryable).
+        assert.equal(receipt.retryable, false);
+        assert.equal(receipt.deliveryUnknown, true);
         assert.equal(receipt.attempts, 1);
       }
     } finally {
diff --git a/tests/unit/mailtrap-transport.test.js b/tests/unit/mailtrap-transport.test.js
index fbb6206..e767ab8 100644
--- a/tests/unit/mailtrap-transport.test.js
+++ b/tests/unit/mailtrap-transport.test.js
@@ -426,6 +426,14 @@ describe('MailtrapTransport - API Errors', () => {
           timeout: 10,
         });
         const receipt = await transport.send(createMessage());
+        // Changed after the port: a network failure or a timeout without any
+        // response may have reached Mailtrap, which has no idempotency key,
+        // so it is not retried but of unknown delivery; upstream retried it.
+        if (failure === 'network' || failure === 'timeout') {
+          assert.equal(receipt.deliveryUnknown, true);
+          assert.equal(requests, 1);
+          return;
+        }
         assert.ok(receipt.successful);
         assert.equal(requests, 2);
       } finally {
diff --git a/tests/unit/resend-transport.test.js b/tests/unit/resend-transport.test.js
index ca45665..00aec0e 100644
--- a/tests/unit/resend-transport.test.js
+++ b/tests/unit/resend-transport.test.js
@@ -264,6 +264,7 @@ describe('ResendTransport - Network Errors', () => {
 
       const transport = new ResendTransport({
         apiKey: 'test-key',
+        retries: 0,
       });
 
       const message = {
@@ -287,8 +288,13 @@ describe('ResendTransport - Network Errors', () => {
         assert.ok(receipt.errorMessages.length > 0);
         assert.ok(receipt.errorMessages[0].includes('Network error'));
         assert.equal(receipt.provider, 'resend');
-        assert.equal(receipt.retryable, true);
-        assert.equal(receipt.attempts, 4);
+        // Changed after the port: Resend deduplicates by Idempotency-Key, so
+        // such a failure is retried, but once the retries are spent (none
+        // here) the request may have been taken: its delivery is unknown
+        // (upstream: retryable, after three retries).
+        assert.equal(receipt.retryable, false);
+        assert.equal(receipt.deliveryUnknown, true);
+        assert.equal(receipt.attempts, 1);
         assert.equal(receipt.errors?.[0]?.category, 'network');
       }
     } finally {
diff --git a/tests/unit/sendgrid-transport.test.js b/tests/unit/sendgrid-transport.test.js
index 541204e..0670f77 100644
--- a/tests/unit/sendgrid-transport.test.js
+++ b/tests/unit/sendgrid-transport.test.js
@@ -251,7 +251,11 @@ describe('SendGridTransport', { concurrency: false }, () => {
         assert.equal(receipt.successful, false);
         if (!receipt.successful) {
           assert.equal(receipt.provider, 'sendgrid');
-          assert.equal(receipt.retryable, true);
+          // Changed after the port: a failure without a response may have
+          // reached SendGrid, which has no idempotency key, so its delivery
+          // is unknown and it is not retryable (upstream: retryable).
+          assert.equal(receipt.retryable, false);
+          assert.equal(receipt.deliveryUnknown, true);
           assert.equal(receipt.errors?.[0]?.category, 'network');
         }
       },

From 25b0548e5cf45ffb895de3f0ae683e3ed486fbf7 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 16:40:55 +0300
Subject: [PATCH 059/158] fix(jmap): key uploaded blobs by attachment, not
 content ID

uploadAttachments kept the blob of each upload in a Map keyed by the
attachment's contentId, and the converter looked parts up by it. A content
ID repeats, and is empty for every attachment that is not inline, so the
uploads overwrote each other: a message with two such attachments pointed
both parts at the last blob, sending the second file twice. The Map is now
keyed by the attachment object itself; the ported converter tests build it
that way.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                              |  3 ++
 CLAUDE.md                                 |  3 ++
 src/jmap/jmap-transport.js                |  4 ++-
 src/jmap/message-converter.js             | 12 +++----
 tests/unit/jmap-message-converter.test.js | 17 +++++----
 tests/unit/jmap.test.js                   | 42 +++++++++++++++++++++++
 6 files changed, 68 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1151307..4e121a4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -163,6 +163,9 @@ fixed ones below.
   unknown delivery, not retried, for `./ses`, `./sendgrid`, `./mailgun`, `./mailtrap`,
   `./maileroo` and `./plunk`. `./resend` and `./lettermint`, which send an idempotency key that
   the provider deduplicates, still retry, and report the last failure as of unknown delivery.
+- **`./jmap` keeps each attachment's own file** (an upstream bug): uploaded files were looked up
+  by content ID, which is empty for every attachment that is not inline, so a message with two
+  such attachments sent the second file twice.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 57ead7c..c648d28 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -246,6 +246,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     it is thrown as `deliveryUnknown` without a retry; a request with an idempotency key
     (`hasIdempotencyKey`: resend, lettermint) is retried and only its last failure is marked; a
     read (`isIdempotent`: jmap queries) is retried and never marked.
+40. jmap: uploaded blobs were keyed by `contentId`, which repeats and is empty for every
+    attachment that is not inline, so attachments overwrote each other's blob and every part
+    pointed at the last one. They are keyed by the attachment object.
 
 ## Repository layout
 
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index f18667d..3a61617 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -740,7 +740,9 @@ class JmapTransport {
 
       const result = await uploadBlob(this.config, session.uploadUrl, accountId, blob, signal);
 
-      uploadedBlobs.set(attachment.contentId, result.blobId);
+      // Keyed by the attachment itself: content IDs repeat, and are empty for
+      // every attachment that is not inline.
+      uploadedBlobs.set(attachment, result.blobId);
     }
 
     return uploadedBlobs;
diff --git a/src/jmap/message-converter.js b/src/jmap/message-converter.js
index dbc0360..604bbf8 100644
--- a/src/jmap/message-converter.js
+++ b/src/jmap/message-converter.js
@@ -91,7 +91,7 @@ const extractCustomHeaders = (message) => {
 /**
  * Builds body structure for the message content.
  * @param message The message to build body structure for.
- * @param uploadedBlobs Map of contentId to blobId for attachments.
+ * @param uploadedBlobs Map of each attachment to its blobId.
  * @returns Object containing bodyStructure and bodyValues.
  */
 const buildBodyStructure = (message, uploadedBlobs) => {
@@ -190,14 +190,14 @@ const buildBodyStructure = (message, uploadedBlobs) => {
 /**
  * Build inline attachment parts from uploaded blobs.
  * @param attachments Array of attachments from the message.
- * @param uploadedBlobs Map of contentId to blobId.
+ * @param uploadedBlobs Map of each attachment to its blobId.
  * @returns Array of JmapBodyPart for inline attachments.
  */
 const buildInlineAttachmentParts = (attachments, uploadedBlobs) => {
   const parts = [];
 
   for (const attachment of attachments) {
-    const blobId = uploadedBlobs.get(attachment.contentId);
+    const blobId = uploadedBlobs.get(attachment);
     if (!blobId) continue;
 
     if (attachment.inline) {
@@ -217,14 +217,14 @@ const buildInlineAttachmentParts = (attachments, uploadedBlobs) => {
 /**
  * Build regular attachment parts from uploaded blobs.
  * @param attachments Array of attachments from the message.
- * @param uploadedBlobs Map of contentId to blobId.
+ * @param uploadedBlobs Map of each attachment to its blobId.
  * @returns Array of JmapBodyPart for regular attachments.
  */
 const buildAttachmentParts = (attachments, uploadedBlobs) => {
   const parts = [];
 
   for (const attachment of attachments) {
-    const blobId = uploadedBlobs.get(attachment.contentId);
+    const blobId = uploadedBlobs.get(attachment);
     if (!blobId) continue;
 
     if (!attachment.inline) {
@@ -244,7 +244,7 @@ const buildAttachmentParts = (attachments, uploadedBlobs) => {
  * Converts an Upyo Message to JMAP Email/set create format.
  * @param message The Upyo message to convert.
  * @param draftMailboxId The mailbox ID to store the draft in.
- * @param uploadedBlobs Map of contentId to blobId for attachments.
+ * @param uploadedBlobs Map of each attachment to its blobId.
  * @returns The JMAP Email/set create object.
  * @throws {TypeError} If the message carries an invalid message identifier or
  * date, or a header value containing a carriage return or line feed.
diff --git a/tests/unit/jmap-message-converter.test.js b/tests/unit/jmap-message-converter.test.js
index d1ea5a3..16ccad2 100644
--- a/tests/unit/jmap-message-converter.test.js
+++ b/tests/unit/jmap-message-converter.test.js
@@ -5,6 +5,11 @@ const { describe, it } = require('node:test');
 const assert = require('node:assert/strict');
 const { convertMessage, formatAddress } = require('../../src/jmap/message-converter.js');
 
+// Changed after the port: uploaded blobs are keyed by the attachment, not its
+// content ID, which repeats or is empty (CLAUDE.md, fixed after the port).
+const attachmentWithId = (message, contentId) =>
+  message.attachments.find((attachment) => attachment.contentId === contentId);
+
 describe('formatAddress', () => {
   it('should format address with name', () => {
     const address = {
@@ -309,7 +314,7 @@ describe('convertMessage', () => {
     };
 
     const uploadedBlobs = new Map();
-    uploadedBlobs.set('attachment-1', 'blob-uploaded-123');
+    uploadedBlobs.set(attachmentWithId(message, 'attachment-1'), 'blob-uploaded-123');
 
     const result = convertMessage(message, 'drafts-123', uploadedBlobs);
 
@@ -353,8 +358,8 @@ describe('convertMessage', () => {
     };
 
     const uploadedBlobs = new Map();
-    uploadedBlobs.set('att-1', 'blob-1');
-    uploadedBlobs.set('att-2', 'blob-2');
+    uploadedBlobs.set(attachmentWithId(message, 'att-1'), 'blob-1');
+    uploadedBlobs.set(attachmentWithId(message, 'att-2'), 'blob-2');
 
     const result = convertMessage(message, 'drafts-123', uploadedBlobs);
 
@@ -388,7 +393,7 @@ describe('convertMessage', () => {
     };
 
     const uploadedBlobs = new Map();
-    uploadedBlobs.set('inline-img', 'blob-inline-123');
+    uploadedBlobs.set(attachmentWithId(message, 'inline-img'), 'blob-inline-123');
 
     const result = convertMessage(message, 'drafts-123', uploadedBlobs);
 
@@ -432,8 +437,8 @@ describe('convertMessage', () => {
     };
 
     const uploadedBlobs = new Map();
-    uploadedBlobs.set('logo', 'blob-logo');
-    uploadedBlobs.set('att-doc', 'blob-doc');
+    uploadedBlobs.set(attachmentWithId(message, 'logo'), 'blob-logo');
+    uploadedBlobs.set(attachmentWithId(message, 'att-doc'), 'blob-doc');
 
     const result = convertMessage(message, 'drafts-123', uploadedBlobs);
 
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index 9ed99ab..84c1d8e 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -229,3 +229,45 @@ test('JMAP: Basic authentication encodes credentials outside Latin-1 as UTF-8',
   const expected = `Basic ${Buffer.from('алекс:пароль-✓').toString('base64')}`;
   assert.deepStrictEqual([...authorizations], [expected]);
 });
+
+test('JMAP: attachments that share a content ID keep their own blobs', async (t) => {
+  let created;
+  serve(t, {
+    'Email/set': (args) => {
+      created = args.create.draft;
+      return defaults['Email/set']();
+    },
+  });
+  const original = globalThis.fetch;
+  let uploads = 0;
+  t.mock.method(globalThis, 'fetch', (input, init) =>
+    String(input).includes('/upload/')
+      ? Promise.resolve(Response.json({ blobId: `blob-${++uploads}` }))
+      : original(input, init),
+  );
+  const attachment = (filename) => ({
+    inline: false,
+    filename,
+    content: new TextEncoder().encode(filename),
+    contentType: 'text/plain',
+    contentId: '',
+  });
+  const receipt = await transport().send(
+    createMessage({
+      from: 'alex@example.com',
+      to: 'bob@example.com',
+      subject: 'Two files',
+      content: { text: 'Hi' },
+      attachments: [attachment('a.txt'), attachment('b.txt')],
+    }),
+  );
+  assert.strictEqual(receipt.successful, true, receipt.errorMessages?.join(' | '));
+  const parts = created.bodyStructure.subParts.filter((part) => part.blobId != null);
+  assert.deepStrictEqual(
+    parts.map((part) => [part.name, part.blobId]),
+    [
+      ['a.txt', 'blob-1'],
+      ['b.txt', 'blob-2'],
+    ],
+  );
+});

From 5c5d4346ae968aa58ca29f25681b3fbb005c44df Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:00:12 +0300
Subject: [PATCH 060/158] fix(jmap): trust only the Session's own origin with
 credentials

send(), sendMany() and sendRaw() used the apiUrl, uploadUrl and downloadUrl
of the Session as given, and sent the bearer token or the Basic password
and the custom headers there: a Session naming another host, by mistake or
by tampering, received them. getSession also cached the Session before
anything checked it, and nothing dropped it on a 401 or a 404, so a bad
Session stayed for sessionCacheTtl.

Those URLs must now be on the origin of sessionUrl, or of baseUrl when the
URLs are rewritten, or on one of the new trustedOrigins (each checked as
HTTPS or loopback HTTP), checked before the Session is cached and in
verify(); apiUrl is required, the others are checked when given. A 401 or a
404 from a send forgets the cached Session, so the next send fetches it
again. The JMAP guide describes trustedOrigins.

An upstream bug, recorded in CLAUDE.md. The bound of the stalled-body
delivery test allows the retry of the keyed providers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  5 +++++
 CLAUDE.md                   |  5 +++++
 docs/transports/jmap.md     | 19 +++++++++++++++++++
 src/jmap/config.js          |  2 ++
 src/jmap/index.d.ts         |  9 +++++++++
 src/jmap/jmap-transport.js  | 38 +++++++++++++++++++++++++++++++++++++
 tests/unit/delivery.test.js |  3 ++-
 tests/unit/jmap.test.js     | 36 +++++++++++++++++++++++++++++++++++
 8 files changed, 116 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4e121a4..7959d2e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -166,6 +166,11 @@ fixed ones below.
 - **`./jmap` keeps each attachment's own file** (an upstream bug): uploaded files were looked up
   by content ID, which is empty for every attachment that is not inline, so a message with two
   such attachments sent the second file twice.
+- **`./jmap` sends its credentials only to the origin of the Session** (an upstream bug): the
+  URLs of the Session were used as given, so a Session naming another host received the bearer
+  token or password, and it stayed cached for five minutes. They must be on the origin of
+  `sessionUrl` (or `baseUrl`), or in the new `trustedOrigins` option; a 401 or a 404 makes the
+  next send fetch the Session again.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index c648d28..0a98d21 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -249,6 +249,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 40. jmap: uploaded blobs were keyed by `contentId`, which repeats and is empty for every
     attachment that is not inline, so attachments overwrote each other's blob and every part
     pointed at the last one. They are keyed by the attachment object.
+41. jmap: `apiUrl`, `uploadUrl` and `downloadUrl` of the Session were used as given, so a
+    Session naming another host received the credentials, and it stayed cached for
+    `sessionCacheTtl` whatever happened. They must be on the Session's origin (that of
+    `baseUrl` when rewritten) or in the new `trustedOrigins`, checked before caching, and a
+    401 or a 404 forgets the cached Session.
 
 ## Repository layout
 
diff --git a/docs/transports/jmap.md b/docs/transports/jmap.md
index 91721f0..59bbe26 100644
--- a/docs/transports/jmap.md
+++ b/docs/transports/jmap.md
@@ -286,6 +286,25 @@ const transport = new JmapTransport({
 This is useful when connecting to containerized servers or when the server
 returns hostnames that differ from the external access URL.
 
+### Trusted origins
+
+The transport sends its credentials to the URLs the Session names, so it
+accepts only URLs on the origin it fetched the Session from (that of `baseUrl`
+when URLs are rewritten). A Session that names another origin is refused
+before it is cached. If your server really serves its API from another host,
+list that origin:
+
+```js
+const transport = new JmapTransport({
+  sessionUrl: 'https://mail.example.com/.well-known/jmap',
+  bearerToken: 'your-bearer-token',
+  trustedOrigins: ['https://api.mail.example.com'],
+});
+```
+
+A cached Session is fetched again after a 401 or a 404, which may mean that it
+changed.
+
 ## Request cancellation
 
 The JMAP transport supports request cancellation using the standard
diff --git a/src/jmap/config.js b/src/jmap/config.js
index 300000c..5b958e5 100644
--- a/src/jmap/config.js
+++ b/src/jmap/config.js
@@ -24,10 +24,12 @@ const createJmapConfig = (config) => {
     headers: config.headers ?? {},
     sessionCacheTtl: config.sessionCacheTtl ?? 300000,
     baseUrl: config.baseUrl ?? null,
+    trustedOrigins: config.trustedOrigins ?? [],
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
   checkSecureUrl(resolved.sessionUrl, 'sessionUrl');
   if (resolved.baseUrl != null) checkSecureUrl(resolved.baseUrl, 'baseUrl');
+  for (const origin of resolved.trustedOrigins) checkSecureUrl(origin, 'trustedOrigins');
   return resolved;
 };
 
diff --git a/src/jmap/index.d.ts b/src/jmap/index.d.ts
index e0334ab..8c6a396 100644
--- a/src/jmap/index.d.ts
+++ b/src/jmap/index.d.ts
@@ -75,6 +75,14 @@ export interface JmapConfig {
    * baseUrl is `http://localhost:8080`, URLs will be rewritten to use localhost.
    */
   readonly baseUrl?: string;
+  /**
+   * Origins besides that of `sessionUrl` (or of `baseUrl`, when set) that
+   * the URLs of the Session may point to, such as
+   * `https://api.mail.example.com`.  The transport sends its credentials to
+   * those URLs, so a Session naming any other origin is refused.
+   * @default []
+   */
+  readonly trustedOrigins?: readonly string[];
 }
 /**
  * Resolved JMAP configuration with all fields populated.
@@ -93,6 +101,7 @@ export type ResolvedJmapConfig = {
   readonly headers: Record<string, string>;
   readonly sessionCacheTtl: number;
   readonly baseUrl: string | null;
+  readonly trustedOrigins: readonly string[];
 };
 /**
  * Creates a resolved JMAP configuration with default values applied.
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index 3a61617..8b6e0ea 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -88,6 +88,7 @@ class JmapTransport {
       validateVerificationSession(session);
       if (this.config.baseUrl) session = this.rewriteSessionUrls(session);
       validateVerificationApiUrl(session.apiUrl);
+      checkSessionUrls(session, this.config);
       if (!Object.values(JMAP_CAPABILITIES).every((cap) => cap in session.capabilities)) {
         throw new JmapApiError('JMAP session lacks core, mail, or submission capability.');
       }
@@ -247,6 +248,7 @@ class JmapTransport {
       // Parse response
       return this.parseResponse(response);
     } catch (error) {
+      this.forgetSessionAfter(error);
       if (signal?.aborted) {
         throw getAbortReason(signal, error);
       }
@@ -328,6 +330,7 @@ class JmapTransport {
         signal,
       );
     } catch (error) {
+      this.forgetSessionAfter(error);
       signal?.throwIfAborted();
       return createJmapFailure(
         error instanceof Error ? error.message : String(error),
@@ -472,6 +475,7 @@ class JmapTransport {
         yield this.parseBatchResponseForIndex(response, i);
       }
     } catch (error) {
+      this.forgetSessionAfter(error);
       if (signal?.aborted) {
         throw getAbortReason(signal, error);
       }
@@ -529,6 +533,10 @@ class JmapTransport {
       session = this.rewriteSessionUrls(session);
     }
 
+    // Checked before it is cached: a Session that names another origin would
+    // receive the credentials for as long as it stays cached.
+    checkSessionUrls(session, this.config);
+
     // Cache it
     this.cachedSession = {
       session,
@@ -538,6 +546,14 @@ class JmapTransport {
     return session;
   }
 
+  // A rejected authentication or a URL that is gone may come from a Session
+  // that changed since it was cached: the next send fetches it again.
+  forgetSessionAfter(error) {
+    if (error instanceof JmapApiError && (error.statusCode === 401 || error.statusCode === 404)) {
+      this.cachedSession = null;
+    }
+  }
+
   /**
    * Rewrites session URLs to use the configured baseUrl.
    * @param session The original session from the server.
@@ -979,6 +995,28 @@ const verificationOperation = async (timeout, operation, signal) => {
   }
 };
 
+// The URLs of a Session the transport sends its credentials to must be on the
+// origin it fetched the Session from (that of baseUrl when URLs are rewritten)
+// or on one of trustedOrigins.
+const checkSessionUrls = (session, config) => {
+  if (!isRecord(session)) throw new JmapApiError('Invalid JMAP Session response.');
+  const trusted = new Set([new URL(config.baseUrl ?? config.sessionUrl).origin]);
+  for (const origin of config.trustedOrigins) trusted.add(new URL(origin).origin);
+  for (const name of ['apiUrl', 'uploadUrl', 'downloadUrl']) {
+    const value = session[name];
+    // Only apiUrl serves every send; the others are checked when given.
+    if (value == null && name !== 'apiUrl') continue;
+    const origin = typeof value === 'string' && URL.canParse(value) ? new URL(value).origin : null;
+    if (origin == null) throw new JmapApiError(`Invalid JMAP Session field: ${name}`);
+    if (!trusted.has(origin)) {
+      throw new JmapApiError(
+        `JMAP Session ${name} is on ${origin}, which is not trusted; ` +
+          'list it in trustedOrigins if it is meant to receive the credentials.',
+      );
+    }
+  }
+};
+
 const validateVerificationApiUrl = (value) => {
   if (typeof value === 'string' && URL.canParse(value)) {
     const url = new URL(value);
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index 54074c1..5313e8e 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -117,7 +117,8 @@ test(
       const started = performance.now();
       const receipt = await transport.send(message());
       t.mock.restoreAll();
-      assert.ok(performance.now() - started < 1000, name);
+      // Resend and Lettermint retry once with their key, after up to a second.
+      assert.ok(performance.now() - started < 3000, name);
       assert.strictEqual(receipt.successful, false, name);
       assert.strictEqual(receipt.deliveryUnknown, true, name);
     }
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index 84c1d8e..6e79cc8 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -271,3 +271,39 @@ test('JMAP: attachments that share a content ID keep their own blobs', async (t)
     ],
   );
 });
+
+test('JMAP: a Session naming another origin is refused, unless that origin is trusted', async (t) => {
+  const evil = 'https://evil.example';
+  const calls = serve(t, { session: session({ apiUrl: `${evil}/api` }) });
+  const refused = await transport().send(message());
+  assert.strictEqual(refused.successful, false);
+  assert.match(refused.errorMessages[0], /evil\.example, which is not trusted/);
+  assert.ok(
+    calls.every((call) => !call.startsWith(evil)),
+    calls.join(' '),
+  );
+
+  const trusted = await transport({ trustedOrigins: [evil] }).send(message());
+  assert.strictEqual(trusted.successful, true, trusted.errorMessages?.join(' | '));
+  assert.ok(calls.some((call) => call.startsWith(evil)));
+});
+
+test('JMAP: a 401 makes the next send fetch the Session again', async (t) => {
+  let sessionFetches = 0;
+  let rejected = false;
+  serve(t);
+  const served = globalThis.fetch;
+  t.mock.method(globalThis, 'fetch', (input, init) => {
+    const url = String(input);
+    if (url.endsWith('/.well-known/jmap')) sessionFetches++;
+    if (url.endsWith('/api') && !rejected) {
+      rejected = true;
+      return Promise.resolve(new Response('', { status: 401 }));
+    }
+    return served(input, init);
+  });
+  const jmap = transport();
+  assert.strictEqual((await jmap.send(message())).successful, false);
+  assert.strictEqual((await jmap.send(message())).successful, true);
+  assert.strictEqual(sessionFetches, 2);
+});

From 16437d07c03f2fc5dc54626dcce0e43a76c8d7f6 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:02:19 +0300
Subject: [PATCH 061/158] fix(jmap): split sendMany by the server's
 maxObjectsInSet

sendMany created every message in one Email/set and submitted them in one
EmailSubmission/set, whatever the maxObjectsInSet that the Session's core
capability declares, so a server with a lower limit refused the whole
batch (RFC 8620 section 2), and any failure at any stage failed every
message.

The discovery of the account, drafts mailbox and identities still runs
once; the messages then go in batches of at most maxObjectsInSet (all of
them when the server declares no limit), each through sendBatch with its
own failure handling, so one refused batch fails only its own messages.
maxSizeRequest is not yet followed.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |   3 +
 CLAUDE.md                  |   4 ++
 src/jmap/jmap-transport.js | 136 +++++++++++++++++++++++++------------
 tests/unit/jmap.test.js    |  34 ++++++++++
 4 files changed, 135 insertions(+), 42 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7959d2e..26434f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -171,6 +171,9 @@ fixed ones below.
   token or password, and it stayed cached for five minutes. They must be on the origin of
   `sessionUrl` (or `baseUrl`), or in the new `trustedOrigins` option; a 401 or a 404 makes the
   next send fetch the Session again.
+- **`./jmap` respects the `maxObjectsInSet` of the server in `sendMany`** (an upstream bug): it
+  sent every message in one request, which a server with a lower limit refuses whole. It sends
+  batches of at most that many messages, and a batch that fails fails only its own messages.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 0a98d21..0df8693 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -254,6 +254,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     `sessionCacheTtl` whatever happened. They must be on the Session's origin (that of
     `baseUrl` when rewritten) or in the new `trustedOrigins`, checked before caching, and a
     401 or a 404 forgets the cached Session.
+42. jmap: `sendMany` put every message into one Email/set and EmailSubmission/set, whatever
+    the `maxObjectsInSet` of the Session, so a server with a limit refused the whole batch,
+    and any failure failed every message. It sends batches of at most that many (`sendBatch`),
+    each failing on its own; discovery still runs once. `maxSizeRequest` is not yet followed.
 
 ## Repository layout
 
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index 8b6e0ea..9e9ba65 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -368,10 +368,10 @@ class JmapTransport {
       return;
     }
 
-    // Track processing stage for better error messages
+    // What every batch shares is discovered once; if it fails, every message
+    // fails with it.
     let processingStage = 'initialization';
-    let attachmentsUploadedCount = 0;
-
+    let discovered;
     try {
       signal?.throwIfAborted();
 
@@ -404,15 +404,47 @@ class JmapTransport {
       const identityMap = await this.getIdentityMap(session, accountId, signal);
       signal?.throwIfAborted();
 
+      discovered = { session, accountId, draftsMailboxId, identityMap };
+    } catch (error) {
+      for (const failure of this.failBatch(
+        error,
+        processingStage,
+        messageArray.length,
+        0,
+        signal,
+      )) {
+        yield failure;
+      }
+      return;
+    }
+
+    // RFC 8620 §2: a server may limit the objects one /set method creates;
+    // a batch over it would be refused as a whole.
+    const limit = getMaxObjectsInSet(discovered.session);
+    for (let start = 0; start < messageArray.length; start += limit) {
+      const batch = messageArray.slice(start, start + limit);
+      for await (const receipt of this.sendBatch(discovered, batch, signal)) {
+        yield receipt;
+      }
+    }
+  }
+
+  /**
+   * Submits one batch of messages in a single Email/set and EmailSubmission/set
+   * request, yielding a receipt per message; a failure fails the batch only.
+   */
+  async *sendBatch(discovered, batch, signal) {
+    const { session, accountId, draftsMailboxId, identityMap } = discovered;
+    let processingStage = 'attachment upload';
+    let attachmentsUploadedCount = 0;
+    try {
       // Upload all attachments for all messages
-      processingStage = 'attachment upload';
       const allUploadedBlobs = new Map();
-      for (let i = 0; i < messageArray.length; i++) {
-        const message = messageArray[i];
+      for (let i = 0; i < batch.length; i++) {
         const uploadedBlobs = await this.uploadAttachments(
           session,
           accountId,
-          message.attachments,
+          batch[i].attachments,
           signal,
         );
         allUploadedBlobs.set(i, uploadedBlobs);
@@ -425,10 +457,9 @@ class JmapTransport {
       const emailCreates = {};
       const submissionCreates = {};
 
-      for (let i = 0; i < messageArray.length; i++) {
-        const message = messageArray[i];
-        const uploadedBlobs = allUploadedBlobs.get(i);
-        const emailCreate = convertMessage(message, draftsMailboxId, uploadedBlobs);
+      for (let i = 0; i < batch.length; i++) {
+        const message = batch[i];
+        const emailCreate = convertMessage(message, draftsMailboxId, allUploadedBlobs.get(i));
 
         // Find identity for this sender
         const senderEmail = message.sender.address.toLowerCase();
@@ -471,44 +502,60 @@ class JmapTransport {
       );
 
       // Parse batch response and yield individual receipts
-      for (let i = 0; i < messageArray.length; i++) {
+      for (let i = 0; i < batch.length; i++) {
         yield this.parseBatchResponseForIndex(response, i);
       }
     } catch (error) {
-      this.forgetSessionAfter(error);
-      if (signal?.aborted) {
-        throw getAbortReason(signal, error);
+      for (const failure of this.failBatch(
+        error,
+        processingStage,
+        batch.length,
+        attachmentsUploadedCount,
+        signal,
+      )) {
+        yield failure;
       }
+    }
+  }
 
-      const timeoutOverride =
-        error instanceof Error && error.name === 'AbortError'
-          ? {
-              category: 'timeout',
-              code: 'abort',
-              retryable: true,
-            }
-          : undefined;
-
-      // For any error during batch processing, yield failure for all messages
-      // with detailed stage information
-      const baseMessage =
-        error instanceof Error && error.name === 'AbortError'
-          ? `Request aborted: ${error.message}`
-          : error instanceof JmapApiError
+  /**
+   * The receipts of a batch that failed at `processingStage`, one per message,
+   * after the abort of the caller, which is thrown instead.
+   */
+  *failBatch(error, processingStage, count, attachmentsUploadedCount, signal) {
+    this.forgetSessionAfter(error);
+    if (signal?.aborted) {
+      throw getAbortReason(signal, error);
+    }
+
+    const timeoutOverride =
+      error instanceof Error && error.name === 'AbortError'
+        ? {
+            category: 'timeout',
+            code: 'abort',
+            retryable: true,
+          }
+        : undefined;
+
+    // For any error during batch processing, yield failure for all messages
+    // with detailed stage information
+    const baseMessage =
+      error instanceof Error && error.name === 'AbortError'
+        ? `Request aborted: ${error.message}`
+        : error instanceof JmapApiError
+          ? error.message
+          : error instanceof Error
             ? error.message
-            : error instanceof Error
-              ? error.message
-              : String(error);
-
-      // Build detailed error message with stage and progress info
-      let detailedMessage = `Failed during ${processingStage}: ${baseMessage}`;
-      if (processingStage === 'attachment upload' && attachmentsUploadedCount > 0) {
-        detailedMessage += ` (${attachmentsUploadedCount}/${messageArray.length} messages had attachments uploaded before failure)`;
-      }
+            : String(error);
 
-      for (let i = 0; i < messageArray.length; i++) {
-        yield createJmapFailure(detailedMessage, error, timeoutOverride);
-      }
+    // Build detailed error message with stage and progress info
+    let detailedMessage = `Failed during ${processingStage}: ${baseMessage}`;
+    if (processingStage === 'attachment upload' && attachmentsUploadedCount > 0) {
+      detailedMessage += ` (${attachmentsUploadedCount}/${count} messages had attachments uploaded before failure)`;
+    }
+
+    for (let i = 0; i < count; i++) {
+      yield createJmapFailure(detailedMessage, error, timeoutOverride);
     }
   }
 
@@ -995,6 +1042,11 @@ const verificationOperation = async (timeout, operation, signal) => {
   }
 };
 
+const getMaxObjectsInSet = (session) => {
+  const limit = session.capabilities?.[JMAP_CAPABILITIES.core]?.maxObjectsInSet;
+  return Number.isInteger(limit) && limit > 0 ? limit : Infinity;
+};
+
 // The URLs of a Session the transport sends its credentials to must be on the
 // origin it fetched the Session from (that of baseUrl when URLs are rewritten)
 // or on one of trustedOrigins.
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index 6e79cc8..cbe0f24 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -307,3 +307,37 @@ test('JMAP: a 401 makes the next send fetch the Session again', async (t) => {
   assert.strictEqual((await jmap.send(message())).successful, true);
   assert.strictEqual(sessionFetches, 2);
 });
+
+test('JMAP: sendMany splits its batch by the maxObjectsInSet of the Session', async (t) => {
+  // Each /set answers its creations, except in the second batch, refused whole.
+  const answer = (prefix) => {
+    let sets = 0;
+    return (args) => {
+      sets++;
+      const keys = Object.keys(args.create);
+      const entries = keys.map((key) => [
+        key,
+        sets === 2 ? { type: 'tooLarge' } : { id: prefix + key },
+      ]);
+      return sets === 2
+        ? { notCreated: Object.fromEntries(entries) }
+        : { created: Object.fromEntries(entries) };
+    };
+  };
+  const calls = serve(t, {
+    session: session({
+      capabilities: { [CORE]: { maxObjectsInSet: 2 }, [MAIL]: {}, [SUBMISSION]: {} },
+    }),
+    'Email/set': answer('e-'),
+    'EmailSubmission/set': answer('s-'),
+  });
+  const receipts = [];
+  for await (const receipt of transport().sendMany([1, 2, 3, 4, 5].map(() => message()))) {
+    receipts.push(receipt);
+  }
+  assert.strictEqual(calls.filter((call) => call === 'Email/set').length, 3);
+  assert.deepStrictEqual(
+    receipts.map((receipt) => receipt.successful),
+    [true, true, false, false, true],
+  );
+});

From eaf765949a0dd6c8e6df76ccadde67c1369e813a Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:03:38 +0300
Subject: [PATCH 062/158] fix: keep configured names inside their part of a
 request URL

The SES region went into the host name of every request as given:
`region: 'foo@evil.example/'` sent the signed request, with its session
token and the message, to evil.example. The Mailgun domain, the Mailtrap
sandbox inboxId and the account ID of a JMAP blob upload went into the path
unencoded, so `../` climbed it. These come from the application today, but
the roadmap's per-tenant credentials would take them from tenants.

createSesConfig refuses, with a TypeError, a region that does not look like
one (us-east-1, eu-central-1, us-gov-west-1); the other three are encoded
with encodeURIComponent as a single path segment, as the raw JMAP upload
already did.

An upstream bug, recorded in CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  5 +++++
 CLAUDE.md                   |  4 ++++
 src/jmap/blob-uploader.js   |  2 +-
 src/mailgun/http-client.js  |  3 ++-
 src/mailtrap/http-client.js |  4 +++-
 src/ses/config.js           |  7 +++++++
 tests/unit/delivery.test.js | 21 +++++++++++++++++++++
 tests/unit/jmap.test.js     | 16 ++++++++++++++++
 8 files changed, 59 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26434f9..b7a3e2f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -174,6 +174,11 @@ fixed ones below.
 - **`./jmap` respects the `maxObjectsInSet` of the server in `sendMany`** (an upstream bug): it
   sent every message in one request, which a server with a lower limit refuses whole. It sends
   batches of at most that many messages, and a batch that fails fails only its own messages.
+- **A configured name can no longer redirect a request** (an upstream bug): the SES `region` went
+  into the host name as given, so `foo@evil.example/` sent the signed request, with its session
+  token, to `evil.example`; the Mailgun `domain`, the Mailtrap `inboxId` and the JMAP account ID
+  of a blob upload went into the path unencoded. A region must look like one (`us-east-1`), and
+  the others are encoded as a single path segment.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 0df8693..03dcd98 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -258,6 +258,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     the `maxObjectsInSet` of the Session, so a server with a limit refused the whole batch,
     and any failure failed every message. It sends batches of at most that many (`sendBatch`),
     each failing on its own; discovery still runs once. `maxSizeRequest` is not yet followed.
+43. ses, mailgun, mailtrap, jmap: the SES `region` went into the host name unchecked
+    (`foo@evil.example/` sent the signed request to `evil.example`), and the Mailgun `domain`,
+    the Mailtrap `inboxId` and the JMAP `accountId` of a blob upload into the path unencoded.
+    The region must look like one (`us-east-1`), and the others are encoded as one segment.
 
 ## Repository layout
 
diff --git a/src/jmap/blob-uploader.js b/src/jmap/blob-uploader.js
index 9a1763b..6ac3ef0 100644
--- a/src/jmap/blob-uploader.js
+++ b/src/jmap/blob-uploader.js
@@ -19,7 +19,7 @@ const { Buffer } = require('node:buffer');
 const uploadBlob = async (config, uploadUrl, accountId, blob, signal) => {
   signal?.throwIfAborted();
 
-  const url = uploadUrl.replace('{accountId}', accountId);
+  const url = uploadUrl.replace('{accountId}', encodeURIComponent(accountId));
 
   let authHeader;
   if (config.bearerToken) {
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index ffada34..94d8463 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -27,7 +27,8 @@ class MailgunHttpClient {
    * @returns Promise that resolves to the Mailgun response.
    */
   sendMessage(formData, signal) {
-    const url = `${this.config.baseUrl}/${this.config.domain}/messages`;
+    // The domain is a path segment: encoded, it cannot climb the path.
+    const url = `${this.config.baseUrl}/${encodeURIComponent(this.config.domain)}/messages`;
 
     return this.makeRequest(url, {
       method: 'POST',
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index 7cd5a7c..f9002a4 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -127,7 +127,9 @@ class MailtrapHttpClient {
   resolveUrl(kind) {
     const baseUrl = this.config.sandbox ? this.config.sandboxBaseUrl : this.config.sendBaseUrl;
     const suffix =
-      this.config.sandbox && this.config.inboxId != null ? `/${this.config.inboxId}` : '';
+      this.config.sandbox && this.config.inboxId != null
+        ? `/${encodeURIComponent(this.config.inboxId)}`
+        : '';
     return `${baseUrl}/api/${kind}${suffix}`;
   }
 
diff --git a/src/ses/config.js b/src/ses/config.js
index 03fa0f8..e10611e 100644
--- a/src/ses/config.js
+++ b/src/ses/config.js
@@ -28,6 +28,9 @@ const { checkRequestOptions } = require('../internal/config.js');
  * @param config The SES configuration object.
  * @returns A resolved configuration with all defaults applied.
  */
+// An AWS region, such as us-east-1, eu-central-1 or us-gov-west-1.
+const AWS_REGION = /^[a-z]{2}(?:-[a-z]+)+-\d+$/;
+
 const createSesConfig = (config) => {
   const resolved = {
     authentication: config.authentication,
@@ -41,6 +44,10 @@ const createSesConfig = (config) => {
     batchSize: config.batchSize ?? 50,
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  // The region goes into the host name of every request, with the signature.
+  if (!AWS_REGION.test(resolved.region)) {
+    throw new TypeError(`Invalid AWS region: ${String(resolved.region)}`);
+  }
   return resolved;
 };
 
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index 5313e8e..31e1895 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -253,3 +253,24 @@ test('Delivery: a lost request is not sent again without a key; a refused one is
     }
   }
 });
+
+test('Delivery: a configured name cannot move a request to another host or path', async (t) => {
+  const authentication = { type: 'credentials', accessKeyId: 'a', secretAccessKey: 'b' };
+  assert.throws(() => new SesTransport({ authentication, region: 'foo@evil.example/' }), TypeError);
+  const gov = new SesTransport({ authentication, region: 'us-gov-west-1' });
+  assert.strictEqual(gov.config.region, 'us-gov-west-1');
+
+  const paths = [];
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    paths.push(new URL(url).pathname);
+    return Response.json({ id: 'x', message: 'ok' });
+  });
+  await new MailgunTransport({ apiKey: 'key', domain: '../../admin', retries: 0 }).send(message());
+  await new MailtrapTransport({
+    apiToken: 'token',
+    sandbox: true,
+    inboxId: '1/../../admin',
+    retries: 0,
+  }).send(message());
+  assert.deepStrictEqual(paths, ['/v3/..%2F..%2Fadmin/messages', '/api/send/1%2F..%2F..%2Fadmin']);
+});
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index cbe0f24..997d980 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -341,3 +341,19 @@ test('JMAP: sendMany splits its batch by the maxObjectsInSet of the Session', as
     [true, true, false, false, true],
   );
 });
+
+test('JMAP: an account ID cannot climb the path of a blob upload', async (t) => {
+  const paths = [];
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    paths.push(new URL(url).pathname);
+    return Response.json({ blobId: 'b1' });
+  });
+  const config = createJmapConfig({ sessionUrl: 'https://jmap.example.com/s', bearerToken: 't' });
+  await uploadBlob(
+    config,
+    'https://jmap.example.com/upload/{accountId}/',
+    'a/../../x',
+    new Blob(['a']),
+  );
+  assert.deepStrictEqual(paths, ['/upload/a%2F..%2F..%2Fx/']);
+});

From 8e772d944afbfc370079dddcbcf8e50b29a64c66 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:05:15 +0300
Subject: [PATCH 063/158] chore(bench): measure the library itself rather than
 reference points

The benchmark predated the port: it timed base64 written in the script,
crypto.sign and JSON calls, as stand-ins for a MIME builder and an audit
log that did not exist, and its header still said so. It now runs the
library: composing a text and HTML message, a message with a 1 MiB
attachment, the same text signed with DKIM (RSA-2048), writing 1 MiB of
message data through the SMTP dot-stuffing, isEmailAddress,
classifyReceiptError and the priority strategy of the pool. benchAsync
measures the asynchronous scenarios. baseline.json holds the numbers
before the performance work, on Node 24.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 bench/baseline.json |  34 +++++-----
 bench/bench.js      | 151 ++++++++++++++++++++++++++++++++++----------
 bench/helpers.js    |  59 ++++++-----------
 3 files changed, 149 insertions(+), 95 deletions(-)

diff --git a/bench/baseline.json b/bench/baseline.json
index 6d35566..cb4819a 100644
--- a/bench/baseline.json
+++ b/bench/baseline.json
@@ -1,38 +1,34 @@
 {
   "node": "v24.14.1",
-  "date": "2026-10-14T15:35:28.049Z",
+  "date": "2026-10-16T14:05:15.910Z",
   "results": [
     {
-      "name": "base64, 76-column lines — 100 KB attachment",
-      "opsPerSec": 9490
+      "name": "MIME — compose a text and HTML message",
+      "opsPerSec": 2796
     },
     {
-      "name": "base64, 76-column lines — 1 MB attachment",
-      "opsPerSec": 1158
+      "name": "MIME — compose a message with a 1 MiB attachment",
+      "opsPerSec": 40
     },
     {
-      "name": "Message-ID — crypto.randomUUID()",
-      "opsPerSec": 7218410
+      "name": "DKIM — compose and sign a text message (RSA-2048)",
+      "opsPerSec": 755
     },
     {
-      "name": "DKIM — RSA-SHA256 signature, 2048-bit key",
-      "opsPerSec": 1835
+      "name": "SMTP — dot-stuff and write 1 MiB of message data",
+      "opsPerSec": 301
     },
     {
-      "name": "Audit log — SHA-256 of an outbox record",
-      "opsPerSec": 1174212
+      "name": "Address — isEmailAddress",
+      "opsPerSec": 1687799
     },
     {
-      "name": "Audit log — HMAC-SHA256 of an address",
-      "opsPerSec": 767227
+      "name": "Receipt — classifyReceiptError of a reset",
+      "opsPerSec": 31384578
     },
     {
-      "name": "Outbox — JSON.stringify of a record",
-      "opsPerSec": 1314416
-    },
-    {
-      "name": "Outbox — JSON.parse of a record",
-      "opsPerSec": 892982
+      "name": "Pool — select by priority among 10 transports",
+      "opsPerSec": 2263836
     }
   ]
 }
diff --git a/bench/bench.js b/bench/bench.js
index cd9b6e7..81955b9 100644
--- a/bench/bench.js
+++ b/bench/bench.js
@@ -4,29 +4,32 @@
  * Run: pnpm bench [filter] [--json] [--save] [--compare]
  *
  * An optional filter runs only the scenarios whose name contains it, e.g.
- * `pnpm bench base64`. `--json` prints the results as JSON, `--save` writes
+ * `pnpm bench MIME`. `--json` prints the results as JSON, `--save` writes
  * them to bench/baseline.json, and `--compare` prints the change against
  * that baseline (numbers are machine-specific: compare on one machine, before
  * and after a change). Manual only, not part of CI.
  *
- * Until the MIME builder and the reliability layer are implemented, the
- * scenarios are the reference points their hot paths are made of: encoding
- * an attachment, a Message-ID, a DKIM signature, the hashes of the audit log
- * and the JSON of an outbox record.
+ * The scenarios run the library itself: composing a message with and
+ * without an attachment or a DKIM signature, writing message data through
+ * the SMTP dot-stuffing, and the checks that run once per message or per
+ * address.
  */
 
 const crypto = require('node:crypto');
+const { EventEmitter } = require('node:events');
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { bench, benchAsync, ATTACHMENT_1M, ADDRESS } = require('./helpers.js');
 const {
-  bench,
-  ATTACHMENT_100K,
-  ATTACHMENT_1M,
-  ADDRESS,
-  OUTBOX_RECORD,
-  DKIM_HEADERS,
-} = require('./helpers.js');
+  classifyReceiptError,
+  createMessage,
+  isEmailAddress,
+  readAttachmentContent,
+} = require('../index.js');
+const { composeMessage } = require('../src/mime/index.js');
+const { writeMessageData } = require('../src/smtp/data-stream.js');
+const { PriorityStrategy } = require('../src/pool/strategies/priority-strategy.js');
 
 const BASELINE = path.join(__dirname, 'baseline.json');
 
@@ -57,46 +60,124 @@ const compare = (results) => {
   }
 };
 
-// RFC 2045: base64 body lines are at most 76 characters, CRLF-separated.
-const LINE = 76;
-const base64Lines = (buffer) => {
-  const text = buffer.toString('base64');
-  const lines = [];
-  for (let i = 0; i < text.length; i += LINE) lines.push(text.slice(i, i + LINE));
-  return lines.join('\r\n');
+const textMessage = createMessage({
+  from: 'Acme <no-reply@acme.example>',
+  to: 'Алекс <alex@example.com>',
+  subject: 'Скидання пароля: перейдіть за посиланням, щоб задати новий',
+  content: {
+    text: 'Перейдіть за посиланням, щоб скинути пароль: https://acme.example/reset/abc123\n'.repeat(
+      20,
+    ),
+    html: '<p>Перейдіть за <a href="https://acme.example/reset/abc123">посиланням</a>.</p>'.repeat(
+      20,
+    ),
+  },
+});
+
+const attachmentMessage = createMessage({
+  from: 'no-reply@acme.example',
+  to: 'alex@example.com',
+  subject: 'Your invoice',
+  content: { text: 'The invoice is attached.' },
+  attachments: [
+    {
+      inline: false,
+      filename: 'рахунок за жовтень.pdf',
+      content: ATTACHMENT_1M,
+      contentType: 'application/pdf',
+      contentId: '',
+    },
+  ],
+});
+
+const composeAndRead = async (message, options) => {
+  const composed = await composeMessage(message, options);
+  return readAttachmentContent(composed.content);
 };
 
-const main = () => {
+// A socket that takes every write at once and answers the end of DATA.
+const fakeSocket = () => {
+  const socket = Object.assign(new EventEmitter(), { destroyed: false, writable: true });
+  socket.destroy = () => {};
+  socket.write = (chunk, callback) => {
+    callback?.();
+    if (chunk.length === 3 && chunk[0] === 0x2e) {
+      queueMicrotask(() => socket.emit('data', Buffer.from('250 ok\r\n')));
+    }
+    return true;
+  };
+  return socket;
+};
+
+// One megabyte of text lines, a third of them starting with a dot.
+const dottedBody = Buffer.from(
+  Array.from({ length: 16384 }, (_, i) => (i % 3 === 0 ? '.' : 'x').repeat(62)).join('\r\n') +
+    '\r\n',
+);
+
+const main = async () => {
   if (!json) console.log(`Node ${process.version} | ${new Date().toISOString()}\n`);
   const { privateKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 });
-  const hmacKey = crypto.randomBytes(32);
-  const recordJson = JSON.stringify(OUTBOX_RECORD);
-  const slow = { warmup: 50 };
+  const dkim = {
+    signatures: [
+      {
+        signingDomain: 'acme.example',
+        selector: 'mail',
+        privateKey: privateKey.export({ type: 'pkcs8', format: 'pem' }),
+      },
+    ],
+  };
+  const strategy = new PriorityStrategy();
+  const transports = Array.from({ length: 10 }, (_, i) => ({
+    transport: { id: `t${i}` },
+    enabled: true,
+    priority: i % 3,
+    weight: 1,
+  }));
+  const failure = new TypeError('fetch failed', {
+    cause: Object.assign(new Error('connect ECONNRESET'), { code: 'ECONNRESET' }),
+  });
+  const slow = { warmup: 20 };
 
   const scenarios = [
-    ['base64, 76-column lines — 100 KB attachment', () => base64Lines(ATTACHMENT_100K), slow],
-    ['base64, 76-column lines — 1 MB attachment', () => base64Lines(ATTACHMENT_1M), slow],
-    ['Message-ID — crypto.randomUUID()', () => `<${crypto.randomUUID()}@acme.example>`],
+    ['MIME — compose a text and HTML message', () => composeAndRead(textMessage), slow],
     [
-      'DKIM — RSA-SHA256 signature, 2048-bit key',
-      () => crypto.sign('sha256', Buffer.from(DKIM_HEADERS), privateKey),
+      'MIME — compose a message with a 1 MiB attachment',
+      () => composeAndRead(attachmentMessage),
       slow,
     ],
     [
-      'Audit log — SHA-256 of an outbox record',
-      () => crypto.createHash('sha256').update(recordJson).digest('hex'),
+      'DKIM — compose and sign a text message (RSA-2048)',
+      () => composeAndRead(textMessage, { dkim }),
+      slow,
+    ],
+    [
+      'SMTP — dot-stuff and write 1 MiB of message data',
+      () =>
+        writeMessageData(
+          fakeSocket(),
+          async function* () {
+            yield dottedBody;
+          },
+          60_000,
+          () => {},
+        ),
+      slow,
     ],
+    ['Address — isEmailAddress', () => isEmailAddress(ADDRESS)],
+    ['Receipt — classifyReceiptError of a reset', () => classifyReceiptError(failure)],
     [
-      'Audit log — HMAC-SHA256 of an address',
-      () => crypto.createHmac('sha256', hmacKey).update(ADDRESS).digest('hex'),
+      'Pool — select by priority among 10 transports',
+      () => strategy.select(textMessage, transports, new Set()),
     ],
-    ['Outbox — JSON.stringify of a record', () => JSON.stringify(OUTBOX_RECORD)],
-    ['Outbox — JSON.parse of a record', () => JSON.parse(recordJson)],
   ];
 
   const results = [];
   for (const [name, fn, options] of scenarios) {
-    if (name.includes(filter)) results.push(bench(name, fn, { ...options, quiet: json }));
+    if (!name.includes(filter)) continue;
+    const isAsync = fn() instanceof Promise;
+    const run = isAsync ? benchAsync : bench;
+    results.push(await run(name, fn, { ...options, quiet: json }));
   }
   if (json) console.log(JSON.stringify(results, null, 2));
   if (flags.has('--save')) {
diff --git a/bench/helpers.js b/bench/helpers.js
index 4255bf4..463048e 100644
--- a/bench/helpers.js
+++ b/bench/helpers.js
@@ -19,6 +19,23 @@ const bench = (name, fn, options = {}) => {
   return { name, opsPerSec };
 };
 
+// The same measure for an asynchronous scenario, each call awaited.
+const benchAsync = async (name, fn, options = {}) => {
+  const { warmup = WARMUP_ITERATIONS, measureMs = MEASURE_MS, quiet = false } = options;
+  for (let i = 0; i < warmup; i++) await fn();
+  let iterations = 0;
+  const start = performance.now();
+  while (performance.now() - start < measureMs) {
+    await fn();
+    iterations++;
+  }
+  const elapsed = performance.now() - start;
+  const opsPerSec = Math.round((iterations / elapsed) * 1000);
+  const ops = opsPerSec.toLocaleString('en-US').padStart(12);
+  if (!quiet) console.log(`${name.padEnd(52)} ${ops} ops/sec`);
+  return { name, opsPerSec };
+};
+
 // Deterministic bytes, so a run measures the same input on every machine.
 const bytes = (size) => {
   const buffer = Buffer.alloc(size);
@@ -26,48 +43,8 @@ const bytes = (size) => {
   return buffer;
 };
 
-const ATTACHMENT_100K = bytes(100 * 1024);
 const ATTACHMENT_1M = bytes(1024 * 1024);
 
 const ADDRESS = 'alex@example.com';
 
-// The record an outbox keeps per message: what to send, to whom, and where it
-// is in its lifecycle.
-const OUTBOX_RECORD = {
-  id: '0193a7c2-6f1e-7c4b-9a51-3d2e8f6b1c0a',
-  tenantId: 'acme',
-  idempotencyKey: 'acme:password-reset:alex@example.com:2026-10-14T10',
-  state: 'queued',
-  attempt: 0,
-  createdAt: '2026-10-14T10:15:00.000Z',
-  message: {
-    from: 'Acme <no-reply@acme.example>',
-    to: ['alex@example.com'],
-    subject: 'Reset your password',
-    text: 'Follow the link to reset your password: https://acme.example/reset/abc123',
-    html: '<p>Follow the <a href="https://acme.example/reset/abc123">link</a> to reset it.</p>',
-    headers: { 'X-Entity-Ref-ID': 'reset-abc123' },
-    tags: { kind: 'password-reset' },
-  },
-};
-
-// The header block a DKIM signature covers (relaxed canonicalization of
-// From, To, Subject, Date and Message-ID, then the DKIM-Signature itself).
-const DKIM_HEADERS = [
-  'from:Acme <no-reply@acme.example>',
-  'to:alex@example.com',
-  'subject:Reset your password',
-  'date:Wed, 14 Oct 2026 10:15:00 +0000',
-  'message-id:<0193a7c2-6f1e-7c4b-9a51-3d2e8f6b1c0a@acme.example>',
-  'dkim-signature:v=1; a=rsa-sha256; c=relaxed/relaxed; d=acme.example; s=mail; ' +
-    'h=from:to:subject:date:message-id; bh=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=; b=',
-].join('\r\n');
-
-module.exports = {
-  bench,
-  ATTACHMENT_100K,
-  ATTACHMENT_1M,
-  ADDRESS,
-  OUTBOX_RECORD,
-  DKIM_HEADERS,
-};
+module.exports = { bench, benchAsync, ATTACHMENT_1M, ADDRESS };

From 0472adbc6faafeab962c95abb1e0172ba38e635d Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:06:51 +0300
Subject: [PATCH 064/158] perf(mime): encode attachments with Buffer and write
 lines into one buffer

base64() built a binary string from 8 KiB slices with String.fromCharCode
and passed it to btoa, about 180 times slower than Buffer on large input,
and encodeAttachment wrapped every chunk by pushing 76-character slices
into an array, joining them and encoding the result again with a new
TextEncoder. base64() now encodes with Buffer over the same memory, the
encoder of utf8() is created once, and the wrapping writes the ASCII text
and its CRLFs straight into one buffer.

Composing a message with a 1 MiB attachment: 9.2 times as fast (40 to 368
ops/sec on the benchmark, Node 24); a text and HTML message: +13%.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mime/bytes.js       | 19 ++++++++++++-------
 src/mime/mime-stream.js | 19 ++++++++++++++-----
 2 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/src/mime/bytes.js b/src/mime/bytes.js
index 5b7e961..0c87272 100644
--- a/src/mime/bytes.js
+++ b/src/mime/bytes.js
@@ -1,17 +1,22 @@
 // Ported from upyo v0.7.0 (packages/mime/src/bytes.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { Buffer } = require('node:buffer');
+
+const ENCODER = new TextEncoder();
+
 /** @internal */
 const utf8 = (value) => {
-  return new TextEncoder().encode(value);
+  return ENCODER.encode(value);
 };
-/** @internal */
+/**
+ * Encodes bytes as base64 with `Buffer`, over the same memory: upstream built
+ * a binary string with `String.fromCharCode` for `btoa`, about 180 times
+ * slower on an attachment.
+ * @internal
+ */
 const base64 = (bytes) => {
-  let binary = '';
-  for (let offset = 0; offset < bytes.length; offset += 8192) {
-    binary += String.fromCharCode(...bytes.subarray(offset, offset + 8192));
-  }
-  return btoa(binary);
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64');
 };
 
 module.exports = { utf8, base64 };
diff --git a/src/mime/mime-stream.js b/src/mime/mime-stream.js
index e323c2a..7c226ab 100644
--- a/src/mime/mime-stream.js
+++ b/src/mime/mime-stream.js
@@ -2,27 +2,36 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { iterateAttachmentContent } = require('../core/attachment.js');
-const { base64, utf8 } = require('./bytes.js');
+const { Buffer } = require('node:buffer');
+const { base64 } = require('./bytes.js');
 
 /** Encodes base64 without retaining producer-owned carry bytes. */
 const encodeAttachment = async function* (content, signal, progress) {
   const carry = new Uint8Array(3);
   let carried = 0;
   let column = 0;
+  // The base64 text is ASCII, so it is written straight into one buffer with
+  // a CRLF after every 76 characters of the attachment, without joining
+  // strings and encoding them again.
   const wrap = (encoded) => {
-    const parts = [];
+    const firstBreak = column === 76 ? 0 : 76 - column;
+    const lineBreaks =
+      encoded.length > firstBreak ? Math.ceil((encoded.length - firstBreak) / 76) : 0;
+    const output = Buffer.allocUnsafe(encoded.length + 2 * lineBreaks);
+    let written = 0;
     let offset = 0;
     while (offset < encoded.length) {
       if (column === 76) {
-        parts.push('\r\n');
+        output[written++] = 0x0d;
+        output[written++] = 0x0a;
         column = 0;
       }
       const take = Math.min(76 - column, encoded.length - offset);
-      parts.push(encoded.slice(offset, offset + take));
+      written += output.latin1Write(encoded.slice(offset, offset + take), written);
       offset += take;
       column += take;
     }
-    return utf8(parts.join(''));
+    return output;
   };
   let processed = 0;
   for await (const chunk of iterateAttachmentContent(content, signal)) {

From b207cca6f7418b76742d0583de005ec3ff4f5abc Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:14:40 +0300
Subject: [PATCH 065/158] perf(smtp): dot-stuff message data by searching for
 line feeds

writeMessageData walked every byte of the message data with for...of,
through the iterator protocol, to double the dot that starts a line, into
a buffer twice the size of each window. stuffDots now finds the line feeds
with Buffer#indexOf, counts the dots that start a line, and copies the runs
between them into a buffer of the exact size; the copy still keeps the
producer's bytes out of the socket's queue.

Writing 1 MiB of message data, a third of its lines starting with a dot:
2.5 times as fast (297 to 740 ops/sec on the benchmark, Node 24).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/smtp/data-stream.js | 47 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 39 insertions(+), 8 deletions(-)

diff --git a/src/smtp/data-stream.js b/src/smtp/data-stream.js
index 01d0838..c6d3ea1 100644
--- a/src/smtp/data-stream.js
+++ b/src/smtp/data-stream.js
@@ -24,6 +24,42 @@ class SmtpDeliveryUnknownError extends Error {
   }
 }
 
+/**
+ * Copies a window of message data with a dot doubled at the start of every
+ * line (RFC 5321 §4.5.2), finding the line feeds with indexOf rather than
+ * looking at every byte.  The copy keeps the producer's bytes out of the
+ * socket's queue.
+ *
+ * @param bytes The bytes to send.
+ * @param isLineStart Whether the window starts a line.
+ * @returns The bytes to write.
+ */
+const stuffDots = (bytes, isLineStart) => {
+  const window = Buffer.isBuffer(bytes)
+    ? bytes
+    : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let dots = isLineStart && window[0] === 0x2e ? 1 : 0;
+  for (let end = window.indexOf(0x0a); end !== -1; end = window.indexOf(0x0a, end + 1)) {
+    if (window[end + 1] === 0x2e) dots++;
+  }
+  const output = Buffer.allocUnsafe(window.length + dots);
+  if (dots === 0) {
+    window.copy(output);
+    return output;
+  }
+  let written = 0;
+  let start = 0;
+  if (isLineStart && window[0] === 0x2e) output[written++] = 0x2e;
+  for (let end = window.indexOf(0x0a); end !== -1; end = window.indexOf(0x0a, end + 1)) {
+    if (window[end + 1] !== 0x2e) continue;
+    written += window.copy(output, written, start, end + 1);
+    output[written++] = 0x2e;
+    start = end + 1;
+  }
+  window.copy(output, written, start);
+  return output;
+};
+
 const prepareOnSocket = async (socket, timeoutMs, prepare, signal) => {
   const controller = new AbortController();
   const combined = combineSignals(controller.signal, signal);
@@ -187,14 +223,9 @@ const writeMessageData = async (socket, source, timeoutMs, checkSize, signal) =>
         size += window.length;
         checkSize(size);
         progress();
-        const output = Buffer.allocUnsafe(window.length * 2);
-        let length = 0;
-        for (const byte of window) {
-          if (lineStart && byte === 46) output[length++] = 46;
-          output[length++] = byte;
-          lineStart = byte === 10;
-        }
-        await write(output.subarray(0, length));
+        const output = stuffDots(window, lineStart);
+        lineStart = window[window.length - 1] === 0x0a;
+        await write(output);
       }
     }
     owned.throwIfAborted();

From f6a27c714ee381a5123aed5939aae8b64efdf5da Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:15:26 +0300
Subject: [PATCH 066/158] perf(core): check raw message bytes in an index loop

The checks of a raw message (CRLF only, no NUL, lines of 998 octets at
most, bytes within the declared encoding) look at every byte, and did so
through for...of, whose iterator protocol cost more than the checks. An
index loop does the same: validating 4 MiB went from 23.5 to 17.3 ms on
Node 24. It runs twice for a raw message whose encoding is not declared.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/core/raw-message.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/core/raw-message.js b/src/core/raw-message.js
index 4b5ec1f..236b96f 100644
--- a/src/core/raw-message.js
+++ b/src/core/raw-message.js
@@ -105,7 +105,10 @@ const iterateRawMessage = async function* (plan, options = {}) {
     for (let start = 0; start < chunk.length; start += 32768) {
       options.signal?.throwIfAborted();
       const window = chunk.subarray(start, start + 32768);
-      for (const byte of window) {
+      // An index loop: the iterator protocol of for...of costs more than the
+      // checks on each byte.
+      for (let index = 0; index < window.length; index++) {
+        const byte = window[index];
         if (pendingCr) {
           if (byte !== 10) fail('Expected LF after CR.');
           if (line === 1 && column === 0) {

From 336a83279a11df19ba6e9433efddd8dd6791fd21 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:17:46 +0300
Subject: [PATCH 067/158] perf(mime): build quoted-printable and encoded words
 without quadratic work

encodeQuotedPrintable concatenated a string per byte and formatted every
escape with toString(16).toUpperCase().padStart(2, '0'); a Cyrillic body,
where every byte is escaped, paid that for each of them. It now writes into
one buffer with a table of hex digits.

encodeHeaderValue cut a long value into encoded words by encoding the
growing word again, with a new TextEncoder, for every character, which is
quadratic in the length of the value; it now adds up the UTF-8 length of
each character and cuts at the 45 bytes an encoded word holds (75
characters), the same rule. It also splits the value into words only when a
long ASCII word matters. The checks of the 998-octet line limit measure
lines with Buffer.byteLength instead of encoding them.

Both produce the same output as before on 5,000 random values (ASCII,
Cyrillic, emoji, line breaks, dots and spaces). Composing a text and HTML
message in Ukrainian: 2.4 times as fast as the baseline (+138%).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mime/message.js | 114 +++++++++++++++++++++++++++-----------------
 src/mime/stream.js  |   3 +-
 2 files changed, 72 insertions(+), 45 deletions(-)

diff --git a/src/mime/message.js b/src/mime/message.js
index 1a8342a..28badb7 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/mime/src/message.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { Buffer } = require('node:buffer');
 const { formatPhrase } = require('../core/address.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { checkAttachment } = require('../core/message.js');
@@ -490,44 +491,51 @@ const encodeAddress = (address) => {
   return `${displayName} <${address.address}>`;
 };
 
-const encodeHeaderValue = (value, encodeLongAsciiWords = false) => {
-  // RFC 2047 encoding for non-ASCII characters in headers
-  const hasLongWord = value.split(/\s+/).some((word) => word.length > 60);
-  if (!/^[\x20-\x7E]*$/.test(value) || (encodeLongAsciiWords && hasLongWord)) {
-    const encodeWord = (text) => {
-      const utf8Bytes = new TextEncoder().encode(text);
-      const encoded = base64(utf8Bytes);
-      return `=?UTF-8?B?${encoded}?=`;
-    };
-    const maxEncodedLength = 75;
-    const encodedWord = encodeWord(value);
-
-    if (encodedWord.length <= maxEncodedLength) {
-      return encodedWord;
-    }
+// Whether a word of the value, between whitespace, is longer than `limit`.
+const hasWordLongerThan = (value, limit) => {
+  let run = 0;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    const isSpace = code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d;
+    run = isSpace ? 0 : run + 1;
+    if (run > limit) return true;
+  }
+  return false;
+};
 
-    const words = [];
-    let currentText = '';
+// An encoded word holds at most 45 bytes of text: `=?UTF-8?B?` and `?=` take
+// 12 of its 75 characters, and 45 bytes are 60 in base64.
+const MAX_ENCODED_WORD_BYTES = 45;
 
-    for (const character of value) {
-      const candidate = currentText + character;
-      if (encodeWord(candidate).length <= maxEncodedLength) {
-        currentText = candidate;
-      } else {
-        if (currentText.length > 0) {
-          words.push(encodeWord(currentText));
-        }
-        currentText = character;
-      }
-    }
+const encodeWord = (text) => `=?UTF-8?B?${base64(utf8(text))}?=`;
 
-    if (currentText.length > 0) {
-      words.push(encodeWord(currentText));
-    }
+const encodeHeaderValue = (value, encodeLongAsciiWords = false) => {
+  // RFC 2047 encoding for non-ASCII characters in headers
+  const isPrintableAscii = /^[\x20-\x7E]*$/.test(value);
+  if (isPrintableAscii && !(encodeLongAsciiWords && hasWordLongerThan(value, 60))) {
+    return value;
+  }
 
-    return words.join(' ');
+  // Each word takes as many whole characters as fit, counted by their UTF-8
+  // length: upstream encoded the growing word again for every character.
+  const words = [];
+  let wordStart = 0;
+  let wordBytes = 0;
+  for (let i = 0; i < value.length;) {
+    const codePoint = value.codePointAt(i);
+    const characterLength = codePoint > 0xffff ? 2 : 1;
+    const characterBytes =
+      codePoint < 0x80 ? 1 : codePoint < 0x800 ? 2 : codePoint < 0x10000 ? 3 : 4;
+    if (wordBytes + characterBytes > MAX_ENCODED_WORD_BYTES) {
+      words.push(encodeWord(value.slice(wordStart, i)));
+      wordStart = i;
+      wordBytes = 0;
+    }
+    wordBytes += characterBytes;
+    i += characterLength;
   }
-  return value;
+  if (wordStart < value.length) words.push(encodeWord(value.slice(wordStart)));
+  return words.join(' ');
 };
 
 const encodeMimeParameter = (name, value) => {
@@ -609,20 +617,32 @@ const foldHeader = (name, value) => {
   }
 
   lines.push(prefix + remaining);
-  if (lines.some((line) => utf8(line).length > 998)) {
+  if (lines.some((line) => Buffer.byteLength(line) > 998)) {
     throw new RangeError(`Header field ${name} contains a token too long to fold.`);
   }
   return lines.join('\r\n');
 };
 
+// The digits of an escaped byte, as character codes.
+const HEX_DIGITS = Buffer.from('0123456789ABCDEF', 'latin1');
+
+/**
+ * Encodes text as quoted-printable (RFC 2045 §6.7), written byte by byte into
+ * one buffer: upstream concatenated a string per byte and formatted every
+ * escape with toString(16).
+ */
 const encodeQuotedPrintable = (text) => {
   const bytes = utf8(text);
-  let result = '';
+  // At most three characters per byte, and a soft line break of three per
+  // 25 escaped bytes.
+  const output = Buffer.allocUnsafe(bytes.length * 3 + Math.ceil(bytes.length / 25) * 3 + 3);
+  let written = 0;
   let column = 0;
   for (let i = 0; i < bytes.length; i++) {
     const byte = bytes[i];
     if (byte === 13 && bytes[i + 1] === 10) {
-      result += '\r\n';
+      output[written++] = 13;
+      output[written++] = 10;
       column = 0;
       i++;
       continue;
@@ -633,17 +653,23 @@ const encodeQuotedPrintable = (text) => {
       byte === 61 ||
       (byte === 32 && (i + 1 === bytes.length || bytes[i + 1] === 13 || bytes[i + 1] === 10)) ||
       (byte === 46 && column === 0);
-    const encoded = escaped
-      ? `=${byte.toString(16).toUpperCase().padStart(2, '0')}`
-      : String.fromCharCode(byte);
-    if (column + encoded.length > 75) {
-      result += '=\r\n';
+    const width = escaped ? 3 : 1;
+    if (column + width > 75) {
+      output[written++] = 61;
+      output[written++] = 13;
+      output[written++] = 10;
       column = 0;
     }
-    result += encoded;
-    column += encoded.length;
+    if (escaped) {
+      output[written++] = 61;
+      output[written++] = HEX_DIGITS[byte >> 4];
+      output[written++] = HEX_DIGITS[byte & 15];
+    } else {
+      output[written++] = byte;
+    }
+    column += width;
   }
-  return result;
+  return output.toString('latin1', 0, written);
 };
 
 module.exports = { prepareMimeMessage };
diff --git a/src/mime/stream.js b/src/mime/stream.js
index 6ff8104..8f68d2d 100644
--- a/src/mime/stream.js
+++ b/src/mime/stream.js
@@ -3,6 +3,7 @@
 
 const { createHash } = require('node:crypto');
 const { RawMessageValidationError } = require('../core/raw-message.js');
+const { Buffer } = require('node:buffer');
 const { base64, utf8 } = require('./bytes.js');
 const { BodyHasher } = require('./dkim/body-hash.js');
 const { signWithBodyHash } = require('./dkim/sign.js');
@@ -77,7 +78,7 @@ const prepareMimeStream = async (plan, options = {}) => {
     console.warn('DKIM signing failed, sending unsigned:', error);
   }
   signal?.throwIfAborted();
-  if (headers.split('\r\n').some((line) => utf8(line).length > 998)) {
+  if (headers.split('\r\n').some((line) => Buffer.byteLength(line) > 998)) {
     throw new RangeError('Signed MIME header exceeds the RFC 5322 line limit.');
   }
   const size = utf8(headers).length + length;

From ac5d6eb5b5370b5f5f050cab58dc53254152b78a Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:20:23 +0300
Subject: [PATCH 068/158] perf: encode provider attachments with one
 Buffer-based encoder

Seven converters carried their own base64: ./ses and ./sendgrid built a
binary string with String.fromCharCode for btoa, ./resend concatenated four
characters per three bytes, ./plunk mapped every byte with Array.from, and
./lettermint, ./mailtrap and ./maileroo tried Uint8Array#toBase64 and
Buffer before falling back to btoa. src/internal/base64.js encodes with
Buffer over the same memory: 0.9 ms for 5 MiB, against 116 ms for
String.fromCharCode with btoa, with the same output.

Node always has Buffer, so the fallbacks for other runtimes go, with the
six ported tests that exercised them (left out with a comment, as the
tests of runtimes without AbortSignal.any were).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/internal/base64.js                        |  17 ++
 src/lettermint/message-converter.js           |  26 +--
 src/maileroo/message-converter.js             |  47 +----
 src/mailtrap/message-converter.js             |  47 +----
 src/plunk/message-converter.js                |  14 +-
 src/resend/message-converter.js               |  39 +---
 src/sendgrid/message-converter.js             |   8 +-
 src/ses/message-converter.js                  |   7 +-
 .../unit/lettermint-message-converter.test.js |  29 +--
 tests/unit/maileroo-message-converter.test.js | 192 +-----------------
 tests/unit/mailtrap-message-converter.test.js |  59 +-----
 11 files changed, 37 insertions(+), 448 deletions(-)
 create mode 100644 src/internal/base64.js

diff --git a/src/internal/base64.js b/src/internal/base64.js
new file mode 100644
index 0000000..d712727
--- /dev/null
+++ b/src/internal/base64.js
@@ -0,0 +1,17 @@
+// Not ported from upyo: the one base64 encoder of the HTTP providers, which
+// carried seven, from String.fromCharCode with btoa to string concatenation
+// byte by byte, all far slower than Buffer, which Node always has.
+
+const { Buffer } = require('node:buffer');
+
+/**
+ * Encodes bytes as base64, over the same memory.
+ *
+ * @param bytes The bytes to encode.
+ * @returns The base64 text.
+ * @internal
+ */
+const toBase64 = (bytes) =>
+  Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64');
+
+module.exports = { toBase64 };
diff --git a/src/lettermint/message-converter.js b/src/lettermint/message-converter.js
index 5991b55..de7f865 100644
--- a/src/lettermint/message-converter.js
+++ b/src/lettermint/message-converter.js
@@ -5,6 +5,7 @@ const { createCalendarAttachment } = require('../core/calendar.js');
 const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
+const { toBase64 } = require('../internal/base64.js');
 
 const STANDARD_HEADERS = new Set([
   'from',
@@ -162,7 +163,7 @@ const convertAttachment = async (attachment, signal) => {
   const content = await readAttachmentContent(attachment.content, signal);
   const converted = {
     filename: attachment.filename,
-    content: uint8ArrayToBase64(content),
+    content: toBase64(content),
     content_type: attachment.contentType,
   };
 
@@ -173,29 +174,6 @@ const convertAttachment = async (attachment, signal) => {
   return converted;
 };
 
-const uint8ArrayToBase64 = (bytes) => {
-  const nativeToBase64 = getNativeToBase64(bytes);
-  if (nativeToBase64 != null) {
-    return nativeToBase64();
-  }
-
-  const chunkSize = 0x8000;
-  const chunks = [];
-
-  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
-    chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + chunkSize)));
-  }
-
-  return btoa(chunks.join(''));
-};
-
-const getNativeToBase64 = (bytes) => {
-  const candidate = bytes;
-  const toBase64 = candidate.toBase64;
-  if (typeof toBase64 !== 'function') return undefined;
-  return () => toBase64.call(bytes);
-};
-
 const isStandardHeader = (headerName) => {
   return STANDARD_HEADERS.has(headerName.toLowerCase());
 };
diff --git a/src/maileroo/message-converter.js b/src/maileroo/message-converter.js
index cdb2247..1ecfb6b 100644
--- a/src/maileroo/message-converter.js
+++ b/src/maileroo/message-converter.js
@@ -5,6 +5,7 @@ const { createCalendarAttachment } = require('../core/calendar.js');
 const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
+const { toBase64 } = require('../internal/base64.js');
 
 const STANDARD_HEADERS = new Set([
   'from',
@@ -193,7 +194,7 @@ const convertAttachment = async (attachment, signal) => {
   return {
     file_name: getAttachmentFileName(attachment),
     content_type: attachment.contentType,
-    content: uint8ArrayToBase64(content),
+    content: toBase64(content),
     inline: attachment.inline || undefined,
   };
 };
@@ -206,50 +207,6 @@ const getAttachmentFileName = (attachment) => {
     : attachment.filename;
 };
 
-const uint8ArrayToBase64 = (bytes) => {
-  const nativeToBase64 = getNativeToBase64(bytes);
-  if (nativeToBase64 != null) {
-    return nativeToBase64();
-  }
-
-  const bufferBase64 = getBufferBase64(bytes);
-  if (bufferBase64 != null) {
-    return bufferBase64;
-  }
-
-  const chunkSize = 4096;
-  const chunks = [];
-
-  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
-    chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + chunkSize)));
-  }
-
-  return btoa(chunks.join(''));
-};
-
-const getNativeToBase64 = (bytes) => {
-  const candidate = bytes;
-  const toBase64 = candidate.toBase64;
-  if (typeof toBase64 !== 'function') return undefined;
-  return () => toBase64.call(bytes);
-};
-
-const getBufferBase64 = (bytes) => {
-  const candidate = globalThis.Buffer;
-  if (typeof candidate?.from !== 'function') return undefined;
-
-  try {
-    const buffer = candidate.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    if (buffer == null || typeof buffer.toString !== 'function') {
-      return undefined;
-    }
-    const base64 = buffer.toString('base64');
-    return typeof base64 === 'string' ? base64 : undefined;
-  } catch {
-    return undefined;
-  }
-};
-
 const isStandardHeader = (headerName) => {
   return STANDARD_HEADERS.has(headerName.toLowerCase());
 };
diff --git a/src/mailtrap/message-converter.js b/src/mailtrap/message-converter.js
index 6244a7e..c265f9b 100644
--- a/src/mailtrap/message-converter.js
+++ b/src/mailtrap/message-converter.js
@@ -5,6 +5,7 @@ const { createCalendarAttachment } = require('../core/calendar.js');
 const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
+const { toBase64 } = require('../internal/base64.js');
 
 const STANDARD_HEADERS = new Set([
   'from',
@@ -159,7 +160,7 @@ const convertAttachment = async (attachment, signal) => {
   const contentBytes = await readAttachmentContent(attachment.content, signal);
   signal?.throwIfAborted();
   const converted = {
-    content: uint8ArrayToBase64(contentBytes),
+    content: toBase64(contentBytes),
     filename: attachment.filename,
   };
 
@@ -177,50 +178,6 @@ const convertAttachment = async (attachment, signal) => {
   return converted;
 };
 
-const uint8ArrayToBase64 = (bytes) => {
-  const nativeToBase64 = getNativeToBase64(bytes);
-  if (nativeToBase64 != null) {
-    return nativeToBase64();
-  }
-
-  const bufferBase64 = getBufferBase64(bytes);
-  if (bufferBase64 != null) {
-    return bufferBase64;
-  }
-
-  const chunkSize = 0x1000;
-  const chunks = [];
-
-  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
-    chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + chunkSize)));
-  }
-
-  return btoa(chunks.join(''));
-};
-
-const getNativeToBase64 = (bytes) => {
-  const candidate = bytes;
-  const toBase64 = candidate.toBase64;
-  if (typeof toBase64 !== 'function') return undefined;
-  return () => toBase64.call(bytes);
-};
-
-const getBufferBase64 = (bytes) => {
-  const candidate = globalThis.Buffer;
-  if (typeof candidate?.from !== 'function') return undefined;
-
-  try {
-    const buffer = candidate.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    if (buffer == null || typeof buffer.toString !== 'function') {
-      return undefined;
-    }
-    const base64 = buffer.toString('base64');
-    return typeof base64 === 'string' ? base64 : undefined;
-  } catch {
-    return undefined;
-  }
-};
-
 const isStandardHeader = (headerName) => {
   return STANDARD_HEADERS.has(headerName.toLowerCase());
 };
diff --git a/src/plunk/message-converter.js b/src/plunk/message-converter.js
index 6d3fb35..9af1887 100644
--- a/src/plunk/message-converter.js
+++ b/src/plunk/message-converter.js
@@ -4,6 +4,7 @@
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
+const { toBase64 } = require('../internal/base64.js');
 
 /**
  * Converts a Upyo message to Plunk API format.
@@ -144,7 +145,7 @@ const convertAttachment = async (attachment, signal) => {
     const content = await readAttachmentContent(attachment.content, signal);
 
     // Convert to base64
-    const base64Content = arrayBufferToBase64(content);
+    const base64Content = toBase64(content);
 
     return {
       filename: attachment.filename,
@@ -160,15 +161,4 @@ const convertAttachment = async (attachment, signal) => {
   }
 };
 
-/**
- * Converts an ArrayBuffer or Uint8Array to base64 string.
- *
- * @param buffer - The buffer to convert
- * @returns Base64 encoded string
- */
-const arrayBufferToBase64 = (buffer) => {
-  const binaryString = Array.from(buffer, (byte) => String.fromCharCode(byte)).join('');
-  return btoa(binaryString);
-};
-
 module.exports = { convertMessage };
diff --git a/src/resend/message-converter.js b/src/resend/message-converter.js
index 86f7e25..584dd38 100644
--- a/src/resend/message-converter.js
+++ b/src/resend/message-converter.js
@@ -6,6 +6,7 @@ const { createCalendarAttachment } = require('../core/calendar.js');
 const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
+const { toBase64 } = require('../internal/base64.js');
 
 /**
  * Converts a Upyo Message to Resend API JSON format.
@@ -182,7 +183,7 @@ const convertAttachment = async (attachment, signal) => {
   const content = await readAttachmentContent(attachment.content, signal);
   const resendAttachment = {
     filename: attachment.filename,
-    content: await uint8ArrayToBase64(content),
+    content: toBase64(content),
   };
 
   if (attachment.contentType) {
@@ -192,42 +193,6 @@ const convertAttachment = async (attachment, signal) => {
   return resendAttachment;
 };
 
-/**
- * Converts a Uint8Array to base64 string using pure JavaScript implementation.
- * This avoids deprecated APIs like btoa() and Node.js-specific Buffer.
- *
- * @param bytes - The Uint8Array to convert
- * @returns Base64 encoded string
- */
-const uint8ArrayToBase64 = (bytes) => {
-  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-  let result = '';
-  let i = 0;
-
-  while (i < bytes.length) {
-    const a = bytes[i++];
-    const b = i < bytes.length ? bytes[i++] : 0;
-    const c = i < bytes.length ? bytes[i++] : 0;
-
-    const bitmap = (a << 16) | (b << 8) | c;
-
-    result +=
-      chars.charAt((bitmap >> 18) & 63) +
-      chars.charAt((bitmap >> 12) & 63) +
-      chars.charAt((bitmap >> 6) & 63) +
-      chars.charAt(bitmap & 63);
-  }
-
-  // Add padding
-  const remainder = bytes.length % 3;
-  if (remainder !== 0) {
-    const padding = 3 - remainder;
-    result = result.slice(0, -padding) + '='.repeat(padding);
-  }
-
-  return result;
-};
-
 /**
  * Checks if a header is a standard email header that should not be prefixed.
  *
diff --git a/src/sendgrid/message-converter.js b/src/sendgrid/message-converter.js
index 30da53c..7a51c32 100644
--- a/src/sendgrid/message-converter.js
+++ b/src/sendgrid/message-converter.js
@@ -5,6 +5,7 @@ const { createCalendarAttachment } = require('../core/calendar.js');
 const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
+const { toBase64 } = require('../internal/base64.js');
 
 /**
  * Converts a Upyo Message to SendGrid API JSON format.
@@ -211,12 +212,7 @@ const convertAttachment = async (attachment, signal) => {
   // Get the content as Uint8Array then convert to base64
   const contentBytes = await readAttachmentContent(attachment.content, signal);
 
-  // Convert to base64
-  const parts = [];
-  for (let offset = 0; offset < contentBytes.length; offset += 8192) {
-    parts.push(String.fromCharCode(...contentBytes.subarray(offset, offset + 8192)));
-  }
-  const base64Content = btoa(parts.join(''));
+  const base64Content = toBase64(contentBytes);
 
   const sendGridAttachment = {
     content: base64Content,
diff --git a/src/ses/message-converter.js b/src/ses/message-converter.js
index c744334..f8436b3 100644
--- a/src/ses/message-converter.js
+++ b/src/ses/message-converter.js
@@ -5,6 +5,7 @@ const { combineSignals } = require('../core/abort-signal.js');
 const { formatQuotedMailbox: formatAddress } = require('../core/address.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
+const { toBase64 } = require('../internal/base64.js');
 
 const convertMessage = async (message, config, signal) => {
   const destination = {};
@@ -103,11 +104,7 @@ const createSimpleContent = async (message, signal) => {
       content.Attachments = await Promise.all(
         attachments.map(async (attachment) => {
           const contentBytes = await readAttachmentContent(attachment.content, combined.signal);
-          const parts = [];
-          for (let offset = 0; offset < contentBytes.length; offset += 8192) {
-            parts.push(String.fromCharCode(...contentBytes.subarray(offset, offset + 8192)));
-          }
-          const base64Content = btoa(parts.join(''));
+          const base64Content = toBase64(contentBytes);
 
           const converted = {
             FileName: attachment.filename,
diff --git a/tests/unit/lettermint-message-converter.test.js b/tests/unit/lettermint-message-converter.test.js
index 8f125d6..58f38d8 100644
--- a/tests/unit/lettermint-message-converter.test.js
+++ b/tests/unit/lettermint-message-converter.test.js
@@ -228,33 +228,8 @@ describe('convertMessage', () => {
     );
   });
 
-  it('uses native Uint8Array base64 conversion when available', async () => {
-    const content = new Uint8Array([1, 2, 3]);
-    Object.defineProperty(content, 'toBase64', {
-      configurable: true,
-      value() {
-        assert.deepEqual([...this], [1, 2, 3]);
-        return 'native-base64';
-      },
-    });
-
-    const result = await convertMessage(
-      createBaseMessage({
-        attachments: [
-          {
-            filename: 'native.bin',
-            content,
-            contentType: 'application/octet-stream',
-            inline: false,
-            contentId: '',
-          },
-        ],
-      }),
-      baseConfig,
-    );
-
-    assert.equal(result.attachments?.[0]?.content, 'native-base64');
-  });
+  // Left out: upstream's tests of base64 without Buffer or with Uint8Array#toBase64,
+  // fallbacks for other runtimes; on Node, Buffer is always there (CLAUDE.md, Platform).
 });
 
 describe('generateIdempotencyKey', () => {
diff --git a/tests/unit/maileroo-message-converter.test.js b/tests/unit/maileroo-message-converter.test.js
index 8d1646d..2b8a140 100644
--- a/tests/unit/maileroo-message-converter.test.js
+++ b/tests/unit/maileroo-message-converter.test.js
@@ -26,23 +26,6 @@ const createBaseMessage = (overrides = {}) => {
   };
 };
 
-let globalMutationChain = Promise.resolve();
-
-const withGlobalMutationLock = async (callback) => {
-  const previous = globalMutationChain;
-  let release = () => {};
-  globalMutationChain = new Promise((resolve) => {
-    release = resolve;
-  });
-  await previous;
-
-  try {
-    return await callback();
-  } finally {
-    release();
-  }
-};
-
 describe('convertMessage', { concurrency: false }, () => {
   it('converts a basic text message', async () => {
     const result = await convertMessage(createBaseMessage(), baseConfig);
@@ -319,179 +302,8 @@ describe('convertMessage', { concurrency: false }, () => {
     assert.equal(abortListeners, 0);
   });
 
-  it('uses native Uint8Array base64 conversion when available', async () => {
-    const content = new Uint8Array([1, 2, 3]);
-    Object.defineProperty(content, 'toBase64', {
-      configurable: true,
-      value() {
-        assert.deepEqual([...this], [1, 2, 3]);
-        return 'native-base64';
-      },
-    });
-
-    const result = await convertMessage(
-      createBaseMessage({
-        attachments: [
-          {
-            filename: 'native.bin',
-            content,
-            contentType: 'application/octet-stream',
-            inline: false,
-            contentId: '',
-          },
-        ],
-      }),
-      baseConfig,
-    );
-
-    assert.equal(result.attachments?.[0]?.content, 'native-base64');
-  });
-
-  it('uses Buffer base64 conversion when available', async () => {
-    await withGlobalMutationLock(async () => {
-      const content = new Uint8Array([1, 2, 3]);
-      Object.defineProperty(content, 'toBase64', {
-        configurable: true,
-        value: undefined,
-      });
-      const originalBuffer = Object.getOwnPropertyDescriptor(globalThis, 'Buffer');
-      let capturedBytes;
-      Object.defineProperty(globalThis, 'Buffer', {
-        configurable: true,
-        value: {
-          from(buffer, byteOffset, byteLength) {
-            capturedBytes = new Uint8Array(buffer, byteOffset, byteLength);
-            return {
-              toString(encoding) {
-                assert.equal(encoding, 'base64');
-                return 'buffer-base64';
-              },
-            };
-          },
-        },
-      });
-
-      try {
-        const result = await convertMessage(
-          createBaseMessage({
-            attachments: [
-              {
-                filename: 'buffer.bin',
-                content,
-                contentType: 'application/octet-stream',
-                inline: false,
-                contentId: '',
-              },
-            ],
-          }),
-          baseConfig,
-        );
-
-        assert.deepEqual([...(capturedBytes ?? [])], [1, 2, 3]);
-        assert.equal(result.attachments?.[0]?.content, 'buffer-base64');
-      } finally {
-        if (originalBuffer == null) {
-          delete globalThis.Buffer;
-        } else {
-          Object.defineProperty(globalThis, 'Buffer', originalBuffer);
-        }
-      }
-    });
-  });
-
-  it('falls back when the Buffer base64 converter is incomplete', async () => {
-    await withGlobalMutationLock(async () => {
-      const content = new Uint8Array([1, 2, 3]);
-      Object.defineProperty(content, 'toBase64', {
-        configurable: true,
-        value: undefined,
-      });
-      const originalBuffer = Object.getOwnPropertyDescriptor(globalThis, 'Buffer');
-      Object.defineProperty(globalThis, 'Buffer', {
-        configurable: true,
-        value: {
-          from() {
-            return { toString: undefined };
-          },
-        },
-      });
-
-      try {
-        const result = await convertMessage(
-          createBaseMessage({
-            attachments: [
-              {
-                filename: 'fallback.bin',
-                content,
-                contentType: 'application/octet-stream',
-                inline: false,
-                contentId: '',
-              },
-            ],
-          }),
-          baseConfig,
-        );
-
-        assert.equal(result.attachments?.[0]?.content, 'AQID');
-      } finally {
-        if (originalBuffer == null) {
-          delete globalThis.Buffer;
-        } else {
-          Object.defineProperty(globalThis, 'Buffer', originalBuffer);
-        }
-      }
-    });
-  });
-
-  it('keeps fallback base64 chunks small', async () => {
-    await withGlobalMutationLock(async () => {
-      const content = new Uint8Array(9000);
-      Object.defineProperty(content, 'toBase64', {
-        configurable: true,
-        value: undefined,
-      });
-      const originalBuffer = Object.getOwnPropertyDescriptor(globalThis, 'Buffer');
-      delete globalThis.Buffer;
-      const originalFromCharCode = String.fromCharCode;
-      const chunkLengths = [];
-      Object.defineProperty(String, 'fromCharCode', {
-        configurable: true,
-        value(...codes) {
-          chunkLengths.push(codes.length);
-          return originalFromCharCode(...codes);
-        },
-      });
-
-      try {
-        await convertMessage(
-          createBaseMessage({
-            attachments: [
-              {
-                filename: 'large.bin',
-                content,
-                contentType: 'application/octet-stream',
-                inline: false,
-                contentId: '',
-              },
-            ],
-          }),
-          baseConfig,
-        );
-      } finally {
-        Object.defineProperty(String, 'fromCharCode', {
-          configurable: true,
-          value: originalFromCharCode,
-        });
-        if (originalBuffer != null) {
-          Object.defineProperty(globalThis, 'Buffer', originalBuffer);
-        }
-      }
-
-      assert.ok(chunkLengths.every((length) => length <= 4096));
-      assert.ok(chunkLengths.includes(4096));
-      assert.ok(chunkLengths.includes(808));
-    });
-  });
+  // Left out: upstream's tests of base64 without Buffer or with Uint8Array#toBase64,
+  // fallbacks for other runtimes; on Node, Buffer is always there (CLAUDE.md, Platform).
 });
 
 const threadingConfig = createMailerooConfig({ apiKey: 'test-key' });
diff --git a/tests/unit/mailtrap-message-converter.test.js b/tests/unit/mailtrap-message-converter.test.js
index 115832a..07e66b6 100644
--- a/tests/unit/mailtrap-message-converter.test.js
+++ b/tests/unit/mailtrap-message-converter.test.js
@@ -27,63 +27,8 @@ const createBaseMessage = (overrides = {}) => {
 };
 
 describe('convertMessage', () => {
-  it('bounds fallback Base64 calls while preserving attachment bytes', async () => {
-    const nativeDescriptor = Object.getOwnPropertyDescriptor(Uint8Array.prototype, 'toBase64');
-    const bufferDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'Buffer');
-    const fromCharCode = String.fromCharCode;
-    const bytes = Uint8Array.from({ length: 1024 * 1024 + 1 }, (_, i) => i % 256);
-    const message = createBaseMessage({
-      attachments: [
-        {
-          filename: 'bytes.bin',
-          contentType: 'application/octet-stream',
-          contentId: 'bytes',
-          content: bytes,
-          inline: false,
-        },
-      ],
-    });
-    let largestCall = 0;
-
-    try {
-      // oxlint-disable-next-line no-extend-native -- upstream
-      Object.defineProperty(Uint8Array.prototype, 'toBase64', {
-        configurable: true,
-        value: undefined,
-      });
-      Object.defineProperty(globalThis, 'Buffer', {
-        configurable: true,
-        value: undefined,
-      });
-      String.fromCharCode = (...codes) => {
-        largestCall = Math.max(largestCall, codes.length);
-        assert.ok(codes.length <= 4096, 'Fallback calls must stay within 4096 arguments.');
-        return fromCharCode(...codes);
-      };
-
-      const result = await convertMessage(message, baseConfig);
-      assert.ok(largestCall > 0);
-      assert.ok(result.attachments);
-      const decoded = Uint8Array.from(atob(result.attachments[0].content), (character) =>
-        character.charCodeAt(0),
-      );
-      assert.deepEqual(decoded, bytes);
-    } finally {
-      String.fromCharCode = fromCharCode;
-      if (nativeDescriptor == null) {
-        Reflect.deleteProperty(Uint8Array.prototype, 'toBase64');
-      } else {
-        // oxlint-disable-next-line no-extend-native -- upstream
-        Object.defineProperty(Uint8Array.prototype, 'toBase64', nativeDescriptor);
-      }
-      if (bufferDescriptor == null) {
-        Reflect.deleteProperty(globalThis, 'Buffer');
-      } else {
-        Object.defineProperty(globalThis, 'Buffer', bufferDescriptor);
-      }
-    }
-  });
-
+  // Left out: upstream's tests of base64 without Buffer or with Uint8Array#toBase64,
+  // fallbacks for other runtimes; on Node, Buffer is always there (CLAUDE.md, Platform).
   it('converts a basic text message', async () => {
     const result = await convertMessage(createBaseMessage(), baseConfig);
 

From 4111b2d6c42800f4e21950bb73271a0b56991376 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:22:14 +0300
Subject: [PATCH 069/158] perf(smtp): look capabilities up by keyword in an
 index

EHLO capabilities were parsed with split, filter, slice, map and filter,
five passes, and every send then scanned the list again for SMTPUTF8,
8BITMIME, SIZE, DSN and PIPELINING, building a new RegExp for each check
of negotiate(), and once more for AUTH and STARTTLS. The reply is now
parsed in one loop, and capabilityLine() and hasCapability() read an index
of the lines by keyword (up to a space, a tab or the "=" of the old
AUTH=LOGIN form), built once and rebuilt when capabilities is replaced, as
tests do. The answers are the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/smtp/smtp-connection.js | 78 ++++++++++++++++++++++++++++---------
 src/smtp/smtp-transport.js  |  3 +-
 tests/unit/smtp.test.js     | 12 ++++++
 3 files changed, 72 insertions(+), 21 deletions(-)

diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index 9530e1c..88ccfe3 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -196,8 +196,24 @@ const CRLF_LENGTH = 2;
  * @param capabilities The extension lines returned by EHLO.
  * @returns The SIZE capability, or `null` when it was not advertised.
  */
-const parseSizeCapability = (capabilities) => {
-  const capability = capabilities.find((value) => /^SIZE(?:[ \t]|$)/i.test(value));
+// The capability lines by keyword (up to a space, a tab or the "=" of the
+// old AUTH=LOGIN form, in upper case), the first line of a keyword winning.
+const indexCapabilities = (lines) => {
+  const index = new Map();
+  for (const line of lines) {
+    let end = 0;
+    while (end < line.length) {
+      const code = line.charCodeAt(end);
+      if (code === 0x20 || code === 0x09 || code === 0x3d) break;
+      end++;
+    }
+    const keyword = line.slice(0, end).toUpperCase();
+    if (!index.has(keyword)) index.set(keyword, line);
+  }
+  return index;
+};
+
+const parseSizeCapability = (capability) => {
   if (capability == null) return null;
 
   const match = /^SIZE(?:[ \t]+([0-9]+))?[ \t]*$/i.exec(capability);
@@ -335,6 +351,8 @@ const isLoopbackConnection = (socket, host) => {
 class SmtpConnection {
   socket = null;
   config;
+  #indexedCapabilities = null;
+  #capabilityIndex = new Map();
   authenticated = false;
   capabilities = [];
   tokenManager;
@@ -668,13 +686,40 @@ class SmtpConnection {
       );
     }
 
-    // Parse capabilities
-    this.capabilities = response.raw
-      .split('\r\n')
-      .filter((line) => line.startsWith('250-') || line.startsWith('250 '))
-      .slice(1)
-      .map((line) => line.substring(4))
-      .filter((line) => line.length > 0);
+    // Parse capabilities: the lines of the reply after the greeting line, in
+    // one pass.
+    const capabilities = [];
+    const lines = response.raw.split('\r\n');
+    let isGreeting = true;
+    for (const line of lines) {
+      if (!line.startsWith('250-') && !line.startsWith('250 ')) continue;
+      if (isGreeting) {
+        isGreeting = false;
+        continue;
+      }
+      if (line.length > 4) capabilities.push(line.substring(4));
+    }
+    this.capabilities = capabilities;
+  }
+
+  /**
+   * The capability line of a keyword, from an index built again whenever
+   * `capabilities` is replaced: a send asks for several, which used to scan
+   * the list each time, with a new RegExp for some.
+   *
+   * @param keyword The keyword, in upper case, such as `SIZE`.
+   * @returns The whole line, or `undefined` when the server lacks it.
+   */
+  capabilityLine(keyword) {
+    if (this.#indexedCapabilities !== this.capabilities) {
+      this.#capabilityIndex = indexCapabilities(this.capabilities);
+      this.#indexedCapabilities = this.capabilities;
+    }
+    return this.#capabilityIndex.get(keyword);
+  }
+
+  hasCapability(keyword) {
+    return this.capabilityLine(keyword) !== undefined;
   }
 
   async starttls(signal) {
@@ -761,7 +806,7 @@ class SmtpConnection {
       return;
     }
 
-    if (!this.capabilities.some((cap) => cap.toUpperCase().startsWith('AUTH'))) {
+    if (!this.hasCapability('AUTH')) {
       throw new SmtpAuthError('Server does not support authentication.');
     }
 
@@ -970,10 +1015,7 @@ class SmtpConnection {
 
     let smtpUtf8Parameters = '';
     const negotiate = (encoding) => {
-      const supports = (name) =>
-        this.capabilities.some((capability) =>
-          new RegExp(`^${name}(?:[ \t]|$)`, 'i').test(capability),
-        );
+      const supports = (name) => this.hasCapability(name);
       if (message.requiresSmtpUtf8 || encoding === 'utf8') {
         if (!supports('SMTPUTF8')) {
           throw new SmtpUtf8UnsupportedError('SMTPUTF8');
@@ -989,11 +1031,11 @@ class SmtpConnection {
     };
     negotiate('rawMessage' in message ? message.rawMessage.encoding : undefined);
 
-    const sizeCapability = parseSizeCapability(this.capabilities);
+    const sizeCapability = parseSizeCapability(this.capabilityLine('SIZE'));
     let sizeParameter = '';
 
     const dsn = message.envelope.dsn;
-    if (dsn != null && !this.capabilities.some((capability) => /^DSN[ \t]*$/i.test(capability))) {
+    if (dsn != null && !/^DSN[ \t]*$/i.test(this.capabilityLine('DSN') ?? '')) {
       throw new SmtpDsnUnsupportedError();
     }
     const mailDsnParameters =
@@ -1050,9 +1092,7 @@ class SmtpConnection {
       const suffix = parameters.length === 0 ? '' : ` ${parameters.join(' ')}`;
       return `RCPT TO:<${recipient}>${suffix}`;
     });
-    const pipelining = this.capabilities.some((capability) =>
-      /^PIPELINING(?:\s|$)/i.test(capability),
-    );
+    const pipelining = this.hasCapability('PIPELINING');
 
     let mailResponse;
     let recipientResponses;
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index 0f85d09..7dba11e 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -635,8 +635,7 @@ class SmtpTransport {
     // even without the capability so STARTTLS stripping fails closed.
     if (
       connection.config.secure === false &&
-      (connection.config.requireTls === true ||
-        connection.capabilities.some((cap) => cap.toUpperCase().startsWith('STARTTLS')))
+      (connection.config.requireTls === true || connection.hasCapability('STARTTLS'))
     ) {
       await connection.starttls(signal);
 
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 9df54f8..9159aa1 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -10,6 +10,7 @@ const { SmtpTransport } = require('../../src/smtp/index.js');
 const { prepareOnSocket, writeMessageData } = require('../../src/smtp/data-stream.js');
 const { checkSmtpPath } = require('../../src/smtp/envelope.js');
 const { OAuth2TokenManager } = require('../../src/smtp/oauth2.js');
+const { SmtpConnection } = require('../../src/smtp/smtp-connection.js');
 const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
 
 const message = () =>
@@ -445,3 +446,14 @@ test('SMTP: AUTH PLAIN and LOGIN encode credentials outside Latin-1 as UTF-8', a
     }
   }
 });
+
+test('SMTP: capabilities are looked up by keyword, rebuilt when replaced', () => {
+  const connection = new SmtpConnection({ host: 'smtp.example.com' });
+  connection.capabilities = ['size 10240000', 'AUTH=LOGIN PLAIN', 'PIPELINING', '8BITMIME'];
+  assert.strictEqual(connection.capabilityLine('SIZE'), 'size 10240000');
+  assert.strictEqual(connection.hasCapability('AUTH'), true);
+  assert.strictEqual(connection.hasCapability('PIPE'), false);
+  connection.capabilities = ['STARTTLS'];
+  assert.strictEqual(connection.hasCapability('PIPELINING'), false);
+  assert.strictEqual(connection.hasCapability('STARTTLS'), true);
+});

From d4f93d1ad49f95ed388473296b22f213383e5efa Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:23:39 +0300
Subject: [PATCH 070/158] perf: filter custom headers without rebuilding lists
 per call

Every converter that forwards custom headers built the set of headers it
owns with new Set([...threading.keys()].map(...)), three passes for a few
names, and ./mailgun, ./sendgrid and ./resend rebuilt their list of
standard headers, as an array or a Set, on every isStandardHeader call,
once per custom header; ./plunk kept an array literal in its loop.
lowerCaseNames (src/internal/headers.js) builds the owned set in one pass,
and the standard headers are module-level Sets, built once, like those of
./mailtrap, ./maileroo and ./lettermint. Each provider keeps its own list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/internal/headers.js             | 17 ++++++++++++
 src/lettermint/message-converter.js |  3 ++-
 src/maileroo/message-converter.js   |  3 ++-
 src/mailgun/message-converter.js    | 34 ++++++++++++------------
 src/mailtrap/message-converter.js   |  3 ++-
 src/plunk/message-converter.js      | 11 ++++----
 src/resend/message-converter.js     | 34 ++++++++++++------------
 src/sendgrid/message-converter.js   | 40 +++++++++++++++--------------
 8 files changed, 86 insertions(+), 59 deletions(-)
 create mode 100644 src/internal/headers.js

diff --git a/src/internal/headers.js b/src/internal/headers.js
new file mode 100644
index 0000000..8d4a332
--- /dev/null
+++ b/src/internal/headers.js
@@ -0,0 +1,17 @@
+// Not ported from upyo: small helpers of header names that the converters of
+// the HTTP providers share.
+
+/**
+ * The names, in lower case, as a set built in one pass.
+ *
+ * @param names Header names, such as the keys of a Map.
+ * @returns A set of the lower-case names.
+ * @internal
+ */
+const lowerCaseNames = (names) => {
+  const set = new Set();
+  for (const name of names) set.add(name.toLowerCase());
+  return set;
+};
+
+module.exports = { lowerCaseNames };
diff --git a/src/lettermint/message-converter.js b/src/lettermint/message-converter.js
index de7f865..df013fb 100644
--- a/src/lettermint/message-converter.js
+++ b/src/lettermint/message-converter.js
@@ -6,6 +6,7 @@ const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
+const { lowerCaseNames } = require('../internal/headers.js');
 
 const STANDARD_HEADERS = new Set([
   'from',
@@ -104,7 +105,7 @@ const convertMessage = async (message, config, signal) => {
   // and from a custom header otherwise.  A field the message owns but left
   // empty writes nothing, which is how a caller drops an inherited header.
   const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+  const ownedHeaders = lowerCaseNames(threading.keys());
 
   for (const [key, value] of message.headers.entries()) {
     if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
diff --git a/src/maileroo/message-converter.js b/src/maileroo/message-converter.js
index 1ecfb6b..7636dd9 100644
--- a/src/maileroo/message-converter.js
+++ b/src/maileroo/message-converter.js
@@ -6,6 +6,7 @@ const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
+const { lowerCaseNames } = require('../internal/headers.js');
 
 const STANDARD_HEADERS = new Set([
   'from',
@@ -173,7 +174,7 @@ const convertHeaders = (message) => {
   // and from a custom header otherwise.  A field the message owns but left
   // empty writes nothing, which is how a caller drops an inherited header.
   const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+  const ownedHeaders = lowerCaseNames(threading.keys());
 
   for (const [key, value] of message.headers.entries()) {
     if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
diff --git a/src/mailgun/message-converter.js b/src/mailgun/message-converter.js
index aadb098..d376aec 100644
--- a/src/mailgun/message-converter.js
+++ b/src/mailgun/message-converter.js
@@ -5,6 +5,7 @@ const { formatQuotedMailbox: formatAddress } = require('../core/address.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
+const { lowerCaseNames } = require('../internal/headers.js');
 
 /**
  * Converts a Upyo Message to Mailgun API FormData format.
@@ -89,7 +90,7 @@ const convertMessage = async (message, config, signal) => {
   // and from a custom header otherwise.  A field the message owns but left
   // empty writes nothing, which is how a caller drops an inherited header.
   const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+  const ownedHeaders = lowerCaseNames(threading.keys());
 
   // Custom headers
   for (const [key, value] of message.headers.entries()) {
@@ -149,6 +150,21 @@ const appendAttachment = async (formData, attachment, signal) => {
   }
 };
 
+// Built once, not on every call.
+const STANDARD_HEADERS = new Set([
+  'from',
+  'to',
+  'cc',
+  'bcc',
+  'reply-to',
+  'subject',
+  'date',
+  'message-id',
+  'content-type',
+  'content-transfer-encoding',
+  'mime-version',
+]);
+
 /**
  * Checks if a header is a standard email header that should not be prefixed with 'h:'.
  *
@@ -156,21 +172,7 @@ const appendAttachment = async (formData, attachment, signal) => {
  * @returns True if it's a standard header
  */
 const isStandardHeader = (headerName) => {
-  const standardHeaders = [
-    'from',
-    'to',
-    'cc',
-    'bcc',
-    'reply-to',
-    'subject',
-    'date',
-    'message-id',
-    'content-type',
-    'content-transfer-encoding',
-    'mime-version',
-  ];
-
-  return standardHeaders.includes(headerName.toLowerCase());
+  return STANDARD_HEADERS.has(headerName.toLowerCase());
 };
 
 module.exports = { convertMessage };
diff --git a/src/mailtrap/message-converter.js b/src/mailtrap/message-converter.js
index c265f9b..9fed84d 100644
--- a/src/mailtrap/message-converter.js
+++ b/src/mailtrap/message-converter.js
@@ -6,6 +6,7 @@ const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
+const { lowerCaseNames } = require('../internal/headers.js');
 
 const STANDARD_HEADERS = new Set([
   'from',
@@ -95,7 +96,7 @@ const convertMessage = async (message, config, signal) => {
   // and from a custom header otherwise.  A field the message owns but left
   // empty writes nothing, which is how a caller drops an inherited header.
   const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+  const ownedHeaders = lowerCaseNames(threading.keys());
 
   for (const [key, value] of message.headers.entries()) {
     if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
diff --git a/src/plunk/message-converter.js b/src/plunk/message-converter.js
index 9af1887..bfe3dda 100644
--- a/src/plunk/message-converter.js
+++ b/src/plunk/message-converter.js
@@ -5,6 +5,7 @@ const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
 const { toBase64 } = require('../internal/base64.js');
+const { lowerCaseNames } = require('../internal/headers.js');
 
 /**
  * Converts a Upyo message to Plunk API format.
@@ -22,6 +23,9 @@ const { toBase64 } = require('../internal/base64.js');
  * @throws {RangeError} If a calendar message carries so many attachments that
  *                      one would have to be dropped.
  */
+// The headers that have fields of their own in a Plunk request.
+const DEDICATED_HEADERS = new Set(['to', 'from', 'reply-to', 'subject', 'content-type']);
+
 const convertMessage = async (message, _config, signal) => {
   // Convert recipients - Plunk accepts either string or array
   const recipients = message.recipients.map((addr) => addr.address);
@@ -49,7 +53,7 @@ const convertMessage = async (message, _config, signal) => {
   // and from a custom header otherwise.  A field the message owns but left
   // empty writes nothing, which is how a caller drops an inherited header.
   const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+  const ownedHeaders = lowerCaseNames(threading.keys());
 
   // Convert headers - merge custom headers but exclude standard ones
   const customHeaders = {};
@@ -57,10 +61,7 @@ const convertMessage = async (message, _config, signal) => {
     for (const [key, value] of message.headers.entries()) {
       // Skip headers that are handled by dedicated fields
       const lowerKey = key.toLowerCase();
-      if (
-        !['to', 'from', 'reply-to', 'subject', 'content-type'].includes(lowerKey) &&
-        !ownedHeaders.has(lowerKey)
-      ) {
+      if (!DEDICATED_HEADERS.has(lowerKey) && !ownedHeaders.has(lowerKey)) {
         customHeaders[lowerKey] = value;
       }
     }
diff --git a/src/resend/message-converter.js b/src/resend/message-converter.js
index 584dd38..a3688fd 100644
--- a/src/resend/message-converter.js
+++ b/src/resend/message-converter.js
@@ -7,6 +7,7 @@ const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
+const { lowerCaseNames } = require('../internal/headers.js');
 
 /**
  * Converts a Upyo Message to Resend API JSON format.
@@ -114,7 +115,7 @@ const convertMessage = async (message, _config, options = {}) => {
   // and from a custom header otherwise.  A field the message owns but left
   // empty writes nothing, which is how a caller drops an inherited header.
   const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+  const ownedHeaders = lowerCaseNames(threading.keys());
 
   for (const [key, value] of message.headers.entries()) {
     // Skip standard headers that are handled separately
@@ -193,6 +194,21 @@ const convertAttachment = async (attachment, signal) => {
   return resendAttachment;
 };
 
+// Built once, not on every call.
+const STANDARD_HEADERS = new Set([
+  'from',
+  'to',
+  'cc',
+  'bcc',
+  'reply-to',
+  'subject',
+  'content-type',
+  'content-transfer-encoding',
+  'mime-version',
+  'date',
+  'message-id',
+]);
+
 /**
  * Checks if a header is a standard email header that should not be prefixed.
  *
@@ -200,21 +216,7 @@ const convertAttachment = async (attachment, signal) => {
  * @returns True if the header is a standard header
  */
 const isStandardHeader = (headerName) => {
-  const standardHeaders = new Set([
-    'from',
-    'to',
-    'cc',
-    'bcc',
-    'reply-to',
-    'subject',
-    'content-type',
-    'content-transfer-encoding',
-    'mime-version',
-    'date',
-    'message-id',
-  ]);
-
-  return standardHeaders.has(headerName.toLowerCase());
+  return STANDARD_HEADERS.has(headerName.toLowerCase());
 };
 
 /**
diff --git a/src/sendgrid/message-converter.js b/src/sendgrid/message-converter.js
index 7a51c32..e9e2aaf 100644
--- a/src/sendgrid/message-converter.js
+++ b/src/sendgrid/message-converter.js
@@ -6,6 +6,7 @@ const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
+const { lowerCaseNames } = require('../internal/headers.js');
 
 /**
  * Converts a Upyo Message to SendGrid API JSON format.
@@ -119,7 +120,7 @@ const convertMessage = async (message, config, signal) => {
   // and from a custom header otherwise.  A field the message owns but left
   // empty writes nothing, which is how a caller drops an inherited header.
   const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = new Set([...threading.keys()].map((name) => name.toLowerCase()));
+  const ownedHeaders = lowerCaseNames(threading.keys());
 
   for (const [key, value] of message.headers.entries()) {
     // Skip standard headers that are handled separately
@@ -233,6 +234,24 @@ const convertAttachment = async (attachment, signal) => {
   return sendGridAttachment;
 };
 
+// Built once, not on every call.
+const STANDARD_HEADERS = new Set([
+  'from',
+  'to',
+  'cc',
+  'bcc',
+  'reply-to',
+  'subject',
+  'date',
+  'message-id',
+  'content-type',
+  'content-transfer-encoding',
+  'mime-version',
+  'x-priority',
+  'x-msmail-priority',
+  'importance',
+]);
+
 /**
  * Checks if a header is a standard email header that should not be added as custom header.
  *
@@ -240,24 +259,7 @@ const convertAttachment = async (attachment, signal) => {
  * @returns True if it's a standard header
  */
 const isStandardHeader = (headerName) => {
-  const standardHeaders = [
-    'from',
-    'to',
-    'cc',
-    'bcc',
-    'reply-to',
-    'subject',
-    'date',
-    'message-id',
-    'content-type',
-    'content-transfer-encoding',
-    'mime-version',
-    'x-priority',
-    'x-msmail-priority',
-    'importance',
-  ];
-
-  return standardHeaders.includes(headerName.toLowerCase());
+  return STANDARD_HEADERS.has(headerName.toLowerCase());
 };
 
 module.exports = { convertMessage };

From 0229ae077d2de9de554dd0f4d6f5f3d97da53bbe Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:26:33 +0300
Subject: [PATCH 071/158] perf(pool): select a transport in one pass without
 wrapper arrays

The strategies mapped every entry to a wrapper object, filtered it, and
the priority strategy sorted the result on every attempt. They now walk
the entries with an index loop: the priority strategy keeps the highest
priority and its candidates as it goes, the weighted one sums the weights
and then picks by the cumulative weight. The order of the candidates and
the number of Math.random calls are unchanged, so a stubbed generator
picks the same transport (select by priority among 10 transports: +357%).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/pool/strategies/priority-strategy.js    | 32 ++++++++++-----------
 src/pool/strategies/round-robin-strategy.js |  3 +-
 src/pool/strategies/selector-strategy.js    | 22 ++++++--------
 src/pool/strategies/weighted-strategy.js    | 30 +++++++++----------
 4 files changed, 42 insertions(+), 45 deletions(-)

diff --git a/src/pool/strategies/priority-strategy.js b/src/pool/strategies/priority-strategy.js
index d144805..bcb1bbe 100644
--- a/src/pool/strategies/priority-strategy.js
+++ b/src/pool/strategies/priority-strategy.js
@@ -21,23 +21,23 @@ class PriorityStrategy {
    *          attempted.
    */
   select(_message, transports, attemptedIndices) {
-    // Filter to enabled transports that haven't been attempted
-    const availableTransports = transports
-      .map((entry, index) => ({ entry, index }))
-      .filter(({ entry, index }) => entry.enabled && !attemptedIndices.has(index));
-
-    if (availableTransports.length < 1) return undefined;
-
-    // Sort by priority (highest first)
-    availableTransports.sort((a, b) => b.entry.priority - a.entry.priority);
-
-    // Get the highest priority value
-    const highestPriority = availableTransports[0].entry.priority;
+    // The enabled transports not attempted yet that share the highest
+    // priority, in their order, found in one pass rather than by mapping,
+    // filtering and sorting them on every attempt.
+    let topPriorityTransports = [];
+    let highestPriority = -Infinity;
+    for (let index = 0; index < transports.length; index++) {
+      const entry = transports[index];
+      if (!entry.enabled || attemptedIndices.has(index)) continue;
+      if (entry.priority > highestPriority) {
+        highestPriority = entry.priority;
+        topPriorityTransports = [{ entry, index }];
+      } else if (entry.priority === highestPriority) {
+        topPriorityTransports.push({ entry, index });
+      }
+    }
 
-    // Filter to only transports with the highest priority
-    const topPriorityTransports = availableTransports.filter(
-      ({ entry }) => entry.priority === highestPriority,
-    );
+    if (topPriorityTransports.length < 1) return undefined;
 
     // If multiple transports have the same priority, select randomly
     if (topPriorityTransports.length > 1) {
diff --git a/src/pool/strategies/round-robin-strategy.js b/src/pool/strategies/round-robin-strategy.js
index ee21b35..b84e428 100644
--- a/src/pool/strategies/round-robin-strategy.js
+++ b/src/pool/strategies/round-robin-strategy.js
@@ -22,7 +22,8 @@ class RoundRobinStrategy {
    *          attempted.
    */
   select(_message, transports, attemptedIndices) {
-    const enabledCount = transports.filter((t) => t.enabled).length;
+    let enabledCount = 0;
+    for (const entry of transports) if (entry.enabled) enabledCount++;
     if (enabledCount < 1) return undefined;
 
     // Try up to the number of enabled transports
diff --git a/src/pool/strategies/selector-strategy.js b/src/pool/strategies/selector-strategy.js
index 4ae2812..f823996 100644
--- a/src/pool/strategies/selector-strategy.js
+++ b/src/pool/strategies/selector-strategy.js
@@ -20,30 +20,26 @@ class SelectorStrategy {
    * @returns The selected transport or `undefined` if no transport matches.
    */
   select(message, transports, attemptedIndices) {
-    // Filter to enabled transports that haven't been attempted
-    const availableTransports = transports
-      .map((entry, index) => ({ entry, index }))
-      .filter(({ entry, index }) => entry.enabled && !attemptedIndices.has(index));
-
-    if (availableTransports.length < 1) return undefined;
-
-    // Separate transports with selectors from those without
+    // Transports whose selector accepts the message, and those without a
+    // selector, which accept every message, in one pass.
     const withSelectors = [];
     const withoutSelectors = [];
 
-    for (const transport of availableTransports) {
-      if (transport.entry.selector) {
+    for (let index = 0; index < transports.length; index++) {
+      const entry = transports[index];
+      if (!entry.enabled || attemptedIndices.has(index)) continue;
+      if (entry.selector) {
         // Evaluate selector function
         try {
-          if (transport.entry.selector(message)) {
-            withSelectors.push(transport);
+          if (entry.selector(message)) {
+            withSelectors.push({ entry, index });
           }
         } catch {
           // If selector throws, skip this transport
         }
       } else {
         // No selector means it accepts all messages
-        withoutSelectors.push(transport);
+        withoutSelectors.push({ entry, index });
       }
     }
 
diff --git a/src/pool/strategies/weighted-strategy.js b/src/pool/strategies/weighted-strategy.js
index aafd72e..8a0652b 100644
--- a/src/pool/strategies/weighted-strategy.js
+++ b/src/pool/strategies/weighted-strategy.js
@@ -21,25 +21,26 @@ class WeightedStrategy {
    *          attempted.
    */
   select(_message, transports, attemptedIndices) {
-    // Filter to enabled transports that haven't been attempted
-    const availableTransports = transports
-      .map((entry, index) => ({ entry, index }))
-      .filter(
-        ({ entry, index }) => entry.enabled && entry.weight > 0 && !attemptedIndices.has(index),
-      );
-
-    if (availableTransports.length < 1) return undefined;
-
-    // Calculate total weight of available transports
-    const totalWeight = availableTransports.reduce((sum, { entry }) => sum + entry.weight, 0);
+    // The total weight of the enabled transports not attempted yet, in one
+    // pass without building a list of them.
+    let totalWeight = 0;
+    let lastIndex = -1;
+    for (let index = 0; index < transports.length; index++) {
+      const entry = transports[index];
+      if (!entry.enabled || !(entry.weight > 0) || attemptedIndices.has(index)) continue;
+      totalWeight += entry.weight;
+      lastIndex = index;
+    }
 
-    if (totalWeight <= 0) return undefined;
+    if (lastIndex === -1 || totalWeight <= 0) return undefined;
 
     // Random selection based on weights
     const random = Math.random() * totalWeight;
     let cumulativeWeight = 0;
 
-    for (const { entry, index } of availableTransports) {
+    for (let index = 0; index < transports.length; index++) {
+      const entry = transports[index];
+      if (!entry.enabled || !(entry.weight > 0) || attemptedIndices.has(index)) continue;
       cumulativeWeight += entry.weight;
       if (random < cumulativeWeight) {
         return { entry, index };
@@ -47,8 +48,7 @@ class WeightedStrategy {
     }
 
     // Fallback to last available transport (shouldn't normally reach here)
-    const last = availableTransports[availableTransports.length - 1];
-    return { entry: last.entry, index: last.index };
+    return { entry: transports[lastIndex], index: lastIndex };
   }
 
   /**

From 568e6f45c939226ac6996c5ae1e2370bc5ead013 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:28:55 +0300
Subject: [PATCH 072/158] perf(core): drop undefined receipt fields in one pass
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

omitUndefined went through Object.entries, filter and Object.fromEntries,
building an array per field on every receipt and receipt error. A for…in
loop copies the defined fields directly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/core/receipt.js | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/core/receipt.js b/src/core/receipt.js
index 8a2f3ec..ac2567d 100644
--- a/src/core/receipt.js
+++ b/src/core/receipt.js
@@ -307,8 +307,14 @@ const getStringProperty = (value, property) => {
   return propertyValue == null ? undefined : String(propertyValue);
 };
 
+// Copies the defined fields of an object literal in one pass, without the
+// entry arrays of Object.entries and Object.fromEntries.
 const omitUndefined = (value) => {
-  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+  const result = {};
+  for (const key in value) {
+    if (value[key] !== undefined) result[key] = value[key];
+  }
+  return result;
 };
 
 module.exports = {

From 238df6d7e6be71d7511fa0b110d950daef60681a Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:28:55 +0300
Subject: [PATCH 073/158] perf(maileroo): hash a reference in one pass and
 encode it with Buffer

The three FNV-1a hashes of an idempotency key each walked its bytes, and
the hex came from a spread, a map and a join. They are now updated
together in one index loop and written into a Buffer that gives the hex;
a random reference is hex-encoded the same way. The test pins two
references so the values stay those of upstream.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/maileroo/message-converter.js | 38 +++++++++++++++----------------
 tests/unit/maileroo.test.js       | 25 ++++++++++++++------
 2 files changed, 36 insertions(+), 27 deletions(-)

diff --git a/src/maileroo/message-converter.js b/src/maileroo/message-converter.js
index 7636dd9..90edebf 100644
--- a/src/maileroo/message-converter.js
+++ b/src/maileroo/message-converter.js
@@ -105,32 +105,30 @@ const convertMessage = async (message, config, signal) => {
 
 const createMailerooReference = (idempotencyKey) => {
   if (idempotencyKey == null || idempotencyKey === '') {
-    const bytes = new Uint8Array(12);
-    crypto.getRandomValues(bytes);
-    return bytesToHex(bytes);
+    return crypto.getRandomValues(Buffer.allocUnsafe(12)).toString('hex');
   }
 
   return hashReference(idempotencyKey);
 };
 
-const bytesToHex = (bytes) => {
-  return [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
-};
-
+// Three 32-bit FNV-1a hashes of the key with different seeds, updated together
+// in a single pass over its UTF-8 bytes.
 const hashReference = (value) => {
-  const bytes = new TextEncoder().encode(value);
-  const seeds = [0x811c9dc5, 0x9e3779b9, 0x85ebca6b];
-
-  return seeds
-    .map((seed) => {
-      let hash = seed;
-      for (const byte of bytes) {
-        hash ^= byte;
-        hash = Math.imul(hash, 0x01000193);
-      }
-      return (hash >>> 0).toString(16).padStart(8, '0');
-    })
-    .join('');
+  const bytes = Buffer.from(value, 'utf8');
+  let first = 0x811c9dc5;
+  let second = 0x9e3779b9;
+  let third = 0x85ebca6b;
+  for (let index = 0; index < bytes.length; index++) {
+    const byte = bytes[index];
+    first = Math.imul(first ^ byte, 0x01000193);
+    second = Math.imul(second ^ byte, 0x01000193);
+    third = Math.imul(third ^ byte, 0x01000193);
+  }
+  const digest = Buffer.allocUnsafe(12);
+  digest.writeUInt32BE(first >>> 0, 0);
+  digest.writeUInt32BE(second >>> 0, 4);
+  digest.writeUInt32BE(third >>> 0, 8);
+  return digest.toString('hex');
 };
 
 const convertAddress = (address) => {
diff --git a/tests/unit/maileroo.test.js b/tests/unit/maileroo.test.js
index 396df3c..6d17cad 100644
--- a/tests/unit/maileroo.test.js
+++ b/tests/unit/maileroo.test.js
@@ -5,13 +5,13 @@ const assert = require('node:assert');
 const { createMessage } = require('../../index.js');
 const { MailerooTransport } = require('../../src/maileroo/index.js');
 
-const message = () =>
-  createMessage({
-    from: 'alex@example.com',
-    to: 'bob@example.com',
-    subject: 'Hello',
-    content: { text: 'Hi' },
-  });
+const base = {
+  from: 'alex@example.com',
+  to: 'bob@example.com',
+  subject: 'Hello',
+  content: { text: 'Hi' },
+};
+const message = () => createMessage(base);
 const config = { apiKey: 'key', retries: 0 };
 
 test('Maileroo: an error body gives its message, its error or its errors', async (t) => {
@@ -32,3 +32,14 @@ test('Maileroo: an unsuccessful 200 without a message fails the send', async (t)
   const receipt = await new MailerooTransport(config).send(message());
   assert.deepStrictEqual(receipt.errorMessages, ['Maileroo reported an unsuccessful response.']);
 });
+
+test('Maileroo: the reference of an idempotency key hashes its UTF-8 bytes', async () => {
+  const { convertMessage } = require('../../src/maileroo/message-converter.js');
+  const referenceOf = async (idempotencyKey) => {
+    const converted = await convertMessage(createMessage({ ...base, idempotencyKey }), {});
+    return converted.reference_id;
+  };
+  // Values of upstream's three FNV-1a hashes, which a Maileroo reference keeps.
+  assert.strictEqual(await referenceOf('welcome-message-1'), '55232a4fbce60dabbd33e909');
+  assert.strictEqual(await referenceOf('Ключ 🔑'), '5ff86cd948e80925429c97c7');
+});

From 3e49407abe7f328cbd0b4b253ce651222285736a Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:28:56 +0300
Subject: [PATCH 074/158] perf: serialize a request body once rather than on
 every attempt

Lettermint, Maileroo, Mailtrap, Plunk and JMAP called JSON.stringify inside
the function that requestWithRetry calls per attempt, so a retried request
serialized its payload, attachments included, again. The JSON is now made
once before the retries; SES, SendGrid and Resend already did so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/jmap/http-client.js       |  6 ++++--
 src/lettermint/http-client.js |  8 +++++---
 src/maileroo/http-client.js   |  8 +++++---
 src/mailtrap/http-client.js   |  8 +++++---
 src/plunk/http-client.js      | 10 ++++++----
 5 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index 3663959..c5c99d4 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -60,6 +60,8 @@ class JmapHttpClient {
    */
   executeRequest(apiUrl, request, signal) {
     signal?.throwIfAborted();
+    // Serialized once rather than on every attempt.
+    const json = JSON.stringify(request);
 
     return requestWithRetry({
       signal,
@@ -77,10 +79,10 @@ class JmapHttpClient {
             // A stream prevents runtime-level replay of a POST after a lost
             // response (observed with Deno even when application retries are 0).
             body: this.replayableRequests
-              ? JSON.stringify(request)
+              ? json
               : new ReadableStream({
                   start(controller) {
-                    controller.enqueue(new TextEncoder().encode(JSON.stringify(request)));
+                    controller.enqueue(Buffer.from(json));
                     controller.close();
                   },
                 }),
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index f56879c..9964f9a 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -100,13 +100,15 @@ class LettermintHttpClient {
   }
 
   makeRequest(url, body, signal, idempotencyKey) {
+    // Serialized once rather than on every attempt.
+    const json = JSON.stringify(body);
     return requestWithRetry({
       signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       // Lettermint deduplicates a repeated Idempotency-Key.
       hasIdempotencyKey: idempotencyKey != null && idempotencyKey !== '',
-      send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal, idempotencyKey),
+      send: (attemptSignal) => this.fetchWithAuth(url, json, attemptSignal, idempotencyKey),
       read: async (response) => {
         const text = await readText(response);
         try {
@@ -132,7 +134,7 @@ class LettermintHttpClient {
     });
   }
 
-  fetchWithAuth(url, body, signal, idempotencyKey) {
+  fetchWithAuth(url, json, signal, idempotencyKey) {
     const headers = new Headers({
       'Content-Type': 'application/json',
       'x-lettermint-token': this.config.apiToken,
@@ -151,7 +153,7 @@ class LettermintHttpClient {
     return globalThis.fetch(url, {
       method: 'POST',
       headers,
-      body: JSON.stringify(body),
+      body: json,
       signal,
       redirect: 'manual',
     });
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index 463ee19..416461d 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -90,11 +90,13 @@ class MailerooHttpClient {
   }
 
   makeRequest(url, body, signal) {
+    // Serialized once rather than on every attempt.
+    const json = JSON.stringify(body);
     return requestWithRetry({
       signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
-      send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
+      send: (attemptSignal) => this.fetchWithAuth(url, json, attemptSignal),
       read: async (response) => parseResponse(await readText(response)),
       reject: async (response, attempt) =>
         new MailerooApiError(
@@ -108,7 +110,7 @@ class MailerooHttpClient {
     });
   }
 
-  fetchWithAuth(url, body, signal) {
+  fetchWithAuth(url, json, signal) {
     const headers = new Headers({
       'Content-Type': 'application/json',
       'X-API-Key': this.config.apiKey,
@@ -123,7 +125,7 @@ class MailerooHttpClient {
     return globalThis.fetch(url, {
       method: 'POST',
       headers,
-      body: JSON.stringify(body),
+      body: json,
       signal,
       redirect: 'manual',
     });
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index f9002a4..11ec25f 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -134,11 +134,13 @@ class MailtrapHttpClient {
   }
 
   makeRequest(url, body, signal) {
+    // Serialized once rather than on every attempt.
+    const json = JSON.stringify(body);
     return requestWithRetry({
       signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
-      send: (attemptSignal) => this.fetchWithAuth(url, body, attemptSignal),
+      send: (attemptSignal) => this.fetchWithAuth(url, json, attemptSignal),
       read: async (response) => {
         const text = await readText(response);
         try {
@@ -169,7 +171,7 @@ class MailtrapHttpClient {
     });
   }
 
-  fetchWithAuth(url, body, signal) {
+  fetchWithAuth(url, json, signal) {
     const headers = new Headers({
       'Content-Type': 'application/json',
       'Api-Token': this.config.apiToken,
@@ -185,7 +187,7 @@ class MailtrapHttpClient {
     return globalThis.fetch(url, {
       method: 'POST',
       headers,
-      body: JSON.stringify(body),
+      body: json,
       signal,
       redirect: 'manual',
     });
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index a7d3be3..ec23dea 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -72,12 +72,14 @@ class PlunkHttpClient {
    */
   sendMessage(emailData, signal) {
     const url = `${this.config.baseUrl}/v1/send`;
+    // Serialized once rather than on every attempt.
+    const json = JSON.stringify(emailData);
 
     return requestWithRetry({
       signal,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
-      send: (attemptSignal) => this.makeRequest(url, emailData, attemptSignal),
+      send: (attemptSignal) => this.makeRequest(url, json, attemptSignal),
       read: (response) => this.parseResponse(response),
       reject: async (response, attempt) => {
         let errorBody;
@@ -115,11 +117,11 @@ class PlunkHttpClient {
    * Makes an HTTP request to the Plunk API.
    *
    * @param url - The request URL
-   * @param emailData - The email data to send
+   * @param json - The email data, serialized as JSON
    * @param signal - Optional AbortSignal for cancellation
    * @returns Promise that resolves to the Response object
    */
-  makeRequest(url, emailData, signal) {
+  makeRequest(url, json, signal) {
     const headers = {
       Authorization: `Bearer ${this.config.apiKey}`,
       'Content-Type': 'application/json',
@@ -131,7 +133,7 @@ class PlunkHttpClient {
     return fetch(url, {
       method: 'POST',
       headers,
-      body: JSON.stringify(emailData),
+      body: json,
       signal,
       redirect: 'manual',
     });

From 4a01de029c8b87b44547cc53ec9924f713a4210b Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:33:14 +0300
Subject: [PATCH 075/158] perf(core): scan atoms and address literals with one
 table and loop

The local part of an address was checked by splitting it into atoms and
matching each character, from Array.from, against a regular expression;
Message-ID atoms tested a regular expression and a string search per
character. src/core/text.js now holds the ATEXT and DTEXT tables and one
index loop over char codes that the address and the Message-ID checks
share, with the same handling of non-ASCII text and unpaired surrogates
(no difference over 900,000 fuzzed inputs; isEmailAddress: +113%). The
local part length comes from Buffer.byteLength, and a raw envelope is
checked without copying its recipients.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/core/address.js     | 34 +++---------------
 src/core/message-id.js  | 78 ++---------------------------------------
 src/core/raw-message.js |  9 ++++-
 src/core/text.js        | 76 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 92 insertions(+), 105 deletions(-)
 create mode 100644 src/core/text.js

diff --git a/src/core/address.js b/src/core/address.js
index 0ea9d46..1b829df 100644
--- a/src/core/address.js
+++ b/src/core/address.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const net = require('node:net');
+const { ATEXT, isDotAtomText } = require('./text.js');
 
 /**
  * Formats an address object into a string representation.  This function is
@@ -28,15 +29,6 @@ const formatAddress = (address) => {
   return address.name == null ? address.address : formatMailbox(address);
 };
 
-// RFC 5322 §3.2.3: the characters of an atom.
-const ATEXT = new Uint8Array(128);
-for (let code = 0x30; code <= 0x39; code++) ATEXT[code] = 1;
-for (let code = 0x41; code <= 0x5a; code++) {
-  ATEXT[code] = 1;
-  ATEXT[code + 0x20] = 1;
-}
-for (const symbol of "!#$%&'*+-/=?^_`{|}~") ATEXT[symbol.charCodeAt(0)] = 1;
-
 // A phrase of atoms separated by spaces goes as it is; anything else, such as
 // "<", ",", "@" or "." that would make a second mailbox or end this one, goes
 // as a quoted string (RFC 5322 §3.4).  So does text that reads as an encoded
@@ -237,7 +229,7 @@ const findClosingQuote = (text) => {
 };
 
 const isValidLocalPart = (localPart) => {
-  if (!localPart || localPart.length === 0 || new TextEncoder().encode(localPart).byteLength > 64) {
+  if (!localPart || localPart.length === 0 || Buffer.byteLength(localPart, 'utf8') > 64) {
     return false;
   }
 
@@ -271,25 +263,9 @@ const isValidLocalPart = (localPart) => {
     return true;
   }
 
-  // Check for dot-atom format (RFC 5322)
-  // No leading/trailing dots, no consecutive dots
-  if (localPart.startsWith('.') || localPart.endsWith('.') || localPart.includes('..')) {
-    return false;
-  }
-
-  // RFC 6531 extends atext with any well-formed non-ASCII UTF-8 character.
-  const asciiAtext = /^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]$/;
-  return localPart.split('.').every(
-    (atom) =>
-      atom.length > 0 &&
-      Array.from(atom).every((character) => {
-        if (asciiAtext.test(character)) return true;
-        const codePoint = character.codePointAt(0);
-        return (
-          codePoint != null && codePoint > 0x7f && !(codePoint >= 0xd800 && codePoint <= 0xdfff)
-        );
-      }),
-  );
+  // Check for dot-atom format (RFC 5322), whose atext RFC 6531 extends with any
+  // well-formed non-ASCII UTF-8 character.
+  return isDotAtomText(localPart);
 };
 
 const isValidDomainPart = (domainPart) => {
diff --git a/src/core/message-id.js b/src/core/message-id.js
index a198a90..579c029 100644
--- a/src/core/message-id.js
+++ b/src/core/message-id.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/core/src/message-id.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { isDotAtomText, isDtextBetween } = require('./text.js');
+
 /**
  * Generates a globally unique message identifier rooted in a domain.
  *
@@ -153,24 +155,6 @@ const isIdRight = (value) => {
   return isDotAtomText(value) || isNoFoldLiteral(value);
 };
 
-/**
- * Tells whether a value is a `dot-atom-text`: one or more `atext` runs joined
- * by single dots, so neither a leading, a trailing, nor a doubled dot.
- *
- * @param value The value to check.
- * @returns Whether the value is a `dot-atom-text`.
- */
-const isDotAtomText = (value) => {
-  if (value === '') return false;
-  for (const atom of value.split('.')) {
-    if (atom === '') return false;
-    for (const character of atom) {
-      if (!isAtext(character)) return false;
-    }
-  }
-  return true;
-};
-
 /**
  * Tells whether a value is a `no-fold-literal`: an address literal such as
  * `[192.0.2.1]`.
@@ -186,63 +170,7 @@ const isNoFoldLiteral = (value) => {
   if (value.length < 3 || !value.startsWith('[') || !value.endsWith(']')) {
     return false;
   }
-  for (const character of value.slice(1, -1)) {
-    if (!isDtext(character)) return false;
-  }
-  return true;
-};
-
-/**
- * The ASCII punctuation RFC 5322 allows in an atom, besides letters and digits.
- */
-const asciiAtextSymbols = "!#$%&'*+-/=?^_`{|}~";
-
-/**
- * Tells whether a character is `atext`, the character class an atom is built
- * from, extended with UTF-8 by RFC 6532.
- *
- * @param character A single character, which may be a surrogate pair.
- * @returns Whether the character is `atext`.
- */
-const isAtext = (character) => {
-  const codePoint = character.codePointAt(0);
-  if (codePoint == null) return false;
-  if (codePoint > 0x7f) return isNonAsciiText(codePoint);
-  return /[A-Za-z0-9]/.test(character) || asciiAtextSymbols.includes(character);
-};
-
-/**
- * Tells whether a character is `dtext`, the character class the inside of an
- * address literal is built from, extended with UTF-8 by RFC 6532.
- *
- * Angle brackets are excluded although RFC 5322 permits them here.  They are
- * unambiguous only to a parser that tracks the literal, and an identifier
- * carrying one would be truncated by every reader that simply looks for the
- * closing bracket of the field.
- *
- * @param character A single character, which may be a surrogate pair.
- * @returns Whether the character is `dtext`.
- */
-const isDtext = (character) => {
-  const codePoint = character.codePointAt(0);
-  if (codePoint == null) return false;
-  if (codePoint > 0x7f) return isNonAsciiText(codePoint);
-  return (
-    ((codePoint >= 0x21 && codePoint <= 0x5a) || (codePoint >= 0x5e && codePoint <= 0x7e)) &&
-    character !== '<' &&
-    character !== '>'
-  );
-};
-
-/**
- * Tells whether a code point beyond ASCII may appear in a header field under
- * RFC 6532.  An unpaired surrogate may not: it cannot be encoded as UTF-8.
- *
- * @param codePoint The code point to check.
- * @returns Whether the code point is usable.
- */
-const isNonAsciiText = (codePoint) => {
-  return codePoint < 0xd800 || codePoint > 0xdfff;
+  return isDtextBetween(value, 1, value.length - 1);
 };
 
 /**
diff --git a/src/core/raw-message.js b/src/core/raw-message.js
index 236b96f..ae63b98 100644
--- a/src/core/raw-message.js
+++ b/src/core/raw-message.js
@@ -36,6 +36,13 @@ class RawMessageValidationError extends TypeError {
  * @throws {RawMessageValidationError} If metadata or the source kind is invalid.
  * @internal
  */
+const areEmailAddresses = (addresses) => {
+  for (let i = 0; i < addresses.length; i++) {
+    if (!isEmailAddress(addresses[i])) return false;
+  }
+  return true;
+};
+
 const createRawMessagePlan = (message) => {
   const content = message?.content;
   if (content instanceof Promise) content.catch(() => {});
@@ -45,7 +52,7 @@ const createRawMessagePlan = (message) => {
     (envelope.from !== null && !isEmailAddress(envelope.from)) ||
     !Array.isArray(envelope.to) ||
     envelope.to.length === 0 ||
-    !Array.from(envelope.to).every(isEmailAddress)
+    !areEmailAddresses(envelope.to)
   ) {
     throw new RawMessageValidationError('Invalid raw message envelope.', 'envelope');
   }
diff --git a/src/core/text.js b/src/core/text.js
new file mode 100644
index 0000000..425ad55
--- /dev/null
+++ b/src/core/text.js
@@ -0,0 +1,76 @@
+// The character classes RFC 5322 builds atoms and address literals from, as
+// tables indexed by char code, and a scan of them in one pass.
+
+const DOT = 0x2e;
+
+// RFC 5322 §3.2.3: the ASCII characters of an atom.
+const ATEXT = new Uint8Array(128);
+for (let code = 0x30; code <= 0x39; code++) ATEXT[code] = 1;
+for (let code = 0x41; code <= 0x5a; code++) {
+  ATEXT[code] = 1;
+  ATEXT[code + 0x20] = 1;
+}
+for (const symbol of "!#$%&'*+-/=?^_`{|}~") ATEXT[symbol.charCodeAt(0)] = 1;
+
+// RFC 5322 §3.4.1: the ASCII characters of an address literal.  Angle brackets
+// are excluded although RFC 5322 permits them: they are unambiguous only to a
+// parser that tracks the literal, and an identifier carrying one would be
+// truncated by every reader that simply looks for the closing bracket.
+const DTEXT = new Uint8Array(128);
+for (let code = 0x21; code <= 0x7e; code++) {
+  if (code < 0x5b || code > 0x5d) DTEXT[code] = 1;
+}
+DTEXT[0x3c] = 0;
+DTEXT[0x3e] = 0;
+
+/**
+ * Gives the length of the character at `index` when it is in the ASCII class
+ * of `table` or is non-ASCII text that UTF-8 can encode (RFC 6532), and 0
+ * when it is neither: an unpaired surrogate cannot be encoded.
+ */
+const textCharLength = (value, index, end, table) => {
+  const code = value.charCodeAt(index);
+  if (code < 0x80) return table[code];
+  if (code < 0xd800 || code > 0xdfff) return 1;
+  if (code > 0xdbff || index + 1 >= end) return 0;
+  const next = value.charCodeAt(index + 1);
+  return next >= 0xdc00 && next <= 0xdfff ? 2 : 0;
+};
+
+/**
+ * Tells whether a value is a `dot-atom-text` extended with UTF-8 by RFC 6532:
+ * atoms separated by single dots, with no dot at either end.
+ *
+ * @param value The value to check.
+ * @returns Whether the value is a `dot-atom-text`.
+ */
+const isDotAtomText = (value) => {
+  const end = value.length;
+  if (end === 0 || value.charCodeAt(0) === DOT || value.charCodeAt(end - 1) === DOT) return false;
+  for (let i = 0; i < end;) {
+    if (value.charCodeAt(i) === DOT) {
+      if (value.charCodeAt(i + 1) === DOT) return false;
+      i++;
+      continue;
+    }
+    const length = textCharLength(value, i, end, ATEXT);
+    if (length === 0) return false;
+    i += length;
+  }
+  return true;
+};
+
+/**
+ * Tells whether the characters of `value` from `start` up to `end` are all
+ * `dtext` extended with UTF-8 by RFC 6532.
+ */
+const isDtextBetween = (value, start, end) => {
+  for (let i = start; i < end;) {
+    const length = textCharLength(value, i, end, DTEXT);
+    if (length === 0) return false;
+    i += length;
+  }
+  return true;
+};
+
+module.exports = { ATEXT, isDotAtomText, isDtextBetween };

From 9f47a1d8de9ee8408c307b2444e6c4463e5583f6 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:33:14 +0300
Subject: [PATCH 076/158] perf(smtp): check envelopes for SMTPUTF8 without
 spreading addresses

Whether a message needs SMTPUTF8 was found by spreading the envelope into
a new array and testing each address with a regular expression, or with
Array.from and a callback per character for a raw message. Both paths now
share hasNonAsciiAddress, a loop over char codes. The XOAUTH2 response is
encoded with Buffer instead of a binary string for btoa, and the error
challenge decoded without a callback per byte.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/smtp/envelope.js          | 28 +++++++++++++++++++++++++++-
 src/smtp/message-converter.js |  6 ++----
 src/smtp/oauth2.js            |  9 +--------
 src/smtp/raw-message.js       |  6 ++----
 src/smtp/smtp-connection.js   |  5 ++---
 5 files changed, 34 insertions(+), 20 deletions(-)

diff --git a/src/smtp/envelope.js b/src/smtp/envelope.js
index 66276f8..a228717 100644
--- a/src/smtp/envelope.js
+++ b/src/smtp/envelope.js
@@ -98,4 +98,30 @@ const checkSmtpPath = (path) => {
   }
 };
 
-module.exports = { SmtpEnvelopeValidationError, checkSmtpPath, resolveSmtpEnvelope };
+const hasNonAscii = (text) => {
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) > 0x7f) return true;
+  }
+  return false;
+};
+
+/**
+ * Tells whether an envelope carries an address beyond ASCII, which needs the
+ * SMTPUTF8 extension (RFC 6531).
+ *
+ * @internal
+ */
+const hasNonAsciiAddress = (envelope) => {
+  if (envelope.from != null && hasNonAscii(envelope.from)) return true;
+  for (let i = 0; i < envelope.to.length; i++) {
+    if (hasNonAscii(envelope.to[i])) return true;
+  }
+  return false;
+};
+
+module.exports = {
+  SmtpEnvelopeValidationError,
+  checkSmtpPath,
+  hasNonAsciiAddress,
+  resolveSmtpEnvelope,
+};
diff --git a/src/smtp/message-converter.js b/src/smtp/message-converter.js
index 461c67d..4056f66 100644
--- a/src/smtp/message-converter.js
+++ b/src/smtp/message-converter.js
@@ -4,7 +4,7 @@
 const { readAttachmentContent } = require('../core/attachment.js');
 const { prepareMimeMessage } = require('../mime/message.js');
 const { prepareMimeStream } = require('../mime/stream.js');
-const { resolveSmtpEnvelope } = require('./envelope.js');
+const { hasNonAsciiAddress, resolveSmtpEnvelope } = require('./envelope.js');
 
 /** Snapshots MIME metadata and preserves the effective SMTP envelope. */
 const prepareMessage = (
@@ -18,9 +18,7 @@ const prepareMessage = (
   return {
     ...plan,
     envelope,
-    requiresSmtpUtf8:
-      plan.encoding === 'utf8' ||
-      [envelope.from ?? '', ...envelope.to].some((address) => /[\u0080-\uffff]/.test(address)),
+    requiresSmtpUtf8: plan.encoding === 'utf8' || hasNonAsciiAddress(envelope),
   };
 };
 /** Collects the shared stream using the historical internal trailing-CRLF convention. */
diff --git a/src/smtp/oauth2.js b/src/smtp/oauth2.js
index 3fef173..127da26 100644
--- a/src/smtp/oauth2.js
+++ b/src/smtp/oauth2.js
@@ -28,14 +28,7 @@ class SmtpAuthError extends Error {
  * @param input The string to encode.
  * @returns The Base64-encoded representation of the UTF-8 bytes of `input`.
  */
-const toBase64 = (input) => {
-  const bytes = new TextEncoder().encode(input);
-  let binary = '';
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
-  }
-  return btoa(binary);
-};
+const toBase64 = (input) => Buffer.from(input, 'utf8').toString('base64');
 
 /**
  * Builds the SASL `XOAUTH2` initial client response for SMTP authentication.
diff --git a/src/smtp/raw-message.js b/src/smtp/raw-message.js
index d975d85..6a0883a 100644
--- a/src/smtp/raw-message.js
+++ b/src/smtp/raw-message.js
@@ -3,6 +3,7 @@
 
 const { analyzeRawMessage, iterateRawMessage } = require('../core/raw-message.js');
 const { readAttachmentContent } = require('../core/attachment.js');
+const { hasNonAsciiAddress } = require('./envelope.js');
 
 /** Missing support for explicitly declared 8-bit MIME bodies. @since 0.6.0 */
 class Smtp8BitMimeUnsupportedError extends TypeError {
@@ -18,10 +19,7 @@ const prepareRawSmtpMessage = (plan, dsn) => {
   return {
     rawMessage: plan,
     envelope: { ...plan.envelope, dsn },
-    requiresSmtpUtf8:
-      [plan.envelope.from ?? '', ...plan.envelope.to].some((address) =>
-        Array.from(address).some((character) => character.charCodeAt(0) > 127),
-      ) || plan.encoding === 'utf8',
+    requiresSmtpUtf8: plan.encoding === 'utf8' || hasNonAsciiAddress(plan.envelope),
   };
 };
 
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index 88ccfe3..5341cb2 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -1343,9 +1343,8 @@ class SmtpResponseError extends Error {
  */
 const decodeOAuth2Challenge = (message) => {
   try {
-    const binary = atob(message.trim());
-    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
-    return new TextDecoder().decode(bytes);
+    // atob refuses text that is not Base64, which Buffer would skip.
+    return Buffer.from(atob(message.trim()), 'latin1').toString('utf8');
   } catch {
     return message;
   }

From fdd76cf52b3dc61aa4bd57c7342797d82b1b5a9b Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:33:14 +0300
Subject: [PATCH 077/158] perf(mime): encode RFC 2231 parameters in one pass
 over the bytes

A filename beyond ASCII was turned into an array of encoded bytes, each
from a regular expression and toString(16), then into an array of
segments joined at the end. A table of the 256 encoded bytes and one loop
now build the continuations directly (no difference over 200,000 fuzzed
values). The SMTP envelope of composeMessage collects the recipients
without spreading the three lists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mime/index.js   | 12 +++++++++---
 src/mime/message.js | 40 +++++++++++++++++++++++++---------------
 2 files changed, 34 insertions(+), 18 deletions(-)

diff --git a/src/mime/index.js b/src/mime/index.js
index 0ed48df..500f847 100644
--- a/src/mime/index.js
+++ b/src/mime/index.js
@@ -24,6 +24,14 @@ const { MimeAttachmentReplayError } = require('./stream.js');
  * Attachment errors can also occur during later content reads, after partial
  * output. Streaming DKIM changes throw {@link MimeAttachmentReplayError}.
  */
+const envelopeRecipients = (message) => {
+  const addresses = [];
+  for (const list of [message.recipients, message.ccRecipients, message.bccRecipients]) {
+    for (let i = 0; i < list.length; i++) addresses.push(list[i].address);
+  }
+  return addresses;
+};
+
 const composeMessage = async (message, options = {}) => {
   const { signal } = options;
   // The neutral plan observes promised sources even when envelope validation fails.
@@ -31,9 +39,7 @@ const composeMessage = async (message, options = {}) => {
   const { envelope } = createRawMessagePlan({
     envelope: {
       from: message.sender.address,
-      to: [...message.recipients, ...message.ccRecipients, ...message.bccRecipients].map(
-        (recipient) => recipient.address,
-      ),
+      to: envelopeRecipients(message),
     },
     content: new Uint8Array(),
   });
diff --git a/src/mime/message.js b/src/mime/message.js
index 28badb7..04347fa 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -538,6 +538,21 @@ const encodeHeaderValue = (value, encodeLongAsciiWords = false) => {
   return words.join(' ');
 };
 
+// Each byte as an RFC 2231 extended value carries it: an attribute-char as it
+// is, any other byte percent-encoded.
+const EXTENDED_VALUE_BYTES = [];
+for (let byte = 0; byte < 256; byte++) {
+  const character = String.fromCharCode(byte);
+  EXTENDED_VALUE_BYTES.push(
+    /^[A-Za-z0-9!#$&+.^_`|~-]$/.test(character)
+      ? character
+      : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`,
+  );
+}
+
+const formatParameterSegment = (name, index, segment) =>
+  index === 0 ? `${name}*0*=UTF-8''${segment}` : `; ${name}*${index}*=${segment}`;
+
 const encodeMimeParameter = (name, value) => {
   const escapedValue = value.replace(/[\\"]/g, '\\$&');
   const quotedParameter = `${name}="${escapedValue}"`;
@@ -545,27 +560,22 @@ const encodeMimeParameter = (name, value) => {
     return quotedParameter;
   }
 
-  const encodedBytes = Array.from(new TextEncoder().encode(value), (byte) => {
-    const character = String.fromCharCode(byte);
-    return /^[A-Za-z0-9!#$&+.^_`|~-]$/.test(character)
-      ? character
-      : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
-  });
-  const segments = [];
+  // Continuations of at most 45 characters each, built in one pass over the
+  // UTF-8 bytes of the value.
+  const bytes = Buffer.from(value, 'utf8');
+  let parameter = '';
   let segment = '';
-
-  for (const encodedByte of encodedBytes) {
+  let index = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    const encodedByte = EXTENDED_VALUE_BYTES[bytes[i]];
     if (segment.length + encodedByte.length > 45) {
-      segments.push(segment);
+      parameter += formatParameterSegment(name, index++, segment);
       segment = '';
     }
     segment += encodedByte;
   }
-  if (segment.length > 0 || segments.length === 0) segments.push(segment);
-
-  return segments
-    .map((part, index) => `${name}*${index}*=${index === 0 ? "UTF-8''" : ''}${part}`)
-    .join('; ');
+  if (segment.length > 0 || index === 0) parameter += formatParameterSegment(name, index, segment);
+  return parameter;
 };
 
 const foldHeader = (name, value) => {

From 2619379363a0c6fcc822a4784098227e00cbc908 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:35:07 +0300
Subject: [PATCH 078/158] perf(mime): count and check MIME text without
 encoding or splitting it

The size of a plan encoded its headers and text parts to UTF-8 only to
read their length, the encoding was chosen over a spread of the filtered
parts, iterated by code point, and the 998-byte limit was checked by
splitting the headers into an array of lines. Sizes now come from
Buffer.byteLength, the encoding from an index loop that stops at the
first byte beyond ASCII, and the line limit from hasLineLongerThan, which
walks the CRLFs and measures only lines that could exceed it. A buffered
DKIM body is replayed from its chunks, so it no longer computes the digest
that only a streamed replay is checked against.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mime/bytes.js   | 20 +++++++++++++++++++-
 src/mime/message.js | 28 ++++++++++++++++++----------
 src/mime/stream.js  | 19 +++++++++++--------
 3 files changed, 48 insertions(+), 19 deletions(-)

diff --git a/src/mime/bytes.js b/src/mime/bytes.js
index 0c87272..7afab16 100644
--- a/src/mime/bytes.js
+++ b/src/mime/bytes.js
@@ -19,4 +19,22 @@ const base64 = (bytes) => {
   return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64');
 };
 
-module.exports = { utf8, base64 };
+/**
+ * Tells whether a text of CRLF-separated lines has one longer than `limit`
+ * bytes in UTF-8, without splitting it into an array of lines.
+ * @internal
+ */
+const hasLineLongerThan = (text, limit) => {
+  for (let start = 0; start <= text.length;) {
+    let end = text.indexOf('\r\n', start);
+    if (end === -1) end = text.length;
+    // A UTF-16 code unit takes at most three bytes in UTF-8.
+    if ((end - start) * 3 > limit && Buffer.byteLength(text.slice(start, end)) > limit) {
+      return true;
+    }
+    start = end + 2;
+  }
+  return false;
+};
+
+module.exports = { utf8, base64, hasLineLongerThan };
diff --git a/src/mime/message.js b/src/mime/message.js
index 04347fa..0f9cc85 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -13,7 +13,7 @@ const {
 const { resolveCalendarContent } = require('../core/calendar.js');
 const { validateDkimBodyMode } = require('./dkim/types.js');
 const { attachmentEncodedSize, encodeAttachment } = require('./mime-stream.js');
-const { base64, utf8 } = require('./bytes.js');
+const { base64, hasLineLongerThan, utf8 } = require('./bytes.js');
 
 /**
  * Freezes message metadata without reading attachment content.
@@ -50,9 +50,7 @@ const prepareMimeMessage = (message, dkimConfig) => {
   const headers = first.slice(0, separator);
   parts[0] = first.slice(separator);
 
-  const encoding = [headers, ...parts.filter((part) => typeof part === 'string')].some(hasNonAscii)
-    ? 'utf8'
-    : '7bit';
+  const encoding = hasNonAsciiText(headers, parts) ? 'utf8' : '7bit';
   return {
     encoding,
     dkim,
@@ -72,11 +70,11 @@ const prepareMimeMessage = (message, dkimConfig) => {
       }
     },
     async size(signal, checkSize) {
-      let size = utf8(headers).length;
+      let size = Buffer.byteLength(headers);
       let unknown = false;
       for (const part of parts) {
         signal?.throwIfAborted();
-        if (typeof part === 'string') size += utf8(part).length;
+        if (typeof part === 'string') size += Buffer.byteLength(part);
         else {
           if (part.content instanceof Promise) {
             part.content = await readAttachmentContent(part.content, signal);
@@ -387,8 +385,17 @@ const reservedHeaders = new Set([
  * @returns Whether the value contains a character outside ASCII.
  */
 const hasNonAscii = (value) => {
-  for (const character of value) {
-    if ((character.codePointAt(0) ?? 0) > 0x7f) return true;
+  for (let i = 0; i < value.length; i++) {
+    if (value.charCodeAt(i) > 0x7f) return true;
+  }
+  return false;
+};
+
+const hasNonAsciiText = (headers, parts) => {
+  if (hasNonAscii(headers)) return true;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (typeof part === 'string' && hasNonAscii(part)) return true;
   }
   return false;
 };
@@ -627,10 +634,11 @@ const foldHeader = (name, value) => {
   }
 
   lines.push(prefix + remaining);
-  if (lines.some((line) => Buffer.byteLength(line) > 998)) {
+  const folded = lines.join('\r\n');
+  if (hasLineLongerThan(folded, 998)) {
     throw new RangeError(`Header field ${name} contains a token too long to fold.`);
   }
-  return lines.join('\r\n');
+  return folded;
 };
 
 // The digits of an escaped byte, as character codes.
diff --git a/src/mime/stream.js b/src/mime/stream.js
index 8f68d2d..d9e10fa 100644
--- a/src/mime/stream.js
+++ b/src/mime/stream.js
@@ -4,7 +4,7 @@
 const { createHash } = require('node:crypto');
 const { RawMessageValidationError } = require('../core/raw-message.js');
 const { Buffer } = require('node:buffer');
-const { base64, utf8 } = require('./bytes.js');
+const { base64, hasLineLongerThan, utf8 } = require('./bytes.js');
 const { BodyHasher } = require('./dkim/body-hash.js');
 const { signWithBodyHash } = require('./dkim/sign.js');
 
@@ -51,19 +51,22 @@ const prepareMimeStream = async (plan, options = {}) => {
     const mode = sig.canonicalization?.endsWith('/simple') ? 'simple' : 'relaxed';
     if (!hashes.has(mode)) hashes.set(mode, new BodyHasher(mode));
   }
-  const rawHash = createHash('sha256');
+  // The digest that a streamed replay is checked against; a buffered body is
+  // replayed from its own chunks and needs none.
+  const rawHash = buffered ? undefined : createHash('sha256');
   let length = 0;
-  const headerLength = utf8(plan.headers).length;
+  const headerLength = Buffer.byteLength(plan.headers);
   for await (const chunk of plan.body(signal, progress)) {
     length += chunk.length;
     checkSize(headerLength + length);
     if (chunk.length > 0) progress();
     if (buffered) chunks.push(chunk.slice());
-    rawHash.update(chunk);
+    rawHash?.update(chunk);
     for (const hash of hashes.values()) hash.update(chunk);
   }
-  const expectedDigest = base64(rawHash.digest());
-  const bodyHashes = new Map(Array.from(hashes, ([mode, hash]) => [mode, hash.digest()]));
+  const expectedDigest = rawHash == null ? undefined : base64(rawHash.digest());
+  const bodyHashes = new Map();
+  for (const [mode, hash] of hashes) bodyHashes.set(mode, hash.digest());
   let headers = plan.headers;
   try {
     for (const sig of signatures) {
@@ -78,10 +81,10 @@ const prepareMimeStream = async (plan, options = {}) => {
     console.warn('DKIM signing failed, sending unsigned:', error);
   }
   signal?.throwIfAborted();
-  if (headers.split('\r\n').some((line) => Buffer.byteLength(line) > 998)) {
+  if (hasLineLongerThan(headers, 998)) {
     throw new RangeError('Signed MIME header exceeds the RFC 5322 line limit.');
   }
-  const size = utf8(headers).length + length;
+  const size = Buffer.byteLength(headers) + length;
   checkSize(size);
   return {
     size,

From c90b8d1a28ddebfb601f9cea783ccf5609b988f1 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:41:11 +0300
Subject: [PATCH 079/158] fix(otel): record metrics for every operation and
 sample only spans

Each record method of the metrics collector drew its own Math.random()
against metrics.samplingRate and recorded the value unscaled, so every
counter and histogram came out low by the rate, and the +1 and -1 of the
active sends counter, sampled apart, drifted. Metrics are now recorded for
every operation and only spans are sampled; metrics.samplingRate throws a
TypeError rather than being accepted and ignored. The ported config test
says where it changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                   |  4 ++++
 CLAUDE.md                      |  4 ++++
 docs/transports/otel.md        | 17 +++++++----------
 src/otel/config.js             | 11 ++++++++++-
 src/otel/index.d.ts            | 18 +++++++++++-------
 src/otel/metrics.js            | 24 ------------------------
 tests/types/otel.test-d.ts     |  2 ++
 tests/unit/otel-config.test.js |  6 +++---
 tests/unit/otel.test.js        | 25 ++++++++++++++++++++++++-
 9 files changed, 65 insertions(+), 46 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b7a3e2f..edd3955 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -182,6 +182,10 @@ fixed ones below.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
+- **`./otel` metrics no longer undercount** (an upstream bug): each counter and histogram was
+  sampled with `metrics.samplingRate` and recorded unscaled, so all of them came out low by the
+  rate, and the count of active sends drifted. Metrics are now recorded for every operation and
+  only spans are sampled (`tracing.samplingRate`); `metrics.samplingRate` throws a `TypeError`.
 
 ### Changed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 03dcd98..fb28176 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -262,6 +262,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     (`foo@evil.example/` sent the signed request to `evil.example`), and the Mailgun `domain`,
     the Mailtrap `inboxId` and the JMAP `accountId` of a blob upload into the path unencoded.
     The region must look like one (`us-east-1`), and the others are encoded as one segment.
+44. otel: every counter and histogram was sampled with `metrics.samplingRate` and recorded
+    unscaled, so each undercounted by the rate, and the UpDownCounter of active sends drifted.
+    Metrics are recorded for every operation, only spans are sampled, and
+    `metrics.samplingRate` throws a `TypeError`.
 
 ## Repository layout
 
diff --git a/docs/transports/otel.md b/docs/transports/otel.md
index b05c66d..2bfd343 100644
--- a/docs/transports/otel.md
+++ b/docs/transports/otel.md
@@ -343,7 +343,6 @@ const transport = createOpenTelemetryTransport(
     metrics: {
       enabled: true,
       prefix: 'marketing',
-      samplingRate: 1.0,
       durationBuckets: [0.1, 0.5, 1.0, 2.0, 5.0, 10.0],
     },
     tracing: {
@@ -354,6 +353,11 @@ const transport = createOpenTelemetryTransport(
 );
 ```
 
+Metrics are recorded for every operation; `tracing.samplingRate` samples
+only the spans. A sampled counter would undercount by the sampling rate, and a
+sampled count of active sends would drift, so the metrics configuration has no
+sampling rate, and setting `metrics.samplingRate` throws a `TypeError`.
+
 The transport collects the following key metrics:
 
 - Email delivery counters: Track successful and failed send attempts
@@ -499,10 +503,7 @@ const transport = createOpenTelemetryTransport(
     tracerProvider,
     meterProvider,
     serviceName: 'newsletter-service',
-    metrics: {
-      enabled: true,
-      samplingRate: 1.0, // Monitor all bulk operations
-    },
+    metrics: { enabled: true },
     tracing: {
       enabled: true,
       samplingRate: 0.01, // Sample 1% of individual messages
@@ -580,7 +581,6 @@ const transport = createOpenTelemetryTransport(
     serviceName: 'production-email',
     metrics: {
       enabled: true,
-      samplingRate: 1.0, // Always collect metrics
       prefix: 'prod',
     },
     tracing: {
@@ -642,10 +642,7 @@ const devTransport = createOpenTelemetryTransport(
     meterProvider,
     serviceName: 'email-service-dev',
     serviceVersion: 'dev',
-    metrics: {
-      enabled: true,
-      samplingRate: 1.0,
-    },
+    metrics: { enabled: true },
     tracing: {
       enabled: true,
       samplingRate: 1.0,
diff --git a/src/otel/config.js b/src/otel/config.js
index dccc946..36e2d34 100644
--- a/src/otel/config.js
+++ b/src/otel/config.js
@@ -7,7 +7,6 @@
 const DEFAULT_CONFIG = {
   metrics: {
     enabled: true,
-    samplingRate: 1.0,
     prefix: 'mailer',
     durationBuckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0],
   },
@@ -26,8 +25,18 @@ const DEFAULT_CONFIG = {
  * @returns A resolved configuration with all defaults applied.
  * @throws {Error} When tracing is enabled but no TracerProvider is provided.
  * @throws {Error} When metrics are enabled but no MeterProvider is provided.
+ * @throws {TypeError} When `metrics.samplingRate` is set.
  */
 const createOpenTelemetryConfig = (config = {}) => {
+  // Sampled counters and histograms undercount by the sampling rate, and a
+  // sampled UpDownCounter drifts, so metrics are recorded for every operation
+  // and only spans are sampled.
+  if (config.metrics?.samplingRate !== undefined) {
+    throw new TypeError(
+      'metrics.samplingRate is not supported: metrics are recorded for every ' +
+        'operation, and only spans are sampled (tracing.samplingRate).',
+    );
+  }
   const resolvedConfig = {
     tracerProvider: config.tracerProvider,
     meterProvider: config.meterProvider,
diff --git a/src/otel/index.d.ts b/src/otel/index.d.ts
index 1cd5d89..93126dc 100644
--- a/src/otel/index.d.ts
+++ b/src/otel/index.d.ts
@@ -72,18 +72,15 @@ export interface MeterProvider {
  */
 export interface ObservabilityConfig {
   /**
-   * Whether tracing is enabled.
+   * Whether the feature is enabled.
    * @default true
    */
   readonly enabled?: boolean;
-  /**
-   * Custom sampling rate for this feature (0.0 to 1.0).
-   * @default 1.0 (sample all)
-   */
-  readonly samplingRate?: number;
 }
 /**
- * Configuration options for metrics collection.
+ * Configuration options for metrics collection.  Metrics are recorded for
+ * every operation: sampled counters would undercount, and a sampled count of
+ * active sends would drift.
  */
 export interface MetricsConfig extends ObservabilityConfig {
   /**
@@ -101,6 +98,11 @@ export interface MetricsConfig extends ObservabilityConfig {
  * Configuration options for tracing.
  */
 export interface TracingConfig extends ObservabilityConfig {
+  /**
+   * The share of operations that get a span (0.0 to 1.0).
+   * @default 1.0 (sample all)
+   */
+  readonly samplingRate?: number;
   /**
    * Whether to record sensitive information in spans.
    * When false, email addresses and subjects are redacted.
@@ -307,6 +309,8 @@ export declare class OpenTelemetryTransport<TProviderId extends string = string>
    *
    * @param transport The base transport to wrap with observability.
    * @param config OpenTelemetry configuration options.
+   * @throws {Error} When an enabled feature has no provider.
+   * @throws {TypeError} When `metrics.samplingRate` is set.
    */
   constructor(transport: Transport<TProviderId>, config?: OpenTelemetryConfig);
   /**
diff --git a/src/otel/metrics.js b/src/otel/metrics.js
index 3f75ac7..3454226 100644
--- a/src/otel/metrics.js
+++ b/src/otel/metrics.js
@@ -71,10 +71,6 @@ class MetricsCollector {
    * Records the start of an email send operation.
    */
   recordSendStart(transport, messageCount = 1) {
-    if (!this.shouldSample()) {
-      return;
-    }
-
     const labels = {
       transport,
     };
@@ -90,10 +86,6 @@ class MetricsCollector {
    * Records the completion of an email send operation.
    */
   recordSendComplete(transport, duration, success, errorType) {
-    if (!this.shouldSample()) {
-      return;
-    }
-
     const labels = {
       transport,
       status: success ? 'success' : 'failure',
@@ -109,10 +101,6 @@ class MetricsCollector {
    * Records metrics for individual messages.
    */
   recordMessage(message, transport) {
-    if (!this.shouldSample()) {
-      return;
-    }
-
     const labels = {
       transport,
       priority: message.priority,
@@ -128,10 +116,6 @@ class MetricsCollector {
    * Records metrics for batch operations.
    */
   recordBatch(messages, transport, duration, successCount, failureCount) {
-    if (!this.shouldSample()) {
-      return;
-    }
-
     // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
     const _totalMessages = messages.length;
     const labels = { transport };
@@ -173,10 +157,6 @@ class MetricsCollector {
    * Records an error for metrics classification.
    */
   recordError(transport, errorType, operation = 'send') {
-    if (!this.shouldSample()) {
-      return;
-    }
-
     this.attemptCounter.add(1, {
       transport,
       status: 'failure',
@@ -185,10 +165,6 @@ class MetricsCollector {
     });
   }
 
-  shouldSample() {
-    return Math.random() < this.config.samplingRate;
-  }
-
   getContentType(message) {
     // A calendar is a second body part wherever it goes: an alternative beside
     // the text and HTML on the transports that compose one, and a synthesized
diff --git a/tests/types/otel.test-d.ts b/tests/types/otel.test-d.ts
index 6090597..9cfada0 100644
--- a/tests/types/otel.test-d.ts
+++ b/tests/types/otel.test-d.ts
@@ -39,3 +39,5 @@ expectAssignable<(error: unknown) => string>(createErrorClassifier({ patterns: {
 expectAssignable<OpenTelemetryConfig>({ tracing: { enabled: false }, metrics: { enabled: false } });
 expectAssignable<Function>(createEmailAttributeExtractor);
 expectError(new OpenTelemetryTransport(new MockTransport(), { tracerProvider: 'global' }));
+// Metrics are recorded for every operation; only tracing has a sampling rate.
+expectError(new OpenTelemetryTransport(new MockTransport(), { metrics: { samplingRate: 0.5 } }));
diff --git a/tests/unit/otel-config.test.js b/tests/unit/otel-config.test.js
index 92bd11a..17817e8 100644
--- a/tests/unit/otel-config.test.js
+++ b/tests/unit/otel-config.test.js
@@ -18,7 +18,8 @@ describe('config', () => {
       });
 
       assert.equal(config.metrics.enabled, true);
-      assert.equal(config.metrics.samplingRate, 1.0);
+      // Changed after the port: metrics have no sampling rate.
+      assert.equal(config.metrics.samplingRate, undefined);
       assert.equal(config.metrics.prefix, 'mailer');
       assert.deepEqual(
         config.metrics.durationBuckets,
@@ -38,10 +39,10 @@ describe('config', () => {
       const config = createOpenTelemetryConfig({
         tracerProvider,
         meterProvider,
+        // Changed after the port: metrics.samplingRate is refused.
         metrics: {
           enabled: true,
           prefix: 'custom',
-          samplingRate: 0.5,
         },
         tracing: {
           enabled: true,
@@ -51,7 +52,6 @@ describe('config', () => {
       });
 
       assert.equal(config.metrics.prefix, 'custom');
-      assert.equal(config.metrics.samplingRate, 0.5);
       assert.equal(config.tracing.recordSensitiveData, true);
       assert.equal(config.tracing.spanPrefix, 'custom_email');
     });
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index ca23755..e254ff2 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -33,7 +33,7 @@ test('OTel: nothing is recorded when sampled out', async () => {
     tracerProvider,
     meterProvider,
     tracing: { samplingRate: 0 },
-    metrics: { samplingRate: 0 },
+    metrics: { enabled: false },
     attributeExtractor: () => ({ 'app.custom': true }),
   };
   const ok = new OpenTelemetryTransport(plain({}), options);
@@ -136,3 +136,26 @@ test('OTel: without sensitive data, error text in spans names no address', async
     if (!recordSensitiveData) assert.match(recorded, /RCPT TO failed for \[REDACTED\]: 550/);
   }
 });
+
+test('OTel: metrics are recorded for every operation, and only spans are sampled', async () => {
+  const { tracerProvider, meterProvider } = providers();
+  const transport = new OpenTelemetryTransport(plain({}), {
+    tracerProvider,
+    meterProvider,
+    tracing: { samplingRate: 0 },
+  });
+  for (let i = 0; i < 20; i++) await transport.send(createTestMessage());
+  assert.deepStrictEqual(tracerProvider.getAllSpans(), []);
+  const attempts = meterProvider.getAllRecords().find((metric) => metric.instrument === 'counter');
+  assert.strictEqual(attempts.records.length, 20);
+
+  assert.throws(
+    () =>
+      new OpenTelemetryTransport(plain({}), {
+        tracerProvider,
+        meterProvider,
+        metrics: { samplingRate: 0.5 },
+      }),
+    { name: 'TypeError', message: /metrics\.samplingRate is not supported/ },
+  );
+});

From ffeba15104c45b0e120d84f97e1d8ddc3e6d2e21 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:42:01 +0300
Subject: [PATCH 080/158] fix(otel): count active sends down when a batch ends

recordSendStart added one to the active sends counter for send and for
sendMany, but only the completion of a single send took it away, so every
batch left one behind. The counter now goes down in the finally block of
both, which also runs when the caller stops reading the receipts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                        |  3 +++
 CLAUDE.md                           |  5 ++--
 src/otel/metrics.js                 |  8 ++++++-
 src/otel/opentelemetry-transport.js |  3 +++
 tests/unit/otel.test.js             | 37 +++++++++++++++++++++++++++++
 5 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index edd3955..2c4c151 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -186,6 +186,9 @@ fixed ones below.
   sampled with `metrics.samplingRate` and recorded unscaled, so all of them came out low by the
   rate, and the count of active sends drifted. Metrics are now recorded for every operation and
   only spans are sampled (`tracing.samplingRate`); `metrics.samplingRate` throws a `TypeError`.
+- **`./otel` counts active sends down after `sendMany`** (an upstream bug): the count went up for
+  a batch and never down. It goes down however a send or a batch ends, also when the caller
+  stops reading the receipts.
 
 ### Changed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index fb28176..05ad2b2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -133,8 +133,7 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 5. `cram-md5` is in the `SmtpAuth` type but not implemented.
 6. DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails.
 7. pool: `continueOnSuccess` is never read.
-8. otel: `_active_sends` is not decremented after `sendMany` and drifts under sampling;
-   `durationBuckets` and `auto` are ignored; `recordRetry` is never called; `sendMany` buffers
+8. otel (partly fixed, see 44 and 45): `durationBuckets` and `auto` are ignored; `recordRetry` is never called; `sendMany` buffers
    its whole input; `defaultErrorClassifier` matches `"auth"` as a substring.
 9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
@@ -266,6 +265,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     unscaled, so each undercounted by the rate, and the UpDownCounter of active sends drifted.
     Metrics are recorded for every operation, only spans are sampled, and
     `metrics.samplingRate` throws a `TypeError`.
+45. otel: the count of active sends went up for a `sendMany` and never down. It goes down when
+    a send or a batch ends, however it ends, a batch the caller stops reading included.
 
 ## Repository layout
 
diff --git a/src/otel/metrics.js b/src/otel/metrics.js
index 3454226..3a6c5e3 100644
--- a/src/otel/metrics.js
+++ b/src/otel/metrics.js
@@ -82,6 +82,13 @@ class MetricsCollector {
     });
   }
 
+  /**
+   * Records the end of an email send operation, however it ended.
+   */
+  recordSendEnd(transport) {
+    this.activeSendsGauge.add(-1, { transport });
+  }
+
   /**
    * Records the completion of an email send operation.
    */
@@ -92,7 +99,6 @@ class MetricsCollector {
       ...(errorType && { error_type: errorType }),
     };
 
-    this.activeSendsGauge.add(-1, { transport });
     this.attemptCounter.add(1, labels);
     this.durationHistogram.record(duration, labels);
   }
diff --git a/src/otel/opentelemetry-transport.js b/src/otel/opentelemetry-transport.js
index ae6e604..646cde2 100644
--- a/src/otel/opentelemetry-transport.js
+++ b/src/otel/opentelemetry-transport.js
@@ -166,6 +166,7 @@ class OpenTelemetryTransport {
 
       throw error;
     } finally {
+      this.metricsCollector?.recordSendEnd(this.transportName);
       span?.end();
     }
   }
@@ -263,6 +264,8 @@ class OpenTelemetryTransport {
 
       throw error;
     } finally {
+      // Also when the caller stops reading the receipts early.
+      this.metricsCollector?.recordSendEnd(this.transportName);
       span?.end();
     }
   }
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index e254ff2..9900e2b 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -159,3 +159,40 @@ test('OTel: metrics are recorded for every operation, and only spans are sampled
     { name: 'TypeError', message: /metrics\.samplingRate is not supported/ },
   );
 });
+
+test('OTel: active sends return to zero however a send or a batch ends', async () => {
+  const { tracerProvider, meterProvider } = providers();
+  const failing = plain({});
+  failing.send = async () => {
+    throw new Error('Connection refused');
+  };
+  failing.sendMany = async function* () {
+    yield { successful: true, messageId: 'm1' };
+    throw new Error('Connection reset');
+  };
+  const ok = new OpenTelemetryTransport(plain({}), { tracerProvider, meterProvider });
+  const broken = new OpenTelemetryTransport(failing, { tracerProvider, meterProvider });
+
+  await ok.send(createTestMessage());
+  await collect(ok.sendMany([createTestMessage(), createTestMessage()]));
+  for await (const receipt of ok.sendMany([createTestMessage(), createTestMessage()])) {
+    assert.strictEqual(receipt.successful, true);
+    break;
+  }
+  await assert.rejects(broken.send(createTestMessage()));
+  await assert.rejects(collect(broken.sendMany([createTestMessage()])));
+
+  const active = meterProvider.getAllRecords().filter((metric) => {
+    return metric.instrument === 'upDownCounter';
+  });
+  let sum = 0;
+  let changes = 0;
+  for (const metric of active) {
+    for (const record of metric.records) {
+      sum += record.value;
+      changes++;
+    }
+  }
+  assert.strictEqual(changes, 10);
+  assert.strictEqual(sum, 0);
+});

From aa111cbc5b2ca3e3884b3f1860d502593ba5ca65 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:43:29 +0300
Subject: [PATCH 081/158] fix(otel): count each message once, with its priority
 and status

recordSendStart added the size of a batch to the message counter and
recordBatch then added its successes and failures, so every message of a
batch was counted twice, and always with priority 'normal' whatever the
message said. The counter now takes each receipt once, with the priority
of the message it answers and a status. The mock meter of the tests keeps
the names and options of its instruments, so tests can tell them apart.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                              |  4 +++
 CLAUDE.md                                 |  3 ++
 src/otel/metrics.js                       | 37 ++++++++---------------
 src/otel/opentelemetry-transport.js       | 15 +++++++--
 tests/helpers/otel/mock-otel-providers.js | 25 +++++++++++----
 tests/unit/otel.test.js                   | 28 ++++++++++++++++-
 6 files changed, 79 insertions(+), 33 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2c4c151..2d219bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -189,6 +189,10 @@ fixed ones below.
 - **`./otel` counts active sends down after `sendMany`** (an upstream bug): the count went up for
   a batch and never down. It goes down however a send or a batch ends, also when the caller
   stops reading the receipts.
+- **`./otel` counts each message once** (an upstream bug): the message counter took a batch
+  twice, its size at the start and then its successes and failures, and every message with
+  `priority: 'normal'`. It now takes each receipt once, with the priority of its message and its
+  `status`.
 
 ### Changed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 05ad2b2..8e9b554 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -267,6 +267,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     `metrics.samplingRate` throws a `TypeError`.
 45. otel: the count of active sends went up for a `sendMany` and never down. It goes down when
     a send or a batch ends, however it ends, a batch the caller stops reading included.
+46. otel: the message counter took every message of a batch twice (its size at the start, then
+    its successes and failures), and always with `priority: 'normal'`. It takes each receipt
+    once, with the priority of its message and its status.
 
 ## Repository layout
 
diff --git a/src/otel/metrics.js b/src/otel/metrics.js
index 3a6c5e3..d5e2d4c 100644
--- a/src/otel/metrics.js
+++ b/src/otel/metrics.js
@@ -34,7 +34,7 @@ class MetricsCollector {
     });
 
     this.messageCounter = this.meter.createCounter(`${config.prefix}_email_messages_total`, {
-      description: 'Total number of email messages processed',
+      description: 'Messages a transport returned a receipt for, by priority and status',
       unit: '1',
     });
 
@@ -70,15 +70,19 @@ class MetricsCollector {
   /**
    * Records the start of an email send operation.
    */
-  recordSendStart(transport, messageCount = 1) {
-    const labels = {
-      transport,
-    };
+  recordSendStart(transport) {
+    this.activeSendsGauge.add(1, { transport });
+  }
 
-    this.activeSendsGauge.add(1, labels);
-    this.messageCounter.add(messageCount, {
-      ...labels,
-      priority: 'normal', // Default, will be overridden by recordMessage if available
+  /**
+   * Records the receipt of one message, once, with the priority of the
+   * message and whether it was sent.
+   */
+  recordMessageOutcome(transport, priority, successful) {
+    this.messageCounter.add(1, {
+      transport,
+      priority,
+      status: successful ? 'success' : 'failure',
     });
   }
 
@@ -142,21 +146,6 @@ class MetricsCollector {
     for (const message of messages) {
       this.recordMessage(message, transport);
     }
-
-    // Record success/failure breakdown
-    if (successCount > 0) {
-      this.messageCounter.add(successCount, {
-        ...labels,
-        status: 'success',
-      });
-    }
-
-    if (failureCount > 0) {
-      this.messageCounter.add(failureCount, {
-        ...labels,
-        status: 'failure',
-      });
-    }
   }
 
   /**
diff --git a/src/otel/opentelemetry-transport.js b/src/otel/opentelemetry-transport.js
index 646cde2..38a67d9 100644
--- a/src/otel/opentelemetry-transport.js
+++ b/src/otel/opentelemetry-transport.js
@@ -122,7 +122,7 @@ class OpenTelemetryTransport {
     const span = this.tracingCollector?.createSendSpan(message, this.extractNetworkAttributes());
 
     // Record metrics start
-    this.metricsCollector?.recordSendStart(this.transportName, 1);
+    this.metricsCollector?.recordSendStart(this.transportName);
     this.metricsCollector?.recordMessage(message, this.transportName);
 
     try {
@@ -140,6 +140,11 @@ class OpenTelemetryTransport {
       // Delegate to wrapped transport
       const receipt = await this.wrappedTransport.send(message, options);
       const duration = (performance.now() - startTime) / 1000; // Convert to seconds
+      this.metricsCollector?.recordMessageOutcome(
+        this.transportName,
+        message.priority,
+        receipt.successful,
+      );
 
       // Record success/failure
       if (receipt.successful) {
@@ -197,7 +202,7 @@ class OpenTelemetryTransport {
     );
 
     // Record batch start
-    this.metricsCollector?.recordSendStart(this.transportName, batchSize);
+    this.metricsCollector?.recordSendStart(this.transportName);
 
     let successCount = 0;
     let failureCount = 0;
@@ -218,6 +223,12 @@ class OpenTelemetryTransport {
 
       // Delegate to wrapped transport
       for await (const receipt of this.wrappedTransport.sendMany(messageArray, options)) {
+        // A receipt answers the message at its position in the batch.
+        this.metricsCollector?.recordMessageOutcome(
+          this.transportName,
+          messageArray[receipts.length]?.priority ?? 'unknown',
+          receipt.successful,
+        );
         receipts.push(receipt);
 
         if (receipt.successful) {
diff --git a/tests/helpers/otel/mock-otel-providers.js b/tests/helpers/otel/mock-otel-providers.js
index 7783eff..4c47646 100644
--- a/tests/helpers/otel/mock-otel-providers.js
+++ b/tests/helpers/otel/mock-otel-providers.js
@@ -154,9 +154,16 @@ class MockTracerProvider {
   }
 }
 
+// Changed after the port: an instrument keeps its name and options, so that
+// tests can tell the instruments apart.
 class MockMetricInstrument {
   records = [];
 
+  constructor(name, options) {
+    this.name = name;
+    this.options = options;
+  }
+
   record(value, attributes) {
     this.records.push({ value, attributes });
   }
@@ -211,20 +218,20 @@ class MockMeter {
   upDownCounters = [];
   histograms = [];
 
-  createCounter(_name, _options) {
-    const counter = new MockCounter();
+  createCounter(name, options) {
+    const counter = new MockCounter(name, options);
     this.counters.push(counter);
     return counter;
   }
 
-  createUpDownCounter(_name, _options) {
-    const upDownCounter = new MockUpDownCounter();
+  createUpDownCounter(name, options) {
+    const upDownCounter = new MockUpDownCounter(name, options);
     this.upDownCounters.push(upDownCounter);
     return upDownCounter;
   }
 
-  createHistogram(_name, _options) {
-    const histogram = new MockHistogram();
+  createHistogram(name, options) {
+    const histogram = new MockHistogram(name, options);
     this.histograms.push(histogram);
     return histogram;
   }
@@ -288,18 +295,24 @@ class MockMeterProvider {
       meter.counters.forEach((counter) => {
         allRecords.push({
           instrument: 'counter',
+          name: counter.name,
+          options: counter.options,
           records: [...counter.records],
         });
       });
       meter.upDownCounters.forEach((upDownCounter) => {
         allRecords.push({
           instrument: 'upDownCounter',
+          name: upDownCounter.name,
+          options: upDownCounter.options,
           records: [...upDownCounter.records],
         });
       });
       meter.histograms.forEach((histogram) => {
         allRecords.push({
           instrument: 'histogram',
+          name: histogram.name,
+          options: histogram.options,
           records: [...histogram.records],
         });
       });
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index 9900e2b..79c4848 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -14,7 +14,7 @@ const providers = () => ({
 });
 const plain = (config, receipt = { successful: true, messageId: 'm1' }) => ({
   config,
-  send: async () => receipt,
+  send: async (message) => (typeof receipt === 'function' ? receipt(message) : receipt),
   async *sendMany(messages) {
     for await (const message of messages) {
       yield typeof receipt === 'function' ? receipt(message) : receipt;
@@ -196,3 +196,29 @@ test('OTel: active sends return to zero however a send or a batch ends', async (
   assert.strictEqual(changes, 10);
   assert.strictEqual(sum, 0);
 });
+
+test('OTel: a message is counted once, with its priority and its outcome', async () => {
+  const { tracerProvider, meterProvider } = providers();
+  const failure = { successful: false, errorMessages: ['Rejected'], errors: [] };
+  const transport = new OpenTelemetryTransport(
+    plain({}, (message) =>
+      message.priority === 'low' ? failure : { successful: true, messageId: 'm1' },
+    ),
+    { tracerProvider, meterProvider },
+  );
+  await transport.send(createTestMessage({ priority: 'high' }));
+  await collect(
+    transport.sendMany([
+      createTestMessage({ priority: 'normal' }),
+      createTestMessage({ priority: 'low' }),
+    ]),
+  );
+  const messages = meterProvider
+    .getAllRecords()
+    .find((metric) => metric.name === 'mailer_email_messages_total');
+  assert.deepStrictEqual(messages.records, [
+    { value: 1, attributes: { transport: 'unknown', priority: 'high', status: 'success' } },
+    { value: 1, attributes: { transport: 'unknown', priority: 'normal', status: 'success' } },
+    { value: 1, attributes: { transport: 'unknown', priority: 'low', status: 'failure' } },
+  ]);
+});

From 7e6139c099b62c2ad8b2c00ff30f45c32ccde169 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:44:10 +0300
Subject: [PATCH 082/158] fix(otel): count a batch that failed entirely as a
 failure

recordBatch labelled every batch with a failure 'partial_failure', so a
batch in which no message was sent looked like one in which some were.
The status is now 'success', 'partial_failure' or 'failure'.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  2 ++
 CLAUDE.md               |  2 ++
 src/otel/metrics.js     |  9 ++++++++-
 tests/unit/otel.test.js | 24 ++++++++++++++++++++++++
 4 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2d219bf..66f8fa9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -193,6 +193,8 @@ fixed ones below.
   twice, its size at the start and then its successes and failures, and every message with
   `priority: 'normal'`. It now takes each receipt once, with the priority of its message and its
   `status`.
+- **`./otel` tells a failed batch from a partly failed one** (an upstream bug): a batch in which
+  every message failed was counted with `status: 'partial_failure'`. It is now a `failure`.
 
 ### Changed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 8e9b554..cfba4bf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -270,6 +270,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 46. otel: the message counter took every message of a batch twice (its size at the start, then
     its successes and failures), and always with `priority: 'normal'`. It takes each receipt
     once, with the priority of its message and its status.
+47. otel: a batch in which every message failed was counted as a `partial_failure`. It is a
+    `failure`; `partial_failure` is left for a batch with both outcomes.
 
 ## Repository layout
 
diff --git a/src/otel/metrics.js b/src/otel/metrics.js
index d5e2d4c..93d1c4b 100644
--- a/src/otel/metrics.js
+++ b/src/otel/metrics.js
@@ -4,6 +4,13 @@
 const metadata = require('../version.js');
 const { estimateMessageSize } = require('./message-size.js');
 
+// A batch with no failure succeeded, one with no success failed, and the rest
+// failed in part.
+const batchStatus = (successCount, failureCount) => {
+  if (failureCount === 0) return 'success';
+  return successCount === 0 ? 'failure' : 'partial_failure';
+};
+
 /**
  * Manages OpenTelemetry metrics collection for email operations.
  */
@@ -133,7 +140,7 @@ class MetricsCollector {
     // Record batch-level metrics
     this.attemptCounter.add(1, {
       ...labels,
-      status: failureCount === 0 ? 'success' : 'partial_failure',
+      status: batchStatus(successCount, failureCount),
       operation: 'batch',
     });
 
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index 79c4848..93569d7 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -222,3 +222,27 @@ test('OTel: a message is counted once, with its priority and its outcome', async
     { value: 1, attributes: { transport: 'unknown', priority: 'low', status: 'failure' } },
   ]);
 });
+
+test('OTel: a batch is a success, a partial failure or a failure', async () => {
+  const failure = { successful: false, errorMessages: ['Rejected'], errors: [] };
+  const sent = { successful: true, messageId: 'm1' };
+  const cases = [
+    [[sent, sent], 'success'],
+    [[sent, failure], 'partial_failure'],
+    [[failure, failure], 'failure'],
+  ];
+  for (const [receipts, status] of cases) {
+    const { tracerProvider, meterProvider } = providers();
+    let index = 0;
+    const transport = new OpenTelemetryTransport(
+      plain({}, () => receipts[index++]),
+      { tracerProvider, meterProvider },
+    );
+    await collect(transport.sendMany([createTestMessage(), createTestMessage()]));
+    const attempts = meterProvider
+      .getAllRecords()
+      .find((metric) => metric.name === 'mailer_email_attempts_total');
+    assert.strictEqual(attempts.records.length, 1);
+    assert.strictEqual(attempts.records[0].attributes.status, status);
+  }
+});

From 90bd1e2cc5eabe5848db2efb004260a2323ce9b5 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:45:02 +0300
Subject: [PATCH 083/158] fix(otel): pass the duration buckets to the histogram

metrics.durationBuckets was resolved with a default and never read, so the
duration histogram always got the SDK's default boundaries. It is now
passed as the advice explicitBucketBoundaries, which the OpenTelemetry API
accepts since 1.7 and a View of the application still overrides. The JSDoc
examples used a histogramBoundaries option that never existed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  3 +++
 CLAUDE.md               |  4 +++-
 docs/transports/otel.md |  3 +++
 src/otel/index.d.ts     | 10 +++++++---
 src/otel/index.js       |  2 +-
 src/otel/metrics.js     |  1 +
 tests/unit/otel.test.js | 15 +++++++++++++++
 7 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 66f8fa9..189a498 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -195,6 +195,9 @@ fixed ones below.
   `status`.
 - **`./otel` tells a failed batch from a partly failed one** (an upstream bug): a batch in which
   every message failed was counted with `status: 'partial_failure'`. It is now a `failure`.
+- **`./otel` applies `metrics.durationBuckets`** (an upstream bug): the option was never read. The
+  duration histogram passes it to the SDK as the advice `explicitBucketBoundaries`
+  (OpenTelemetry API 1.7 or later), which a View of the application still overrides.
 
 ### Changed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index cfba4bf..be2f1b2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -133,7 +133,7 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 5. `cram-md5` is in the `SmtpAuth` type but not implemented.
 6. DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails.
 7. pool: `continueOnSuccess` is never read.
-8. otel (partly fixed, see 44 and 45): `durationBuckets` and `auto` are ignored; `recordRetry` is never called; `sendMany` buffers
+8. otel (partly fixed, see 44, 45 and 48): `auto` is ignored; `recordRetry` is never called; `sendMany` buffers
    its whole input; `defaultErrorClassifier` matches `"auth"` as a substring.
 9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
@@ -272,6 +272,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     once, with the priority of its message and its status.
 47. otel: a batch in which every message failed was counted as a `partial_failure`. It is a
     `failure`; `partial_failure` is left for a batch with both outcomes.
+48. otel: `metrics.durationBuckets` was never read. The duration histogram passes it to the SDK
+    as the advice `explicitBucketBoundaries`.
 
 ## Repository layout
 
diff --git a/docs/transports/otel.md b/docs/transports/otel.md
index 2bfd343..6546938 100644
--- a/docs/transports/otel.md
+++ b/docs/transports/otel.md
@@ -357,6 +357,9 @@ Metrics are recorded for every operation; `tracing.samplingRate` samples
 only the spans. A sampled counter would undercount by the sampling rate, and a
 sampled count of active sends would drift, so the metrics configuration has no
 sampling rate, and setting `metrics.samplingRate` throws a `TypeError`.
+`durationBuckets` reaches the SDK as the advice `explicitBucketBoundaries` of the
+duration histogram (OpenTelemetry API 1.7 or later); a View of the application
+takes precedence over it.
 
 The transport collects the following key metrics:
 
diff --git a/src/otel/index.d.ts b/src/otel/index.d.ts
index 93126dc..a784184 100644
--- a/src/otel/index.d.ts
+++ b/src/otel/index.d.ts
@@ -43,6 +43,8 @@ export interface TracerProvider {
 export interface MetricOptions {
   description?: string;
   unit?: string;
+  /** Hints for the SDK, such as the bucket boundaries of a histogram. */
+  advice?: { explicitBucketBoundaries?: number[] };
 }
 
 /** A counter, or an up-down counter, of the OpenTelemetry API. */
@@ -89,7 +91,9 @@ export interface MetricsConfig extends ObservabilityConfig {
    */
   readonly prefix?: string;
   /**
-   * Custom histogram buckets for duration metrics (in seconds).
+   * Bucket boundaries of the duration histogram, in seconds, passed to the SDK
+   * as the advice `explicitBucketBoundaries` (OpenTelemetry API 1.7 or later;
+   * a View of the application takes precedence).
    * @default [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0]
    */
   readonly durationBuckets?: readonly number[];
@@ -358,7 +362,7 @@ export declare class OpenTelemetryTransport<TProviderId extends string = string>
  *   },
  *   metrics: {
  *     enabled: true,
- *     histogramBoundaries: [10, 50, 100, 500, 1000],
+ *     durationBuckets: [0.1, 0.5, 1, 5, 10],
  *   },
  *   auto: {
  *     tracing: {
@@ -459,7 +463,7 @@ export interface CreateOpenTelemetryTransportConfig extends Omit<OpenTelemetryCo
  *   },
  *   metrics: {
  *     enabled: true,
- *     histogramBoundaries: [10, 50, 100, 500, 1000, 5000],
+ *     durationBuckets: [0.1, 0.5, 1, 5, 10],
  *   },
  * });
  * ```
diff --git a/src/otel/index.js b/src/otel/index.js
index 1ac1435..2d28243 100644
--- a/src/otel/index.js
+++ b/src/otel/index.js
@@ -73,7 +73,7 @@ const { defaultErrorClassifier } = require('./config.js');
  *   },
  *   metrics: {
  *     enabled: true,
- *     histogramBoundaries: [10, 50, 100, 500, 1000, 5000],
+ *     durationBuckets: [0.1, 0.5, 1, 5, 10],
  *   },
  * });
  * ```
diff --git a/src/otel/metrics.js b/src/otel/metrics.js
index 93d1c4b..4c278d4 100644
--- a/src/otel/metrics.js
+++ b/src/otel/metrics.js
@@ -49,6 +49,7 @@ class MetricsCollector {
     this.durationHistogram = this.meter.createHistogram(`${config.prefix}_email_duration_seconds`, {
       description: 'Duration of email send operations',
       unit: 's',
+      advice: { explicitBucketBoundaries: [...config.durationBuckets] },
     });
 
     this.messageSizeHistogram = this.meter.createHistogram(
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index 93569d7..39fd92f 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -246,3 +246,18 @@ test('OTel: a batch is a success, a partial failure or a failure', async () => {
     assert.strictEqual(attempts.records[0].attributes.status, status);
   }
 });
+
+test('OTel: the duration buckets reach the histogram as advice', () => {
+  for (const [metrics, buckets] of [
+    [{}, [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0]],
+    [{ durationBuckets: [0.5, 2] }, [0.5, 2]],
+  ]) {
+    const { tracerProvider, meterProvider } = providers();
+    // oxlint-disable-next-line no-new -- the instruments are made by the constructor
+    new OpenTelemetryTransport(plain({}), { tracerProvider, meterProvider, metrics });
+    const duration = meterProvider
+      .getAllRecords()
+      .find((metric) => metric.name === 'mailer_email_duration_seconds');
+    assert.deepStrictEqual(duration.options.advice, { explicitBucketBoundaries: buckets });
+  }
+});

From 5feb44ab116a3c8db2c76a1b9fcc283a88107531 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:47:10 +0300
Subject: [PATCH 084/158] fix(otel)!: refuse the auto and service options it
 never read

createOpenTelemetryTransport took serviceName, serviceVersion and auto
and passed them on to a configuration that dropped them, so the exporters
and resource attributes they described were never set up. Those belong to
the OpenTelemetry SDK that builds the providers the transport is given,
so the options now throw a TypeError, AutoConfig and
CreateOpenTelemetryTransportConfig are removed, and the factory takes an
OpenTelemetryConfig like the constructor. The docs no longer pass them,
and the known issues page drops the otel bugs fixed so far.

BREAKING CHANGE: auto, serviceName and serviceVersion throw a TypeError.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                  |   5 ++
 CLAUDE.md                     |   5 +-
 docs/guide/known-issues.md    |   5 +-
 docs/transports/otel.md       |  22 ++----
 src/otel/config.js            |  16 ++++-
 src/otel/index.d.ts           | 131 +++-------------------------------
 src/otel/index.js             |  58 ++-------------
 tests/types/otel.test-d.ts    |   2 +
 tests/unit/otel-index.test.js |  45 ++++++------
 9 files changed, 73 insertions(+), 216 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 189a498..11f2ae6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -198,6 +198,11 @@ fixed ones below.
 - **`./otel` applies `metrics.durationBuckets`** (an upstream bug): the option was never read. The
   duration histogram passes it to the SDK as the advice `explicitBucketBoundaries`
   (OpenTelemetry API 1.7 or later), which a View of the application still overrides.
+- **`./otel` refuses the options it cannot honor** (an upstream bug): `auto`, `serviceName` and
+  `serviceVersion` were accepted and never read, since the providers are passed in and the
+  exporters and resource attributes belong to the SDK that builds them. They now throw a
+  `TypeError`; the types `AutoConfig` and `CreateOpenTelemetryTransportConfig` are removed and
+  `createOpenTelemetryTransport` takes an `OpenTelemetryConfig`.
 
 ### Changed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index be2f1b2..4d0fbc9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -133,7 +133,7 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 5. `cram-md5` is in the `SmtpAuth` type but not implemented.
 6. DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails.
 7. pool: `continueOnSuccess` is never read.
-8. otel (partly fixed, see 44, 45 and 48): `auto` is ignored; `recordRetry` is never called; `sendMany` buffers
+8. otel (partly fixed, see 44, 45, 48 and 49): `recordRetry` is never called; `sendMany` buffers
    its whole input; `defaultErrorClassifier` matches `"auth"` as a substring.
 9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
@@ -274,6 +274,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     `failure`; `partial_failure` is left for a batch with both outcomes.
 48. otel: `metrics.durationBuckets` was never read. The duration histogram passes it to the SDK
     as the advice `explicitBucketBoundaries`.
+49. otel: `auto`, `serviceName` and `serviceVersion` were accepted and never read: exporters and
+    resource attributes belong to the SDK that builds the providers passed in. They throw a
+    `TypeError`, and `AutoConfig` and `CreateOpenTelemetryTransportConfig` are gone.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 3219397..7329fc0 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -32,6 +32,5 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 ## Decorators
 
 - `./pool`: `continueOnSuccess` is never read.
-- `./otel`: `durationBuckets` and `auto` are ignored, `recordRetry` is never called, `sendMany`
-  buffers its whole input, the active sends gauge drifts under sampling, and the default error
-  classifier matches `auth` and status codes as substrings of the message.
+- `./otel`: `recordRetry` is never called, `sendMany` buffers its whole input, and the default
+  error classifier matches `auth` and status codes as substrings of the message.
diff --git a/docs/transports/otel.md b/docs/transports/otel.md
index 6546938..f4fc482 100644
--- a/docs/transports/otel.md
+++ b/docs/transports/otel.md
@@ -88,8 +88,7 @@ for analysis and monitoring.
 
 ## Simplified setup
 
-For easier configuration, use the factory function, which applies sensible
-defaults:
+The factory function takes the same configuration as the constructor:
 
 ```js
 const { trace, metrics } = require('@opentelemetry/api');
@@ -109,8 +108,6 @@ const baseTransport = new SmtpTransport({
 const transport = createOpenTelemetryTransport(baseTransport, {
   tracerProvider: trace.getTracerProvider(),
   meterProvider: metrics.getMeterProvider(),
-  serviceName: 'email-service',
-  serviceVersion: '1.2.0',
   metrics: {
     enabled: true,
     prefix: 'myapp',
@@ -126,7 +123,9 @@ The providers are always passed in, while tracing or metrics are enabled: there
 is no fallback to the global providers of `@opentelemetry/api`, since this
 package does not require it.  Pass `trace.getTracerProvider()` and
 `metrics.getMeterProvider()` for the global ones, or providers of your own as
-below.
+below.  Exporters and resource attributes such as `service.name` are set up with
+the SDK that builds those providers, so the `auto`, `serviceName` and
+`serviceVersion` options of upyo throw a `TypeError` here.
 
 ## Using existing providers
 
@@ -172,8 +171,6 @@ const transport = createOpenTelemetryTransport(
   {
     tracerProvider, // Use your existing tracer provider
     meterProvider, // Use your existing meter provider
-    serviceName: 'my-application',
-    serviceVersion: '1.0.0',
     tracing: {
       enabled: true,
       recordSensitiveData: false,
@@ -232,7 +229,6 @@ await using transport = createOpenTelemetryTransport(
   {
     tracerProvider,
     meterProvider,
-    serviceName: 'notification-service',
     tracing: { enabled: true },
     metrics: { enabled: true },
   },
@@ -274,7 +270,6 @@ const transport = createOpenTelemetryTransport(
   {
     tracerProvider,
     meterProvider,
-    serviceName: 'user-service',
     tracing: {
       enabled: true,
       recordSensitiveData: false,
@@ -339,7 +334,6 @@ const transport = createOpenTelemetryTransport(
   {
     tracerProvider,
     meterProvider,
-    serviceName: 'marketing-service',
     metrics: {
       enabled: true,
       prefix: 'marketing',
@@ -416,7 +410,6 @@ const transport = createOpenTelemetryTransport(
   {
     tracerProvider,
     meterProvider,
-    serviceName: 'notification-service',
     errorClassifier: customClassifier,
     metrics: { enabled: true },
     tracing: { enabled: true },
@@ -470,7 +463,6 @@ const transport = createOpenTelemetryTransport(
   {
     tracerProvider,
     meterProvider,
-    serviceName: 'transactional-email',
     attributeExtractor: customExtractor,
     tracing: { enabled: true },
     metrics: { enabled: true },
@@ -505,7 +497,6 @@ const transport = createOpenTelemetryTransport(
   {
     tracerProvider,
     meterProvider,
-    serviceName: 'newsletter-service',
     metrics: { enabled: true },
     tracing: {
       enabled: true,
@@ -581,7 +572,6 @@ const transport = createOpenTelemetryTransport(
   {
     tracerProvider,
     meterProvider,
-    serviceName: 'production-email',
     metrics: {
       enabled: true,
       prefix: 'prod',
@@ -607,7 +597,6 @@ const bulkTransport = createOpenTelemetryTransport(
   {
     tracerProvider,
     meterProvider,
-    serviceName: 'bulk-email',
     metrics: { enabled: true },
     tracing: { enabled: false }, // Disable tracing for maximum performance
   },
@@ -643,8 +632,6 @@ const devTransport = createOpenTelemetryTransport(
   {
     tracerProvider,
     meterProvider,
-    serviceName: 'email-service-dev',
-    serviceVersion: 'dev',
     metrics: { enabled: true },
     tracing: {
       enabled: true,
@@ -658,7 +645,6 @@ const devTransport = createOpenTelemetryTransport(
 const testTransport = createOpenTelemetryTransport(new MockTransport({ failureRate: 0 }), {
   tracerProvider,
   meterProvider,
-  serviceName: 'email-service-test',
   metrics: { enabled: true },
   tracing: { enabled: true },
   errorClassifier: (error) => {
diff --git a/src/otel/config.js b/src/otel/config.js
index 36e2d34..d2ec8a2 100644
--- a/src/otel/config.js
+++ b/src/otel/config.js
@@ -18,6 +18,11 @@ const DEFAULT_CONFIG = {
   },
 };
 
+// Options of upstream that set up exporters and resource attributes, which
+// belong to the OpenTelemetry SDK of the application: it builds the providers
+// passed in.  They were accepted and never read.
+const SDK_OPTIONS = ['auto', 'serviceName', 'serviceVersion'];
+
 /**
  * Creates a resolved OpenTelemetry configuration with defaults applied.
  *
@@ -25,9 +30,18 @@ const DEFAULT_CONFIG = {
  * @returns A resolved configuration with all defaults applied.
  * @throws {Error} When tracing is enabled but no TracerProvider is provided.
  * @throws {Error} When metrics are enabled but no MeterProvider is provided.
- * @throws {TypeError} When `metrics.samplingRate` is set.
+ * @throws {TypeError} When `metrics.samplingRate`, `auto`, `serviceName` or
+ *                     `serviceVersion` is set.
  */
 const createOpenTelemetryConfig = (config = {}) => {
+  for (const option of SDK_OPTIONS) {
+    if (config[option] !== undefined) {
+      throw new TypeError(
+        `${option} is not supported: exporters and resource attributes are set up ` +
+          'with the OpenTelemetry SDK of the application, whose providers are passed in.',
+      );
+    }
+  }
   // Sampled counters and histograms undercount by the sampling rate, and a
   // sampled UpDownCounter drifts, so metrics are recorded for every operation
   // and only spans are sampled.
diff --git a/src/otel/index.d.ts b/src/otel/index.d.ts
index a784184..be1ec17 100644
--- a/src/otel/index.d.ts
+++ b/src/otel/index.d.ts
@@ -132,34 +132,6 @@ export type AttributeExtractor = (
  * Custom error classifier function type.
  */
 export type ErrorClassifier = (error: unknown) => string;
-/**
- * Configuration options for auto-setup scenarios.
- */
-export interface AutoConfig {
-  /**
-   * Service name for OpenTelemetry resource attributes.
-   * @default "email-service"
-   */
-  readonly serviceName?: string;
-  /**
-   * Service version for OpenTelemetry resource attributes.
-   */
-  readonly serviceVersion?: string;
-  /**
-   * Tracing endpoint configuration.
-   */
-  readonly tracing?: {
-    readonly endpoint?: string;
-    readonly headers?: Record<string, string>;
-  };
-  /**
-   * Metrics endpoint configuration.
-   */
-  readonly metrics?: {
-    readonly endpoint?: string;
-    readonly headers?: Record<string, string>;
-  };
-}
 /**
  * Configuration for the OpenTelemetry transport.
  */
@@ -194,11 +166,6 @@ export interface OpenTelemetryConfig {
    * Called to classify errors into categories for metrics.
    */
   readonly errorClassifier?: ErrorClassifier;
-  /**
-   * Auto-configuration options for simplified setup.
-   * When provided, missing providers will be auto-configured.
-   */
-  readonly auto?: AutoConfig;
 }
 /**
  * Resolved configuration with all defaults applied.
@@ -314,7 +281,8 @@ export declare class OpenTelemetryTransport<TProviderId extends string = string>
    * @param transport The base transport to wrap with observability.
    * @param config OpenTelemetry configuration options.
    * @throws {Error} When an enabled feature has no provider.
-   * @throws {TypeError} When `metrics.samplingRate` is set.
+   * @throws {TypeError} When `auto`, `serviceName`, `serviceVersion` or
+   *                     `metrics.samplingRate` is set.
    */
   constructor(transport: Transport<TProviderId>, config?: OpenTelemetryConfig);
   /**
@@ -342,58 +310,6 @@ export declare class OpenTelemetryTransport<TProviderId extends string = string>
   [Symbol.asyncDispose](): Promise<void>;
 }
 
-/**
- * Configuration options for the createOpenTelemetryTransport factory function.
- *
- * This interface extends the base OpenTelemetryConfig with additional options
- * for service identification and auto-configuration. It provides a simplified
- * way to configure OpenTelemetry observability without manually setting up
- * providers and exporters.
- *
- * @example
- * ```typescript
- * const config: CreateOpenTelemetryTransportConfig = {
- *   serviceName: "email-service",
- *   serviceVersion: "1.2.0",
- *   tracing: {
- *     enabled: true,
- *     samplingRate: 0.1,
- *     recordSensitiveData: false,
- *   },
- *   metrics: {
- *     enabled: true,
- *     durationBuckets: [0.1, 0.5, 1, 5, 10],
- *   },
- *   auto: {
- *     tracing: {
- *       endpoint: "http://jaeger:14268/api/traces",
- *     },
- *     metrics: {
- *       endpoint: "http://prometheus:9090/api/v1/write",
- *     },
- *   },
- * };
- * ```
- */
-export interface CreateOpenTelemetryTransportConfig extends Omit<OpenTelemetryConfig, 'auto'> {
-  /**
-   * Service name for OpenTelemetry resource attributes.
-   * This identifies your service in distributed traces and metrics.
-   * @default "email-service"
-   */
-  readonly serviceName?: string;
-  /**
-   * Service version for OpenTelemetry resource attributes.
-   * Useful for tracking performance across different deployment versions.
-   */
-  readonly serviceVersion?: string;
-  /**
-   * Auto-configuration options for setting up OpenTelemetry exporters and processors.
-   * When provided, the factory function will automatically configure the necessary
-   * infrastructure for sending telemetry data to observability backends.
-   */
-  readonly auto?: AutoConfig;
-}
 /**
  * Creates an OpenTelemetry transport for email operations with comprehensive
  * observability features.
@@ -405,21 +321,18 @@ export interface CreateOpenTelemetryTransportConfig extends Omit<OpenTelemetryCo
  * The `tracerProvider` and `meterProvider` are passed in, from the
  * application's OpenTelemetry setup: this package does not require
  * `@opentelemetry/api`, so there is no fallback to its global providers.
+ * Exporters and resource attributes, such as the service name, belong to that
+ * setup too, so the `auto`, `serviceName` and `serviceVersion` options of
+ * upstream are refused.
  *
  * @param baseTransport The underlying email transport to wrap with
  *                      OpenTelemetry instrumentation.
  * @param config Configuration options for OpenTelemetry setup including
  *               providers, sampling rates, and custom extractors.
- * @param config.serviceName Service name for OpenTelemetry resource attributes.
- *                           Defaults to "email-service".
- * @param config.serviceVersion Service version for OpenTelemetry resource
- *                              attributes.
  * @param config.tracerProvider The TracerProvider of the application, required
  *                              while tracing is enabled.
  * @param config.meterProvider The MeterProvider of the application, required
  *                             while metrics are enabled.
- * @param config.auto Auto-configuration options for setting up exporters and
- *                    processors.
  * @param config.tracing Tracing configuration including sampling rates and
  *                       span settings.
  * @param config.metrics Metrics configuration including histogram boundaries
@@ -430,24 +343,10 @@ export interface CreateOpenTelemetryTransportConfig extends Omit<OpenTelemetryCo
  *                               types.
  * @returns An OpenTelemetry-enabled transport that instruments all email
  *          operations with traces and metrics.
+ * @throws {TypeError} When `auto`, `serviceName`, `serviceVersion` or
+ *                     `metrics.samplingRate` is set.
  *
- * @example With minimal configuration
- * ```typescript
- * import { createOpenTelemetryTransport } from "@alexify/mailer/otel";
- * import { createSmtpTransport } from "@alexify/mailer/smtp";
- *
- * const smtpTransport = createSmtpTransport({
- *   host: "smtp.example.com",
- *   port: 587,
- * });
- *
- * const transport = createOpenTelemetryTransport(smtpTransport, {
- *   serviceName: "email-service",
- *   serviceVersion: "1.0.0",
- * });
- * ```
- *
- * @example With explicit providers
+ * @example
  * ```typescript
  * import { createOpenTelemetryTransport } from "@alexify/mailer/otel";
  * import { trace, metrics } from "@opentelemetry/api";
@@ -455,7 +354,6 @@ export interface CreateOpenTelemetryTransportConfig extends Omit<OpenTelemetryCo
  * const transport = createOpenTelemetryTransport(baseTransport, {
  *   tracerProvider: trace.getTracerProvider(),
  *   meterProvider: metrics.getMeterProvider(),
- *   serviceName: "my-email-service",
  *   tracing: {
  *     enabled: true,
  *     samplingRate: 0.1,
@@ -467,21 +365,10 @@ export interface CreateOpenTelemetryTransportConfig extends Omit<OpenTelemetryCo
  *   },
  * });
  * ```
- *
- * @example With auto-configuration
- * ```typescript
- * const transport = createOpenTelemetryTransport(baseTransport, {
- *   serviceName: "email-service",
- *   auto: {
- *     tracing: { endpoint: "http://jaeger:14268/api/traces" },
- *     metrics: { endpoint: "http://prometheus:9090/api/v1/write" }
- *   }
- * });
- * ```
  */
 export declare function createOpenTelemetryTransport<TProviderId extends string = string>(
   baseTransport: Transport<TProviderId>,
-  config?: CreateOpenTelemetryTransportConfig,
+  config?: OpenTelemetryConfig,
 ): OpenTelemetryTransport<TProviderId>;
 /**
  * Creates a custom email attribute extractor function for OpenTelemetry
diff --git a/src/otel/index.js b/src/otel/index.js
index 2d28243..0708a5c 100644
--- a/src/otel/index.js
+++ b/src/otel/index.js
@@ -15,21 +15,18 @@ const { defaultErrorClassifier } = require('./config.js');
  * The `tracerProvider` and `meterProvider` are passed in, from the
  * application's OpenTelemetry setup: this package does not require
  * `@opentelemetry/api`, so there is no fallback to its global providers.
+ * Exporters and resource attributes, such as the service name, belong to that
+ * setup too, so the `auto`, `serviceName` and `serviceVersion` options of
+ * upstream are refused.
  *
  * @param baseTransport The underlying email transport to wrap with
  *                      OpenTelemetry instrumentation.
  * @param config Configuration options for OpenTelemetry setup including
  *               providers, sampling rates, and custom extractors.
- * @param config.serviceName Service name for OpenTelemetry resource attributes.
- *                           Defaults to "email-service".
- * @param config.serviceVersion Service version for OpenTelemetry resource
- *                              attributes.
  * @param config.tracerProvider The TracerProvider of the application, required
  *                              while tracing is enabled.
  * @param config.meterProvider The MeterProvider of the application, required
  *                             while metrics are enabled.
- * @param config.auto Auto-configuration options for setting up exporters and
- *                    processors.
  * @param config.tracing Tracing configuration including sampling rates and
  *                       span settings.
  * @param config.metrics Metrics configuration including histogram boundaries
@@ -40,24 +37,10 @@ const { defaultErrorClassifier } = require('./config.js');
  *                               types.
  * @returns An OpenTelemetry-enabled transport that instruments all email
  *          operations with traces and metrics.
+ * @throws {TypeError} When `auto`, `serviceName`, `serviceVersion` or
+ *                     `metrics.samplingRate` is set.
  *
- * @example With minimal configuration
- * ```typescript
- * import { createOpenTelemetryTransport } from "@alexify/mailer/otel";
- * import { createSmtpTransport } from "@alexify/mailer/smtp";
- *
- * const smtpTransport = createSmtpTransport({
- *   host: "smtp.example.com",
- *   port: 587,
- * });
- *
- * const transport = createOpenTelemetryTransport(smtpTransport, {
- *   serviceName: "email-service",
- *   serviceVersion: "1.0.0",
- * });
- * ```
- *
- * @example With explicit providers
+ * @example
  * ```typescript
  * import { createOpenTelemetryTransport } from "@alexify/mailer/otel";
  * import { trace, metrics } from "@opentelemetry/api";
@@ -65,7 +48,6 @@ const { defaultErrorClassifier } = require('./config.js');
  * const transport = createOpenTelemetryTransport(baseTransport, {
  *   tracerProvider: trace.getTracerProvider(),
  *   meterProvider: metrics.getMeterProvider(),
- *   serviceName: "my-email-service",
  *   tracing: {
  *     enabled: true,
  *     samplingRate: 0.1,
@@ -77,35 +59,9 @@ const { defaultErrorClassifier } = require('./config.js');
  *   },
  * });
  * ```
- *
- * @example With auto-configuration
- * ```typescript
- * const transport = createOpenTelemetryTransport(baseTransport, {
- *   serviceName: "email-service",
- *   auto: {
- *     tracing: { endpoint: "http://jaeger:14268/api/traces" },
- *     metrics: { endpoint: "http://prometheus:9090/api/v1/write" }
- *   }
- * });
- * ```
  */
 const createOpenTelemetryTransport = (baseTransport, config = {}) => {
-  const { serviceName = 'email-service', serviceVersion, auto, ...otherConfig } = config;
-
-  // The providers come from the application, never from a global API.
-  const finalConfig = {
-    ...otherConfig,
-    // Add auto-configuration if specified
-    ...(auto && {
-      auto: {
-        serviceName,
-        serviceVersion,
-        ...auto,
-      },
-    }),
-  };
-
-  return new OpenTelemetryTransport(baseTransport, finalConfig);
+  return new OpenTelemetryTransport(baseTransport, config);
 };
 
 /**
diff --git a/tests/types/otel.test-d.ts b/tests/types/otel.test-d.ts
index 9cfada0..79b861f 100644
--- a/tests/types/otel.test-d.ts
+++ b/tests/types/otel.test-d.ts
@@ -41,3 +41,5 @@ expectAssignable<Function>(createEmailAttributeExtractor);
 expectError(new OpenTelemetryTransport(new MockTransport(), { tracerProvider: 'global' }));
 // Metrics are recorded for every operation; only tracing has a sampling rate.
 expectError(new OpenTelemetryTransport(new MockTransport(), { metrics: { samplingRate: 0.5 } }));
+// Exporters and resource attributes belong to the SDK of the application.
+expectError(createOpenTelemetryTransport(new MockTransport(), { serviceName: 'billing' }));
diff --git a/tests/unit/otel-index.test.js b/tests/unit/otel-index.test.js
index cb960d3..99b02a4 100644
--- a/tests/unit/otel-index.test.js
+++ b/tests/unit/otel-index.test.js
@@ -23,31 +23,37 @@ describe('index', () => {
       assert.ok(transport instanceof OpenTelemetryTransport);
     });
 
+    // Changed after the port: the service name and version, and the auto
+    // configuration, were accepted and never read; they belong to the SDK
+    // that builds the providers, and are refused.
     it('should use custom service name and version', () => {
       const setup = createTestSetup();
-      const transport = createOpenTelemetryTransport(setup.mockTransport, {
-        tracerProvider: setup.tracerProvider,
-        meterProvider: setup.meterProvider,
-        serviceName: 'my-email-service',
-        serviceVersion: '1.2.3',
-      });
-
-      assert.ok(transport instanceof OpenTelemetryTransport);
+      assert.throws(
+        () =>
+          createOpenTelemetryTransport(setup.mockTransport, {
+            tracerProvider: setup.tracerProvider,
+            meterProvider: setup.meterProvider,
+            serviceName: 'my-email-service',
+            serviceVersion: '1.2.3',
+          }),
+        { name: 'TypeError', message: /^serviceName is not supported/ },
+      );
     });
 
     it('should work with auto configuration', () => {
       const setup = createTestSetup();
-      const transport = createOpenTelemetryTransport(setup.mockTransport, {
-        tracerProvider: setup.tracerProvider,
-        meterProvider: setup.meterProvider,
-        serviceName: 'email-service',
-        auto: {
-          tracing: { endpoint: 'http://jaeger:14268/api/traces' },
-          metrics: { endpoint: 'http://prometheus:9090/api/v1/write' },
-        },
-      });
-
-      assert.ok(transport instanceof OpenTelemetryTransport);
+      assert.throws(
+        () =>
+          createOpenTelemetryTransport(setup.mockTransport, {
+            tracerProvider: setup.tracerProvider,
+            meterProvider: setup.meterProvider,
+            auto: {
+              tracing: { endpoint: 'http://jaeger:14268/api/traces' },
+              metrics: { endpoint: 'http://prometheus:9090/api/v1/write' },
+            },
+          }),
+        { name: 'TypeError', message: /^auto is not supported/ },
+      );
     });
 
     // Changed in the port: the providers are passed in, with no fallback to
@@ -74,7 +80,6 @@ describe('index', () => {
         meterProvider: setup.meterProvider,
         metrics: { prefix: 'custom' },
         tracing: { recordSensitiveData: true },
-        serviceName: 'test-service',
       });
 
       assert.equal(transport.config.metrics.prefix, 'custom');

From d22d19d37a6e997dc2ccbd7fb8fca059f7828789 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:48:57 +0300
Subject: [PATCH 085/158] fix(otel): classify thrown errors with the classifier
 of the receipts

defaultErrorClassifier tested the message for substrings in a fixed
order, so "Author unknown" was an auth error, "timeout after 5000ms" a
server error because of its "500", and its categories differed from those
the receipts of the same failures carried. It now returns the category of
classifyReceiptError, which reads words and status codes whole, and
"aborted" for an AbortError, which upstream counted as a network failure.
The ported tests say where the expectations changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                   |  5 ++
 CLAUDE.md                      |  8 +++-
 docs/guide/known-issues.md     |  3 +-
 docs/transports/otel.md        |  8 ++--
 src/otel/config.js             | 85 ++++++----------------------------
 src/otel/index.d.ts            | 14 ++++--
 tests/unit/otel-config.test.js | 18 ++++---
 tests/unit/otel.test.js        | 13 ++++++
 8 files changed, 63 insertions(+), 91 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 11f2ae6..fb5c43f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -203,6 +203,11 @@ fixed ones below.
   exporters and resource attributes belong to the SDK that builds them. They now throw a
   `TypeError`; the types `AutoConfig` and `CreateOpenTelemetryTransportConfig` are removed and
   `createOpenTelemetryTransport` takes an `OpenTelemetryConfig`.
+- **`./otel` classifies a thrown error like a failed receipt** (an upstream bug): the default
+  classifier looked for words and status codes as substrings, so `Author unknown` was an `auth`
+  error and `timeout after 5000ms` a `server-error`. It now gives the category of
+  `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
+  `aborted` for an `AbortError`, which upstream counted as `network`.
 
 ### Changed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 4d0fbc9..66ca3e4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -133,8 +133,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 5. `cram-md5` is in the `SmtpAuth` type but not implemented.
 6. DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails.
 7. pool: `continueOnSuccess` is never read.
-8. otel (partly fixed, see 44, 45, 48 and 49): `recordRetry` is never called; `sendMany` buffers
-   its whole input; `defaultErrorClassifier` matches `"auth"` as a substring.
+8. otel (partly fixed, see 44, 45 and 48 to 50): `recordRetry` is never called; `sendMany`
+   buffers its whole input.
 9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
 10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
@@ -277,6 +277,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 49. otel: `auto`, `serviceName` and `serviceVersion` were accepted and never read: exporters and
     resource attributes belong to the SDK that builds the providers passed in. They throw a
     `TypeError`, and `AutoConfig` and `CreateOpenTelemetryTransportConfig` are gone.
+50. otel: `defaultErrorClassifier` looked for words and status codes as substrings, before the
+    network check (`"Author unknown"` was `auth`, `"timeout after 5000ms"` a server error), and
+    disagreed with the categories of the receipts. It is `classifyReceiptError` of the root, plus
+    `aborted` for an `AbortError`, which upstream counted as a network failure.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 7329fc0..d7ef39c 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -32,5 +32,4 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 ## Decorators
 
 - `./pool`: `continueOnSuccess` is never read.
-- `./otel`: `recordRetry` is never called, `sendMany` buffers its whole input, and the default
-  error classifier matches `auth` and status codes as substrings of the message.
+- `./otel`: `recordRetry` is never called, and `sendMany` buffers its whole input.
diff --git a/docs/transports/otel.md b/docs/transports/otel.md
index f4fc482..9684e49 100644
--- a/docs/transports/otel.md
+++ b/docs/transports/otel.md
@@ -424,9 +424,11 @@ Error classifications appear in both metrics and trace data, allowing you to:
  -  Analyze error patterns across different email types
  -  Identify systematic issues vs. temporary problems
 
-The default classifier recognizes common email error patterns including
-authentication failures, rate limiting, network issues, validation errors,
-and server problems.
+The default classifier gives the category that `classifyReceiptError` of the
+root entry gives a failed receipt (`auth`, `rate-limit`, `network`, `timeout`,
+`validation`, `server-error` and so on), so a thrown error and a failed receipt
+land in the same categories, and `aborted` for an `AbortError`, which is a
+cancellation rather than a failure of the transport.
 
 ## Custom attributes and context
 
diff --git a/src/otel/config.js b/src/otel/config.js
index d2ec8a2..85df26f 100644
--- a/src/otel/config.js
+++ b/src/otel/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/opentelemetry/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { classifyReceiptError } = require('../core/receipt.js');
+
 /**
  * Default configuration values.
  */
@@ -85,7 +87,11 @@ const createOpenTelemetryConfig = (config = {}) => {
 };
 
 /**
- * Default error classifier that categorizes errors into standard types.
+ * Default error classifier that categorizes errors into standard types: the
+ * categories of a `ReceiptError`, from `classifyReceiptError` of the root
+ * entry, so that a thrown error and a failed receipt are classified alike,
+ * and `"aborted"` for an `AbortError`, which is a cancellation rather than a
+ * failure of the transport.
  *
  * @example
  * ```typescript
@@ -93,85 +99,20 @@ const createOpenTelemetryConfig = (config = {}) => {
  *
  * console.log(defaultErrorClassifier(new Error("401 Unauthorized"))); // "auth"
  * console.log(defaultErrorClassifier(new Error("Rate limit exceeded"))); // "rate-limit"
- * console.log(defaultErrorClassifier(new Error("Connection timeout"))); // "network"
+ * console.log(defaultErrorClassifier(new Error("Connection timeout"))); // "timeout"
  * console.log(defaultErrorClassifier(new Error("Invalid email format"))); // "validation"
  * console.log(defaultErrorClassifier(new Error("500 Internal Server Error"))); // "server-error"
  * console.log(defaultErrorClassifier(new Error("Something else"))); // "unknown"
  * ```
  *
  * @param error The error to classify.
- * @returns A string category such as `"auth"`, `"rate-limit"`, `"network"`,
- *          `"validation"`, `"service-unavailable"`, `"server-error"`, or
- *          `"unknown"`.
+ * @returns A category of `ReceiptError`, such as `"auth"`, `"rate-limit"`,
+ *          `"network"`, `"timeout"`, `"validation"`, `"server-error"` or
+ *          `"unknown"`, or `"aborted"`.
  */
 const defaultErrorClassifier = (error) => {
-  if (error instanceof Error) {
-    const message = error.message.toLowerCase();
-    const name = error.name.toLowerCase();
-
-    // Authentication errors
-    if (
-      message.includes('auth') ||
-      message.includes('unauthorized') ||
-      message.includes('invalid api key') ||
-      message.includes('403')
-    ) {
-      return 'auth';
-    }
-
-    // Rate limiting
-    if (
-      message.includes('rate limit') ||
-      message.includes('429') ||
-      message.includes('quota exceeded') ||
-      message.includes('throttle')
-    ) {
-      return 'rate-limit';
-    }
-
-    // Server errors (check before network errors to catch "504 Gateway Timeout")
-    if (
-      message.includes('500') ||
-      message.includes('502') ||
-      message.includes('504') ||
-      message.includes('internal server error')
-    ) {
-      return 'server-error';
-    }
-
-    // Network errors
-    if (
-      name.includes('network') ||
-      message.includes('connect') ||
-      message.includes('timeout') ||
-      message.includes('dns') ||
-      name === 'aborterror'
-    ) {
-      return 'network';
-    }
-
-    // Validation errors
-    if (
-      message.includes('invalid') ||
-      message.includes('malformed') ||
-      message.includes('validation') ||
-      message.includes('400')
-    ) {
-      return 'validation';
-    }
-
-    // Service unavailable
-    if (
-      message.includes('503') ||
-      message.includes('service unavailable') ||
-      message.includes('temporarily unavailable')
-    ) {
-      return 'service-unavailable';
-    }
-  }
-
-  // Fallback category
-  return 'unknown';
+  if (error instanceof Error && error.name === 'AbortError') return 'aborted';
+  return classifyReceiptError(error).category;
 };
 
 module.exports = { createOpenTelemetryConfig, defaultErrorClassifier };
diff --git a/src/otel/index.d.ts b/src/otel/index.d.ts
index be1ec17..49bf088 100644
--- a/src/otel/index.d.ts
+++ b/src/otel/index.d.ts
@@ -188,7 +188,11 @@ interface ResolvedOpenTelemetryConfig {
  */
 
 /**
- * Default error classifier that categorizes errors into standard types.
+ * Default error classifier that categorizes errors into standard types: the
+ * categories of a `ReceiptError`, from `classifyReceiptError` of the root
+ * entry, so that a thrown error and a failed receipt are classified alike,
+ * and `"aborted"` for an `AbortError`, which is a cancellation rather than a
+ * failure of the transport.
  *
  * @example
  * ```typescript
@@ -196,16 +200,16 @@ interface ResolvedOpenTelemetryConfig {
  *
  * console.log(defaultErrorClassifier(new Error("401 Unauthorized"))); // "auth"
  * console.log(defaultErrorClassifier(new Error("Rate limit exceeded"))); // "rate-limit"
- * console.log(defaultErrorClassifier(new Error("Connection timeout"))); // "network"
+ * console.log(defaultErrorClassifier(new Error("Connection timeout"))); // "timeout"
  * console.log(defaultErrorClassifier(new Error("Invalid email format"))); // "validation"
  * console.log(defaultErrorClassifier(new Error("500 Internal Server Error"))); // "server-error"
  * console.log(defaultErrorClassifier(new Error("Something else"))); // "unknown"
  * ```
  *
  * @param error The error to classify.
- * @returns A string category such as `"auth"`, `"rate-limit"`, `"network"`,
- *          `"validation"`, `"service-unavailable"`, `"server-error"`, or
- *          `"unknown"`.
+ * @returns A category of `ReceiptError`, such as `"auth"`, `"rate-limit"`,
+ *          `"network"`, `"timeout"`, `"validation"`, `"server-error"` or
+ *          `"unknown"`, or `"aborted"`.
  */
 export declare function defaultErrorClassifier(error: unknown): string;
 
diff --git a/tests/unit/otel-config.test.js b/tests/unit/otel-config.test.js
index 17817e8..550978b 100644
--- a/tests/unit/otel-config.test.js
+++ b/tests/unit/otel-config.test.js
@@ -134,18 +134,14 @@ describe('config', () => {
 
     it('should classify network errors', () => {
       const errors = [
-        new Error('Connection timeout'),
+        // Changed after the port: a timeout and an abort have categories of
+        // their own (see "should tell timeouts and aborts" below).
         new Error('DNS resolution failed'),
         (() => {
           const e = new Error('Network is unreachable');
           e.name = 'NetworkError';
           return e;
         })(),
-        (() => {
-          const e = new Error('Operation was aborted');
-          e.name = 'AbortError';
-          return e;
-        })(),
       ];
 
       for (const error of errors) {
@@ -181,11 +177,19 @@ describe('config', () => {
       }
     });
 
+    // Changed after the port: the classifier is that of the receipts.
+    it('should tell timeouts and aborts', () => {
+      const aborted = new Error('Operation was aborted');
+      aborted.name = 'AbortError';
+      assert.equal(defaultErrorClassifier(new Error('Connection timeout')), 'timeout');
+      assert.equal(defaultErrorClassifier(new Error('HTTP 504 Gateway Timeout')), 'timeout');
+      assert.equal(defaultErrorClassifier(aborted), 'aborted');
+    });
+
     it('should classify server errors', () => {
       const errors = [
         new Error('HTTP 500 Internal Server Error'),
         new Error('HTTP 502 Bad Gateway'),
-        new Error('HTTP 504 Gateway Timeout'),
         new Error('Internal server error occurred'),
       ];
 
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index 39fd92f..c56385f 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -261,3 +261,16 @@ test('OTel: the duration buckets reach the histogram as advice', () => {
     assert.deepStrictEqual(duration.options.advice, { explicitBucketBoundaries: buckets });
   }
 });
+
+test('OTel: the default classifier reads words and status codes whole', () => {
+  const { defaultErrorClassifier } = require('../../src/otel/index.js');
+  const cases = [
+    ['Author unknown', 'unknown'],
+    ['timeout after 5000ms', 'timeout'],
+    ['Message size 4013 octets exceeds the limit', 'unknown'],
+    ['HTTP 403 Forbidden', 'auth'],
+  ];
+  for (const [text, category] of cases) {
+    assert.strictEqual(defaultErrorClassifier(new Error(text)), category, text);
+  }
+});

From a90e6dcf82c93cf598651ec67728cc8cdb0b9756 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:50:57 +0300
Subject: [PATCH 086/158] fix(otel): stream sendMany instead of reading its
 input first

sendMany collected every message into an array before the first one was
sent, to size the batch span, and kept every receipt to report the error
messages of a failed batch, so a long batch was held in memory twice and an
endless one never started. The messages now pass to the wrapped transport
as it reads them, each receipt is paired with the oldest message still
waiting for one, the batch and custom attributes are set when the batch
ends, and a failed batch keeps its first ten error messages with the count
of all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                        |   5 ++
 CLAUDE.md                           |   8 +-
 docs/guide/known-issues.md          |   3 +-
 src/otel/attributes.js              |  22 ++----
 src/otel/metrics.js                 |  12 +--
 src/otel/opentelemetry-transport.js | 113 +++++++++++++++-------------
 src/otel/tracing.js                 |  24 +++---
 tests/unit/otel.test.js             |  39 ++++++++++
 8 files changed, 138 insertions(+), 88 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fb5c43f..f67d185 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -208,6 +208,11 @@ fixed ones below.
   error and `timeout after 5000ms` a `server-error`. It now gives the category of
   `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
   `aborted` for an `AbortError`, which upstream counted as `network`.
+- **`./otel` streams `sendMany`** (an upstream bug): it read the whole input into an array before
+  the first message went out, and kept every receipt to the end, so a long or endless batch
+  held it all in memory. The messages now pass on as the wrapped transport reads them; the batch
+  attributes and the custom attributes of the span are set when the batch ends, and the span of
+  a failed batch keeps its first ten error messages with the count of all.
 
 ### Changed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 66ca3e4..b3ef070 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -133,8 +133,7 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 5. `cram-md5` is in the `SmtpAuth` type but not implemented.
 6. DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails.
 7. pool: `continueOnSuccess` is never read.
-8. otel (partly fixed, see 44, 45 and 48 to 50): `recordRetry` is never called; `sendMany`
-   buffers its whole input.
+8. otel (partly fixed, see 44, 45 and 48 to 51): `recordRetry` is never called.
 9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
 10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
@@ -281,6 +280,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     network check (`"Author unknown"` was `auth`, `"timeout after 5000ms"` a server error), and
     disagreed with the categories of the receipts. It is `classifyReceiptError` of the root, plus
     `aborted` for an `AbortError`, which upstream counted as a network failure.
+51. otel: `sendMany` read its whole input into an array before sending the first message, and
+    kept every receipt to the end. It passes the messages on as the wrapped transport reads
+    them, pairs each receipt with the oldest message still waiting for one, sets the batch
+    attributes of its span at the end, and keeps the first ten error messages of a failed batch
+    with the count of all.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index d7ef39c..80072b7 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -32,4 +32,5 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 ## Decorators
 
 - `./pool`: `continueOnSuccess` is never read.
-- `./otel`: `recordRetry` is never called, and `sendMany` buffers its whole input.
+- `./otel`: `recordRetry` is never called, so a span does not show the retries of the transport
+  it wraps.
diff --git a/src/otel/attributes.js b/src/otel/attributes.js
index b00d9a3..9e975dd 100644
--- a/src/otel/attributes.js
+++ b/src/otel/attributes.js
@@ -92,30 +92,24 @@ class EmailAttributeExtractor {
   }
 
   /**
-   * Extracts attributes for batch send operations.
+   * Extracts attributes for batch send operations, from the totals of the
+   * messages the batch read.
    */
-  extractBatchAttributes(messages, batchSize) {
-    const totalAttachments = messages.reduce((sum, msg) => sum + msg.attachments.length, 0);
-    const totalSize = messages.reduce((sum, msg) => sum + estimateMessageSize(msg), 0);
-
+  extractBatchAttributes(totals) {
     const attributes = {
       // General operation attributes
       'operation.name': 'email.send_batch',
       'operation.type': 'email',
 
       // Batch-specific attributes
-      'email.batch.size': batchSize,
-      'email.batch.total_recipients': messages.reduce(
-        (sum, msg) =>
-          sum + msg.recipients.length + msg.ccRecipients.length + msg.bccRecipients.length,
-        0,
-      ),
-      'email.batch.total_attachments': totalAttachments,
-      'email.batch.total_size': totalSize,
+      'email.batch.size': totals.count,
+      'email.batch.total_recipients': totals.recipients,
+      'email.batch.total_attachments': totals.attachments,
+      'email.batch.total_size': totals.size,
 
       // Upyo-specific attributes
       'mailer.transport.name': this.transportName,
-      'mailer.batch.size': batchSize,
+      'mailer.batch.size': totals.count,
     };
 
     // Add transport version if available
diff --git a/src/otel/metrics.js b/src/otel/metrics.js
index 4c278d4..4fbcd03 100644
--- a/src/otel/metrics.js
+++ b/src/otel/metrics.js
@@ -118,14 +118,13 @@ class MetricsCollector {
   /**
    * Records metrics for individual messages.
    */
-  recordMessage(message, transport) {
+  recordMessage(message, transport, messageSize = estimateMessageSize(message)) {
     const labels = {
       transport,
       priority: message.priority,
       content_type: this.getContentType(message),
     };
 
-    const messageSize = estimateMessageSize(message);
     this.messageSizeHistogram.record(messageSize, labels);
     this.attachmentCountHistogram.record(message.attachments.length, labels);
   }
@@ -133,9 +132,7 @@ class MetricsCollector {
   /**
    * Records metrics for batch operations.
    */
-  recordBatch(messages, transport, duration, successCount, failureCount) {
-    // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
-    const _totalMessages = messages.length;
+  recordBatch(transport, duration, successCount, failureCount) {
     const labels = { transport };
 
     // Record batch-level metrics
@@ -149,11 +146,6 @@ class MetricsCollector {
       ...labels,
       operation: 'batch',
     });
-
-    // Record individual message metrics
-    for (const message of messages) {
-      this.recordMessage(message, transport);
-    }
   }
 
   /**
diff --git a/src/otel/opentelemetry-transport.js b/src/otel/opentelemetry-transport.js
index 38a67d9..6d5427b 100644
--- a/src/otel/opentelemetry-transport.js
+++ b/src/otel/opentelemetry-transport.js
@@ -6,6 +6,18 @@ const { MetricsCollector } = require('./metrics.js');
 const { TracingCollector } = require('./tracing.js');
 const { estimateMessageSize } = require('./message-size.js');
 
+// How many error messages of a failed batch its span keeps; the count says how
+// many there were in all.
+const MAX_RECORDED_ERROR_MESSAGES = 10;
+
+// Passes the messages of a batch on one at a time, telling `onMessage` of each.
+const observeMessages = async function* (messages, onMessage) {
+  for await (const message of messages) {
+    onMessage(message);
+    yield message;
+  }
+};
+
 /**
  * OpenTelemetry decorator transport that adds observability to any existing transport.
  *
@@ -185,56 +197,55 @@ class OpenTelemetryTransport {
    */
   async *sendMany(messages, options) {
     const startTime = performance.now();
-    const messageArray = [];
-
-    // Collect messages for batch metrics
-    for await (const message of messages) {
-      messageArray.push(message);
-    }
-
-    const batchSize = messageArray.length;
+    const metrics = this.metricsCollector;
+    const transportName = this.transportName;
 
     // Create batch span if tracing is enabled
-    const span = this.tracingCollector?.createBatchSpan(
-      messageArray,
-      batchSize,
-      this.extractNetworkAttributes(),
-    );
+    const span = this.tracingCollector?.createBatchSpan(this.extractNetworkAttributes());
 
     // Record batch start
-    this.metricsCollector?.recordSendStart(this.transportName);
+    metrics?.recordSendStart(transportName);
+
+    // The messages are observed as the wrapped transport reads them rather
+    // than collected first, so a batch of any length takes bounded memory.
+    // The priority of each waits in `pending` for the receipt that answers it.
+    const totals = { count: 0, recipients: 0, attachments: 0, size: 0 };
+    const pending = [];
+    let head = 0;
+    const observed = observeMessages(messages, (message) => {
+      const size = estimateMessageSize(message);
+      totals.count++;
+      totals.recipients +=
+        message.recipients.length + message.ccRecipients.length + message.bccRecipients.length;
+      totals.attachments += message.attachments.length;
+      totals.size += size;
+      pending.push(message.priority);
+      metrics?.recordMessage(message, transportName, size);
+    });
 
     let successCount = 0;
     let failureCount = 0;
-    const receipts = [];
+    // The first error messages of the failed receipts, and how many in all.
+    const errorMessages = [];
+    let errorMessageCount = 0;
 
     try {
-      // Apply custom attributes if configured
-      if (this.config.attributeExtractor && span) {
-        const totalSize = messageArray.reduce((sum, msg) => sum + estimateMessageSize(msg), 0);
-        const customAttributes = this.config.attributeExtractor(
-          'send_batch',
-          this.transportName,
-          batchSize,
-          totalSize,
-        );
-        span.setAttributes(customAttributes);
-      }
-
-      // Delegate to wrapped transport
-      for await (const receipt of this.wrappedTransport.sendMany(messageArray, options)) {
-        // A receipt answers the message at its position in the batch.
-        this.metricsCollector?.recordMessageOutcome(
-          this.transportName,
-          messageArray[receipts.length]?.priority ?? 'unknown',
-          receipt.successful,
-        );
-        receipts.push(receipt);
+      for await (const receipt of this.wrappedTransport.sendMany(observed, options)) {
+        // A receipt answers the oldest message still waiting for one.
+        const priority = head < pending.length ? pending[head++] : 'unknown';
+        if (head === pending.length) {
+          pending.length = 0;
+          head = 0;
+        }
+        metrics?.recordMessageOutcome(transportName, priority, receipt.successful);
 
         if (receipt.successful) {
           successCount++;
         } else {
           failureCount++;
+          for (const errorMessage of receipt.errorMessages) {
+            if (errorMessageCount++ < MAX_RECORDED_ERROR_MESSAGES) errorMessages.push(errorMessage);
+          }
         }
 
         yield receipt;
@@ -243,13 +254,7 @@ class OpenTelemetryTransport {
       const duration = (performance.now() - startTime) / 1000;
 
       // Record batch completion
-      this.metricsCollector?.recordBatch(
-        messageArray,
-        this.transportName,
-        duration,
-        successCount,
-        failureCount,
-      );
+      metrics?.recordBatch(transportName, duration, successCount, failureCount);
 
       // Update span based on results
       if (failureCount === 0) {
@@ -260,24 +265,28 @@ class OpenTelemetryTransport {
           failure_count: failureCount,
         });
       } else {
-        const allErrorMessages = receipts
-          .filter((r) => !r.successful)
-          .flatMap((r) => r.errorMessages);
-        span?.recordFailure(allErrorMessages);
+        span?.recordFailure(errorMessages, errorMessageCount);
       }
     } catch (error) {
-      // oxlint-disable-next-line no-underscore-dangle, no-unused-vars -- upstream
-      const _duration = (performance.now() - startTime) / 1000;
       const errorCategory = this.classifyError(error);
 
       span?.recordError(error, errorCategory);
-      this.metricsCollector?.recordError(this.transportName, errorCategory, 'send_batch');
+      metrics?.recordError(transportName, errorCategory, 'send_batch');
 
       throw error;
     } finally {
       // Also when the caller stops reading the receipts early.
-      this.metricsCollector?.recordSendEnd(this.transportName);
-      span?.end();
+      metrics?.recordSendEnd(transportName);
+      if (span) {
+        span.recordBatchTotals(totals);
+        // Apply custom attributes if configured
+        if (this.config.attributeExtractor) {
+          span.setAttributes(
+            this.config.attributeExtractor('send_batch', transportName, totals.count, totals.size),
+          );
+        }
+        span.end();
+      }
     }
   }
 
diff --git a/src/otel/tracing.js b/src/otel/tracing.js
index ba03f56..71b995a 100644
--- a/src/otel/tracing.js
+++ b/src/otel/tracing.js
@@ -53,9 +53,10 @@ class TracingCollector {
   }
 
   /**
-   * Creates a span for a batch email send operation.
+   * Creates a span for a batch email send operation.  Its batch attributes
+   * come at its end (`recordBatchTotals`), once the batch has been read.
    */
-  createBatchSpan(messages, batchSize, networkAttributes) {
+  createBatchSpan(networkAttributes) {
     if (!this.shouldSample()) {
       return new NoOpEmailSpan();
     }
@@ -65,10 +66,6 @@ class TracingCollector {
       kind: SPAN_KIND_CLIENT,
     });
 
-    // Set batch attributes
-    const batchAttributes = this.attributeExtractor.extractBatchAttributes(messages, batchSize);
-    span.setAttributes(batchAttributes);
-
     // Set network attributes if provided
     if (networkAttributes) {
       span.setAttributes(networkAttributes);
@@ -151,7 +148,11 @@ class LiveEmailSpan {
     });
   }
 
-  recordFailure(errorMessages) {
+  /**
+   * Records a failure from its error messages, or the first of them when
+   * `errorCount` says how many there were in all.
+   */
+  recordFailure(errorMessages, errorCount = errorMessages.length) {
     const extractor = this.attributeExtractor;
     const described = [];
     for (const errorMessage of errorMessages) described.push(extractor.describeError(errorMessage));
@@ -161,15 +162,19 @@ class LiveEmailSpan {
     });
 
     this.span.setAttributes({
-      'email.error.count': errorMessages.length,
+      'email.error.count': errorCount,
     });
 
     this.span.addEvent('email.send_failed', {
-      'error.count': errorMessages.length,
+      'error.count': errorCount,
       'error.messages': JSON.stringify(described),
     });
   }
 
+  recordBatchTotals(totals) {
+    this.span.setAttributes(this.attributeExtractor.extractBatchAttributes(totals));
+  }
+
   end() {
     this.span.end();
   }
@@ -188,6 +193,7 @@ class NoOpEmailSpan {
   /* c8 ignore stop */
   recordSuccess() {}
   recordFailure() {}
+  recordBatchTotals() {}
   end() {}
 }
 
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index c56385f..6482a40 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -274,3 +274,42 @@ test('OTel: the default classifier reads words and status codes whole', () => {
     assert.strictEqual(defaultErrorClassifier(new Error(text)), category, text);
   }
 });
+
+test('OTel: sendMany passes the messages on as they come', async () => {
+  const { tracerProvider, meterProvider } = providers();
+  let produced = 0;
+  const messages = async function* () {
+    while (produced < 1000) {
+      produced++;
+      yield createTestMessage({ recipients: [{ address: 'bob@example.com' }] });
+    }
+  };
+  const transport = new OpenTelemetryTransport(plain({}), { tracerProvider, meterProvider });
+  let received = 0;
+  for await (const receipt of transport.sendMany(messages())) {
+    assert.strictEqual(receipt.successful, true);
+    if (++received === 3) break;
+  }
+  assert.ok(produced <= 4, `read ${produced} messages for 3 receipts`);
+  const [span] = tracerProvider.getAllSpans();
+  assert.strictEqual(span.attributes['email.batch.size'], 3);
+  assert.strictEqual(span.attributes['email.batch.total_recipients'], 3);
+  assert.strictEqual(span.ended, true);
+});
+
+test('OTel: a failed batch keeps its first error messages and counts them all', async () => {
+  const { tracerProvider, meterProvider } = providers();
+  let index = 0;
+  const transport = new OpenTelemetryTransport(
+    plain({}, () => ({ successful: false, errorMessages: [`Rejected ${index++}`], errors: [] })),
+    { tracerProvider, meterProvider },
+  );
+  const batch = [];
+  for (let i = 0; i < 25; i++) batch.push(createTestMessage());
+  await collect(transport.sendMany(batch));
+  const [span] = tracerProvider.getAllSpans();
+  const failed = span.events.find((event) => event.name === 'email.send_failed');
+  assert.strictEqual(failed.attributes['error.count'], 25);
+  assert.strictEqual(JSON.parse(failed.attributes['error.messages']).length, 10);
+  assert.strictEqual(span.attributes['email.error.count'], 25);
+});

From df78ea83fce597ef3635428f3a8a71144e5e4331 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:55:44 +0300
Subject: [PATCH 087/158] feat: tell the caller of each retry through onRetry

The retries a provider makes on its own were invisible to everything
around it, so ./otel had nothing to call recordRetry with and a
dashboard could not tell a slow send from a retried one. TransportOptions
gets onRetry, which requestWithRetry calls before each wait with the
attempt that failed, the wait and the error, and which the eight HTTP
providers pass from send and their batch calls down to it. ./retry calls
it before its own waits too and, like every decorator, passes the options
on, so one callback hears every level. JMAP threads its signal through
too many helpers to follow yet, which the known issues page says.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                           |  3 ++
 docs/guide/known-issues.md             |  1 +
 docs/transports/custom.md              |  5 ++++
 docs/transports/retry.md               | 21 +++++++++++++
 index.d.ts                             | 27 +++++++++++++++++
 src/internal/http.js                   | 11 +++++--
 src/lettermint/http-client.js          | 11 +++----
 src/lettermint/lettermint-transport.js |  8 ++++-
 src/maileroo/http-client.js            |  7 +++--
 src/maileroo/maileroo-transport.js     |  6 +++-
 src/mailgun/http-client.js             | 20 ++++++++-----
 src/mailgun/mailgun-transport.js       |  6 +++-
 src/mailtrap/http-client.js            | 11 +++----
 src/mailtrap/mailtrap-transport.js     | 12 ++++++--
 src/plunk/http-client.js               |  3 +-
 src/plunk/plunk-transport.js           |  6 +++-
 src/resend/http-client.js              | 41 ++++++++++++++++----------
 src/resend/resend-transport.js         |  8 ++++-
 src/retry/retry-transport.js           |  9 +++++-
 src/sendgrid/http-client.js            | 24 +++++++++------
 src/sendgrid/sendgrid-transport.js     |  6 +++-
 src/ses/http-client.js                 | 23 +++++++++------
 src/ses/ses-transport.js               |  6 +++-
 tests/types/index.test-d.ts            | 21 +++++++++++++
 tests/unit/delivery.test.js            | 23 +++++++++++++++
 tests/unit/internal.test.js            | 15 ++++++++++
 tests/unit/retry.test.js               | 24 +++++++++++++++
 27 files changed, 291 insertions(+), 67 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f67d185..1967cce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,9 @@ fixed ones below.
   `Retry-After`), `./otel` (spans and metrics, with the OpenTelemetry providers passed in, the
   attributes as `mailer.*`) and `./logger` (the lifecycle logged through any pino-like logger
   passed in, in place of upstream's LogTape transport); and `./mock` for tests.
+- **`onRetry` in the options of a send:** the HTTP providers and `./retry` call it before each
+  retry with the attempt, the wait and the error, and the decorators pass it on, so one callback
+  hears every level (not yet from `./jmap`).
 - **Documentation** for every subpath, adapted from upyo's guides.
 - **Package scaffold** set up like the other Alexis libraries: plain CommonJS with no build step,
   a hand-written `index.d.ts`, a closed `exports` map, Node.js 22 or newer, and zero runtime
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 80072b7..641b665 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -26,6 +26,7 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 - Resend's `Idempotency-Key` comes from `Math.random`.
 - SES: custom and threading headers are not sent.
 - Plunk: an attachment that cannot be read is left out with a `console.warn`.
+- JMAP does not report its retries through `onRetry`.
 - JMAP on Node 24: an authentication rejection (401) of a streamed request body (raw upload,
   import, raw submission) becomes a retryable network error, as Node's `fetch` reports it so.
 
diff --git a/docs/transports/custom.md b/docs/transports/custom.md
index b4ef0de..dbb2b9e 100644
--- a/docs/transports/custom.md
+++ b/docs/transports/custom.md
@@ -274,6 +274,11 @@ loops.
 > that won't be resolved by retrying. Only retry 5xx server errors and
 > network failures.
 
+A transport that retries on its own should call `options.onRetry` before each
+wait, with `{ attempt, delayMilliseconds, error }`, so that the decorators
+around it, such as `./otel`, can record the retry; and a decorator should pass
+the options of a send on to the transport it wraps.
+
 ### Configuration validation
 
 Robust configuration validation prevents runtime errors and provides clear
diff --git a/docs/transports/retry.md b/docs/transports/retry.md
index 4ef6c22..7244d59 100644
--- a/docs/transports/retry.md
+++ b/docs/transports/retry.md
@@ -192,6 +192,27 @@ for await (const receipt of transport.sendMany(messages)) {
 Receipts are yielded in the same order as input messages, even when later
 messages finish first.
 
+## Observing retries
+
+Pass `onRetry` in the options of a send to hear of every retry before its wait:
+those of `RetryTransport` and, since it passes the options on, those that an
+HTTP provider makes on its own (`retries`).  The event carries the attempt that
+failed, from 1, the wait in milliseconds and the error behind it: the error of
+the request for a provider, the error a send threw or the first `ReceiptError`
+of its receipt for `RetryTransport`.
+
+```js
+const receipt = await transport.send(message, {
+  onRetry: ({ attempt, delayMilliseconds, error }) => {
+    console.warn(`Attempt ${attempt} failed, retrying in ${delayMilliseconds} ms`, error);
+  },
+});
+```
+
+An error thrown by the callback rejects the send. `./otel` records these retries
+on its span and in its metrics, and the JMAP transport does not report its own
+yet.
+
 ## Composition
 
 Retry transport composes with other decorators because it preserves the
diff --git a/index.d.ts b/index.d.ts
index 547ae93..3869f6a 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -1068,6 +1068,33 @@ export interface TransportOptions {
    * The abort signal to cancel the operation if needed.
    */
   readonly signal?: AbortSignal;
+  /**
+   * Called before a request is sent again after a failure: by an HTTP
+   * provider that retries its own requests (`retries`), and by the `./retry`
+   * decorator.  The decorators pass it on to the transport they wrap, so one
+   * callback hears the retries of every level.  An error it throws rejects
+   * the send.  The JMAP transport does not call it yet.
+   */
+  readonly onRetry?: (event: RetryEvent) => void;
+}
+/**
+ * A retry about to happen, as {@link TransportOptions.onRetry} is told of it.
+ */
+export interface RetryEvent {
+  /**
+   * The attempt that failed, from 1.
+   */
+  readonly attempt: number;
+  /**
+   * How long the transport waits before the next attempt, in milliseconds.
+   */
+  readonly delayMilliseconds: number;
+  /**
+   * Why: the error of the failed request, such as the API error of a provider
+   * with its `statusCode`, or, from `./retry`, the error a send threw or the
+   * first `ReceiptError` of the receipt it returned.
+   */
+  readonly error: unknown;
 }
 /**
  * Optional capability for delivering already serialized MIME messages.
diff --git a/src/internal/http.js b/src/internal/http.js
index 9d522da..1de5666 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -136,7 +136,8 @@ const startDeadline = (timeoutMs, signal) => {
  * - optional `wrapAccepted(error, attempts)`, `isAnswer(error)` (an error that
  *   is the provider's own answer in a 2xx, such as a refusal in its body,
  *   thrown as it is rather than as of unknown delivery), `hasIdempotencyKey`,
- *   `isIdempotent`, `sleep`.
+ *   `isIdempotent`, `sleep`, and `onRetry(event)`, the `onRetry` of the
+ *   caller's `TransportOptions`, told of each retry before its wait.
  * The deadline of an attempt lasts until its response is read, body
  * included, so a body that never ends cannot hold a send.  Between attempts
  * it waits at least the failure's `retryAfterMilliseconds`, the server's
@@ -191,8 +192,12 @@ const requestWithRetry = async (request) => {
     if (attempt >= request.retries || retryAfterMs > MAX_RETRY_AFTER_WAIT_MS) {
       throw settle(request.finalError?.(failure, attempt + 1) ?? failure);
     }
-    const delayMs = (request.retryDelayMs ?? jitteredDelayMs)(attempt, failure);
-    await wait(Math.max(delayMs, retryAfterMs), signal);
+    const waitMs = Math.max(
+      (request.retryDelayMs ?? jitteredDelayMs)(attempt, failure),
+      retryAfterMs,
+    );
+    request.onRetry?.({ attempt: attempt + 1, delayMilliseconds: waitMs, error: failure });
+    await wait(waitMs, signal);
   }
 };
 
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index 9964f9a..8e3b4b1 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -81,9 +81,9 @@ class LettermintHttpClient {
    * @param idempotencyKey Optional idempotency key for request deduplication.
    * @returns Promise that resolves to the Lettermint response.
    */
-  sendMessage(messageData, signal, idempotencyKey) {
+  sendMessage(messageData, signal, idempotencyKey, onRetry) {
     const url = `${this.config.baseUrl}/v1/send`;
-    return this.makeRequest(url, messageData, signal, idempotencyKey);
+    return this.makeRequest(url, messageData, signal, idempotencyKey, onRetry);
   }
 
   /**
@@ -94,16 +94,17 @@ class LettermintHttpClient {
    * @param idempotencyKey Optional idempotency key for request deduplication.
    * @returns Promise that resolves to the Lettermint batch response.
    */
-  sendBatch(messagesData, signal, idempotencyKey) {
+  sendBatch(messagesData, signal, idempotencyKey, onRetry) {
     const url = `${this.config.baseUrl}/v1/send/batch`;
-    return this.makeRequest(url, messagesData, signal, idempotencyKey);
+    return this.makeRequest(url, messagesData, signal, idempotencyKey, onRetry);
   }
 
-  makeRequest(url, body, signal, idempotencyKey) {
+  makeRequest(url, body, signal, idempotencyKey, onRetry) {
     // Serialized once rather than on every attempt.
     const json = JSON.stringify(body);
     return requestWithRetry({
       signal,
+      onRetry,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       // Lettermint deduplicates a repeated Idempotency-Key.
diff --git a/src/lettermint/lettermint-transport.js b/src/lettermint/lettermint-transport.js
index ab8accf..ff9b72e 100644
--- a/src/lettermint/lettermint-transport.js
+++ b/src/lettermint/lettermint-transport.js
@@ -91,6 +91,7 @@ class LettermintTransport {
         emailData,
         options?.signal,
         idempotencyKey,
+        options?.onRetry,
       );
 
       return responseToReceipt(response);
@@ -159,7 +160,12 @@ class LettermintTransport {
     try {
       options?.signal?.throwIfAborted();
 
-      const response = await this.httpClient.sendBatch(batchData, options?.signal, idempotencyKey);
+      const response = await this.httpClient.sendBatch(
+        batchData,
+        options?.signal,
+        idempotencyKey,
+        options?.onRetry,
+      );
 
       let responseIndex = 0;
       for (let index = 0; index < receipts.length; index++) {
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index 416461d..cfd6c9e 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -84,16 +84,17 @@ class MailerooHttpClient {
    * @throws {MailerooApiError} If Maileroo returns an API error.
    * @throws {MailerooTimeoutError} If the request timeout elapses.
    */
-  sendMessage(messageData, signal) {
+  sendMessage(messageData, signal, onRetry) {
     const url = `${this.config.baseUrl}/emails`;
-    return this.makeRequest(url, messageData, signal);
+    return this.makeRequest(url, messageData, signal, onRetry);
   }
 
-  makeRequest(url, body, signal) {
+  makeRequest(url, body, signal, onRetry) {
     // Serialized once rather than on every attempt.
     const json = JSON.stringify(body);
     return requestWithRetry({
       signal,
+      onRetry,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       send: (attemptSignal) => this.fetchWithAuth(url, json, attemptSignal),
diff --git a/src/maileroo/maileroo-transport.js b/src/maileroo/maileroo-transport.js
index eded3e9..37bd21b 100644
--- a/src/maileroo/maileroo-transport.js
+++ b/src/maileroo/maileroo-transport.js
@@ -81,7 +81,11 @@ class MailerooTransport {
 
       options?.signal?.throwIfAborted();
 
-      const response = await this.httpClient.sendMessage(emailData, options?.signal);
+      const response = await this.httpClient.sendMessage(
+        emailData,
+        options?.signal,
+        options?.onRetry,
+      );
 
       return responseToReceipt(response);
     } catch (error) {
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index 94d8463..0457fde 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -24,17 +24,22 @@ class MailgunHttpClient {
    *
    * @param formData The form data to send to Mailgun.
    * @param signal Optional AbortSignal for cancellation.
+   * @param onRetry Optional callback told of each retry.
    * @returns Promise that resolves to the Mailgun response.
    */
-  sendMessage(formData, signal) {
+  sendMessage(formData, signal, onRetry) {
     // The domain is a path segment: encoded, it cannot climb the path.
     const url = `${this.config.baseUrl}/${encodeURIComponent(this.config.domain)}/messages`;
 
-    return this.makeRequest(url, {
-      method: 'POST',
-      body: formData,
-      signal,
-    });
+    return this.makeRequest(
+      url,
+      {
+        method: 'POST',
+        body: formData,
+        signal,
+      },
+      onRetry,
+    );
   }
 
   /**
@@ -46,9 +51,10 @@ class MailgunHttpClient {
    * @throws {MailgunApiError} If Mailgun returns an error response or all
    *                           retry attempts are exhausted.
    */
-  makeRequest(url, options) {
+  makeRequest(url, options, onRetry) {
     return requestWithRetry({
       signal: options.signal,
+      onRetry,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       send: (signal) => this.fetchWithAuth(url, options, signal),
diff --git a/src/mailgun/mailgun-transport.js b/src/mailgun/mailgun-transport.js
index 7560412..cfa833e 100644
--- a/src/mailgun/mailgun-transport.js
+++ b/src/mailgun/mailgun-transport.js
@@ -110,7 +110,11 @@ class MailgunTransport {
 
       options?.signal?.throwIfAborted();
 
-      const response = await this.httpClient.sendMessage(formData, options?.signal);
+      const response = await this.httpClient.sendMessage(
+        formData,
+        options?.signal,
+        options?.onRetry,
+      );
 
       return {
         successful: true,
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index 11ec25f..c65b5de 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -107,9 +107,9 @@ class MailtrapHttpClient {
    * @param signal Optional AbortSignal for cancellation.
    * @returns Promise that resolves to the Mailtrap response.
    */
-  sendMessage(messageData, signal) {
+  sendMessage(messageData, signal, onRetry) {
     const url = this.resolveUrl('send');
-    return this.makeRequest(url, messageData, signal);
+    return this.makeRequest(url, messageData, signal, onRetry);
   }
 
   /**
@@ -119,9 +119,9 @@ class MailtrapHttpClient {
    * @param signal Optional AbortSignal for cancellation.
    * @returns Promise that resolves to the Mailtrap batch response.
    */
-  sendBatch(requests, signal) {
+  sendBatch(requests, signal, onRetry) {
     const url = this.resolveUrl('batch');
-    return this.makeRequest(url, { requests }, signal);
+    return this.makeRequest(url, { requests }, signal, onRetry);
   }
 
   resolveUrl(kind) {
@@ -133,11 +133,12 @@ class MailtrapHttpClient {
     return `${baseUrl}/api/${kind}${suffix}`;
   }
 
-  makeRequest(url, body, signal) {
+  makeRequest(url, body, signal, onRetry) {
     // Serialized once rather than on every attempt.
     const json = JSON.stringify(body);
     return requestWithRetry({
       signal,
+      onRetry,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       send: (attemptSignal) => this.fetchWithAuth(url, json, attemptSignal),
diff --git a/src/mailtrap/mailtrap-transport.js b/src/mailtrap/mailtrap-transport.js
index 6288780..2c9823c 100644
--- a/src/mailtrap/mailtrap-transport.js
+++ b/src/mailtrap/mailtrap-transport.js
@@ -90,7 +90,11 @@ class MailtrapTransport {
 
       options?.signal?.throwIfAborted();
 
-      const response = await this.httpClient.sendMessage(emailData, options?.signal);
+      const response = await this.httpClient.sendMessage(
+        emailData,
+        options?.signal,
+        options?.onRetry,
+      );
 
       return responseToReceipt(response);
     } catch (error) {
@@ -150,7 +154,11 @@ class MailtrapTransport {
     try {
       options?.signal?.throwIfAborted();
 
-      const response = await this.httpClient.sendBatch(batchData, options?.signal);
+      const response = await this.httpClient.sendBatch(
+        batchData,
+        options?.signal,
+        options?.onRetry,
+      );
 
       if (response.success === false) {
         const errorMessage = formatErrors(response.errors) ?? 'Mailtrap batch request failed.';
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index ec23dea..440d40f 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -70,13 +70,14 @@ class PlunkHttpClient {
    * @returns Promise that resolves to Plunk API response
    * @throws PlunkError if the request fails after all retries
    */
-  sendMessage(emailData, signal) {
+  sendMessage(emailData, signal, onRetry) {
     const url = `${this.config.baseUrl}/v1/send`;
     // Serialized once rather than on every attempt.
     const json = JSON.stringify(emailData);
 
     return requestWithRetry({
       signal,
+      onRetry,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       send: (attemptSignal) => this.makeRequest(url, json, attemptSignal),
diff --git a/src/plunk/plunk-transport.js b/src/plunk/plunk-transport.js
index 1b00583..4cc6a68 100644
--- a/src/plunk/plunk-transport.js
+++ b/src/plunk/plunk-transport.js
@@ -112,7 +112,11 @@ class PlunkTransport {
 
       options?.signal?.throwIfAborted();
 
-      const response = await this.httpClient.sendMessage(emailData, options?.signal);
+      const response = await this.httpClient.sendMessage(
+        emailData,
+        options?.signal,
+        options?.onRetry,
+      );
 
       // Extract message ID from response
       const messageId = this.extractMessageId(response, message);
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index c37ad3d..6064502 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -61,9 +61,10 @@ class ResendHttpClient {
    * @param messageData The JSON data to send to Resend.
    * @param signal Optional AbortSignal for cancellation.
    * @param idempotencyKey Optional idempotency key for request deduplication.
+   * @param onRetry Optional callback told of each retry.
    * @returns Promise that resolves to the Resend response.
    */
-  sendMessage(messageData, signal, idempotencyKey) {
+  sendMessage(messageData, signal, idempotencyKey, onRetry) {
     const url = `${this.config.baseUrl}/emails`;
     const headers = {
       'Content-Type': 'application/json',
@@ -73,12 +74,16 @@ class ResendHttpClient {
       headers['Idempotency-Key'] = idempotencyKey;
     }
 
-    return this.makeRequest(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(messageData),
-      signal,
-    });
+    return this.makeRequest(
+      url,
+      {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(messageData),
+        signal,
+      },
+      onRetry,
+    );
   }
 
   /**
@@ -87,9 +92,10 @@ class ResendHttpClient {
    * @param messagesData Array of message data objects to send.
    * @param signal Optional AbortSignal for cancellation.
    * @param idempotencyKey Optional idempotency key for request deduplication.
+   * @param onRetry Optional callback told of each retry.
    * @returns Promise that resolves to the Resend batch response.
    */
-  sendBatch(messagesData, signal, idempotencyKey) {
+  sendBatch(messagesData, signal, idempotencyKey, onRetry) {
     const url = `${this.config.baseUrl}/emails/batch`;
     const headers = {
       'Content-Type': 'application/json',
@@ -99,12 +105,16 @@ class ResendHttpClient {
       headers['Idempotency-Key'] = idempotencyKey;
     }
 
-    return this.makeRequest(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(messagesData),
-      signal,
-    });
+    return this.makeRequest(
+      url,
+      {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(messagesData),
+        signal,
+      },
+      onRetry,
+    );
   }
 
   /**
@@ -114,9 +124,10 @@ class ResendHttpClient {
    * @param options Fetch options.
    * @returns Promise that resolves to the parsed response.
    */
-  makeRequest(url, options) {
+  makeRequest(url, options, onRetry) {
     return requestWithRetry({
       signal: options.signal,
+      onRetry,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       // Resend answers a repeated Idempotency-Key with its first answer.
diff --git a/src/resend/resend-transport.js b/src/resend/resend-transport.js
index 54cc335..9b4cfd1 100644
--- a/src/resend/resend-transport.js
+++ b/src/resend/resend-transport.js
@@ -125,6 +125,7 @@ class ResendTransport {
         emailData,
         options?.signal,
         idempotencyKey,
+        options?.onRetry,
       );
 
       return {
@@ -273,7 +274,12 @@ class ResendTransport {
 
       options?.signal?.throwIfAborted();
 
-      const response = await this.httpClient.sendBatch(batchData, options?.signal, idempotencyKey);
+      const response = await this.httpClient.sendBatch(
+        batchData,
+        options?.signal,
+        idempotencyKey,
+        options?.onRetry,
+      );
 
       // Yield receipt for each message
       for (const result of response.data) {
diff --git a/src/retry/retry-transport.js b/src/retry/retry-transport.js
index cbab977..d7a5b2d 100644
--- a/src/retry/retry-transport.js
+++ b/src/retry/retry-transport.js
@@ -77,6 +77,7 @@ class RetryTransport {
             reason: 'retry',
           },
           options?.signal,
+          options?.onRetry,
         );
         continue;
       }
@@ -106,6 +107,7 @@ class RetryTransport {
           reason: 'retry',
         },
         options?.signal,
+        options?.onRetry,
       );
     }
 
@@ -371,7 +373,12 @@ class RetryTransport {
     return Math.floor(random() * computedDelay);
   }
 
-  waitBeforeRetry(context, signal) {
+  waitBeforeRetry(context, signal, onRetry) {
+    onRetry?.({
+      attempt: context.attempt,
+      delayMilliseconds: context.delayMilliseconds,
+      error: context.error ?? context.receipt?.errors?.[0],
+    });
     const wait = this.config.wait;
     return wait(context, signal);
   }
diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
index 3c304b4..84550fa 100644
--- a/src/sendgrid/http-client.js
+++ b/src/sendgrid/http-client.js
@@ -23,19 +23,24 @@ class SendGridHttpClient {
    *
    * @param messageData The JSON data to send to SendGrid.
    * @param signal Optional AbortSignal for cancellation.
+   * @param onRetry Optional callback told of each retry.
    * @returns Promise that resolves to the SendGrid response.
    */
-  sendMessage(messageData, signal) {
+  sendMessage(messageData, signal, onRetry) {
     const url = `${this.config.baseUrl}/mail/send`;
 
-    return this.makeRequest(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
+    return this.makeRequest(
+      url,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(messageData),
+        signal,
       },
-      body: JSON.stringify(messageData),
-      signal,
-    });
+      onRetry,
+    );
   }
 
   /**
@@ -48,9 +53,10 @@ class SendGridHttpClient {
    * @throws {SendGridApiError} If SendGrid returns a client error or all retry
    *                            attempts are exhausted.
    */
-  makeRequest(url, options) {
+  makeRequest(url, options, onRetry) {
     return requestWithRetry({
       signal: options.signal,
+      onRetry,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       send: (signal) => this.fetchWithAuth(url, options, signal),
diff --git a/src/sendgrid/sendgrid-transport.js b/src/sendgrid/sendgrid-transport.js
index 6570bb4..00de745 100644
--- a/src/sendgrid/sendgrid-transport.js
+++ b/src/sendgrid/sendgrid-transport.js
@@ -110,7 +110,11 @@ class SendGridTransport {
 
       options?.signal?.throwIfAborted();
 
-      const response = await this.httpClient.sendMessage(mailData, options?.signal);
+      const response = await this.httpClient.sendMessage(
+        mailData,
+        options?.signal,
+        options?.onRetry,
+      );
 
       // SendGrid returns 202 for successful sends, but doesn't provide a message ID
       // in the response body. We'll generate a synthetic ID based on the response.
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index 575d352..2f1c04b 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -14,18 +14,22 @@ class SesHttpClient {
     this.config = config;
   }
 
-  sendMessage(messageData, signal) {
+  sendMessage(messageData, signal, onRetry) {
     const region = this.config.region;
     const url = `https://email.${region}.amazonaws.com/v2/email/outbound-emails`;
 
-    return this.makeRequest(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
+    return this.makeRequest(
+      url,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(messageData),
+        signal,
       },
-      body: JSON.stringify(messageData),
-      signal,
-    });
+      onRetry,
+    );
   }
 
   /**
@@ -38,9 +42,10 @@ class SesHttpClient {
    * @throws {SesApiError} If SES returns a client error or all retry attempts
    *                       are exhausted.
    */
-  makeRequest(url, options) {
+  makeRequest(url, options, onRetry) {
     return requestWithRetry({
       signal: options.signal,
+      onRetry,
       retries: this.config.retries,
       timeoutMs: this.config.timeout,
       send: (signal) => this.fetchWithAuth(url, options, signal),
diff --git a/src/ses/ses-transport.js b/src/ses/ses-transport.js
index 8b4b027..0420acf 100644
--- a/src/ses/ses-transport.js
+++ b/src/ses/ses-transport.js
@@ -114,7 +114,11 @@ class SesTransport {
 
       options?.signal?.throwIfAborted();
 
-      const response = await this.httpClient.sendMessage(sesMessage, options?.signal);
+      const response = await this.httpClient.sendMessage(
+        sesMessage,
+        options?.signal,
+        options?.onRetry,
+      );
 
       const messageId = this.extractMessageId(response);
 
diff --git a/tests/types/index.test-d.ts b/tests/types/index.test-d.ts
index bbe6048..64628d4 100644
--- a/tests/types/index.test-d.ts
+++ b/tests/types/index.test-d.ts
@@ -12,6 +12,7 @@ import {
   type RawTransport,
   type Receipt,
   type ReceiptError,
+  type RetryEvent,
   type Transport,
   type VerifiableTransport,
 } from '../../index.js';
@@ -69,3 +70,23 @@ if (isRawTransport(transport)) expectType<RawTransport<'smtp'>>(transport);
 if (isVerifiableTransport(transport)) expectType<VerifiableTransport<'smtp'>>(transport);
 
 expectAssignable<TypeError>(new RawMessageValidationError('Bad line.', 'content', 12, 2));
+
+// onRetry hears each retry of a transport and of the decorators around it.
+declare const retried: Transport;
+expectType<Promise<Receipt>>(
+  retried.send(
+    createMessage({
+      from: 'a@example.com',
+      to: 'b@example.com',
+      subject: 's',
+      content: { text: 't' },
+    }),
+    {
+      onRetry: (event: RetryEvent) => {
+        expectType<number>(event.attempt);
+        expectType<number>(event.delayMilliseconds);
+        expectType<unknown>(event.error);
+      },
+    },
+  ),
+);
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index 31e1895..3edb348 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -274,3 +274,26 @@ test('Delivery: a configured name cannot move a request to another host or path'
   }).send(message());
   assert.deepStrictEqual(paths, ['/v3/..%2F..%2Fadmin/messages', '/api/send/1%2F..%2F..%2Fadmin']);
 });
+
+test('Delivery: every HTTP provider tells onRetry of its retries', async (t) => {
+  // A 503, which is retried, then a 400, which is not; the providers run
+  // together so that their delays before the retry overlap.
+  const requests = new Map();
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    const key = String(url);
+    const count = (requests.get(key) ?? 0) + 1;
+    requests.set(key, count);
+    return new Response('{"message":"Busy"}', { status: count === 1 ? 503 : 400 });
+  });
+  await Promise.all(
+    providers.map(async ([name, , create]) => {
+      const events = [];
+      const receipt = await create().send(message(), { onRetry: (event) => events.push(event) });
+      assert.strictEqual(receipt.successful, false, name);
+      assert.strictEqual(events.length, 1, name);
+      assert.strictEqual(events[0].attempt, 1, name);
+      assert.ok(events[0].delayMilliseconds > 0, name);
+      assert.strictEqual(events[0].error.statusCode, 503, name);
+    }),
+  );
+});
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index bb4fa4d..bdd9cfd 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -306,3 +306,18 @@ test('Internal: an ambiguous failure of a send is not retried, unless it has a k
   assert.strictEqual(read.sends(), 2);
   assert.strictEqual(isDeliveryUnknown(readError), false);
 });
+
+test('Internal: onRetry hears each retry, with its attempt, wait and error, before the wait', async () => {
+  const events = [];
+  const failure = new TypeError('fetch failed');
+  const busy = Object.assign(new Error('Busy'), { retryAfterMilliseconds: 1500 });
+  const { request, delays } = scripted([failure, busy, new Response('ok')], {
+    onRetry: (event) => events.push({ ...event, waitedBefore: delays.length }),
+  });
+  assert.strictEqual(await requestWithRetry(request), 'ok');
+  assert.deepStrictEqual(events, [
+    { attempt: 1, delayMilliseconds: 1, error: failure, waitedBefore: 0 },
+    { attempt: 2, delayMilliseconds: 1500, error: busy, waitedBefore: 1 },
+  ]);
+  assert.deepStrictEqual(delays, [1, 1500]);
+});
diff --git a/tests/unit/retry.test.js b/tests/unit/retry.test.js
index bb0360b..0067ed7 100644
--- a/tests/unit/retry.test.js
+++ b/tests/unit/retry.test.js
@@ -148,3 +148,27 @@ test('Retry: every attempt sends the same Message-ID, without changing the messa
   await new RetryTransport(base, { maxAttempts: 1 }).send(own);
   assert.strictEqual(ids[2], 'own@example.com');
 });
+
+test('Retry: onRetry hears the retries of the decorator and reaches the wrapped transport', async () => {
+  const events = [];
+  const seen = [];
+  const base = sequence(failure(true), failure(true), success);
+  const send = base.send;
+  base.send = (sent, options) => {
+    seen.push(options?.onRetry);
+    return send(sent, options);
+  };
+  const onRetry = (event) => events.push(event);
+  const transport = new RetryTransport(base, {
+    maxAttempts: 3,
+    jitter: 'none',
+    backoff: { baseDelayMilliseconds: 10, factor: 2 },
+    wait: async () => {},
+  });
+  assert.strictEqual((await transport.send(message(), { onRetry })).successful, true);
+  assert.deepStrictEqual(events, [
+    { attempt: 1, delayMilliseconds: 10, error: failure(true).errors[0] },
+    { attempt: 2, delayMilliseconds: 20, error: failure(true).errors[0] },
+  ]);
+  assert.deepStrictEqual(seen, [onRetry, onRetry, onRetry]);
+});

From 36ece4003e84ced669e873a1a3e55dd021db4f8b Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:57:18 +0300
Subject: [PATCH 088/158] fix(otel): record the retries of the wrapped
 transport

recordRetry was dead code, so a span showed mailer.retry.count 0 however
many times the provider underneath retried. The decorator now passes the
wrapped transport an onRetry that adds a retry event to the span and
counts every retry in mailer.retry.count, adds to a new counter of
retries labelled with the category of the failure, and then calls the
caller's own onRetry. This closes the last of known upstream bug 8.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                        |  4 +++
 CLAUDE.md                           | 11 +++++--
 docs/guide/known-issues.md          |  2 --
 docs/transports/otel.md             |  3 ++
 src/otel/metrics.js                 | 14 ++++++++
 src/otel/opentelemetry-transport.js | 27 ++++++++++++++--
 src/otel/tracing.js                 | 14 ++++----
 tests/unit/otel.test.js             | 50 +++++++++++++++++++++++++++++
 8 files changed, 112 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1967cce..43e43fb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -216,6 +216,10 @@ fixed ones below.
   held it all in memory. The messages now pass on as the wrapped transport reads them; the batch
   attributes and the custom attributes of the span are set when the batch ends, and the span of
   a failed batch keeps its first ten error messages with the count of all.
+- **`./otel` records the retries of the transport it wraps** (an upstream bug): `recordRetry`
+  was never called. Through the new `onRetry`, each retry of the wrapped transport or of a
+  `./retry` inside it now adds a `retry` event and to `mailer.retry.count` on the span, and to
+  a new counter of retries, and still reaches the caller's own `onRetry`.
 
 ### Changed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index b3ef070..bacaebd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -116,7 +116,7 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
   over lines in a test goes through a variable (`no-unexpected-multiline`).
 - **Coverage keeps the gates of the package.** Paths that upstream reached only end to end get flat
   suites against fakes (`tests/unit/<subpath>.test.js`); `/* c8 ignore */` marks only code that is
-  dead upstream (`convertMessagesToBulk`, `recordRetry`) or unreachable on Node, each with its
+  dead upstream (`convertMessagesToBulk`) or unreachable on Node, each with its
   reason. Upstream tests of a runtime without `AbortSignal.any` are left out with a comment.
 - Ported test suites keep upstream's `describe`/`it`, so they can be compared with upyo's; new
   suites use the flat style of "Testing notes". Tests for paths that upstream's suites leave out go
@@ -133,7 +133,10 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 5. `cram-md5` is in the `SmtpAuth` type but not implemented.
 6. DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails.
 7. pool: `continueOnSuccess` is never read.
-8. otel (partly fixed, see 44, 45 and 48 to 51): `recordRetry` is never called.
+8. (fixed, see 44, 45 and 48 to 52) otel: `_active_sends` was not decremented after `sendMany`
+   and drifted under sampling; `durationBuckets` and `auto` were ignored; `recordRetry` was
+   never called; `sendMany` buffered its whole input; `defaultErrorClassifier` matched `"auth"`
+   as a substring.
 9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
 10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
@@ -285,6 +288,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     them, pairs each receipt with the oldest message still waiting for one, sets the batch
     attributes of its span at the end, and keeps the first ten error messages of a failed batch
     with the count of all.
+52. otel: `recordRetry` was never called, since nothing told the decorator of a retry. The
+    wrapped transport now reports its retries through `onRetry` of `TransportOptions`; the
+    decorator records each on the span (`mailer.retry.count` and a `retry` event), counts it
+    in `mailer_email_retries_total`, and passes it on to the caller's `onRetry`.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 641b665..e387328 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -33,5 +33,3 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 ## Decorators
 
 - `./pool`: `continueOnSuccess` is never read.
-- `./otel`: `recordRetry` is never called, so a span does not show the retries of the transport
-  it wraps.
diff --git a/docs/transports/otel.md b/docs/transports/otel.md
index 9684e49..1f85187 100644
--- a/docs/transports/otel.md
+++ b/docs/transports/otel.md
@@ -365,6 +365,9 @@ The transport collects the following key metrics:
 
 - Active operation gauges: Track concurrent email sending operations
 
+- Retries: Count the requests the wrapped transport sent again, by the category
+  of the failure; a span shows them as `retry` events and in `mailer.retry.count`
+
 - Error classification: Categorize failures by type (auth, network, etc.)
 
 These metrics are exported to your configured observability backend
diff --git a/src/otel/metrics.js b/src/otel/metrics.js
index 4fbcd03..7b532cd 100644
--- a/src/otel/metrics.js
+++ b/src/otel/metrics.js
@@ -21,6 +21,7 @@ class MetricsCollector {
   // Counters
   attemptCounter;
   messageCounter;
+  retryCounter;
 
   // Histograms
   durationHistogram;
@@ -45,6 +46,11 @@ class MetricsCollector {
       unit: '1',
     });
 
+    this.retryCounter = this.meter.createCounter(`${config.prefix}_email_retries_total`, {
+      description: 'Requests the wrapped transport sent again after a failure',
+      unit: '1',
+    });
+
     // Initialize histograms
     this.durationHistogram = this.meter.createHistogram(`${config.prefix}_email_duration_seconds`, {
       description: 'Duration of email send operations',
@@ -148,6 +154,14 @@ class MetricsCollector {
     });
   }
 
+  /**
+   * Records a retry of the wrapped transport, with the category of the
+   * failure it retries.
+   */
+  recordRetry(transport, errorType) {
+    this.retryCounter.add(1, { transport, error_type: errorType });
+  }
+
   /**
    * Records an error for metrics classification.
    */
diff --git a/src/otel/opentelemetry-transport.js b/src/otel/opentelemetry-transport.js
index 6d5427b..2c597e8 100644
--- a/src/otel/opentelemetry-transport.js
+++ b/src/otel/opentelemetry-transport.js
@@ -150,7 +150,10 @@ class OpenTelemetryTransport {
       }
 
       // Delegate to wrapped transport
-      const receipt = await this.wrappedTransport.send(message, options);
+      const receipt = await this.wrappedTransport.send(
+        message,
+        this.withRetryRecording(options, span),
+      );
       const duration = (performance.now() - startTime) / 1000; // Convert to seconds
       this.metricsCollector?.recordMessageOutcome(
         this.transportName,
@@ -230,7 +233,8 @@ class OpenTelemetryTransport {
     let errorMessageCount = 0;
 
     try {
-      for await (const receipt of this.wrappedTransport.sendMany(observed, options)) {
+      const sendOptions = this.withRetryRecording(options, span);
+      for await (const receipt of this.wrappedTransport.sendMany(observed, sendOptions)) {
         // A receipt answers the oldest message still waiting for one.
         const priority = head < pending.length ? pending[head++] : 'unknown';
         if (head === pending.length) {
@@ -385,6 +389,25 @@ class OpenTelemetryTransport {
     return undefined;
   }
 
+  /**
+   * The options passed on to the wrapped transport: its retries are recorded
+   * on the span and in the metrics, and still reach the caller's `onRetry`.
+   */
+  withRetryRecording(options, span) {
+    const metrics = this.metricsCollector;
+    if (span == null && metrics == null) return options;
+    const onRetry = options?.onRetry;
+    return {
+      ...options,
+      onRetry: (event) => {
+        const errorType = this.classifyError(event.error);
+        span?.recordRetry(event.attempt, errorType);
+        metrics?.recordRetry(this.transportName, errorType);
+        onRetry?.(event);
+      },
+    };
+  }
+
   classifyError(error) {
     const classifier = this.config.errorClassifier || defaultErrorClassifier;
     return classifier(error);
diff --git a/src/otel/tracing.js b/src/otel/tracing.js
index 71b995a..957db74 100644
--- a/src/otel/tracing.js
+++ b/src/otel/tracing.js
@@ -85,6 +85,7 @@ class TracingCollector {
 class LiveEmailSpan {
   span;
   attributeExtractor;
+  retryCount = 0;
 
   constructor(span, attributeExtractor) {
     this.span = span;
@@ -120,11 +121,14 @@ class LiveEmailSpan {
     });
   }
 
-  // Dead upstream: nothing calls recordRetry (CLAUDE.md, known upstream bugs).
-  /* c8 ignore start */
+  /**
+   * Records a retry of the wrapped transport, at any level: the count is of
+   * every retry the operation heard, the attempt that of the level retrying.
+   */
   recordRetry(attempt, reason) {
+    this.retryCount++;
     this.span.setAttributes({
-      'mailer.retry.count': attempt,
+      'mailer.retry.count': this.retryCount,
     });
 
     this.span.addEvent('retry', {
@@ -132,7 +136,6 @@ class LiveEmailSpan {
       ...(reason && { 'retry.reason': reason }),
     });
   }
-  /* c8 ignore stop */
 
   recordSuccess(messageId) {
     this.span.setStatus({ code: SPAN_STATUS_OK });
@@ -187,10 +190,7 @@ class NoOpEmailSpan {
   addEvent() {}
   setAttributes() {}
   recordError() {}
-  // Dead upstream: nothing calls recordRetry.
-  /* c8 ignore start */
   recordRetry() {}
-  /* c8 ignore stop */
   recordSuccess() {}
   recordFailure() {}
   recordBatchTotals() {}
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index 6482a40..1612eb4 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -313,3 +313,53 @@ test('OTel: a failed batch keeps its first error messages and counts them all',
   assert.strictEqual(JSON.parse(failed.attributes['error.messages']).length, 10);
   assert.strictEqual(span.attributes['email.error.count'], 25);
 });
+
+test('OTel: the retries of the wrapped transport reach the span, the metrics and onRetry', async () => {
+  const busy = Object.assign(new Error('Service Unavailable'), { statusCode: 503 });
+  const retrying = plain({});
+  retrying.send = async (_message, options) => {
+    options.onRetry({ attempt: 1, delayMilliseconds: 10, error: busy });
+    options.onRetry({ attempt: 2, delayMilliseconds: 20, error: busy });
+    return { successful: true, messageId: 'm1' };
+  };
+  retrying.sendMany = async function* (messages, options) {
+    for await (const message of messages) yield await retrying.send(message, options);
+  };
+  const { tracerProvider, meterProvider } = providers();
+  const transport = new OpenTelemetryTransport(retrying, { tracerProvider, meterProvider });
+  const heard = [];
+  const onRetry = (event) => heard.push(event.attempt);
+  await transport.send(createTestMessage(), { onRetry });
+  await collect(transport.sendMany([createTestMessage()], { onRetry }));
+
+  assert.deepStrictEqual(heard, [1, 2, 1, 2]);
+  for (const span of tracerProvider.getAllSpans()) {
+    assert.strictEqual(span.attributes['mailer.retry.count'], 2);
+    const retries = span.events.filter((event) => event.name === 'retry');
+    assert.deepStrictEqual(
+      retries.map((event) => event.attributes),
+      [
+        { 'retry.attempt': 1, 'retry.reason': 'service-unavailable' },
+        { 'retry.attempt': 2, 'retry.reason': 'service-unavailable' },
+      ],
+    );
+  }
+  const retries = meterProvider
+    .getAllRecords()
+    .find((metric) => metric.name === 'mailer_email_retries_total');
+  assert.strictEqual(retries.records.length, 4);
+  assert.deepStrictEqual(retries.records[0].attributes, {
+    transport: 'unknown',
+    error_type: 'service-unavailable',
+  });
+
+  // A span sampled out records nothing, and the retries still reach onRetry.
+  const unsampled = providers();
+  heard.length = 0;
+  await new OpenTelemetryTransport(retrying, {
+    ...unsampled,
+    tracing: { samplingRate: 0 },
+  }).send(createTestMessage(), { onRetry });
+  assert.deepStrictEqual(heard, [1, 2]);
+  assert.deepStrictEqual(unsampled.tracerProvider.getAllSpans(), []);
+});

From 201d5710d7bbb42d29322b3c5d7ff902a6d41437 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 17:59:21 +0300
Subject: [PATCH 089/158] feat(logger): log the retries of the wrapped
 transport

The logger saw a send start and end, but not the retries in between, so
a slow send looked like a slow provider. It now passes the wrapped
transport an onRetry that logs an email.retrying event, at the new level
levels.retrying (warn by default), with the attempt, the wait, the error
text without its addresses unless the message is recorded, and the status
code, and then calls the caller's own onRetry. A logger wrapping a
transport needs a method for that level; a log-only one does not.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                   |  3 ++
 docs/transports/logger.md      | 13 +++++++--
 src/logger/config.js           |  7 ++++-
 src/logger/index.d.ts          | 16 +++++++++--
 src/logger/logger-transport.js | 39 ++++++++++++++++++++++++--
 tests/unit/logger.test.js      | 51 ++++++++++++++++++++++++++++++++++
 6 files changed, 121 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43e43fb..9b7e2cf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,9 @@ fixed ones below.
 - **`onRetry` in the options of a send:** the HTTP providers and `./retry` call it before each
   retry with the attempt, the wait and the error, and the decorators pass it on, so one callback
   hears every level (not yet from `./jmap`).
+- **`./logger` logs retries** as `email.retrying` events, at the new level `levels.retrying`
+  (`warn` by default), with the attempt, the wait, the redacted error text and its status code.
+  With a wrapped transport, the logger needs a method for that level.
 - **Documentation** for every subpath, adapted from upyo's guides.
 - **Package scaffold** set up like the other Alexis libraries: plain CommonJS with no build step,
   a hand-written `index.d.ts`, a closed `exports` map, Node.js 22 or newer, and zero runtime
diff --git a/docs/transports/logger.md b/docs/transports/logger.md
index 26376d8..63c1839 100644
--- a/docs/transports/logger.md
+++ b/docs/transports/logger.md
@@ -89,6 +89,13 @@ to disposable wrapped transports. Completion logs are emitted as callers consume
 receipts. If a caller stops reading a batch early, the wrapped iterator is closed
 without being drained so the logging layer does not start additional delivery work.
 
+The retries of the wrapped transport, those an HTTP provider makes on its own and
+those of a `./retry` inside the logger transport, are logged as `email.retrying`
+events, with the attempt that failed, the wait in milliseconds, the text of the
+error (its addresses replaced by `[REDACTED]` unless the message is recorded)
+and its `statusCode` when it has one. They come from `onRetry` of the send
+options, which still reaches a callback of your own.
+
 The logger transport can be nested with retry, pool, and OpenTelemetry transports.
 The outer decorator observes the complete operation performed by the inner
 transport, so choose the order according to which retries or failovers should
@@ -115,9 +122,11 @@ const transport = new LoggerTransport({
 - `sending`: Level for `email.sending` events. Defaults to `"debug"`.
 - `sent`: Level for `email.sent` events. Defaults to `"info"`.
 - `failed`: Level for failed receipts and thrown errors. Defaults to `"error"`.
+- `retrying`: Level for `email.retrying` events. Defaults to `"warn"`.
 
-The transport checks when it is made that the logger has a method for each of the
-three levels, and throws a `TypeError` otherwise.
+The transport checks when it is made that the logger has a method for each of these
+levels, that of `retrying` only when it wraps a transport, and throws a
+`TypeError` otherwise.
 
 Every event includes the operation, transport id, recipient counts, attachment
 count, and priority. Completion events additionally include duration and receipt or
diff --git a/src/logger/config.js b/src/logger/config.js
index c48f03d..a9d3cbf 100644
--- a/src/logger/config.js
+++ b/src/logger/config.js
@@ -11,7 +11,8 @@ const LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
  * @param options User-provided transport options.
  * @returns Fully resolved transport options.
  * @throws {TypeError} If the logger is missing, a level is not one of pino's,
- *                     or the logger has no method for a configured level.
+ *                     or the logger has no method for a configured level (that
+ *                     of the retries only when a transport is wrapped).
  */
 const resolveLoggerTransportOptions = (options) => {
   const { logger } = options;
@@ -24,8 +25,12 @@ const resolveLoggerTransportOptions = (options) => {
     sending: options.levels?.sending ?? 'debug',
     sent: options.levels?.sent ?? 'info',
     failed: options.levels?.failed ?? 'error',
+    retrying: options.levels?.retrying ?? 'warn',
   };
   for (const [event, level] of Object.entries(levels)) {
+    // Only a wrapped transport retries, so a log-only transport needs no
+    // method for the retries.
+    if (event === 'retrying' && options.transport == null) continue;
     if (!LEVELS.includes(level)) {
       throw new TypeError(
         `Expected levels.${event} to be one of ${LEVELS.join(', ')}: ${JSON.stringify(level)}`,
diff --git a/src/logger/index.d.ts b/src/logger/index.d.ts
index e89ac91..3e453ef 100644
--- a/src/logger/index.d.ts
+++ b/src/logger/index.d.ts
@@ -20,7 +20,8 @@ export type LogMethod = (properties: object, message: string) => unknown;
 /**
  * The logger the transport writes to: a pino logger, a child of one
  * (`logger.child({ component: 'mail' })`), or anything with the methods of the
- * levels in use. `debug`, `info` and `error` are the default levels.
+ * levels in use. `debug`, `info` and `error` are the default levels, and `warn`
+ * when a transport is wrapped.
  */
 export interface Logger {
   readonly trace?: LogMethod;
@@ -53,6 +54,13 @@ export interface LoggerTransportLevels {
    * @default "error"
    */
   readonly failed?: LoggerLevel;
+  /**
+   * Level used when the wrapped transport, or a `./retry` inside it, is about
+   * to retry, as `onRetry` of `TransportOptions` tells.
+   *
+   * @default "warn"
+   */
+  readonly retrying?: LoggerLevel;
 }
 
 /**
@@ -123,8 +131,10 @@ type LoggerTransportConstructorArguments<TProviderId extends string> = [TProvide
  * Transport that records email delivery lifecycle events through a logger the
  * application passes in: any pino-like logger whose methods take the
  * properties first and the message second (`logger.info(properties, message)`).
- * The events are `email.sending`, `email.sent` and `email.failed`; a thrown
- * error is logged under `err`, the key pino serializes.
+ * The events are `email.sending`, `email.sent`, `email.retrying` and
+ * `email.failed`; a thrown error is logged under `err`, the key pino
+ * serializes.  A retry is logged with its attempt, its wait and the text of its
+ * error, without the addresses in it unless the message is recorded.
  *
  * With no wrapped transport, this class acts as a log-only transport and
  * returns synthetic successful receipts.  When a transport is supplied, it
diff --git a/src/logger/logger-transport.js b/src/logger/logger-transport.js
index 6d0271d..ddd6331 100644
--- a/src/logger/logger-transport.js
+++ b/src/logger/logger-transport.js
@@ -95,7 +95,8 @@ class LoggerTransport {
     );
 
     try {
-      for await (const receipt of this.wrappedTransport.sendMany(observedMessages, options)) {
+      const sendOptions = this.withRetryLogging(options, undefined, 'sendMany');
+      for await (const receipt of this.wrappedTransport.sendMany(observedMessages, sendOptions)) {
         const current = pending.dequeue();
         completedCount++;
         this.logReceipt(receipt, current, 'sendMany');
@@ -134,7 +135,10 @@ class LoggerTransport {
       const receipt =
         this.wrappedTransport == null
           ? this.createSyntheticReceipt()
-          : await this.wrappedTransport.send(message, options);
+          : await this.wrappedTransport.send(
+              message,
+              this.withRetryLogging(options, message, operation),
+            );
       this.logReceipt(receipt, { message, startedAt }, operation);
       return receipt;
     } catch (error) {
@@ -153,6 +157,37 @@ class LoggerTransport {
     }
   }
 
+  /**
+   * The options passed on to the wrapped transport: its retries are logged,
+   * and still reach the caller's `onRetry`.
+   */
+  withRetryLogging(options, message, operation) {
+    const onRetry = options?.onRetry;
+    return {
+      ...options,
+      onRetry: (event) => {
+        this.logRetry(event, message, operation);
+        onRetry?.(event);
+      },
+    };
+  }
+
+  logRetry(event, message, operation) {
+    const errorMessage = describe(event.error);
+    const statusCode = event.error?.statusCode;
+    this.log(this.config.levels.retrying, 'Retrying email.', {
+      ...(message == null ? {} : this.getMessageProperties(message)),
+      event: 'email.retrying',
+      operation,
+      transportId: this.id,
+      attempt: event.attempt,
+      delayMilliseconds: event.delayMilliseconds,
+      errorMessage:
+        this.config.recordMessage === false ? redactAddresses(errorMessage) : errorMessage,
+      ...(statusCode == null ? {} : { statusCode }),
+    });
+  }
+
   createSyntheticReceipt() {
     return {
       successful: true,
diff --git a/tests/unit/logger.test.js b/tests/unit/logger.test.js
index 6a2754b..8bc6ecc 100644
--- a/tests/unit/logger.test.js
+++ b/tests/unit/logger.test.js
@@ -85,6 +85,7 @@ test('Logger: unless the message is recorded, a failure is logged without addres
     const logger = {
       debug: () => {},
       info: () => {},
+      warn: () => {},
       error: (properties) => calls.push(properties),
     };
     await new LoggerTransport({ logger, transport, recordMessage }).send(message());
@@ -99,3 +100,53 @@ test('Logger: unless the message is recorded, a failure is logged without addres
     }
   }
 });
+
+test('Logger: a retry of the wrapped transport is logged, and still reaches onRetry', async () => {
+  const calls = [];
+  const logger = {};
+  for (const level of ['debug', 'info', 'warn', 'error']) {
+    logger[level] = (properties, text) => calls.push({ level, text, properties });
+  }
+  const busy = Object.assign(new Error('Mailbox of bob@example.com is busy'), { statusCode: 503 });
+  const base = {
+    id: 'base',
+    send: async (_message, options) => {
+      options.onRetry({ attempt: 1, delayMilliseconds: 250, error: busy });
+      return { successful: true, messageId: 'm1' };
+    },
+    async *sendMany(messages, options) {
+      for await (const sent of messages) yield await base.send(sent, options);
+    },
+  };
+  const heard = [];
+  const transport = new LoggerTransport({ transport: base, logger });
+  await transport.send(message(), { onRetry: (event) => heard.push(event.attempt) });
+  for await (const receipt of transport.sendMany([message()])) {
+    assert.strictEqual(receipt.successful, true);
+  }
+
+  assert.deepStrictEqual(heard, [1]);
+  const retries = calls.filter((call) => call.properties.event === 'email.retrying');
+  assert.strictEqual(retries.length, 2);
+  assert.strictEqual(retries[0].level, 'warn');
+  assert.strictEqual(retries[0].text, 'Retrying email.');
+  assert.strictEqual(retries[0].properties.operation, 'send');
+  assert.strictEqual(retries[0].properties.recipientCount, 1);
+  assert.strictEqual(retries[1].properties.operation, 'sendMany');
+  assert.strictEqual(retries[1].properties.recipientCount, undefined);
+  for (const retry of retries) {
+    assert.strictEqual(retry.properties.attempt, 1);
+    assert.strictEqual(retry.properties.delayMilliseconds, 250);
+    assert.strictEqual(retry.properties.statusCode, 503);
+    assert.strictEqual(retry.properties.errorMessage, 'Error: Mailbox of [REDACTED] is busy');
+  }
+
+  const minimal = methods('debug', 'info', 'error');
+  assert.throws(() => new LoggerTransport({ transport: base, logger: minimal }), {
+    message: 'Expected the logger to have a warn() method for levels.retrying.',
+  });
+  assert.strictEqual(
+    new LoggerTransport({ transport: base, logger: minimal, levels: { retrying: 'info' } }).id,
+    'base',
+  );
+});

From f818556a4334d252a3ae5c13ecddb796a815d7e8 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:00:14 +0300
Subject: [PATCH 090/158] fix(otel): redact the error.message attribute of a
 thrown error

extractErrorAttributes recorded error.message without recordSensitiveData
when the message began like a transport failure, such as "Connection
refused by mx for bob@example.com", so the recipient reached the span
whatever the option said. The message now goes through describeError, as
the span status and events do. The safe beginnings are one module-level
regular expression instead of ten built on every call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  4 ++++
 CLAUDE.md               |  3 +++
 src/otel/attributes.js  | 25 +++++++++----------------
 tests/unit/otel.test.js | 23 +++++++++++++++++++++++
 4 files changed, 39 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b7e2cf..9f65a77 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -87,6 +87,10 @@ fixed ones below.
   reached telemetry and logs. Without `recordSensitiveData` (otel) or `recordMessage` (logger),
   every address in that text is now `[REDACTED]`, and the logger leaves `providerDetails` out.
   `./plunk` no longer puts the start of the recipient's address into a synthetic message ID.
+- **`./otel` redacts the `error.message` attribute too** (an upstream bug): a thrown error whose
+  message began like a transport failure (`Connection…`, `Timeout…`) was recorded as it was, so
+  `Connection refused by mx for bob@example.com` named the recipient. Its addresses are now
+  `[REDACTED]` unless `recordSensitiveData` is on.
 
 ### Fixed
 
diff --git a/CLAUDE.md b/CLAUDE.md
index bacaebd..5c3900c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -292,6 +292,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     wrapped transport now reports its retries through `onRetry` of `TransportOptions`; the
     decorator records each on the span (`mailer.retry.count` and a `retry` event), counts it
     in `mailer_email_retries_total`, and passes it on to the caller's `onRetry`.
+53. otel: the `error.message` attribute of a thrown error was recorded raw when the message
+    began like a transport failure (`Connection…`), whatever addresses followed. It goes
+    through `describeError`, the redaction of the span status and events.
 
 ## Repository layout
 
diff --git a/src/otel/attributes.js b/src/otel/attributes.js
index 9e975dd..9697fd1 100644
--- a/src/otel/attributes.js
+++ b/src/otel/attributes.js
@@ -33,6 +33,11 @@ const { estimateMessageSize } = require('./message-size.js');
  * const errorAttrs = extractor.extractErrorAttributes(error, "network");
  * ```
  */
+// The beginnings of an error message that describe the transport rather than
+// a recipient.
+const SAFE_ERROR_MESSAGE =
+  /^(?:timeout|connection|network|dns|rate limit|quota exceeded|service unavailable|internal server error|bad gateway|gateway timeout)/i;
+
 class EmailAttributeExtractor {
   recordSensitiveData;
   transportName;
@@ -153,9 +158,10 @@ class EmailAttributeExtractor {
     if (error instanceof Error) {
       attributes['error.name'] = error.name;
 
-      // Only record error message if not sensitive data mode or if it's a safe error
+      // Only record error message if not sensitive data mode or if it's a safe error,
+      // and then without the addresses a safe-looking message may still name.
       if (this.recordSensitiveData || this.isSafeErrorMessage(error.message)) {
-        attributes['error.message'] = error.message;
+        attributes['error.message'] = this.describeError(error.message);
       }
     }
 
@@ -197,20 +203,7 @@ class EmailAttributeExtractor {
   }
 
   isSafeErrorMessage(message) {
-    const safePatterns = [
-      /^timeout/i,
-      /^connection/i,
-      /^network/i,
-      /^dns/i,
-      /^rate limit/i,
-      /^quota exceeded/i,
-      /^service unavailable/i,
-      /^internal server error/i,
-      /^bad gateway/i,
-      /^gateway timeout/i,
-    ];
-
-    return safePatterns.some((pattern) => pattern.test(message));
+    return SAFE_ERROR_MESSAGE.test(message);
   }
 }
 
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index 1612eb4..1784dbe 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -363,3 +363,26 @@ test('OTel: the retries of the wrapped transport reach the span, the metrics and
   assert.deepStrictEqual(heard, [1, 2]);
   assert.deepStrictEqual(unsampled.tracerProvider.getAllSpans(), []);
 });
+
+test('OTel: a safe-looking error message is recorded without its addresses', async () => {
+  const thrown = plain({});
+  thrown.send = async () => {
+    throw new Error('Connection refused by mx for bob@example.com');
+  };
+  for (const recordSensitiveData of [false, true]) {
+    const { tracerProvider, meterProvider } = providers();
+    const transport = new OpenTelemetryTransport(thrown, {
+      tracerProvider,
+      meterProvider,
+      tracing: { recordSensitiveData },
+    });
+    await assert.rejects(transport.send(createTestMessage()));
+    const [span] = tracerProvider.getAllSpans();
+    assert.strictEqual(
+      span.attributes['error.message'],
+      recordSensitiveData
+        ? 'Connection refused by mx for bob@example.com'
+        : 'Connection refused by mx for [REDACTED]',
+    );
+  }
+});

From d0df2919d60bdaf4add5c8771d3e0a0f88c479f1 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:03:19 +0300
Subject: [PATCH 091/158] refactor(otel)!: name metrics and attributes after
 the semantic conventions

The instruments were named the Prometheus way (mailer_email_attempts_total,
_seconds, _bytes) with bare attribute keys (transport, status, error_type),
which an OpenTelemetry backend neither expects nor converts. Before the
first release is the cheapest time to rename them: the metrics are now
dotted names under the prefix (mailer.email.attempts, .messages,
.retries, .duration, .message.size, .attachments, .active_sends) with
units in the instrument, and their attributes namespaced
(mailer.transport.name, mailer.operation.name, mailer.status,
email.priority, email.content.type, error.type). Every send operation is
recorded by one recordAttempt, a failed batch with its duration too. An
HTTP transport's spans name the protocol http and the scheme in
url.scheme, the port is a Number, and the exception event carries the
stack with its message redacted. The ported tests say where they changed.

BREAKING CHANGE: metric names and metric attribute keys of ./otel change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  10 ++
 CLAUDE.md                                     |   2 +-
 docs/transports/otel.md                       |  39 +++--
 src/otel/metrics.js                           | 141 ++++++++----------
 src/otel/opentelemetry-transport.js           |  24 ++-
 src/otel/tracing.js                           |  16 ++
 tests/unit/otel-content-type.test.js          |   4 +-
 .../unit/otel-opentelemetry-transport.test.js |  12 +-
 tests/unit/otel.test.js                       |  74 +++++++--
 9 files changed, 201 insertions(+), 121 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9f65a77..af8d2c0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -230,6 +230,16 @@ fixed ones below.
 
 ### Changed
 
+- **`./otel` names its instruments and attributes after the OpenTelemetry semantic
+  conventions.** The metrics are `mailer.email.attempts`, `.messages`, `.retries`, `.duration`,
+  `.message.size`, `.attachments` and `.active_sends` under `metrics.prefix`, with units such as
+  `{attempt}`, `s` and `By` in the instrument rather than `_total`, `_seconds` and `_bytes` in
+  the name; their attributes are `mailer.transport.name`, `mailer.operation.name`,
+  `mailer.status`, `email.priority`, `email.content.type` and `error.type` instead of
+  `transport`, `operation`, `status`, `priority`, `content_type` and `error_type`. An HTTP
+  transport's spans get `network.protocol.name: 'http'` and `url.scheme` instead of the scheme
+  as the protocol, and the `exception` event carries `exception.stacktrace`, its message
+  redacted.
 - **One retry policy for every HTTP provider.** A request timeout (408), a rate limit (429), a
   server error (5xx) and a failure without a response are retried, after an exponential backoff
   capped at ten seconds and spread over its upper half (jitter), or after `Retry-After`. `./ses`,
diff --git a/CLAUDE.md b/CLAUDE.md
index 5c3900c..fc8a243 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -291,7 +291,7 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 52. otel: `recordRetry` was never called, since nothing told the decorator of a retry. The
     wrapped transport now reports its retries through `onRetry` of `TransportOptions`; the
     decorator records each on the span (`mailer.retry.count` and a `retry` event), counts it
-    in `mailer_email_retries_total`, and passes it on to the caller's `onRetry`.
+    in `mailer.email.retries`, and passes it on to the caller's `onRetry`.
 53. otel: the `error.message` attribute of a thrown error was recorded raw when the message
     began like a transport failure (`Connection…`), whatever addresses followed. It goes
     through `describeError`, the redaction of the span status and events.
diff --git a/docs/transports/otel.md b/docs/transports/otel.md
index 1f85187..df38685 100644
--- a/docs/transports/otel.md
+++ b/docs/transports/otel.md
@@ -355,20 +355,31 @@ sampling rate, and setting `metrics.samplingRate` throws a `TypeError`.
 duration histogram (OpenTelemetry API 1.7 or later); a View of the application
 takes precedence over it.
 
-The transport collects the following key metrics:
-
-- Email delivery counters: Track successful and failed send attempts
-
-- Duration histograms: Measure how long email operations take
-
-- Message size histograms: Monitor email size distribution
-
-- Active operation gauges: Track concurrent email sending operations
-
-- Retries: Count the requests the wrapped transport sent again, by the category
-  of the failure; a span shows them as `retry` events and in `mailer.retry.count`
-
-- Error classification: Categorize failures by type (auth, network, etc.)
+The instruments follow the naming of the OpenTelemetry semantic conventions:
+dotted names under `metrics.prefix` (`mailer` by default), with the unit in the
+`unit` of the instrument rather than in its name, which an exporter such as
+Prometheus turns into its own (`mailer_email_attempts_total`):
+
+| Instrument | Kind | Unit | Attributes |
+|---|---|---|---|
+| `mailer.email.attempts` | counter | `{attempt}` | `mailer.transport.name`, `mailer.operation.name` (`send`, `send_batch`), `mailer.status` (`success`, `failure`, `partial_failure`), `error.type` on a failure |
+| `mailer.email.duration` | histogram | `s` | as `mailer.email.attempts` |
+| `mailer.email.messages` | counter | `{message}` | `mailer.transport.name`, `email.priority`, `mailer.status` |
+| `mailer.email.retries` | counter | `{retry}` | `mailer.transport.name`, `error.type` |
+| `mailer.email.message.size` | histogram | `By` | `mailer.transport.name`, `email.priority`, `email.content.type` |
+| `mailer.email.attachments` | histogram | `{attachment}` | as `mailer.email.message.size` |
+| `mailer.email.active_sends` | up-down counter | `{send}` | `mailer.transport.name` |
+
+A message is counted once in `mailer.email.messages`, when its receipt comes back;
+a send operation, of one message or a whole batch, once in `mailer.email.attempts`.
+`error.type` is the category of the failure, from `errorClassifier`. The retries
+are those of the wrapped transport, reported through `onRetry`; a span shows
+them as `retry` events and in `mailer.retry.count`.
+
+An HTTP transport gives its spans `network.protocol.name` `http` with `url.scheme`
+(`https`), `server.address` and `server.port`; an SMTP one `smtp`. The `exception`
+event of a thrown error carries `exception.stacktrace`, with the message redacted
+like the rest of the error text.
 
 These metrics are exported to your configured observability backend
 (Prometheus, DataDog, etc.) where you can create dashboards and alerts
diff --git a/src/otel/metrics.js b/src/otel/metrics.js
index 7b532cd..b27854a 100644
--- a/src/otel/metrics.js
+++ b/src/otel/metrics.js
@@ -13,6 +13,11 @@ const batchStatus = (successCount, failureCount) => {
 
 /**
  * Manages OpenTelemetry metrics collection for email operations.
+ *
+ * The instruments are named after the OpenTelemetry semantic conventions:
+ * dotted names under the prefix, units in `unit` rather than in the name,
+ * and namespaced attributes (`mailer.transport.name`, `mailer.operation.name`,
+ * `mailer.status`, `email.priority`, `email.content.type`, `error.type`).
  */
 class MetricsCollector {
   meter;
@@ -34,50 +39,45 @@ class MetricsCollector {
   constructor(meterProvider, config) {
     this.config = config;
     this.meter = meterProvider.getMeter(metadata.name, metadata.version);
+    const prefix = `${config.prefix}.email`;
 
     // Initialize counters
-    this.attemptCounter = this.meter.createCounter(`${config.prefix}_email_attempts_total`, {
-      description: 'Total number of email send attempts',
-      unit: '1',
+    this.attemptCounter = this.meter.createCounter(`${prefix}.attempts`, {
+      description: 'Send operations, of one message or a batch, by outcome',
+      unit: '{attempt}',
     });
 
-    this.messageCounter = this.meter.createCounter(`${config.prefix}_email_messages_total`, {
+    this.messageCounter = this.meter.createCounter(`${prefix}.messages`, {
       description: 'Messages a transport returned a receipt for, by priority and status',
-      unit: '1',
+      unit: '{message}',
     });
 
-    this.retryCounter = this.meter.createCounter(`${config.prefix}_email_retries_total`, {
+    this.retryCounter = this.meter.createCounter(`${prefix}.retries`, {
       description: 'Requests the wrapped transport sent again after a failure',
-      unit: '1',
+      unit: '{retry}',
     });
 
     // Initialize histograms
-    this.durationHistogram = this.meter.createHistogram(`${config.prefix}_email_duration_seconds`, {
+    this.durationHistogram = this.meter.createHistogram(`${prefix}.duration`, {
       description: 'Duration of email send operations',
       unit: 's',
       advice: { explicitBucketBoundaries: [...config.durationBuckets] },
     });
 
-    this.messageSizeHistogram = this.meter.createHistogram(
-      `${config.prefix}_email_message_size_bytes`,
-      {
-        description: 'Size of email messages in bytes',
-        unit: 'By',
-      },
-    );
-
-    this.attachmentCountHistogram = this.meter.createHistogram(
-      `${config.prefix}_email_attachments_count`,
-      {
-        description: 'Number of attachments per email',
-        unit: '1',
-      },
-    );
+    this.messageSizeHistogram = this.meter.createHistogram(`${prefix}.message.size`, {
+      description: 'Estimated size of email messages',
+      unit: 'By',
+    });
+
+    this.attachmentCountHistogram = this.meter.createHistogram(`${prefix}.attachments`, {
+      description: 'Number of attachments per email',
+      unit: '{attachment}',
+    });
 
     // Initialize gauge
-    this.activeSendsGauge = this.meter.createUpDownCounter(`${config.prefix}_email_active_sends`, {
-      description: 'Number of currently active email send operations',
-      unit: '1',
+    this.activeSendsGauge = this.meter.createUpDownCounter(`${prefix}.active_sends`, {
+      description: 'Email send operations in progress',
+      unit: '{send}',
     });
   }
 
@@ -85,7 +85,14 @@ class MetricsCollector {
    * Records the start of an email send operation.
    */
   recordSendStart(transport) {
-    this.activeSendsGauge.add(1, { transport });
+    this.activeSendsGauge.add(1, { 'mailer.transport.name': transport });
+  }
+
+  /**
+   * Records the end of an email send operation, however it ended.
+   */
+  recordSendEnd(transport) {
+    this.activeSendsGauge.add(-1, { 'mailer.transport.name': transport });
   }
 
   /**
@@ -94,64 +101,48 @@ class MetricsCollector {
    */
   recordMessageOutcome(transport, priority, successful) {
     this.messageCounter.add(1, {
-      transport,
-      priority,
-      status: successful ? 'success' : 'failure',
+      'mailer.transport.name': transport,
+      'email.priority': priority,
+      'mailer.status': successful ? 'success' : 'failure',
     });
   }
 
   /**
-   * Records the end of an email send operation, however it ended.
+   * Records a finished send operation: `send` or `send_batch`, its duration
+   * in seconds, its status (`success`, `failure` or, for a batch,
+   * `partial_failure`) and the category of its failure, if any.
    */
-  recordSendEnd(transport) {
-    this.activeSendsGauge.add(-1, { transport });
+  recordAttempt(transport, operation, duration, status, errorType) {
+    const attributes = {
+      'mailer.transport.name': transport,
+      'mailer.operation.name': operation,
+      'mailer.status': status,
+      ...(errorType && { 'error.type': errorType }),
+    };
+
+    this.attemptCounter.add(1, attributes);
+    this.durationHistogram.record(duration, attributes);
   }
 
   /**
-   * Records the completion of an email send operation.
+   * Records a finished batch from the counts of its receipts.
    */
-  recordSendComplete(transport, duration, success, errorType) {
-    const labels = {
-      transport,
-      status: success ? 'success' : 'failure',
-      ...(errorType && { error_type: errorType }),
-    };
-
-    this.attemptCounter.add(1, labels);
-    this.durationHistogram.record(duration, labels);
+  recordBatch(transport, duration, successCount, failureCount) {
+    this.recordAttempt(transport, 'send_batch', duration, batchStatus(successCount, failureCount));
   }
 
   /**
    * Records metrics for individual messages.
    */
   recordMessage(message, transport, messageSize = estimateMessageSize(message)) {
-    const labels = {
-      transport,
-      priority: message.priority,
-      content_type: this.getContentType(message),
+    const attributes = {
+      'mailer.transport.name': transport,
+      'email.priority': message.priority,
+      'email.content.type': this.getContentType(message),
     };
 
-    this.messageSizeHistogram.record(messageSize, labels);
-    this.attachmentCountHistogram.record(message.attachments.length, labels);
-  }
-
-  /**
-   * Records metrics for batch operations.
-   */
-  recordBatch(transport, duration, successCount, failureCount) {
-    const labels = { transport };
-
-    // Record batch-level metrics
-    this.attemptCounter.add(1, {
-      ...labels,
-      status: batchStatus(successCount, failureCount),
-      operation: 'batch',
-    });
-
-    this.durationHistogram.record(duration, {
-      ...labels,
-      operation: 'batch',
-    });
+    this.messageSizeHistogram.record(messageSize, attributes);
+    this.attachmentCountHistogram.record(message.attachments.length, attributes);
   }
 
   /**
@@ -159,19 +150,7 @@ class MetricsCollector {
    * failure it retries.
    */
   recordRetry(transport, errorType) {
-    this.retryCounter.add(1, { transport, error_type: errorType });
-  }
-
-  /**
-   * Records an error for metrics classification.
-   */
-  recordError(transport, errorType, operation = 'send') {
-    this.attemptCounter.add(1, {
-      transport,
-      status: 'failure',
-      error_type: errorType,
-      operation,
-    });
+    this.retryCounter.add(1, { 'mailer.transport.name': transport, 'error.type': errorType });
   }
 
   getContentType(message) {
diff --git a/src/otel/opentelemetry-transport.js b/src/otel/opentelemetry-transport.js
index 2c597e8..8e7edc8 100644
--- a/src/otel/opentelemetry-transport.js
+++ b/src/otel/opentelemetry-transport.js
@@ -164,14 +164,15 @@ class OpenTelemetryTransport {
       // Record success/failure
       if (receipt.successful) {
         span?.recordSuccess(receipt.messageId);
-        this.metricsCollector?.recordSendComplete(this.transportName, duration, true);
+        this.metricsCollector?.recordAttempt(this.transportName, 'send', duration, 'success');
       } else {
         const errorCategory = this.classifyReceipt(receipt);
         span?.recordFailure(receipt.errorMessages);
-        this.metricsCollector?.recordSendComplete(
+        this.metricsCollector?.recordAttempt(
           this.transportName,
+          'send',
           duration,
-          false,
+          'failure',
           errorCategory,
         );
       }
@@ -182,7 +183,13 @@ class OpenTelemetryTransport {
       const errorCategory = this.classifyError(error);
 
       span?.recordError(error, errorCategory);
-      this.metricsCollector?.recordSendComplete(this.transportName, duration, false, errorCategory);
+      this.metricsCollector?.recordAttempt(
+        this.transportName,
+        'send',
+        duration,
+        'failure',
+        errorCategory,
+      );
 
       throw error;
     } finally {
@@ -272,10 +279,11 @@ class OpenTelemetryTransport {
         span?.recordFailure(errorMessages, errorMessageCount);
       }
     } catch (error) {
+      const duration = (performance.now() - startTime) / 1000;
       const errorCategory = this.classifyError(error);
 
       span?.recordError(error, errorCategory);
-      metrics?.recordError(transportName, errorCategory, 'send_batch');
+      metrics?.recordAttempt(transportName, 'send_batch', duration, 'failure', errorCategory);
 
       throw error;
     } finally {
@@ -374,10 +382,12 @@ class OpenTelemetryTransport {
         if (url && typeof url === 'string') {
           try {
             const parsedUrl = new URL(url);
+            // The protocol is HTTP whether or not over TLS; the scheme says which.
             return {
-              'network.protocol.name': parsedUrl.protocol.replace(':', ''),
+              'network.protocol.name': 'http',
+              'url.scheme': parsedUrl.protocol.slice(0, -1),
               'server.address': parsedUrl.hostname,
-              ...(parsedUrl.port && { 'server.port': parseInt(parsedUrl.port) }),
+              ...(parsedUrl.port && { 'server.port': Number(parsedUrl.port) }),
             };
           } catch {
             // Invalid URL, skip network attributes
diff --git a/src/otel/tracing.js b/src/otel/tracing.js
index 957db74..d6711c1 100644
--- a/src/otel/tracing.js
+++ b/src/otel/tracing.js
@@ -9,6 +9,20 @@ const SPAN_STATUS_ERROR = 2;
 const { EmailAttributeExtractor } = require('./attributes.js');
 const metadata = require('../version.js');
 
+// The stack of an error for the `exception.stacktrace` of the semantic
+// conventions, with its message described as the status and the events
+// describe it.  Only the message is redacted where the stack repeats it: the
+// frames hold no address, and paths such as node_modules/@scope/... would read
+// as one; a stack that does not repeat its message is redacted whole.
+const describeStack = (error, extractor) => {
+  const stack = error.stack;
+  if (typeof stack !== 'string' || stack === '') return undefined;
+  const at = error.message === '' ? -1 : stack.indexOf(error.message);
+  if (at === -1) return extractor.describeError(stack);
+  const message = extractor.describeError(error.message);
+  return stack.slice(0, at) + message + stack.slice(at + error.message.length);
+};
+
 /**
  * Manages OpenTelemetry tracing for email operations.
  */
@@ -113,11 +127,13 @@ class LiveEmailSpan {
     this.span.setAttributes(errorAttributes);
 
     // Add error event
+    const stacktrace = error instanceof Error ? describeStack(error, extractor) : undefined;
     this.span.addEvent('exception', {
       'exception.type': error instanceof Error ? error.constructor.name : 'unknown',
       'exception.message': extractor.describeError(
         error instanceof Error ? error.message : String(error),
       ),
+      ...(stacktrace && { 'exception.stacktrace': stacktrace }),
     });
   }
 
diff --git a/tests/unit/otel-content-type.test.js b/tests/unit/otel-content-type.test.js
index 3da30a3..769f603 100644
--- a/tests/unit/otel-content-type.test.js
+++ b/tests/unit/otel-content-type.test.js
@@ -1,5 +1,7 @@
 // Ported from upyo v0.7.0 (packages/opentelemetry/src/content-type.test.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+//
+// Changed after the port: metric attributes follow the semantic conventions.
 
 const { createMessage } = require('../../src/core/message.js');
 const assert = require('node:assert/strict');
@@ -66,7 +68,7 @@ describe('content type detection', () => {
     const labelled = meterProvider.meters
       .flatMap((meter) => meter.histograms)
       .flatMap((histogram) => histogram.records)
-      .map((record) => record.attributes?.content_type)
+      .map((record) => record.attributes?.['email.content.type'])
       .filter((value) => value !== undefined);
     assert.ok(labelled.length > 0, 'no histogram recorded a content type');
     for (const value of labelled) assert.equal(value, 'multipart');
diff --git a/tests/unit/otel-opentelemetry-transport.test.js b/tests/unit/otel-opentelemetry-transport.test.js
index a7c2480..4aca710 100644
--- a/tests/unit/otel-opentelemetry-transport.test.js
+++ b/tests/unit/otel-opentelemetry-transport.test.js
@@ -1,5 +1,7 @@
 // Ported from upyo v0.7.0 (packages/opentelemetry/src/opentelemetry-transport.test.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+//
+// Changed after the port: metric attributes follow the semantic conventions.
 
 const { describe, it } = require('node:test');
 const { strict: assert } = require('node:assert');
@@ -114,8 +116,8 @@ describe('OpenTelemetryTransport', () => {
       // Verify error metrics
       const metrics = extractMetrics(setup.meterProvider);
       const attemptRecords =
-        metrics.find((m) => m.records.some((r) => r.attributes?.status === 'failure'))?.records ||
-        [];
+        metrics.find((m) => m.records.some((r) => r.attributes?.['mailer.status'] === 'failure'))
+          ?.records || [];
       assert.ok(attemptRecords.length > 0);
     });
 
@@ -160,9 +162,9 @@ describe('OpenTelemetryTransport', () => {
       const metrics = extractMetrics(setup.meterProvider);
       const failureRecord = metrics
         .flatMap((metric) => metric.records)
-        .find((record) => record.attributes?.status === 'failure');
+        .find((record) => record.attributes?.['mailer.status'] === 'failure');
 
-      assert.equal(failureRecord?.attributes?.error_type, 'rate-limit');
+      assert.equal(failureRecord?.attributes?.['error.type'], 'rate-limit');
     });
 
     it('should respect abort signals', async () => {
@@ -471,7 +473,7 @@ describe('OpenTelemetryTransport', () => {
       const metrics = extractMetrics(setup.meterProvider);
       const failureRecords = metrics
         .flatMap((m) => m.records)
-        .filter((r) => r.attributes?.error_type === 'custom_error');
+        .filter((r) => r.attributes?.['error.type'] === 'custom_error');
 
       assert.ok(failureRecords.length > 0);
     });
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index 1784dbe..f52e20e 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -21,6 +21,11 @@ const plain = (config, receipt = { successful: true, messageId: 'm1' }) => ({
     }
   },
 });
+const outcome = (priority, status) => ({
+  'mailer.transport.name': 'unknown',
+  'email.priority': priority,
+  'mailer.status': status,
+});
 const collect = async (iterable) => {
   const items = [];
   for await (const item of iterable) items.push(item);
@@ -64,7 +69,7 @@ test('OTel: the transport name and the network attributes come from its config',
     [
       { host: 'smtp.example.com', port: 587 },
       'smtp',
-      { 'server.address': 'smtp.example.com', 'server.port': 587 },
+      { 'network.protocol.name': 'smtp', 'server.address': 'smtp.example.com', 'server.port': 587 },
     ],
     [
       { domain: 'mg.example.com', region: 'eu' },
@@ -74,7 +79,7 @@ test('OTel: the transport name and the network attributes come from its config',
     [
       { apiKey: 'k', region: 'us', baseUrl: 'https://api.example.com:8443' },
       'sendgrid',
-      { 'server.port': 8443 },
+      { 'network.protocol.name': 'http', 'url.scheme': 'https', 'server.port': 8443 },
     ],
     [{ accessKeyId: 'a', endpoint: 'not a url' }, 'ses', {}],
     [{ version: 3 }, 'unknown', {}],
@@ -215,11 +220,11 @@ test('OTel: a message is counted once, with its priority and its outcome', async
   );
   const messages = meterProvider
     .getAllRecords()
-    .find((metric) => metric.name === 'mailer_email_messages_total');
+    .find((metric) => metric.name === 'mailer.email.messages');
   assert.deepStrictEqual(messages.records, [
-    { value: 1, attributes: { transport: 'unknown', priority: 'high', status: 'success' } },
-    { value: 1, attributes: { transport: 'unknown', priority: 'normal', status: 'success' } },
-    { value: 1, attributes: { transport: 'unknown', priority: 'low', status: 'failure' } },
+    { value: 1, attributes: outcome('high', 'success') },
+    { value: 1, attributes: outcome('normal', 'success') },
+    { value: 1, attributes: outcome('low', 'failure') },
   ]);
 });
 
@@ -241,9 +246,9 @@ test('OTel: a batch is a success, a partial failure or a failure', async () => {
     await collect(transport.sendMany([createTestMessage(), createTestMessage()]));
     const attempts = meterProvider
       .getAllRecords()
-      .find((metric) => metric.name === 'mailer_email_attempts_total');
+      .find((metric) => metric.name === 'mailer.email.attempts');
     assert.strictEqual(attempts.records.length, 1);
-    assert.strictEqual(attempts.records[0].attributes.status, status);
+    assert.strictEqual(attempts.records[0].attributes['mailer.status'], status);
   }
 });
 
@@ -257,7 +262,7 @@ test('OTel: the duration buckets reach the histogram as advice', () => {
     new OpenTelemetryTransport(plain({}), { tracerProvider, meterProvider, metrics });
     const duration = meterProvider
       .getAllRecords()
-      .find((metric) => metric.name === 'mailer_email_duration_seconds');
+      .find((metric) => metric.name === 'mailer.email.duration');
     assert.deepStrictEqual(duration.options.advice, { explicitBucketBoundaries: buckets });
   }
 });
@@ -346,11 +351,11 @@ test('OTel: the retries of the wrapped transport reach the span, the metrics and
   }
   const retries = meterProvider
     .getAllRecords()
-    .find((metric) => metric.name === 'mailer_email_retries_total');
+    .find((metric) => metric.name === 'mailer.email.retries');
   assert.strictEqual(retries.records.length, 4);
   assert.deepStrictEqual(retries.records[0].attributes, {
-    transport: 'unknown',
-    error_type: 'service-unavailable',
+    'mailer.transport.name': 'unknown',
+    'error.type': 'service-unavailable',
   });
 
   // A span sampled out records nothing, and the retries still reach onRetry.
@@ -386,3 +391,48 @@ test('OTel: a safe-looking error message is recorded without its addresses', asy
     );
   }
 });
+
+test('OTel: the instruments are named after the semantic conventions', () => {
+  const { tracerProvider, meterProvider } = providers();
+  // oxlint-disable-next-line no-new -- the instruments are made by the constructor
+  new OpenTelemetryTransport(plain({}), {
+    tracerProvider,
+    meterProvider,
+    metrics: { prefix: 'billing' },
+  });
+  const instruments = [];
+  for (const metric of meterProvider.getAllRecords()) {
+    instruments.push(`${metric.instrument} ${metric.name} ${metric.options.unit}`);
+  }
+  assert.deepStrictEqual(instruments.sort(), [
+    'counter billing.email.attempts {attempt}',
+    'counter billing.email.messages {message}',
+    'counter billing.email.retries {retry}',
+    'histogram billing.email.attachments {attachment}',
+    'histogram billing.email.duration s',
+    'histogram billing.email.message.size By',
+    'upDownCounter billing.email.active_sends {send}',
+  ]);
+});
+
+test('OTel: an exception event carries the stack, its message redacted', async () => {
+  for (const recordSensitiveData of [false, true]) {
+    const thrown = plain({});
+    thrown.send = async () => {
+      throw new Error('Connection refused for bob@example.com');
+    };
+    const { tracerProvider, meterProvider } = providers();
+    const transport = new OpenTelemetryTransport(thrown, {
+      tracerProvider,
+      meterProvider,
+      tracing: { recordSensitiveData },
+    });
+    await assert.rejects(transport.send(createTestMessage()));
+    const [span] = tracerProvider.getAllSpans();
+    const exception = span.events.find((event) => event.name === 'exception');
+    const stacktrace = exception.attributes['exception.stacktrace'];
+    const address = recordSensitiveData ? 'bob@example.com' : '[REDACTED]';
+    assert.ok(stacktrace.startsWith(`Error: Connection refused for ${address}\n`), stacktrace);
+    assert.match(stacktrace, /\n {4}at /);
+  }
+});

From 2c8718cdfd7918386c15984d8e9f704058a8a04b Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:04:17 +0300
Subject: [PATCH 092/158] perf(otel): estimate a message's size once, without
 encoding it

send estimated the size of its message for the span, the size histogram
and the custom attributes, each time encoding the subject, the bodies and
the calendar to UTF-8 only to read their length. The size is now
estimated once per send and passed to all three, and counted with
Buffer.byteLength, which gives the same byte count without the copies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/otel/attributes.js              |  4 ++--
 src/otel/message-size.js            |  6 +++---
 src/otel/opentelemetry-transport.js | 12 +++++++++---
 src/otel/tracing.js                 |  7 +++++--
 4 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/src/otel/attributes.js b/src/otel/attributes.js
index 9697fd1..d91e8ea 100644
--- a/src/otel/attributes.js
+++ b/src/otel/attributes.js
@@ -52,7 +52,7 @@ class EmailAttributeExtractor {
   /**
    * Extracts attributes for a single message send operation.
    */
-  extractMessageAttributes(message) {
+  extractMessageAttributes(message, messageSize = estimateMessageSize(message)) {
     const attributes = {
       // General operation attributes (following OTel patterns)
       'operation.name': 'email.send',
@@ -91,7 +91,7 @@ class EmailAttributeExtractor {
     attributes['email.content.type'] = this.detectContentType(message);
 
     // Calculate message size estimate
-    attributes['email.message.size'] = estimateMessageSize(message);
+    attributes['email.message.size'] = messageSize;
 
     return attributes;
   }
diff --git a/src/otel/message-size.js b/src/otel/message-size.js
index 5fc6947..f1f5e5a 100644
--- a/src/otel/message-size.js
+++ b/src/otel/message-size.js
@@ -1,8 +1,6 @@
 // Ported from upyo v0.7.0 (packages/opentelemetry/src/message-size.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const encoder = new TextEncoder();
-
 /**
  * Counts a string in UTF-8 bytes rather than UTF-16 code units.
  *
@@ -11,11 +9,13 @@ const encoder = new TextEncoder();
  * real size, an emoji a half.  The size these estimates report is in bytes, so
  * they have to be counted that way.
  *
+ * Counted with `Buffer.byteLength`, without encoding the text.
+ *
  * @param text The string to measure.
  * @returns The number of bytes the string occupies in UTF-8.
  */
 const utf8Length = (text) => {
-  return encoder.encode(text).length;
+  return Buffer.byteLength(text, 'utf8');
 };
 
 /**
diff --git a/src/otel/opentelemetry-transport.js b/src/otel/opentelemetry-transport.js
index 8e7edc8..bde4cb1 100644
--- a/src/otel/opentelemetry-transport.js
+++ b/src/otel/opentelemetry-transport.js
@@ -129,13 +129,19 @@ class OpenTelemetryTransport {
    */
   async send(message, options) {
     const startTime = performance.now();
+    // Estimated once, for the span, the metrics and the custom attributes.
+    const messageSize = estimateMessageSize(message);
 
     // Create span if tracing is enabled
-    const span = this.tracingCollector?.createSendSpan(message, this.extractNetworkAttributes());
+    const span = this.tracingCollector?.createSendSpan(
+      message,
+      this.extractNetworkAttributes(),
+      messageSize,
+    );
 
     // Record metrics start
     this.metricsCollector?.recordSendStart(this.transportName);
-    this.metricsCollector?.recordMessage(message, this.transportName);
+    this.metricsCollector?.recordMessage(message, this.transportName, messageSize);
 
     try {
       // Apply custom attributes if configured
@@ -144,7 +150,7 @@ class OpenTelemetryTransport {
           'send',
           this.transportName,
           1,
-          estimateMessageSize(message),
+          messageSize,
         );
         span.setAttributes(customAttributes);
       }
diff --git a/src/otel/tracing.js b/src/otel/tracing.js
index d6711c1..ca5253a 100644
--- a/src/otel/tracing.js
+++ b/src/otel/tracing.js
@@ -44,7 +44,7 @@ class TracingCollector {
   /**
    * Creates a span for a single email send operation.
    */
-  createSendSpan(message, networkAttributes) {
+  createSendSpan(message, networkAttributes, messageSize) {
     if (!this.shouldSample()) {
       return new NoOpEmailSpan();
     }
@@ -55,7 +55,10 @@ class TracingCollector {
     });
 
     // Set message attributes
-    const messageAttributes = this.attributeExtractor.extractMessageAttributes(message);
+    const messageAttributes = this.attributeExtractor.extractMessageAttributes(
+      message,
+      messageSize,
+    );
     span.setAttributes(messageAttributes);
 
     // Set network attributes if provided

From 74353917b76e094d3ee96208a0f6bda75da3f5bc Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:09:04 +0300
Subject: [PATCH 093/158] ci: raise the size budgets that the shared request
 code outgrew

Each HTTP provider now bundles the shared request code of src/internal
(the retry loop with its deadlines, the bounded body reader, the checks of
the configuration and of an ambiguous failure), and ./logger its retry
logging, which took eight subpaths past budgets set before them: resend
4.1 KB, sendgrid 4.0, mailgun 3.7, mailtrap 4.9, maileroo 4.3,
lettermint 4.5, plunk 3.8, logger 2.0 and jmap 10.1. The budgets now sit
about 0.4 KB above those, as decimals, which the size script accepts. A
local check had read only the first five budgets of the CI step, so the
crossings went unnoticed when they happened.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/npm-publish/SKILL.md | 2 +-
 .github/workflows/ci.yml            | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/npm-publish/SKILL.md b/.claude/skills/npm-publish/SKILL.md
index 2924981..1e88c29 100644
--- a/.claude/skills/npm-publish/SKILL.md
+++ b/.claude/skills/npm-publish/SKILL.md
@@ -37,7 +37,7 @@ pnpm run check:dts               # tsc over the d.ts of every entry of the expor
 These are the same gates `prepublishOnly` runs. CI adds three more; run them too:
 
 ```bash
-pnpm size --max-gzip 7 --max-gzip-smtp 17 …                     # the budgets: copy the size step of ci.yml
+pnpm size --max-gzip 8 --max-gzip-smtp 18 …                     # the budgets: copy the size step of ci.yml
 pnpm docs:comparison && git diff --exit-code docs/guide/comparison.md   # the table matches docs/comparison.json
 pnpm run docs:build                                              # the docs site; a dead link fails it
 ```
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d7c6b08..c805646 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 18 --max-gzip-jmap 10 --max-gzip-ses 5 --max-gzip-resend 3 --max-gzip-sendgrid 3 --max-gzip-mailgun 3 --max-gzip-mailtrap 4 --max-gzip-maileroo 4 --max-gzip-lettermint 4 --max-gzip-plunk 3 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2
+      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 18 --max-gzip-jmap 10.5 --max-gzip-ses 5 --max-gzip-resend 4.5 --max-gzip-sendgrid 4.5 --max-gzip-mailgun 4 --max-gzip-mailtrap 5.5 --max-gzip-maileroo 5 --max-gzip-lettermint 5 --max-gzip-plunk 4.5 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
 
   types:
     runs-on: ubuntu-latest

From f197c0a1678667124710ad6072e32d023492bfe4 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:09:29 +0300
Subject: [PATCH 094/158] fix(smtp): judge a loopback host by one rule
 everywhere

The OAuth 2.0 token endpoint allowed plain http: only to the four
spellings localhost, 127.0.0.1, [::1] and ::1, while SMTP AUTH without TLS
accepted any loopback host through sixty lines of its own IPv4 and IPv6
parsing, and the HTTP providers had a third rule. internal/loopback.js now
holds one: localhost, a name under .localhost, 127.0.0.0/8 and ::1, also
IPv4-mapped, checked with net.BlockList, for SMTP, OAuth 2.0 and the
providers alike.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |   4 ++
 CLAUDE.md                   |   5 ++
 docs/transports/smtp.md     |   4 +-
 src/internal/config.js      |   4 +-
 src/internal/loopback.js    |  48 +++++++++++-----
 src/smtp/oauth2.js          |   8 +--
 src/smtp/smtp-connection.js | 106 +-----------------------------------
 tests/unit/internal.test.js |  47 ++++++++++++++++
 8 files changed, 99 insertions(+), 127 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index af8d2c0..93a60d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -189,6 +189,10 @@ fixed ones below.
   token, to `evil.example`; the Mailgun `domain`, the Mailtrap `inboxId` and the JMAP account ID
   of a blob upload went into the path unencoded. A region must look like one (`us-east-1`), and
   the others are encoded as a single path segment.
+- **One rule tells a loopback host** (an upstream bug): the OAuth 2.0 token endpoint of `./smtp`
+  could use plain `http:` only to `localhost`, `127.0.0.1` and `::1`, while SMTP AUTH without TLS
+  allowed any loopback host. Both, and the HTTP providers, now take `localhost`, a name under
+  `.localhost`, 127.0.0.0/8 and `::1`, also as an IPv4-mapped address.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index fc8a243..f47de02 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -295,6 +295,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 53. otel: the `error.message` attribute of a thrown error was recorded raw when the message
     began like a transport failure (`Connection…`), whatever addresses followed. It goes
     through `describeError`, the redaction of the span status and events.
+54. smtp: the OAuth 2.0 token endpoint allowed `http:` only to `localhost`, `127.0.0.1` and
+    `::1`, while SMTP AUTH without TLS took any loopback host. `internal/loopback.js` holds
+    the one rule (`localhost`, `*.localhost`, 127.0.0.0/8 and `::1`, also IPv4-mapped, on
+    `net.BlockList`) for SMTP, OAuth 2.0 and the HTTP providers, in place of SMTP's own IPv4
+    and IPv6 parsers.
 
 ## Repository layout
 
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index 88399f7..bd31ae3 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -497,7 +497,9 @@ if you don't specify one.
 > SMTP authentication requires a secure connection (`secure: true`, or a
 > successful STARTTLS upgrade on port 587).  To protect passwords and access
 > tokens, authentication over a cleartext connection to a non-loopback host is
-> refused.  Loopback hosts remain available for local development.
+> refused.  Loopback hosts remain available for local development: `localhost`,
+> a name under `.localhost`, 127.0.0.0/8 and `::1` (also IPv4-mapped), the same
+> hosts to which an OAuth 2.0 token endpoint may use plain `http:`.
 
 ### OAuth 2.0 authentication
 
diff --git a/src/internal/config.js b/src/internal/config.js
index ebfad7a..74ce06b 100644
--- a/src/internal/config.js
+++ b/src/internal/config.js
@@ -1,7 +1,7 @@
 // Not ported from upyo: the checks of the options that every HTTP provider
 // shares, made once, when its configuration is made.
 
-const { isLoopbackHostname } = require('./loopback.js');
+const { isLoopbackHost } = require('./loopback.js');
 
 /**
  * Checks the timeout and the retries of a provider's configuration.
@@ -40,7 +40,7 @@ const checkSecureUrl = (value, name) => {
     throw new TypeError(`\`${name}\` must be a URL: ${String(value)}`);
   }
   if (url.protocol === 'https:') return;
-  if (url.protocol === 'http:' && isLoopbackHostname(url.hostname)) return;
+  if (url.protocol === 'http:' && isLoopbackHost(url.hostname)) return;
   throw new TypeError(
     `\`${name}\` must use HTTPS, or plain HTTP only to a loopback host, ` +
       `so that credentials are not sent in clear: ${value}`,
diff --git a/src/internal/loopback.js b/src/internal/loopback.js
index 5971660..01624bd 100644
--- a/src/internal/loopback.js
+++ b/src/internal/loopback.js
@@ -1,23 +1,45 @@
-// Not ported from upyo: whether a host name of a URL is this machine, the one
-// place where credentials may go over plain HTTP, to a local fake server.
+// Not ported from upyo: whether a host is this machine, the one place where
+// credentials may go over plain text: SMTP AUTH without TLS, an OAuth 2.0 token
+// endpoint or an HTTP provider over http:, to a local fake server.  One rule
+// for all three, which upstream wrote three times, differently.
 
 const net = require('node:net');
 
+// 127.0.0.0/8 and ::1; BlockList also matches their IPv4-mapped IPv6 forms.
+const LOOPBACK = new net.BlockList();
+LOOPBACK.addSubnet('127.0.0.0', 8, 'ipv4');
+LOOPBACK.addAddress('::1', 'ipv6');
+
+/**
+ * Whether an IP address is a loopback address: one of 127.0.0.0/8 or `::1`,
+ * also IPv4-mapped (`::ffff:127.0.0.1`), bracketed or with a zone.
+ *
+ * @param address An IPv4 or IPv6 address, such as `socket.remoteAddress`.
+ * @returns `true` for a loopback address, `false` for any other text.
+ * @internal
+ */
+const isLoopbackAddress = (address) => {
+  let name = address;
+  if (name.startsWith('[') && name.endsWith(']')) name = name.slice(1, -1);
+  const zone = name.indexOf('%');
+  if (zone !== -1) name = name.slice(0, zone);
+  const family = net.isIP(name);
+  if (family === 0) return false;
+  return LOOPBACK.check(name, family === 4 ? 'ipv4' : 'ipv6');
+};
+
 /**
- * Whether the host name of a parsed URL is a loopback host: `localhost`, a
- * name under `.localhost`, an address of 127.0.0.0/8, or `::1` (also as an
- * IPv4-mapped 127 address).  `URL` has already put the name in its canonical
- * form, so `127.1` reads `127.0.0.1` and an IPv6 address is bracketed.
+ * Whether a host is a loopback host: `localhost`, a name under `.localhost`,
+ * or a loopback address.  It takes a configured host as well as the
+ * `hostname` of a `URL`, whose IPv6 address is bracketed.
  *
- * @param hostname The `hostname` of a `URL`.
+ * @param host The host name or address.
  * @returns `true` for a loopback host.
  * @internal
  */
-const isLoopbackHostname = (hostname) => {
-  const name = hostname.toLowerCase().replace(/\.$/, '');
-  if (name === 'localhost' || name.endsWith('.localhost')) return true;
-  if (net.isIPv4(name)) return name.startsWith('127.');
-  return name === '[::1]' || name.startsWith('[::ffff:7f');
+const isLoopbackHost = (host) => {
+  const name = host.toLowerCase().replace(/\.$/, '');
+  return name === 'localhost' || name.endsWith('.localhost') || isLoopbackAddress(name);
 };
 
-module.exports = { isLoopbackHostname };
+module.exports = { isLoopbackAddress, isLoopbackHost };
diff --git a/src/smtp/oauth2.js b/src/smtp/oauth2.js
index 127da26..bf13b46 100644
--- a/src/smtp/oauth2.js
+++ b/src/smtp/oauth2.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/smtp/src/oauth2.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { isLoopbackHost } = require('../internal/loopback.js');
 const { readText } = require('../internal/body.js');
 
 /**
@@ -121,12 +122,7 @@ const assertSecureTokenEndpoint = (endpoint) => {
     throw new TypeError(`Invalid OAuth 2.0 token endpoint URL: ${endpoint}`);
   }
   if (url.protocol === 'https:') return;
-  const isLoopback =
-    url.hostname === 'localhost' ||
-    url.hostname === '127.0.0.1' ||
-    url.hostname === '[::1]' ||
-    url.hostname === '::1';
-  if (url.protocol === 'http:' && isLoopback) return;
+  if (url.protocol === 'http:' && isLoopbackHost(url.hostname)) return;
   throw new TypeError(
     'OAuth 2.0 token endpoint must use HTTPS to protect client credentials: ' + endpoint,
   );
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index 5341cb2..eff2198 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -9,6 +9,7 @@ const { connect: tlsConnect, TLSSocket } = require('node:tls');
 const { createSmtpConfig } = require('./config.js');
 const { SmtpDsnUnsupportedError } = require('./delivery-status.js');
 const { checkSmtpPath } = require('./envelope.js');
+const { isLoopbackAddress, isLoopbackHost } = require('../internal/loopback.js');
 const {
   formatOauthbearer,
   formatXoauth2,
@@ -230,111 +231,6 @@ const parseSizeCapability = (capability) => {
  */
 const QUIT_TIMEOUT_MS = 5000;
 
-/**
- * Parse an IPv4 address into its four octets.
- *
- * @param address The IPv4 address to parse.
- * @returns The parsed octets, or `null` if the address is invalid.
- */
-const parseIpv4Address = (address) => {
-  const octets = address.split('.');
-  if (
-    octets.length !== 4 ||
-    !octets.every((octet) => /^(?:0|[1-9]\d{0,2})$/.test(octet) && Number(octet) <= 255)
-  ) {
-    return null;
-  }
-
-  return octets.map(Number);
-};
-
-/**
- * Parse an IPv6 address into its eight 16-bit groups.
- *
- * @param address The IPv6 address to parse.
- * @returns The parsed groups, or `null` if the address is invalid.
- */
-const parseIpv6Address = (address) => {
-  const compressionParts = address.split('::');
-  if (compressionParts.length > 2) return null;
-
-  const parseGroups = (part) => {
-    if (part === '') return [];
-
-    const tokens = part.split(':');
-    const groups = [];
-    for (const [index, token] of tokens.entries()) {
-      if (token.includes('.')) {
-        if (index !== tokens.length - 1) return null;
-        const octets = parseIpv4Address(token);
-        if (octets == null) return null;
-        groups.push((octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]);
-      } else if (/^[0-9a-f]{1,4}$/.test(token)) {
-        groups.push(Number.parseInt(token, 16));
-      } else {
-        return null;
-      }
-    }
-    return groups;
-  };
-
-  const left = parseGroups(compressionParts[0]);
-  const right = parseGroups(compressionParts[1] ?? '');
-  if (left == null || right == null) return null;
-
-  if (compressionParts.length === 1) {
-    return left.length === 8 ? left : null;
-  }
-
-  const omittedGroups = 8 - left.length - right.length;
-  if (omittedGroups < 1) return null;
-  return [...left, ...Array.from({ length: omittedGroups }, () => 0), ...right];
-};
-
-/**
- * Whether an IP address refers to the local loopback interface.
- *
- * @param address The IPv4 or IPv6 address to check.
- * @returns `true` if the address is a loopback address.
- */
-const isLoopbackAddress = (address) => {
-  let normalized = address.toLowerCase();
-  if (normalized.startsWith('[') && normalized.endsWith(']')) {
-    normalized = normalized.slice(1, -1);
-  }
-  const zoneIndex = normalized.indexOf('%');
-  if (zoneIndex >= 0) normalized = normalized.slice(0, zoneIndex);
-
-  const ipv4Octets = parseIpv4Address(normalized);
-  if (ipv4Octets != null) return ipv4Octets[0] === 127;
-
-  const ipv6Groups = parseIpv6Address(normalized);
-  if (ipv6Groups == null) return false;
-  return (
-    (ipv6Groups.slice(0, 7).every((group) => group === 0) && ipv6Groups[7] === 1) ||
-    (ipv6Groups.slice(0, 5).every((group) => group === 0) &&
-      ipv6Groups[5] === 0xffff &&
-      ipv6Groups[6] >> 8 === 127)
-  );
-};
-
-/**
- * Whether a configured host name or address represents a loopback endpoint.
- *
- * This is a fallback for sockets that do not expose their connected peer
- * address.  A connected peer address takes precedence so a misleading host
- * name cannot bypass the TLS requirement.
- *
- * @param host The configured SMTP host.
- * @returns `true` if the host represents a loopback endpoint.
- */
-const isLoopbackHost = (host) => {
-  const normalized = host.toLowerCase().replace(/\.$/, '');
-  return (
-    normalized === 'localhost' || normalized.endsWith('.localhost') || isLoopbackAddress(normalized)
-  );
-};
-
 /**
  * Whether the SMTP connection is local enough to permit cleartext
  * authentication during development.
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index bdd9cfd..3e045bc 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -321,3 +321,50 @@ test('Internal: onRetry hears each retry, with its attempt, wait and error, befo
   ]);
   assert.deepStrictEqual(delays, [1, 1500]);
 });
+
+test('Internal: one loopback rule serves SMTP, OAuth 2.0 and the HTTP providers', () => {
+  const { isLoopbackAddress, isLoopbackHost } = require('../../src/internal/loopback.js');
+  const { OAuth2TokenManager } = require('../../src/smtp/oauth2.js');
+  const loopback = [
+    'localhost',
+    'LOCALHOST.',
+    'mail.localhost',
+    '127.0.0.1',
+    '127.12.0.3',
+    '::1',
+    '[::1]',
+    '::ffff:127.0.0.1',
+    '0:0:0:0:0:0:0:1',
+    '::1%lo0',
+  ];
+  for (const host of loopback) assert.strictEqual(isLoopbackHost(host), true, host);
+  for (const host of [
+    'example.com',
+    'localhost.example.com',
+    '10.0.0.1',
+    '::2',
+    '::ffff:10.0.0.1',
+    '127.1',
+  ]) {
+    assert.strictEqual(isLoopbackHost(host), false, host);
+  }
+  assert.strictEqual(isLoopbackAddress('localhost'), false);
+
+  // The token endpoint of OAuth 2.0 used to allow only four spellings.
+  const refresh = (tokenEndpoint) => ({
+    type: 'oauth2',
+    user: 'u',
+    clientId: 'id',
+    clientSecret: 'secret',
+    refreshToken: 'refresh',
+    tokenEndpoint,
+  });
+  for (const endpoint of [
+    'http://127.0.0.2/token',
+    'http://auth.localhost/token',
+    'http://[::ffff:7f00:1]/',
+  ]) {
+    assert.doesNotThrow(() => new OAuth2TokenManager(refresh(endpoint)), endpoint);
+  }
+  assert.throws(() => new OAuth2TokenManager(refresh('http://auth.example.com/token')), TypeError);
+});

From 2c5495fa5aa98d54251184c61646f8509339bef8 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:11:02 +0300
Subject: [PATCH 095/158] fix(smtp): send the host name for SNI over TLS and
 STARTTLS

Neither tls.connect call passed servername, and Node sends no SNI without
it, so a server that chooses its certificate by name answered with its
default one; verification then failed, which pushes users towards
rejectUnauthorized: false. Both now send the configured host, without a
final dot, and nothing for an IP address, which SNI cannot carry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  4 +++
 CLAUDE.md                   |  4 +++
 docs/transports/smtp.md     |  3 ++
 src/smtp/smtp-connection.js | 10 +++++-
 tests/unit/smtp.test.js     | 69 +++++++++++++++++++++++++++++++++++++
 5 files changed, 89 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 93a60d1..42df6d7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -193,6 +193,10 @@ fixed ones below.
   could use plain `http:` only to `localhost`, `127.0.0.1` and `::1`, while SMTP AUTH without TLS
   allowed any loopback host. Both, and the HTTP providers, now take `localhost`, a name under
   `.localhost`, 127.0.0.0/8 and `::1`, also as an IPv4-mapped address.
+- **`./smtp` sends the host name for SNI** (an upstream bug): neither implicit TLS nor STARTTLS
+  passed `servername`, and Node sends no SNI without it, so a server that picks its certificate
+  by name answered with its default one, which then failed verification. Both send the host,
+  and nothing for an IP address.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index f47de02..f62177d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -300,6 +300,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     the one rule (`localhost`, `*.localhost`, 127.0.0.0/8 and `::1`, also IPv4-mapped, on
     `net.BlockList`) for SMTP, OAuth 2.0 and the HTTP providers, in place of SMTP's own IPv4
     and IPv6 parsers.
+55. smtp: implicit TLS and STARTTLS sent no SNI, as Node sends none without `servername`, so
+    a server with a certificate per name answered with its default one, and a user was pushed
+    towards `rejectUnauthorized: false`. Both send the host (without a final dot, and nothing
+    for an IP address).
 
 ## Repository layout
 
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index bd31ae3..575948b 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -606,6 +606,9 @@ Setting `secure: true` establishes a TLS connection from the start,
 while `rejectUnauthorized: true` ensures certificate validation.
 You can specify custom certificate authorities, client certificates,
 and acceptable TLS versions based on your security requirements.
+Both implicit TLS and STARTTLS send the host name for SNI, so a server with a
+certificate per name answers with the one for `host`; a host given as an IP
+address sends none, as SNI carries only names.
 
 ### STARTTLS support
 
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index eff2198..6901549 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -3,7 +3,7 @@
 
 const { prepareRawSmtpStream, Smtp8BitMimeUnsupportedError } = require('./raw-message.js');
 const { Buffer } = require('node:buffer');
-const { Socket } = require('node:net');
+const { isIP, Socket } = require('node:net');
 const { StringDecoder } = require('node:string_decoder');
 const { connect: tlsConnect, TLSSocket } = require('node:tls');
 const { createSmtpConfig } = require('./config.js');
@@ -231,6 +231,12 @@ const parseSizeCapability = (capability) => {
  */
 const QUIT_TIMEOUT_MS = 5000;
 
+// The name a TLS client sends for SNI (RFC 6066 §3): the host without a final
+// dot, and none for an IP address, which SNI does not carry.  Node sends none
+// unless it is given, so a server with a certificate per name could only
+// answer with its default one.
+const serverNameOf = (host) => (isIP(host) === 0 ? host.replace(/\.$/, '') : undefined);
+
 /**
  * Whether the SMTP connection is local enough to permit cleartext
  * authentication during development.
@@ -319,6 +325,7 @@ class SmtpConnection {
         if (this.config.secure) {
           this.socket = tlsConnect({
             host: this.config.host,
+            servername: serverNameOf(this.config.host),
             port: this.config.port,
             rejectUnauthorized: this.config.tls?.rejectUnauthorized ?? true,
             ca: this.config.tls?.ca,
@@ -648,6 +655,7 @@ class SmtpConnection {
     const tlsSocket = tlsConnect({
       socket: plainSocket,
       host: this.config.host,
+      servername: serverNameOf(this.config.host),
       rejectUnauthorized: this.config.tls?.rejectUnauthorized ?? true,
       ca: this.config.tls?.ca,
       key: this.config.tls?.key,
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 9159aa1..02ede09 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -457,3 +457,72 @@ test('SMTP: capabilities are looked up by keyword, rebuilt when replaced', () =>
   assert.strictEqual(connection.hasCapability('PIPELINING'), false);
   assert.strictEqual(connection.hasCapability('STARTTLS'), true);
 });
+
+test('SMTP: implicit TLS and STARTTLS send the host name for SNI, and no IP address', async () => {
+  const { readFileSync } = require('node:fs');
+  const path = require('node:path');
+  const tls = require('node:tls');
+  const credentials = {
+    key: readFileSync(path.join(__dirname, '../fixtures/smtp/server-key.pem')),
+    cert: readFileSync(path.join(__dirname, '../fixtures/smtp/server-cert.pem')),
+  };
+  const names = [];
+  // Answers EHLO and QUIT over a socket that is already secure or upgrades.
+  const serve = (socket, secure) => {
+    socket.on('error', () => {});
+    if (!secure) socket.write('220 ready\r\n');
+    let buffer = '';
+    const onData = (chunk) => {
+      buffer += chunk.toString('latin1');
+      let end;
+      while ((end = buffer.indexOf('\r\n')) >= 0) {
+        const line = buffer.slice(0, end);
+        buffer = buffer.slice(end + 2);
+        if (line.startsWith('EHLO')) {
+          socket.write(secure ? '250 ready\r\n' : '250-ready\r\n250 STARTTLS\r\n');
+        } else if (line === 'STARTTLS') {
+          socket.off('data', onData);
+          socket.write('220 go ahead\r\n');
+          const upgraded = new tls.TLSSocket(socket, {
+            isServer: true,
+            secureContext: tls.createSecureContext(credentials),
+          });
+          upgraded.on('secure', () => names.push(upgraded.servername));
+          serve(upgraded, true);
+          return;
+        } else if (line === 'QUIT') {
+          socket.end('221 bye\r\n');
+        }
+      }
+    };
+    socket.on('data', onData);
+  };
+  const implicit = tls.createServer(credentials, (socket) => {
+    names.push(socket.servername);
+    socket.write('220 ready\r\n');
+    serve(socket, true);
+  });
+  const starttls = createServer((socket) => serve(socket, false));
+  for (const server of [implicit, starttls]) {
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  }
+  try {
+    for (const host of ['localhost', 'localhost.', '127.0.0.1']) {
+      for (const server of [implicit, starttls]) {
+        const transport = new SmtpTransport({
+          host,
+          port: server.address().port,
+          secure: server === implicit,
+          tls: { rejectUnauthorized: false },
+        });
+        await transport.verify();
+        await transport.closeAllConnections();
+      }
+    }
+  } finally {
+    for (const server of [implicit, starttls]) {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  }
+  assert.deepStrictEqual(names, ['localhost', 'localhost', 'localhost', 'localhost', false, false]);
+});

From 5939dba93126ab4c4248907dcc600d10a04ade4b Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:11:50 +0300
Subject: [PATCH 096/158] fix(smtp): connect implicit TLS once its handshake
 completes

connect() resolved on the TCP connect event for secure: true as well, so
the connection timeout stopped before the TLS handshake had begun, and a
server that never answered it held the send until the socket timeout of
the greeting, with an error about the greeting. It now resolves on
secureConnect, and a stalled or failed handshake fails the connection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  4 ++++
 CLAUDE.md                   |  3 +++
 src/smtp/smtp-connection.js |  8 +++++--
 tests/unit/smtp.test.js     | 44 +++++++++++++++++++++++++++++++++++++
 4 files changed, 57 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 42df6d7..93a490d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -197,6 +197,10 @@ fixed ones below.
   passed `servername`, and Node sends no SNI without it, so a server that picks its certificate
   by name answered with its default one, which then failed verification. Both send the host,
   and nothing for an IP address.
+- **`./smtp` waits for the TLS handshake of `secure: true`** (an upstream bug): the connection
+  counted as made when TCP connected, so `connectionTimeout` did not cover the handshake, and a
+  server that never completed it held the send until the socket timeout. It is made once the
+  handshake completes.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index f62177d..e678237 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -304,6 +304,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     a server with a certificate per name answered with its default one, and a user was pushed
     towards `rejectUnauthorized: false`. Both send the host (without a final dot, and nothing
     for an IP address).
+56. smtp: implicit TLS resolved `connect()` on the TCP `connect`, before its handshake, so the
+    connection timeout did not cover the handshake and a failed one surfaced later, while the
+    greeting was read. It resolves on `secureConnect`.
 
 ## Repository layout
 
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index 6901549..bafc90d 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -283,6 +283,10 @@ class SmtpConnection {
 
     signal?.throwIfAborted();
 
+    // Implicit TLS is established once its handshake completes, not when the
+    // TCP connection opens, so the connection timeout covers the handshake.
+    const establishedEvent = this.config.secure ? 'secureConnect' : 'connect';
+
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
         onError(new TypeError('Connection timeout.'));
@@ -291,7 +295,7 @@ class SmtpConnection {
 
       const cleanup = () => {
         clearTimeout(timeout);
-        this.socket?.off('connect', onConnect);
+        this.socket?.off(establishedEvent, onConnect);
         this.socket?.off('error', onError);
         this.socket?.off('close', onClose);
         this.socket?.off('timeout', onTimeout);
@@ -341,7 +345,7 @@ class SmtpConnection {
 
         this.socket.setTimeout(this.config.socketTimeout);
         this.observeSocket(this.socket);
-        this.socket.once('connect', onConnect);
+        this.socket.once(establishedEvent, onConnect);
         this.socket.once('error', onError);
         this.socket.once('close', onClose);
         this.socket.once('timeout', onTimeout);
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 02ede09..29471a4 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -526,3 +526,47 @@ test('SMTP: implicit TLS and STARTTLS send the host name for SNI, and no IP addr
   }
   assert.deepStrictEqual(names, ['localhost', 'localhost', 'localhost', 'localhost', false, false]);
 });
+
+test('SMTP: implicit TLS is connected once its handshake completes, within the timeout', async () => {
+  // A server that accepts the connection and never answers the handshake.
+  const sockets = new Set();
+  const server = createServer((socket) => {
+    sockets.add(socket);
+    socket.on('error', () => {});
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const connection = new SmtpConnection({
+    host: '127.0.0.1',
+    port: server.address().port,
+    secure: true,
+    connectionTimeout: 100,
+    socketTimeout: 5000,
+  });
+  try {
+    await assert.rejects(connection.connect(), { message: 'Connection timeout.' });
+  } finally {
+    connection.socket?.destroy();
+    for (const socket of sockets) socket.destroy();
+    await new Promise((resolve) => server.close(resolve));
+  }
+});
+
+test('SMTP: an abort while waiting for the greeting rejects with its reason', async () => {
+  const { server, port } = await scripted(
+    () => {},
+    () => {},
+  );
+  const connection = new SmtpConnection({ host: '127.0.0.1', port, socketTimeout: 5000 });
+  const controller = new AbortController();
+  const reason = new Error('Stop.');
+  try {
+    await connection.connect();
+    const greeting = connection.greeting(controller.signal);
+    controller.abort(reason);
+    await assert.rejects(greeting, (error) => error === reason);
+    assert.strictEqual(connection.socket.destroyed, true);
+  } finally {
+    connection.socket?.destroy();
+    await stop(server);
+  }
+});

From 2ee2c07d9ffb10d0579e34b2b7a1c48b4e850104 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:16:27 +0300
Subject: [PATCH 097/158] refactor(smtp): send a batch in one loop for both
 kinds of input

sendMany carried two copies of its loop, one with for await for an async
iterable and one with for for a synchronous one, identical but for the
keyword. for await takes a synchronous iterable too, so one loop remains.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/smtp/smtp-transport.js | 88 +++++++++++---------------------------
 1 file changed, 25 insertions(+), 63 deletions(-)

diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index 7dba11e..a78577e 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -368,77 +368,39 @@ class SmtpTransport {
     };
 
     try {
-      const isAsyncIterable = Symbol.asyncIterator in messages;
+      // for await takes a synchronous iterable as well.
+      let index = 0;
+      for await (const message of messages) {
+        options?.signal?.throwIfAborted();
+
+        if (!connectionValid) {
+          yield createSmtpFailure('Connection is no longer valid');
+          continue;
+        }
 
-      if (isAsyncIterable) {
-        let index = 0;
-        for await (const message of messages) {
+        try {
+          const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
+          const dsn = resolveSmtpDsn(envelope, options?.dsn);
+          const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
           options?.signal?.throwIfAborted();
 
-          if (!connectionValid) {
-            yield createSmtpFailure('Connection is no longer valid');
-            continue;
-          }
+          const result = await connection.sendMessage(smtpMessage, options?.signal);
 
-          try {
-            const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
-            const dsn = resolveSmtpDsn(envelope, options?.dsn);
-            const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
-            options?.signal?.throwIfAborted();
-
-            const result = await connection.sendMessage(smtpMessage, options?.signal);
-
-            yield {
-              successful: true,
-              messageId: result.messageId,
-              provider: 'smtp',
-              rejectedRecipients: result.rejectedRecipients,
-            };
-          } catch (error) {
-            // Cancellation rejects rather than producing a receipt.
-            options?.signal?.throwIfAborted();
-
-            if (!connection.usable || !isReusableLocalFailure(error)) {
-              connectionValid = false;
-            }
-
-            yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
-          }
-        }
-      } else {
-        let index = 0;
-        for (const message of messages) {
+          yield {
+            successful: true,
+            messageId: result.messageId,
+            provider: 'smtp',
+            rejectedRecipients: result.rejectedRecipients,
+          };
+        } catch (error) {
+          // Cancellation rejects rather than producing a receipt.
           options?.signal?.throwIfAborted();
 
-          if (!connectionValid) {
-            yield createSmtpFailure('Connection is no longer valid');
-            continue;
+          if (!connection.usable || !isReusableLocalFailure(error)) {
+            connectionValid = false;
           }
 
-          try {
-            const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
-            const dsn = resolveSmtpDsn(envelope, options?.dsn);
-            const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
-            options?.signal?.throwIfAborted();
-
-            const result = await connection.sendMessage(smtpMessage, options?.signal);
-
-            yield {
-              successful: true,
-              messageId: result.messageId,
-              provider: 'smtp',
-              rejectedRecipients: result.rejectedRecipients,
-            };
-          } catch (error) {
-            // Cancellation rejects rather than producing a receipt.
-            options?.signal?.throwIfAborted();
-
-            if (!connection.usable || !isReusableLocalFailure(error)) {
-              connectionValid = false;
-            }
-
-            yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
-          }
+          yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
         }
       }
     } catch (error) {

From 45e2b8870d35fa7bcd05bb498997ce3293ac2562 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:17:54 +0300
Subject: [PATCH 098/158] fix(smtp): compose a message before taking a
 connection

send and sendMany connected, upgraded and authenticated before composing
the message, so a message that could not be composed cost a connection,
and its error, not one of the reusable local failures, discarded it; a
batch then failed every later message as "Connection is no longer valid".
The message is now composed first and a failure to compose touches no
connection. sendMany takes its connection for the first message that
composes, so an empty batch, or one of broken messages, opens none, and a
failed setup still fails each message that follows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  5 +++
 CLAUDE.md                  |  5 +++
 src/smtp/smtp-transport.js | 82 ++++++++++++++++++++------------------
 tests/unit/smtp.test.js    | 37 +++++++++++++++++
 4 files changed, 91 insertions(+), 38 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 93a490d..33b583f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -201,6 +201,11 @@ fixed ones below.
   counted as made when TCP connected, so `connectionTimeout` did not cover the handshake, and a
   server that never completed it held the send until the socket timeout. It is made once the
   handshake completes.
+- **A message that cannot be composed no longer costs `./smtp` its connection** (an upstream bug):
+  the message was composed after connecting and authenticating, and an error in it discarded
+  the connection, failing every later message of a `sendMany` with "Connection is no longer
+  valid". It is now composed first and fails alone; `sendMany` connects for its first composed
+  message, and an empty batch opens no connection.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index e678237..8da6aa3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -307,6 +307,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 56. smtp: implicit TLS resolved `connect()` on the TCP `connect`, before its handshake, so the
     connection timeout did not cover the handshake and a failed one surfaced later, while the
     greeting was read. It resolves on `secureConnect`.
+57. smtp: `send` and `sendMany` composed a message only after connecting, upgrading and
+    authenticating, and a composition error, not a reusable local failure, discarded the
+    connection; in `sendMany` every later message then failed with "Connection is no longer
+    valid". A message is composed first, a failure to compose takes and fails no connection,
+    and `sendMany` connects for its first composed message (none for an empty batch).
 
 ## Repository layout
 
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index a78577e..0b35398 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -216,6 +216,9 @@ class SmtpTransport {
     try {
       const envelope = resolveEnvelopeOption(message, options?.envelope, 0);
       const dsn = resolveSmtpDsn(envelope, options?.dsn);
+      // Composed before a connection is taken: a message that cannot be
+      // composed costs no connection, and fails no connection either.
+      const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
 
       // Establishing the connection—including authentication, e.g. acquiring an
       // OAuth 2.0 access token—is part of delivery, so setup failures are
@@ -226,10 +229,6 @@ class SmtpTransport {
 
       options?.signal?.throwIfAborted();
 
-      const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
-
-      options?.signal?.throwIfAborted();
-
       const result = await connection.sendMessage(smtpMessage, options?.signal);
 
       await this.returnConnection(connection);
@@ -335,37 +334,12 @@ class SmtpTransport {
   async *sendMany(messages, options) {
     options?.signal?.throwIfAborted();
 
+    // The connection is taken for the first message that is composed, so a
+    // batch of nothing, or of messages that cannot be composed, takes none.
     let connection;
-    try {
-      connection = await this.getConnection(options?.signal);
-    } catch (error) {
-      // Cancellation rejects rather than producing receipts.
-      options?.signal?.throwIfAborted();
-
-      // Connection setup (including authentication) failed, so no message can
-      // be delivered.  Report a failed receipt for each message rather than
-      // throwing.
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      // oxlint-disable-next-line no-unused-vars -- upstream
-      for await (const _ of messages) {
-        options?.signal?.throwIfAborted();
-        yield createSmtpFailure(errorMessage, error);
-      }
-      return;
-    }
-
+    // A setup that failed, including authentication, fails every message.
+    let setupError;
     let connectionValid = true;
-    let connectionReleased = false;
-
-    const releaseConnection = async () => {
-      if (connectionReleased) return;
-      connectionReleased = true;
-      if (connectionValid) {
-        await this.returnConnection(connection);
-      } else {
-        await this.discardConnection(connection);
-      }
-    };
 
     try {
       // for await takes a synchronous iterable as well.
@@ -373,17 +347,43 @@ class SmtpTransport {
       for await (const message of messages) {
         options?.signal?.throwIfAborted();
 
+        let smtpMessage;
+        try {
+          const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
+          const dsn = resolveSmtpDsn(envelope, options?.dsn);
+          smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
+        } catch (error) {
+          // A message that cannot be composed never reaches the connection.
+          yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+          continue;
+        }
+
+        if (setupError !== undefined) {
+          const errorMessage =
+            setupError instanceof Error ? setupError.message : String(setupError);
+          yield createSmtpFailure(errorMessage, setupError);
+          continue;
+        }
+
         if (!connectionValid) {
           yield createSmtpFailure('Connection is no longer valid');
           continue;
         }
 
+        if (connection == null) {
+          try {
+            connection = await this.getConnection(options?.signal);
+          } catch (error) {
+            // Cancellation rejects rather than producing receipts.
+            options?.signal?.throwIfAborted();
+            setupError = error;
+            yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+            continue;
+          }
+        }
+
         try {
-          const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
-          const dsn = resolveSmtpDsn(envelope, options?.dsn);
-          const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
           options?.signal?.throwIfAborted();
-
           const result = await connection.sendMessage(smtpMessage, options?.signal);
 
           yield {
@@ -411,7 +411,13 @@ class SmtpTransport {
       // Runs on normal completion, on error, and when the consumer abandons
       // the iteration early with `break` or `return`.  Without it an abandoned
       // iteration would hold its connection slot forever.
-      await releaseConnection();
+      if (connection != null) {
+        if (connectionValid) {
+          await this.returnConnection(connection);
+        } else {
+          await this.discardConnection(connection);
+        }
+      }
     }
   }
 
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 29471a4..0fd35ac 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -570,3 +570,40 @@ test('SMTP: an abort while waiting for the greeting rejects with its reason', as
     await stop(server);
   }
 });
+
+test('SMTP: a message that cannot be composed takes no connection and fails no other', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  // A content type with a line break fails composition, past createMessage.
+  const broken = {
+    ...message(),
+    attachments: [
+      {
+        inline: false,
+        filename: 'a.txt',
+        contentType: 'text/plain\r\nX-Injected: yes',
+        content: new Uint8Array([0x61]),
+        contentId: '',
+      },
+    ],
+  };
+  try {
+    const transport = new SmtpTransport({ host: 'localhost', port, poolSize: 1 });
+    assert.strictEqual((await transport.send(broken)).successful, false);
+    const empty = [];
+    for await (const receipt of transport.sendMany([])) empty.push(receipt);
+    assert.deepStrictEqual(empty, []);
+    assert.strictEqual(server.getConnectionCount(), 0);
+
+    const outcomes = [];
+    for await (const receipt of transport.sendMany([broken, message(), broken, message()])) {
+      outcomes.push(receipt.successful);
+    }
+    assert.deepStrictEqual(outcomes, [false, true, false, true]);
+    assert.strictEqual(server.getReceivedMessages().length, 2);
+    assert.strictEqual(server.getConnectionCount(), 1);
+    await transport.closeAllConnections();
+  } finally {
+    await server.stop();
+  }
+});

From dd57efe79383ef2026367302535ea5ab04b664a8 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:25:15 +0300
Subject: [PATCH 099/158] fix(smtp): reset a pooled connection when it is next
 taken

returnConnection sent RSET and waited for its reply before send returned
its receipt, a round trip added to every send that no signal could cut
short, and a connection the server closed while it sat idle still looked
usable and failed the next send at MAIL FROM. The connection now goes back
to the pool marked as needing a reset, and takePooledConnection resets it
under the signal of the call that takes it; one that fails its reset is
closed, and the call takes another or opens a new one. The ported pool
tests say where they changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  5 ++
 CLAUDE.md                                     |  5 ++
 docs/transports/smtp.md                       |  6 ++
 src/smtp/smtp-connection.js                   |  2 +
 src/smtp/smtp-transport.js                    | 58 +++++++++++++------
 .../smtp-transport.pool.integration.test.js   |  7 ++-
 tests/unit/smtp.test.js                       | 51 ++++++++++++++++
 7 files changed, 114 insertions(+), 20 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33b583f..66f54ca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -206,6 +206,11 @@ fixed ones below.
   the connection, failing every later message of a `sendMany` with "Connection is no longer
   valid". It is now composed first and fails alone; `sendMany` connects for its first composed
   message, and an empty batch opens no connection.
+- **`./smtp` resets a pooled connection when it is next used** (an upstream bug): RSET ran before
+  `send` returned its receipt, a round trip added to every send that ignored the caller's
+  signal, and a connection the server had closed while idle failed the next send. The reset
+  now runs when the connection is taken again, under that call's signal, and a connection that
+  fails it is closed and replaced by another.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 8da6aa3..e0f87c4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -312,6 +312,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     connection; in `sendMany` every later message then failed with "Connection is no longer
     valid". A message is composed first, a failure to compose takes and fails no connection,
     and `sendMany` connects for its first composed message (none for an empty batch).
+58. smtp: a pooled connection was reset (RSET) before `send` returned its receipt, adding a
+    round trip to every send, without the caller's signal, and a connection the server dropped
+    while idle then failed the next send. RSET runs when the connection is next taken
+    (`takePooledConnection`), under that caller's signal; one that fails it is closed and
+    replaced.
 
 ## Repository layout
 
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index 575948b..e8cec1a 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -155,6 +155,12 @@ simultaneous-connection limit your provider enforces.  A waiting call still
 honours its `AbortSignal`, so cancelling it rejects without sending the message.
 Setting `SmtpConfig.poolSize` to `Infinity` opts out of the limit entirely.
 
+A connection handed back to the pool is reset (`RSET`) when it is next taken,
+under the signal of the call that takes it, rather than before the previous
+send returns its receipt. The reset also tells whether the server kept the
+connection while it sat idle: one that fails its reset is closed, and the call
+takes another connection or opens a new one.
+
 > [!NOTE]
 > Because a `SmtpTransport.sendMany()` call holds its connection until the
 > iteration ends, running more concurrent `SmtpTransport.sendMany()` calls than
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index bafc90d..bb01c66 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -259,6 +259,8 @@ class SmtpConnection {
   capabilities = [];
   tokenManager;
   active = false;
+  /** Whether the connection sits in a pool and must be reset before reuse. */
+  needsReset = false;
 
   get usable() {
     return this.socket != null && !this.socket.destroyed && this.socket.writable;
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index 0b35398..1903ba9 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -481,12 +481,9 @@ class SmtpTransport {
       }
       // Reuse an idle connection when the pool has one.  It already holds a
       // slot, so nothing else needs to be reserved.
-      let pooled = fresh ? undefined : this.connectionPool.pop();
-      while (pooled != null) {
-        if (pooled.usable) return pooled;
-        // Dropping a connection that went stale in the pool frees its slot.
-        await this.discardConnection(pooled);
-        pooled = this.connectionPool.pop();
+      if (!fresh) {
+        const pooled = await this.takePooledConnection(signal);
+        if (pooled != null) return pooled;
       }
 
       if (this.openConnectionCount < this.poolSize) {
@@ -509,6 +506,38 @@ class SmtpTransport {
     }
   }
 
+  /**
+   * Takes an idle connection from the pool, reset and ready to send, or gives
+   * `undefined` when none is left.  One that went stale while idle, or fails
+   * its reset, is closed and gives its slot back.
+   *
+   * @param signal Signal that cancels the reset.
+   * @returns A connection ready to send, or `undefined`.
+   * @throws The reason of `signal` if it aborts during a reset.
+   */
+  async takePooledConnection(signal) {
+    let pooled = this.connectionPool.pop();
+    while (pooled != null) {
+      if (pooled.usable) {
+        if (!pooled.needsReset) return pooled;
+        try {
+          await pooled.reset(signal);
+          pooled.needsReset = false;
+          return pooled;
+        } catch {
+          // Its state is unknown after a failed or aborted RSET.
+          await this.discardConnection(pooled);
+          signal?.throwIfAborted();
+        }
+      } else {
+        // Dropping a connection that went stale in the pool frees its slot.
+        await this.discardConnection(pooled);
+      }
+      pooled = this.connectionPool.pop();
+    }
+    return undefined;
+  }
+
   /** Establishes a connection using a slot already owned by this acquisition. */
   async setupReservedConnection(signal) {
     let connection;
@@ -631,19 +660,10 @@ class SmtpTransport {
       return;
     }
 
-    try {
-      await connection.reset();
-    } catch {
-      // A connection that cannot be reset is not safe to reuse.
-      await this.discardConnection(connection);
-      return;
-    }
-
-    // Shutdown may have started while RSET was awaiting its reply.
-    if (this.closing != null) {
-      await this.discardConnection(connection);
-      return;
-    }
+    // The RSET that clears its state runs when the connection is next taken
+    // (takePooledConnection), with that caller's signal: the receipt does not
+    // wait for it, and it finds a connection the server dropped while idle.
+    connection.needsReset = true;
 
     // The connection keeps its slot while it sits idle, so no separate check
     // against `poolSize` is needed here: at most `poolSize` connections can be
diff --git a/tests/unit/smtp-transport.pool.integration.test.js b/tests/unit/smtp-transport.pool.integration.test.js
index e60d8e7..4061d61 100644
--- a/tests/unit/smtp-transport.pool.integration.test.js
+++ b/tests/unit/smtp-transport.pool.integration.test.js
@@ -263,9 +263,11 @@ describe('SmtpTransport connection limit', () => {
             }
             assert.strictEqual(receipts, stopEarly ? 1 : 2);
             assert.strictEqual(server.getReceivedMessages().length, receipts);
+            // Changed after the port: a pooled connection is reset when it is
+            // next taken, not when it is returned, so the batch sends no RSET.
             assert.strictEqual(
               server.getReceivedCommands().filter((command) => command === 'RSET').length,
-              pool ? 1 : 0,
+              0,
             );
 
             await transport.closeAllConnections();
@@ -318,6 +320,9 @@ describe('SmtpTransport connection limit', () => {
     for (const pool of command === 'RSET' ? [true] : [true, false]) {
       test(`shutdown drains sends during ${command}, pool=${pool}`, async () => {
         const { server, transport } = await setupTest({ pool, poolSize: 1 });
+        // Changed after the port: RSET runs when a pooled connection is taken
+        // again, so a first send puts one in the pool for the second to reset.
+        if (command === 'RSET') assert.ok((await transport.send(createTestMessage())).successful);
         server.setResponseDelay(command === 'DATA' ? 'DATA_END' : command, 100);
         const sending = transport.send(createTestMessage());
         try {
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 0fd35ac..a469026 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -607,3 +607,54 @@ test('SMTP: a message that cannot be composed takes no connection and fails no o
     await server.stop();
   }
 });
+
+test('SMTP: a pooled connection is reset when it is next taken, not before the receipt', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  server.setResponseDelay('RSET', 300);
+  try {
+    const transport = new SmtpTransport({ host: 'localhost', port, poolSize: 1 });
+    const started = performance.now();
+    assert.strictEqual((await transport.send(message())).successful, true);
+    assert.ok(performance.now() - started < 300, 'the receipt waited for RSET');
+    assert.ok(!server.getReceivedCommands().includes('RSET'));
+
+    assert.strictEqual((await transport.send(message())).successful, true);
+    const commands = server.getReceivedCommands();
+    const reset = commands.indexOf('RSET');
+    assert.ok(reset > 0 && commands.slice(reset).some((command) => command.startsWith('MAIL')));
+    assert.strictEqual(server.getConnectionCount(), 1);
+    await transport.closeAllConnections();
+  } finally {
+    await server.stop();
+  }
+});
+
+test('SMTP: a pooled connection whose reset fails is replaced, and an abort rejects', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  try {
+    const transport = new SmtpTransport({ host: 'localhost', port, poolSize: 1 });
+    assert.strictEqual((await transport.send(message())).successful, true);
+    server.setResponse('RSET', { code: 421, message: 'Closing idle connection' });
+    assert.strictEqual((await transport.send(message())).successful, true);
+    assert.strictEqual(server.getConnectionCount(), 2);
+
+    server.setResponse('RSET', { code: 250, message: 'OK' });
+    server.setResponseDelay('RSET', 2000);
+    const controller = new AbortController();
+    const reason = new Error('Stop.');
+    const sending = transport.send(message(), { signal: controller.signal });
+    while (!server.getReceivedCommands().includes('RSET')) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    controller.abort(reason);
+    await assert.rejects(sending, (error) => error === reason);
+    server.setResponseDelay('RSET', 0);
+    assert.strictEqual((await transport.send(message())).successful, true);
+    assert.strictEqual(server.getConnectionCount(), 3);
+    await transport.closeAllConnections();
+  } finally {
+    await server.stop();
+  }
+});

From c1b2b44cd5cdbe902581f564e8e92366b35964eb Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:26:08 +0300
Subject: [PATCH 100/158] fix(smtp): let an idle pooled connection not hold the
 process

A connection kept in the pool held a referenced socket, so the event loop
stayed alive until the socket timeout and a script that sent one message
did not exit unless it closed the transport. The socket is unref'd when
the connection goes back to the pool and ref'd again when it is taken.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  3 +++
 CLAUDE.md                  |  3 +++
 docs/transports/smtp.md    |  5 ++++-
 src/smtp/smtp-transport.js |  3 +++
 tests/unit/smtp.test.js    | 30 ++++++++++++++++++++++++++++++
 5 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 66f54ca..d9fbc5d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -211,6 +211,9 @@ fixed ones below.
   signal, and a connection the server had closed while idle failed the next send. The reset
   now runs when the connection is taken again, under that call's signal, and a connection that
   fails it is closed and replaced by another.
+- **An idle `./smtp` connection no longer keeps the process alive** (an upstream bug): a pooled
+  socket held the event loop until its socket timeout, so a script that sent a message hung
+  unless it called `closeAllConnections()`. Idle sockets are now unref'd.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index e0f87c4..c60c398 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -317,6 +317,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     while idle then failed the next send. RSET runs when the connection is next taken
     (`takePooledConnection`), under that caller's signal; one that fails it is closed and
     replaced.
+59. smtp: an idle pooled socket kept the event loop alive until its socket timeout, so a
+    script that sent a message did not exit without `closeAllConnections()`. A pooled socket
+    is unref'd while idle and ref'd again when taken.
 
 ## Repository layout
 
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index e8cec1a..6ac8289 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -159,7 +159,10 @@ A connection handed back to the pool is reset (`RSET`) when it is next taken,
 under the signal of the call that takes it, rather than before the previous
 send returns its receipt. The reset also tells whether the server kept the
 connection while it sat idle: one that fails its reset is closed, and the call
-takes another connection or opens a new one.
+takes another connection or opens a new one. An idle connection does not keep
+the process alive, so a script that sends a message and returns can exit
+without `closeAllConnections()`, though closing still ends the session politely
+with QUIT.
 
 > [!NOTE]
 > Because a `SmtpTransport.sendMany()` call holds its connection until the
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index 1903ba9..b9ec355 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -519,6 +519,7 @@ class SmtpTransport {
     let pooled = this.connectionPool.pop();
     while (pooled != null) {
       if (pooled.usable) {
+        pooled.socket.ref();
         if (!pooled.needsReset) return pooled;
         try {
           await pooled.reset(signal);
@@ -664,6 +665,8 @@ class SmtpTransport {
     // (takePooledConnection), with that caller's signal: the receipt does not
     // wait for it, and it finds a connection the server dropped while idle.
     connection.needsReset = true;
+    // An idle connection does not keep the process alive.
+    connection.socket.unref();
 
     // The connection keeps its slot while it sits idle, so no separate check
     // against `poolSize` is needed here: at most `poolSize` connections can be
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index a469026..ecb9a26 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -658,3 +658,33 @@ test('SMTP: a pooled connection whose reset fails is replaced, and an abort reje
     await server.stop();
   }
 });
+
+test('SMTP: an idle pooled connection does not keep the process alive', async () => {
+  const { spawn } = require('node:child_process');
+  const path = require('node:path');
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  const script = `
+    const { SmtpTransport } = require(${JSON.stringify(path.join(__dirname, '../../src/smtp/index.js'))});
+    const { createMessage } = require(${JSON.stringify(path.join(__dirname, '../../index.js'))});
+    const transport = new SmtpTransport({ host: 'localhost', port: ${port}, socketTimeout: 30000 });
+    transport
+      .send(createMessage({ from: 'a@example.com', to: 'b@example.com', subject: 's', content: { text: 't' } }))
+      .then((receipt) => { if (!receipt.successful) process.exitCode = 2; });
+  `;
+  const child = spawn(process.execPath, ['-e', script], { stdio: 'ignore' });
+  try {
+    const exited = await new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(null), 5000);
+      child.on('exit', (code) => {
+        clearTimeout(timer);
+        resolve(code);
+      });
+    });
+    assert.strictEqual(exited, 0, 'the process did not exit on its own');
+    assert.strictEqual(server.getReceivedMessages().length, 1);
+  } finally {
+    child.kill();
+    await server.stop();
+  }
+});

From 1ea1c6f3ff9858ef933f58d4aaa7cab990ff349f Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:28:45 +0300
Subject: [PATCH 101/158] fix(dkim): sign the instances of a field from the
 bottom up
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

parseHeaders kept one instance per field name, the last, so a name that
h= listed twice signed the same line twice, and over-signing such as
h=from:from, which RFC 6376 recommends to keep a second From from being
added, gave a signature no verifier accepts. The headers now keep every
instance, and each name in h= takes the next one from the bottom up as
§5.4.2 says; a name with none left contributes nothing. The new flat
suite verifies against an input built by hand from the wire headers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                 |  5 ++++
 CLAUDE.md                    |  4 +++
 src/mime/dkim/sign.js        | 36 +++++++++++++----------
 tests/unit/mime-dkim.test.js | 57 ++++++++++++++++++++++++++++++++++++
 4 files changed, 86 insertions(+), 16 deletions(-)
 create mode 100644 tests/unit/mime-dkim.test.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d9fbc5d..e802bf3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -214,6 +214,11 @@ fixed ones below.
 - **An idle `./smtp` connection no longer keeps the process alive** (an upstream bug): a pooled
   socket held the event loop until its socket timeout, so a script that sent a message hung
   unless it called `closeAllConnections()`. Idle sockets are now unref'd.
+- **DKIM signs repeated and over-signed fields as RFC 6376 says** (an upstream bug): the signer kept
+  one instance of each field, the last, so a name listed twice in `headerFields` signed that
+  instance twice, and over-signing such as `['from', 'from']` produced a signature that failed
+  verification. Each name now signs the next instance from the bottom up (§5.4.2), and one with
+  no instance left signs nothing, which keeps another from being added.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index c60c398..87b4583 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -320,6 +320,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 59. smtp: an idle pooled socket kept the event loop alive until its socket timeout, so a
     script that sent a message did not exit without `closeAllConnections()`. A pooled socket
     is unref'd while idle and ref'd again when taken.
+60. DKIM: the header fields were kept one per name, the last, so a name listed twice in `h=`
+    signed that instance twice, against RFC 6376 §5.4.2, and over-signing (`h=from:from`) made
+    a signature no verifier accepts. Each name in `h=` signs the next instance from the bottom
+    up, and one with none left signs nothing.
 
 ## Repository layout
 
diff --git a/src/mime/dkim/sign.js b/src/mime/dkim/sign.js
index 782b5c0..82ef4cf 100644
--- a/src/mime/dkim/sign.js
+++ b/src/mime/dkim/sign.js
@@ -113,8 +113,8 @@ const parseMessage = (rawMessage) => {
 };
 
 /**
- * Parses header section into a map of header name to value.
- * Handles folded headers (continuation lines).
+ * Parses header section into a map from the lower-case name of a field to
+ * its instances, top to bottom.  Handles folded headers (continuation lines).
  */
 const parseHeaders = (headerSection) => {
   const headers = new Map();
@@ -122,6 +122,13 @@ const parseHeaders = (headerSection) => {
 
   let currentName = '';
   let currentValue = '';
+  const save = () => {
+    const key = currentName.toLowerCase();
+    const instances = headers.get(key);
+    const field = { name: currentName, value: currentValue };
+    if (instances === undefined) headers.set(key, [field]);
+    else instances.push(field);
+  };
 
   for (const line of lines) {
     if (line.startsWith(' ') || line.startsWith('\t')) {
@@ -129,12 +136,7 @@ const parseHeaders = (headerSection) => {
       currentValue += '\r\n' + line;
     } else {
       // New header - save previous if exists
-      if (currentName) {
-        headers.set(currentName.toLowerCase(), {
-          name: currentName,
-          value: currentValue,
-        });
-      }
+      if (currentName) save();
 
       const colonIndex = line.indexOf(':');
       if (colonIndex > 0) {
@@ -145,12 +147,7 @@ const parseHeaders = (headerSection) => {
   }
 
   // Save the last header
-  if (currentName) {
-    headers.set(currentName.toLowerCase(), {
-      name: currentName,
-      value: currentValue,
-    });
-  }
+  if (currentName) save();
 
   return headers;
 };
@@ -239,9 +236,16 @@ const buildDkimHeaderValue = (params) => {
 const buildSignatureData = (headers, headerFields, canonMethod, dkimHeaderValue) => {
   const lines = [];
 
-  // Canonicalize each header specified in h= tag
+  // RFC 6376 §5.4.2: each name in h= signs the next instance of that field
+  // from the bottom up, and one with no instance left signs nothing, which
+  // keeps another instance from being added (over-signing).
+  const nextInstance = new Map();
   for (const field of headerFields) {
-    const header = headers.get(field.toLowerCase());
+    const key = field.toLowerCase();
+    const instances = headers.get(key);
+    const index = nextInstance.get(key) ?? (instances === undefined ? -1 : instances.length - 1);
+    nextInstance.set(key, index - 1);
+    const header = index >= 0 ? instances[index] : undefined;
     if (header !== undefined) {
       const canonicalized =
         canonMethod === 'relaxed'
diff --git a/tests/unit/mime-dkim.test.js b/tests/unit/mime-dkim.test.js
new file mode 100644
index 0000000..bf0ebcf
--- /dev/null
+++ b/tests/unit/mime-dkim.test.js
@@ -0,0 +1,57 @@
+// Paths of the ported DKIM signer (src/mime/dkim/) that upstream's suites leave
+// out. A signature is verified with node:crypto over an input built here by
+// hand from the wire headers, not with the signer's own canonicalization.
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { createHash, verify } = require('node:crypto');
+const {
+  TEST_DKIM_DOMAIN,
+  TEST_DKIM_PRIVATE_KEY,
+  TEST_DKIM_PUBLIC_KEY,
+  TEST_DKIM_SELECTOR,
+} = require('../helpers/mime/dkim-test-keys.js');
+const { signMessage } = require('../../src/mime/dkim/sign.js');
+
+const config = (extra) => ({
+  signingDomain: TEST_DKIM_DOMAIN,
+  selector: TEST_DKIM_SELECTOR,
+  privateKey: TEST_DKIM_PRIVATE_KEY,
+  ...extra,
+});
+
+// Whether an RSA signature with relaxed header canonicalization covers exactly
+// `signed`, the relaxed form of the fields in h= order.
+const verifies = (result, signed) => {
+  const signature = /(?:^|;\s*)b=([^;]+)$/.exec(result.signature)[1];
+  const unsigned = result.signature.slice(0, -signature.length);
+  const input = [...signed, `dkim-signature:${unsigned.trim()}`].join('\r\n');
+  return verify(
+    'RSA-SHA256',
+    Buffer.from(input),
+    TEST_DKIM_PUBLIC_KEY,
+    Buffer.from(signature, 'base64'),
+  );
+};
+
+test('DKIM: h= signs the instances of a field from the bottom up, and over-signs', async () => {
+  const raw =
+    'From: alex@example.com\r\n' +
+    'X-Tag: one\r\n' +
+    'Subject: Hello\r\n' +
+    'X-Tag: two\r\n' +
+    '\r\n' +
+    'Hi\r\n';
+  const result = await signMessage(
+    raw,
+    config({ headerFields: ['from', 'x-tag', 'x-tag', 'x-tag', 'subject', 'subject'] }),
+  );
+  assert.ok(result.signature.includes('h=from:x-tag:x-tag:x-tag:subject:subject;'));
+  assert.ok(
+    result.signature.includes(`bh=${createHash('sha256').update('Hi\r\n').digest('base64')};`),
+  );
+  // The third x-tag and the second subject have no instance left: they add nothing.
+  assert.strictEqual(
+    verifies(result, ['from:alex@example.com', 'x-tag:two', 'x-tag:one', 'subject:Hello']),
+    true,
+  );
+});

From c71f80a555c4debb0d61d345fb5088caa059b0cd Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:31:21 +0300
Subject: [PATCH 102/158] fix(dkim): sign the fields a reader trusts by default
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The default h= was from, to, subject and date, so a Reply-To added after
signing, or a changed Cc, Message-ID or Content-Type, left the signature
valid. The default now also signs reply-to, cc, message-id, in-reply-to,
references, mime-version and content-type, present or not, and lists
from, reply-to and subject twice so that a second instance cannot be
added either. The flat suite verifies with a small verifier of its own
that reads h= from the signature, and shows each forgery failing; the
verifier of the ported large-attachment test took the first instance of
each name and an empty line for an absent one, and now follows §5.4.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  5 ++
 CLAUDE.md                                     |  4 ++
 docs/transports/smtp.md                       | 10 ++-
 src/mime/dkim/types.js                        | 23 ++++++-
 src/mime/index.d.ts                           |  8 ++-
 tests/unit/mime-dkim-sign.test.js             | 10 ++-
 tests/unit/mime-dkim.test.js                  | 61 ++++++++++++++++---
 .../smtp-large-attachment.integration.test.js | 20 ++++--
 8 files changed, 120 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e802bf3..a95545c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -219,6 +219,11 @@ fixed ones below.
   instance twice, and over-signing such as `['from', 'from']` produced a signature that failed
   verification. Each name now signs the next instance from the bottom up (§5.4.2), and one with
   no instance left signs nothing, which keeps another from being added.
+- **DKIM signs the fields a reader trusts by default** (an upstream bug): the default
+  `headerFields` were From, To, Subject and Date, so a Reply-To could be added, or the Cc,
+  Message-ID or Content-Type changed, without breaking the signature. The default now also
+  covers Reply-To, Cc, Message-ID, In-Reply-To, References, MIME-Version and Content-Type, and
+  over-signs From, Reply-To and Subject.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 87b4583..f992817 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -324,6 +324,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     signed that instance twice, against RFC 6376 §5.4.2, and over-signing (`h=from:from`) made
     a signature no verifier accepts. Each name in `h=` signs the next instance from the bottom
     up, and one with none left signs nothing.
+61. DKIM: the default `h=` was From, To, Subject and Date, so Reply-To, Cc, Message-ID or the
+    Content-Type could be changed or added without breaking the signature. It adds Reply-To,
+    Cc, Message-ID, In-Reply-To, References, MIME-Version and Content-Type, and over-signs
+    From, Reply-To and Subject.
 
 ## Repository layout
 
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index 6ac8289..5bfdbd2 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -725,7 +725,15 @@ Each signature in the `signatures` array can have the following options:
 | `privateKey`       | `string \| CryptoKey`              | (required)                          | Private key (PEM string or CryptoKey) |
 | `algorithm`        | `"rsa-sha256" \| "ed25519-sha256"` | `"rsa-sha256"`                      | Signing algorithm (a= tag)            |
 | `canonicalization` | `string`                           | `"relaxed/relaxed"`                 | Header/body canonicalization (c= tag) |
-| `headerFields`     | `string[]`                         | `["from", "to", "subject", "date"]` | Headers to sign (h= tag)              |
+| `headerFields`     | `string[]`                         | see below                           | Headers to sign (h= tag)              |
+
+By default the signature covers From, Reply-To, Subject, To, Cc, Date,
+Message-ID, In-Reply-To, References, MIME-Version and Content-Type, present or
+not, since a field absent when signed cannot be added afterwards without
+breaking the signature; From, Reply-To and Subject are listed twice, so that a
+second instance cannot be added either (over-signing, RFC 6376 §8.15). A name
+listed more than once in `headerFields` signs the instances of that field from
+the bottom up, as RFC 6376 §5.4.2 says.
 
 ### Using Ed25519 keys
 
diff --git a/src/mime/dkim/types.js b/src/mime/dkim/types.js
index bc5d4c4..cb8e940 100644
--- a/src/mime/dkim/types.js
+++ b/src/mime/dkim/types.js
@@ -17,9 +17,28 @@ const validateDkimBodyMode = (config) => {
 };
 
 /**
- * Default header fields to sign if not specified.
+ * Default header fields to sign if not specified: those a reader trusts or a
+ * client renders, present or not, since a field absent when signed cannot be
+ * added afterwards without breaking the signature.  From, Reply-To and
+ * Subject are listed once more than they can appear, so that a second
+ * instance cannot be added either (over-signing, RFC 6376 §8.15).
  */
-const DEFAULT_SIGNED_HEADERS = ['from', 'to', 'subject', 'date'];
+const DEFAULT_SIGNED_HEADERS = [
+  'from',
+  'from',
+  'reply-to',
+  'reply-to',
+  'subject',
+  'subject',
+  'to',
+  'cc',
+  'date',
+  'message-id',
+  'in-reply-to',
+  'references',
+  'mime-version',
+  'content-type',
+];
 
 /**
  * Default DKIM algorithm.
diff --git a/src/mime/index.d.ts b/src/mime/index.d.ts
index 6ee4010..dc9306b 100644
--- a/src/mime/index.d.ts
+++ b/src/mime/index.d.ts
@@ -108,8 +108,12 @@ export interface DkimSignature {
    */
   readonly canonicalization?: DkimCanonicalization;
   /**
-   * Header fields to include in the signature (h= tag).
-   * @default ["from", "to", "subject", "date"]
+   * Header fields to include in the signature (h= tag).  A name listed more
+   * than once signs the next instance of the field from the bottom up, and
+   * one with no instance left keeps another from being added.
+   * @default ["from", "from", "reply-to", "reply-to", "subject", "subject", "to",
+   *   "cc", "date", "message-id", "in-reply-to", "references", "mime-version",
+   *   "content-type"]
    */
   readonly headerFields?: readonly string[];
 }
diff --git a/tests/unit/mime-dkim-sign.test.js b/tests/unit/mime-dkim-sign.test.js
index ffe3e88..b5e05af 100644
--- a/tests/unit/mime-dkim-sign.test.js
+++ b/tests/unit/mime-dkim-sign.test.js
@@ -107,8 +107,14 @@ describe('DKIM Signing', () => {
         privateKey: TEST_DKIM_PRIVATE_KEY,
       });
 
-      // Default headers: from, to, subject, date
-      assert.ok(result.signature.includes('h=from:to:subject:date'));
+      // Changed after the port: the default signs more fields, and over-signs
+      // From, Reply-To and Subject (upstream signed from, to, subject, date).
+      assert.ok(
+        result.signature.includes(
+          'h=from:from:reply-to:reply-to:subject:subject:to:cc:date:message-id:in-reply-to:' +
+            'references:mime-version:content-type;',
+        ),
+      );
     });
 
     it('should use specified canonicalization method', async () => {
diff --git a/tests/unit/mime-dkim.test.js b/tests/unit/mime-dkim.test.js
index bf0ebcf..f12bcfa 100644
--- a/tests/unit/mime-dkim.test.js
+++ b/tests/unit/mime-dkim.test.js
@@ -19,11 +19,35 @@ const config = (extra) => ({
   ...extra,
 });
 
-// Whether an RSA signature with relaxed header canonicalization covers exactly
-// `signed`, the relaxed form of the fields in h= order.
-const verifies = (result, signed) => {
+// Whether an RSA signature with relaxed header canonicalization verifies over
+// `wire`, the header lines a receiver sees: a small verifier of its own that
+// reads h= from the signature and takes the instances of each name from the
+// bottom up (RFC 6376 §5.4.2), with relaxed canonicalization (§3.4.2).
+const verifies = (result, wire) => {
   const signature = /(?:^|;\s*)b=([^;]+)$/.exec(result.signature)[1];
   const unsigned = result.signature.slice(0, -signature.length);
+  const names = /(?:^|;\s*)h=([^;]+);/.exec(result.signature)[1].split(':');
+  const fields = wire.map((line) => {
+    const colon = line.indexOf(':');
+    return [
+      line.slice(0, colon).trim().toLowerCase(),
+      line
+        .slice(colon + 1)
+        .replace(/\s+/g, ' ')
+        .trim(),
+    ];
+  });
+  const used = new Set();
+  const signed = [];
+  for (const name of names) {
+    for (let i = fields.length - 1; i >= 0; i--) {
+      if (fields[i][0] === name.toLowerCase() && !used.has(i)) {
+        used.add(i);
+        signed.push(`${fields[i][0]}:${fields[i][1]}`);
+        break;
+      }
+    }
+  }
   const input = [...signed, `dkim-signature:${unsigned.trim()}`].join('\r\n');
   return verify(
     'RSA-SHA256',
@@ -49,9 +73,30 @@ test('DKIM: h= signs the instances of a field from the bottom up, and over-signs
   assert.ok(
     result.signature.includes(`bh=${createHash('sha256').update('Hi\r\n').digest('base64')};`),
   );
-  // The third x-tag and the second subject have no instance left: they add nothing.
-  assert.strictEqual(
-    verifies(result, ['from:alex@example.com', 'x-tag:two', 'x-tag:one', 'subject:Hello']),
-    true,
-  );
+  const wire = ['From: alex@example.com', 'X-Tag: one', 'Subject: Hello', 'X-Tag: two'];
+  assert.strictEqual(verifies(result, wire), true);
+  // The third x-tag has no instance left, so a third cannot be added.
+  assert.strictEqual(verifies(result, [...wire, 'X-Tag: three']), false);
+});
+
+test('DKIM: by default, a forged Reply-To or a second From breaks the signature', async () => {
+  const headers = [
+    'From: alex@example.com',
+    'To: bob@example.com',
+    'Subject: Hello',
+    'Date: Thu, 01 Jan 2026 00:00:00 +0000',
+    'Message-ID: <1@example.com>',
+    'MIME-Version: 1.0',
+    'Content-Type: text/plain; charset=utf-8',
+  ];
+  const result = await signMessage(`${headers.join('\r\n')}\r\n\r\nHi\r\n`, config());
+  assert.strictEqual(verifies(result, headers), true);
+  // Fields a client shows, added after signing, now break the signature.
+  for (const forged of [
+    'Reply-To: eve@evil.example',
+    'From: eve@evil.example',
+    'Cc: eve@evil.example',
+  ]) {
+    assert.strictEqual(verifies(result, [forged, ...headers]), false, forged);
+  }
 });
diff --git a/tests/unit/smtp-large-attachment.integration.test.js b/tests/unit/smtp-large-attachment.integration.test.js
index fbbdbe9..ce28c40 100644
--- a/tests/unit/smtp-large-attachment.integration.test.js
+++ b/tests/unit/smtp-large-attachment.integration.test.js
@@ -156,12 +156,20 @@ for (const megabytes of [8, 64]) {
               }),
           );
           assert.equal(tags.get('bh'), bodyHash.digest('base64'));
-          const selected = tags
-            .get('h')
-            .split(':')
-            .map((name) =>
-              headers.find((line) => line.toLowerCase().startsWith(name.toLowerCase() + ':')),
-            );
+          // Changed after the port: each name takes the next instance from the
+          // bottom up, and a name with none left adds nothing (RFC 6376 §5.4.2),
+          // as the default h= now lists absent and over-signed fields.
+          const used = new Set();
+          const selected = [];
+          for (const name of tags.get('h').split(':')) {
+            for (let i = headers.length - 1; i >= 0; i--) {
+              if (!used.has(i) && headers[i].toLowerCase().startsWith(`${name.toLowerCase()}:`)) {
+                used.add(i);
+                selected.push(headers[i]);
+                break;
+              }
+            }
+          }
           selected.push(signature.replace(/b=[^;]*$/, 'b='));
           assert.ok(
             verify(

From fb1d5a470e92847e2fe65dcac7aec14ca15648ab Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:35:02 +0300
Subject: [PATCH 103/158] fix(dkim): refuse settings that could break the
 signature field

The signing domain, the selector, the signed field names, the algorithm
and the canonicalization were written into the DKIM-Signature field as
given: a domain of "example.com\r\nBcc: eve@evil.example" added a Bcc to
every signed message, and a ";" in any of them ended a tag early.
checkDkimConfig, run when an SMTP transport is made and at every
composition, now requires domain names of LDH labels (U-labels allowed,
as RFC 8616 lets them be), field names without ":" or ";", and a known
algorithm and canonicalization. The ported test of an overlong domain
now expects the TypeError, and keeps its RangeError case with a long h=.
The checks take mime to 6.0 KB and smtp to 18.1 KB, so their budgets
rise to 6.5 and 18.5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/npm-publish/SKILL.md |  2 +-
 .github/workflows/ci.yml            |  2 +-
 CHANGELOG.md                        |  6 +++
 CLAUDE.md                           |  4 ++
 docs/transports/smtp.md             |  6 +++
 src/mime/dkim/types.js              | 61 +++++++++++++++++++++++++++++
 src/mime/message.js                 |  4 +-
 src/smtp/config.js                  |  4 +-
 src/smtp/smtp-transport.js          |  4 +-
 tests/unit/mime-compose.test.js     |  9 +++++
 tests/unit/mime-dkim.test.js        | 33 ++++++++++++++++
 11 files changed, 127 insertions(+), 8 deletions(-)

diff --git a/.claude/skills/npm-publish/SKILL.md b/.claude/skills/npm-publish/SKILL.md
index 1e88c29..195eb72 100644
--- a/.claude/skills/npm-publish/SKILL.md
+++ b/.claude/skills/npm-publish/SKILL.md
@@ -37,7 +37,7 @@ pnpm run check:dts               # tsc over the d.ts of every entry of the expor
 These are the same gates `prepublishOnly` runs. CI adds three more; run them too:
 
 ```bash
-pnpm size --max-gzip 8 --max-gzip-smtp 18 …                     # the budgets: copy the size step of ci.yml
+pnpm size --max-gzip 8 --max-gzip-smtp 18.5 …                   # the budgets: copy the size step of ci.yml
 pnpm docs:comparison && git diff --exit-code docs/guide/comparison.md   # the table matches docs/comparison.json
 pnpm run docs:build                                              # the docs site; a dead link fails it
 ```
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c805646..6a17fc7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 8 --max-gzip-mime 6 --max-gzip-smtp 18 --max-gzip-jmap 10.5 --max-gzip-ses 5 --max-gzip-resend 4.5 --max-gzip-sendgrid 4.5 --max-gzip-mailgun 4 --max-gzip-mailtrap 5.5 --max-gzip-maileroo 5 --max-gzip-lettermint 5 --max-gzip-plunk 4.5 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
+      - run: pnpm size --max-gzip 8 --max-gzip-mime 6.5 --max-gzip-smtp 18.5 --max-gzip-jmap 10.5 --max-gzip-ses 5 --max-gzip-resend 4.5 --max-gzip-sendgrid 4.5 --max-gzip-mailgun 4 --max-gzip-mailtrap 5.5 --max-gzip-maileroo 5 --max-gzip-lettermint 5 --max-gzip-plunk 4.5 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
 
   types:
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a95545c..8d64176 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -55,6 +55,12 @@ fixed ones below.
 
 ### Security
 
+- **A DKIM setting can no longer add a header field** (an upstream bug): the signing domain,
+  the selector, the signed field names, the algorithm and the canonicalization went into the
+  `DKIM-Signature` field as given, so a domain such as `example.com\r\nBcc: …` added a Bcc to
+  every message, and a `;` ended a tag early. They must now be valid (domain names, field names
+  without `:` or `;`, known algorithms and canonicalizations), or the SMTP transport refuses
+  them when it is made and `composeMessage` throws a `TypeError`.
 - **An address can no longer end the path of an SMTP command** (an upstream bug). A quote in the
   domain hid a second `@` from the scan of `isEmailAddress`, and `URL.canParse` accepted the rest
   as userinfo, so `user@example.com> NOTIFY=NEVER ORCPT=rfc822;a"@x.com` passed and became
diff --git a/CLAUDE.md b/CLAUDE.md
index f992817..d4946fa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -328,6 +328,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     Content-Type could be changed or added without breaking the signature. It adds Reply-To,
     Cc, Message-ID, In-Reply-To, References, MIME-Version and Content-Type, and over-signs
     From, Reply-To and Subject.
+62. DKIM: `signingDomain`, `selector`, the names in `headerFields`, the algorithm and the
+    canonicalization went into the DKIM-Signature field unchecked, so a domain with a line
+    break added a header field such as Bcc to the message, and a `;` ended a tag early.
+    `checkDkimConfig` refuses them, from the SMTP constructor and at every composition.
 
 ## Repository layout
 
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index 5bfdbd2..f5b3373 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -735,6 +735,12 @@ second instance cannot be added either (over-signing, RFC 6376 §8.15). A name
 listed more than once in `headerFields` signs the instances of that field from
 the bottom up, as RFC 6376 §5.4.2 says.
 
+The signing domain and the selector must be domain names (letters, digits and
+hyphens, or U-labels that convert to such A-labels), the field names printable
+ASCII without `:` or `;`, and the algorithm and canonicalization among those
+above; anything else throws a `TypeError` when the transport is made, since
+these values are written into the `DKIM-Signature` field as they are.
+
 ### Using Ed25519 keys
 
 Ed25519 offers shorter keys than RSA while providing equivalent security.
diff --git a/src/mime/dkim/types.js b/src/mime/dkim/types.js
index cb8e940..f099ff8 100644
--- a/src/mime/dkim/types.js
+++ b/src/mime/dkim/types.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/mime/src/dkim/types.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { domainToASCII } = require('node:url');
+
 /**
  * Validates the runtime body-mode option without changing config identity.
  * @param config Optional signing configuration.
@@ -16,6 +18,64 @@ const validateDkimBodyMode = (config) => {
   }
 };
 
+// The tags that go into the DKIM-Signature field as they are.  A domain or a
+// selector is dot-separated labels of letters, digits and hyphens (RFC 6376
+// §3.5, sub-domain of RFC 5321), in A-labels once converted, since RFC 8616
+// lets an internationalized message carry U-labels; a header field name is printable ASCII
+// without the ":" that ends it, nor the ";" that would end the h= tag.  Any
+// other character could end a tag early or, with a line break, add a field.
+const LABEL = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/;
+const FIELD_NAME = /^[!-9<-~]+$/;
+const ALGORITHMS = new Set(['rsa-sha256', 'ed25519-sha256']);
+const CANONICALIZATIONS = new Set([
+  'relaxed/relaxed',
+  'relaxed/simple',
+  'simple/relaxed',
+  'simple/simple',
+]);
+
+const isDomainName = (value) => {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  // domainToASCII gives '' for a name it cannot convert, such as one with a
+  // space, a semicolon or a line break.
+  const ascii = domainToASCII(value);
+  if (ascii.length === 0 || ascii.length > 253) return false;
+  for (const label of ascii.split('.')) {
+    if (!LABEL.test(label)) return false;
+  }
+  return true;
+};
+
+/**
+ * Checks a DKIM configuration: its body mode, and in each signature the
+ * domain (`d=`), the selector (`s=`), the algorithm, the canonicalization
+ * and the names of the signed fields, which all go into the signature field.
+ *
+ * @param config Optional signing configuration.
+ * @throws {TypeError} If any of them is not valid.
+ */
+const checkDkimConfig = (config) => {
+  validateDkimBodyMode(config);
+  if (config == null) return;
+  if (!Array.isArray(config.signatures)) refuse('signatures', config.signatures);
+  for (const signature of config.signatures) {
+    if (!isDomainName(signature.signingDomain)) refuse('signing domain', signature.signingDomain);
+    if (!isDomainName(signature.selector)) refuse('selector', signature.selector);
+    const { algorithm, canonicalization, headerFields } = signature;
+    if (algorithm !== undefined && !ALGORITHMS.has(algorithm)) refuse('algorithm', algorithm);
+    if (canonicalization !== undefined && !CANONICALIZATIONS.has(canonicalization)) {
+      refuse('canonicalization', canonicalization);
+    }
+    for (const field of headerFields ?? []) {
+      if (typeof field !== 'string' || !FIELD_NAME.test(field)) refuse('header field', field);
+    }
+  }
+};
+
+const refuse = (what, value) => {
+  throw new TypeError(`Invalid DKIM ${what}: ${JSON.stringify(value)}.`);
+};
+
 /**
  * Default header fields to sign if not specified: those a reader trusts or a
  * client renders, present or not, since a field absent when signed cannot be
@@ -51,6 +111,7 @@ const DEFAULT_ALGORITHM = 'rsa-sha256';
 const DEFAULT_CANONICALIZATION = 'relaxed/relaxed';
 
 module.exports = {
+  checkDkimConfig,
   validateDkimBodyMode,
   DEFAULT_SIGNED_HEADERS,
   DEFAULT_ALGORITHM,
diff --git a/src/mime/message.js b/src/mime/message.js
index 0f9cc85..b43fb75 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -11,7 +11,7 @@ const {
   resolveThreadingHeaders,
 } = require('../core/message-id.js');
 const { resolveCalendarContent } = require('../core/calendar.js');
-const { validateDkimBodyMode } = require('./dkim/types.js');
+const { checkDkimConfig } = require('./dkim/types.js');
 const { attachmentEncodedSize, encodeAttachment } = require('./mime-stream.js');
 const { base64, hasLineLongerThan, utf8 } = require('./bytes.js');
 
@@ -42,7 +42,7 @@ const prepareMimeMessage = (message, dkimConfig) => {
             headerFields: signature.headerFields == null ? undefined : [...signature.headerFields],
           })),
         };
-  if (dkim != null) validateDkimBodyMode(dkim);
+  if (dkim != null) checkDkimConfig(dkim);
   const parts = buildMimeParts(message);
   const first = parts[0];
   if (typeof first !== 'string') throw new TypeError('Missing MIME headers.');
diff --git a/src/smtp/config.js b/src/smtp/config.js
index c7cc7eb..e574cc5 100644
--- a/src/smtp/config.js
+++ b/src/smtp/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/smtp/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { validateDkimBodyMode } = require('../mime/dkim/types.js');
+const { checkDkimConfig } = require('../mime/dkim/types.js');
 
 /**
  * Creates a resolved SMTP configuration by applying default values to optional fields.
@@ -15,7 +15,7 @@ const { validateDkimBodyMode } = require('../mime/dkim/types.js');
  * @internal
  */
 const createSmtpConfig = (config) => {
-  validateDkimBodyMode(config.dkim);
+  checkDkimConfig(config.dkim);
   const port = config.port ?? 587;
 
   return {
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index b9ec355..2970c9f 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -21,7 +21,7 @@ const { OAuth2TokenManager } = require('./oauth2.js');
 const { prepareMessage } = require('./message-converter.js');
 const { SmtpAttachmentReplayError } = require('./message-stream.js');
 const { SmtpDeliveryUnknownError } = require('./data-stream.js');
-const { validateDkimBodyMode } = require('../mime/dkim/types.js');
+const { checkDkimConfig } = require('../mime/dkim/types.js');
 const { parseEnhancedSmtpStatusCode } = require('./smtp-status-code.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
@@ -117,7 +117,7 @@ class SmtpTransport {
    *                        `Infinity`.
    */
   constructor(config) {
-    validateDkimBodyMode(config.dkim);
+    checkDkimConfig(config.dkim);
     this.config = config;
     const poolSize = config.poolSize ?? 5;
     if (
diff --git a/tests/unit/mime-compose.test.js b/tests/unit/mime-compose.test.js
index f62b926..2dd23b5 100644
--- a/tests/unit/mime-compose.test.js
+++ b/tests/unit/mime-compose.test.js
@@ -294,10 +294,19 @@ test('nested and signed Unicode headers determine MIME encoding', async () => {
     ).encoding,
     'utf8',
   );
+  // Changed after the port: a signing domain of 1000 characters is no domain
+  // name and is refused as such; an h= of many fields still makes a signature
+  // line longer than 998 octets.
   await assert.rejects(
     composeMessage(message(), {
       dkim: { signatures: [{ ...signature, signingDomain: 'x'.repeat(1000) }] },
     }),
+    TypeError,
+  );
+  await assert.rejects(
+    composeMessage(message(), {
+      dkim: { signatures: [{ ...signature, headerFields: Array(100).fill('x-long-field-name') }] },
+    }),
     RangeError,
   );
 });
diff --git a/tests/unit/mime-dkim.test.js b/tests/unit/mime-dkim.test.js
index f12bcfa..e8fd859 100644
--- a/tests/unit/mime-dkim.test.js
+++ b/tests/unit/mime-dkim.test.js
@@ -100,3 +100,36 @@ test('DKIM: by default, a forged Reply-To or a second From breaks the signature'
     assert.strictEqual(verifies(result, [forged, ...headers]), false, forged);
   }
 });
+
+test('DKIM: a domain, selector or field name that could break the signature field is refused', async () => {
+  const { composeMessage } = require('../../src/mime/index.js');
+  const { SmtpTransport } = require('../../src/smtp/index.js');
+  const { createMessage } = require('../../index.js');
+  const message = createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Hello',
+    content: { text: 'Hi' },
+  });
+  const wrong = [
+    { signingDomain: 'example.com\r\nBcc: eve@evil.example' },
+    { signingDomain: 'example.com; x=1' },
+    { signingDomain: '-example.com' },
+    { selector: 'mail\r\nX: y' },
+    { selector: 'a;b' },
+    { headerFields: ['from', 'subject; x=1'] },
+    { headerFields: ['from:to'] },
+    { algorithm: 'rsa-sha1' },
+    { canonicalization: 'relaxed' },
+  ];
+  for (const extra of wrong) {
+    const signatures = [config(extra)];
+    await assert.rejects(composeMessage(message, { dkim: { signatures } }), TypeError);
+    // The SMTP transport refuses it when it is made, before any message.
+    assert.throws(() => new SmtpTransport({ host: 'localhost', dkim: { signatures } }), TypeError);
+  }
+  // An internationalized domain may stay in U-labels (RFC 8616).
+  await composeMessage(message, {
+    dkim: { signatures: [config({ signingDomain: 'приклад.укр' })] },
+  });
+});

From d17c9d53d88a908465ff2cce822d3437ab21daf3 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:36:06 +0300
Subject: [PATCH 104/158] fix(dkim): import a PKCS#1 private key

importPrivateKey stripped the armor of a PEM and gave the base64 to Web
Crypto as PKCS#8, so a key in PKCS#1 (BEGIN RSA PRIVATE KEY), the form
openssl genrsa writes, failed to import (known upstream bug 6). The PEM is
now read by createPrivateKey of node:crypto, which takes either form, and
exported to Web Crypto as PKCS#8 DER; the import error keeps its cause.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                 |  2 ++
 CLAUDE.md                    |  6 +++++-
 docs/guide/known-issues.md   |  2 --
 src/mime/dkim/sign.js        | 20 ++++++--------------
 tests/unit/mime-dkim.test.js | 28 ++++++++++++++++++++++++++++
 5 files changed, 41 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8d64176..5fdf393 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -230,6 +230,8 @@ fixed ones below.
   Message-ID or Content-Type changed, without breaking the signature. The default now also
   covers Reply-To, Cc, Message-ID, In-Reply-To, References, MIME-Version and Content-Type, and
   over-signs From, Reply-To and Subject.
+- **DKIM takes a PKCS#1 key** (known upstream bug 6): a `BEGIN RSA PRIVATE KEY` PEM was imported
+  as PKCS#8 and failed. The PEM is now read by `node:crypto`, which takes PKCS#1 and PKCS#8.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index d4946fa..1a56191 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -131,7 +131,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 4. (fixed, see 38) SMTP AUTH PLAIN and LOGIN encoded with `btoa`, which fails on non-Latin-1
    credentials; so did Basic auth in jmap and mailgun.
 5. `cram-md5` is in the `SmtpAuth` type but not implemented.
-6. DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails.
+6. (fixed, see 63) DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) was imported as PKCS#8 and
+   failed.
 7. pool: `continueOnSuccess` is never read.
 8. (fixed, see 44, 45 and 48 to 52) otel: `_active_sends` was not decremented after `sendMany`
    and drifted under sampling; `durationBuckets` and `auto` were ignored; `recordRetry` was
@@ -332,6 +333,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     canonicalization went into the DKIM-Signature field unchecked, so a domain with a line
     break added a header field such as Bcc to the message, and a `;` ended a tag early.
     `checkDkimConfig` refuses them, from the SMTP constructor and at every composition.
+63. DKIM (known bug 6): a PEM was stripped of its armor and imported as PKCS#8, so a PKCS#1
+    key (`BEGIN RSA PRIVATE KEY`) failed. `createPrivateKey` of node:crypto reads either and
+    the key reaches Web Crypto as PKCS#8; the import error keeps its cause.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index e387328..807cc74 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -10,8 +10,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
   clients show them as attachments.
 - The first encoded word of a header shares its line with the field name
   (`Subject: =?UTF-8?B?…?=`), past the 76 characters that RFC 2047 allows such a line.
-- DKIM: a PKCS#1 key (`BEGIN RSA PRIVATE KEY`) is imported as PKCS#8 and fails; convert it to
-  PKCS#8 first.
 - DKIM: when signing fails and `send-unsigned` is set, the warning goes to `console.warn`.
 
 ## SMTP
diff --git a/src/mime/dkim/sign.js b/src/mime/dkim/sign.js
index 82ef4cf..532b403 100644
--- a/src/mime/dkim/sign.js
+++ b/src/mime/dkim/sign.js
@@ -9,6 +9,7 @@
  * @see https://www.rfc-editor.org/rfc/rfc6376
  */
 
+const { createPrivateKey } = require('node:crypto');
 const {
   canonicalizeBodyRelaxed,
   canonicalizeBodySimple,
@@ -164,22 +165,13 @@ const getPrivateKey = (key, algorithm) => {
 };
 
 /**
- * Imports a PEM-encoded private key for use with Web Crypto API.
+ * Imports a PEM-encoded private key for use with Web Crypto API.  The PEM is
+ * read by node:crypto, which takes PKCS#8 (`BEGIN PRIVATE KEY`) and PKCS#1
+ * (`BEGIN RSA PRIVATE KEY`) alike, and handed to Web Crypto as PKCS#8.
  */
 const importPrivateKey = async (pem, algorithm) => {
   try {
-    // Remove PEM headers/footers and whitespace
-    const pemContents = pem
-      .replace(/-----BEGIN (?:RSA )?PRIVATE KEY-----/, '')
-      .replace(/-----END (?:RSA )?PRIVATE KEY-----/, '')
-      .replace(/\s/g, '');
-
-    // Decode Base64 to binary
-    const binaryString = atob(pemContents);
-    const bytes = new Uint8Array(binaryString.length);
-    for (let i = 0; i < binaryString.length; i++) {
-      bytes[i] = binaryString.charCodeAt(i);
-    }
+    const bytes = createPrivateKey(pem).export({ type: 'pkcs8', format: 'der' });
 
     // Determine the algorithm parameters based on DKIM algorithm
     const keyAlgorithm =
@@ -189,9 +181,9 @@ const importPrivateKey = async (pem, algorithm) => {
 
     return await crypto.subtle.importKey('pkcs8', bytes, keyAlgorithm, false, ['sign']);
   } catch (error) {
-    // oxlint-disable-next-line preserve-caught-error -- upstream
     throw new Error(
       `Failed to import private key: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
     );
   }
 };
diff --git a/tests/unit/mime-dkim.test.js b/tests/unit/mime-dkim.test.js
index e8fd859..be5489f 100644
--- a/tests/unit/mime-dkim.test.js
+++ b/tests/unit/mime-dkim.test.js
@@ -133,3 +133,31 @@ test('DKIM: a domain, selector or field name that could break the signature fiel
     dkim: { signatures: [config({ signingDomain: 'приклад.укр' })] },
   });
 });
+
+test('DKIM: a PKCS#1 key (BEGIN RSA PRIVATE KEY) signs like a PKCS#8 one', async () => {
+  const { generateKeyPairSync } = require('node:crypto');
+  const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    privateKeyEncoding: { type: 'pkcs1', format: 'pem' },
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+  });
+  assert.match(privateKey, /^-----BEGIN RSA PRIVATE KEY-----/);
+  const result = await signMessage(
+    'From: alex@example.com\r\nSubject: Hello\r\n\r\nHi\r\n',
+    config({ privateKey, headerFields: ['from', 'subject'] }),
+  );
+  const signature = /(?:^|;\s*)b=([^;]+)$/.exec(result.signature)[1];
+  const unsigned = result.signature.slice(0, -signature.length);
+  const input = ['from:alex@example.com', 'subject:Hello', `dkim-signature:${unsigned.trim()}`];
+  assert.ok(
+    verify(
+      'RSA-SHA256',
+      Buffer.from(input.join('\r\n')),
+      publicKey,
+      Buffer.from(signature, 'base64'),
+    ),
+  );
+  await assert.rejects(signMessage('From: a@example.com\r\n\r\n', config({ privateKey: 'nope' })), {
+    message: /^Failed to import private key/,
+  });
+});

From ab7041bf6301530c43223436ec8cb7bc37e7c172 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:40:13 +0300
Subject: [PATCH 105/158] fix(dkim): import a key once and check it when the
 transport is made

A PEM key was parsed and imported through Web Crypto for every message,
and a broken key surfaced only when the first message was signed.
resolvePrivateKey imports it once per signature configuration, kept in a
WeakMap so it goes with the configuration, and prepareMimeMessage hands
the signer that import; SmtpTransport reads each PEM synchronously when
it is made and throws a TypeError for one it cannot read, unless the
configuration sends unsigned on a signing failure. The secrets test now
gives the transport a real key, and checks that no line of it shows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                 |  4 +++
 CLAUDE.md                    |  4 +++
 docs/transports/smtp.md      |  5 +++-
 src/mime/dkim/sign.js        | 58 +++++++++++++++++++++++++++++++++++-
 src/mime/message.js          |  6 +++-
 src/smtp/smtp-transport.js   |  4 +++
 tests/unit/graph.test.js     |  2 ++
 tests/unit/mime-dkim.test.js | 35 ++++++++++++++++++++++
 tests/unit/secrets.test.js   | 12 +++++++-
 9 files changed, 126 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5fdf393..c51e2dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -232,6 +232,10 @@ fixed ones below.
   over-signs From, Reply-To and Subject.
 - **DKIM takes a PKCS#1 key** (known upstream bug 6): a `BEGIN RSA PRIVATE KEY` PEM was imported
   as PKCS#8 and failed. The PEM is now read by `node:crypto`, which takes PKCS#1 and PKCS#8.
+- **DKIM imports a key once, and `./smtp` checks it when made** (an upstream bug): a PEM key was
+  parsed and imported for every message, and a broken one failed only at the first send. It is
+  now imported once per signature configuration, and `SmtpTransport` throws a `TypeError` for
+  a PEM it cannot read, unless `onSigningFailure` is `send-unsigned`.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 1a56191..b2f55b0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -336,6 +336,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 63. DKIM (known bug 6): a PEM was stripped of its armor and imported as PKCS#8, so a PKCS#1
     key (`BEGIN RSA PRIVATE KEY`) failed. `createPrivateKey` of node:crypto reads either and
     the key reaches Web Crypto as PKCS#8; the import error keeps its cause.
+64. DKIM: a PEM key was parsed and imported for every message, and a broken one failed only at
+    the first send. It is imported once per signature configuration (`resolvePrivateKey`, a
+    WeakMap), and the SMTP transport reads it when it is made (`checkDkimKeys`), unless the
+    configuration sends unsigned on a signing failure.
 
 ## Repository layout
 
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index f5b3373..cd4327e 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -739,7 +739,10 @@ The signing domain and the selector must be domain names (letters, digits and
 hyphens, or U-labels that convert to such A-labels), the field names printable
 ASCII without `:` or `;`, and the algorithm and canonicalization among those
 above; anything else throws a `TypeError` when the transport is made, since
-these values are written into the `DKIM-Signature` field as they are.
+these values are written into the `DKIM-Signature` field as they are. A PEM key
+is read when the transport is made too, so a broken key fails there rather than
+at the first message (unless `onSigningFailure` is `send-unsigned`), and it is
+imported once per signature configuration, not once per message.
 
 ### Using Ed25519 keys
 
diff --git a/src/mime/dkim/sign.js b/src/mime/dkim/sign.js
index 532b403..ca5e86b 100644
--- a/src/mime/dkim/sign.js
+++ b/src/mime/dkim/sign.js
@@ -153,6 +153,62 @@ const parseHeaders = (headerSection) => {
   return headers;
 };
 
+// Imported keys by the signature configuration that holds their PEM: a key is
+// parsed and imported once per configuration rather than once per message, and
+// goes with the configuration.
+const importedKeys = new WeakMap();
+
+/**
+ * Gives the private key of a signature configuration: its CryptoKey, or the
+ * import of its PEM, started once per configuration object and algorithm.
+ *
+ * @param signature A signature configuration of the caller.
+ * @returns A CryptoKey, or a promise of the imported one.
+ * @internal
+ */
+const resolvePrivateKey = (signature) => {
+  const key = signature.privateKey;
+  if (typeof key !== 'string') return key;
+  const algorithm = signature.algorithm ?? DEFAULT_ALGORITHM;
+  let cached = importedKeys.get(signature);
+  if (cached === undefined || cached.pem !== key || cached.algorithm !== algorithm) {
+    const imported = importPrivateKey(key, algorithm);
+    const entry = { pem: key, algorithm, imported };
+    importedKeys.set(signature, entry);
+    // A failed import is tried again with the next message.
+    imported.catch(() => {
+      if (importedKeys.get(signature) === entry) importedKeys.delete(signature);
+    });
+    cached = entry;
+  }
+  return cached.imported;
+};
+
+/**
+ * Checks, once and synchronously, that each PEM key of a configuration can be
+ * read, so that a broken key fails when a transport is made rather than at
+ * its first message.  A configuration that sends unsigned on a signing
+ * failure is left to do so.
+ *
+ * @param config Optional signing configuration.
+ * @throws {TypeError} If a PEM key cannot be read.
+ * @internal
+ */
+const checkDkimKeys = (config) => {
+  if (config == null || config.onSigningFailure === 'send-unsigned') return;
+  for (const signature of config.signatures) {
+    if (typeof signature.privateKey !== 'string') continue;
+    try {
+      createPrivateKey(signature.privateKey);
+    } catch (error) {
+      throw new TypeError(
+        `Invalid DKIM private key for ${signature.signingDomain}: ${error.message}`,
+        { cause: error },
+      );
+    }
+  }
+};
+
 /**
  * Gets the private key, either using a provided CryptoKey or importing from PEM.
  */
@@ -292,4 +348,4 @@ const arrayBufferToBase64 = (buffer) => {
   return btoa(binary);
 };
 
-module.exports = { signMessage, signWithBodyHash };
+module.exports = { checkDkimKeys, resolvePrivateKey, signMessage, signWithBodyHash };
diff --git a/src/mime/message.js b/src/mime/message.js
index b43fb75..66d2e70 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -12,6 +12,7 @@ const {
 } = require('../core/message-id.js');
 const { resolveCalendarContent } = require('../core/calendar.js');
 const { checkDkimConfig } = require('./dkim/types.js');
+const { resolvePrivateKey } = require('./dkim/sign.js');
 const { attachmentEncodedSize, encodeAttachment } = require('./mime-stream.js');
 const { base64, hasLineLongerThan, utf8 } = require('./bytes.js');
 
@@ -32,6 +33,8 @@ const prepareMimeMessage = (message, dkimConfig) => {
       attachment.content.catch(() => {});
     }
   }
+  // Checked before a key import is started for it.
+  if (dkimConfig != null) checkDkimConfig(dkimConfig);
   const dkim =
     dkimConfig == null
       ? undefined
@@ -39,10 +42,11 @@ const prepareMimeMessage = (message, dkimConfig) => {
           ...dkimConfig,
           signatures: dkimConfig.signatures.map((signature) => ({
             ...signature,
+            // Imported once per signature configuration of the caller.
+            privateKey: resolvePrivateKey(signature),
             headerFields: signature.headerFields == null ? undefined : [...signature.headerFields],
           })),
         };
-  if (dkim != null) checkDkimConfig(dkim);
   const parts = buildMimeParts(message);
   const first = parts[0];
   if (typeof first !== 'string') throw new TypeError('Missing MIME headers.');
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index 2970c9f..94a7a78 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -22,6 +22,7 @@ const { prepareMessage } = require('./message-converter.js');
 const { SmtpAttachmentReplayError } = require('./message-stream.js');
 const { SmtpDeliveryUnknownError } = require('./data-stream.js');
 const { checkDkimConfig } = require('../mime/dkim/types.js');
+const { checkDkimKeys } = require('../mime/dkim/sign.js');
 const { parseEnhancedSmtpStatusCode } = require('./smtp-status-code.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
@@ -115,9 +116,12 @@ class SmtpTransport {
    *               and options.
    * @throws {RangeError} If `config.poolSize` is neither a positive integer nor
    *                        `Infinity`.
+   * @throws {TypeError} If the DKIM configuration is invalid, or a PEM key of
+   *                     it cannot be read (unless it sends unsigned).
    */
   constructor(config) {
     checkDkimConfig(config.dkim);
+    checkDkimKeys(config.dkim);
     this.config = config;
     const poolSize = config.poolSize ?? 5;
     if (
diff --git a/tests/unit/graph.test.js b/tests/unit/graph.test.js
index 2e34d1b..2fe0c4a 100644
--- a/tests/unit/graph.test.js
+++ b/tests/unit/graph.test.js
@@ -89,6 +89,8 @@ const SUBPATH_EDGES = [
   'smtp/message-converter.js -> mime/message.js',
   'smtp/message-converter.js -> mime/stream.js',
   'smtp/message-stream.js -> mime/stream.js',
+  // The transport checks the DKIM keys when it is made.
+  'smtp/smtp-transport.js -> mime/dkim/sign.js',
   'smtp/smtp-transport.js -> mime/dkim/types.js',
 ];
 
diff --git a/tests/unit/mime-dkim.test.js b/tests/unit/mime-dkim.test.js
index be5489f..9850d08 100644
--- a/tests/unit/mime-dkim.test.js
+++ b/tests/unit/mime-dkim.test.js
@@ -161,3 +161,38 @@ test('DKIM: a PKCS#1 key (BEGIN RSA PRIVATE KEY) signs like a PKCS#8 one', async
     message: /^Failed to import private key/,
   });
 });
+
+test('DKIM: a PEM key is imported once per configuration, and a broken one fails early', async (t) => {
+  const { composeMessage } = require('../../src/mime/index.js');
+  const { SmtpTransport } = require('../../src/smtp/index.js');
+  const { createMessage, readAttachmentContent } = require('../../index.js');
+  const importKey = t.mock.method(crypto.subtle, 'importKey');
+  const dkim = { signatures: [config()] };
+  for (let i = 0; i < 3; i++) {
+    const composed = await composeMessage(
+      createMessage({
+        from: 'alex@example.com',
+        to: 'bob@example.com',
+        subject: 'Hello',
+        content: { text: `${i}` },
+      }),
+      { dkim },
+    );
+    await readAttachmentContent(composed.content);
+  }
+  assert.strictEqual(importKey.mock.callCount(), 1);
+
+  const broken = { signatures: [config({ privateKey: '-----BEGIN PRIVATE KEY-----\nnope\n' })] };
+  assert.throws(() => new SmtpTransport({ host: 'localhost', dkim: broken }), {
+    name: 'TypeError',
+    message: /^Invalid DKIM private key for /,
+  });
+  // One that sends unsigned on a signing failure is left to do so.
+  assert.doesNotThrow(
+    () =>
+      new SmtpTransport({
+        host: 'localhost',
+        dkim: { ...broken, onSigningFailure: 'send-unsigned' },
+      }),
+  );
+});
diff --git a/tests/unit/secrets.test.js b/tests/unit/secrets.test.js
index c7f4218..78cd1d6 100644
--- a/tests/unit/secrets.test.js
+++ b/tests/unit/secrets.test.js
@@ -18,13 +18,21 @@ const { SendGridTransport } = require('../../src/sendgrid/index.js');
 const { SesTransport } = require('../../src/ses/index.js');
 const { SmtpTransport } = require('../../src/smtp/index.js');
 
+const { TEST_DKIM_PRIVATE_KEY } = require('../helpers/mime/dkim-test-keys.js');
+
 const SECRET = 'secret-value-1f3a';
+// A line of the body of the PEM key, which a transport now reads when made.
+const KEY_LINE = TEST_DKIM_PRIVATE_KEY.split('\n')[1];
 
 const transports = () => [
   new SmtpTransport({
     host: 'smtp.example.com',
     auth: { user: 'alex', pass: SECRET },
-    dkim: { signatures: [{ signingDomain: 'example.com', selector: 's', privateKey: SECRET }] },
+    dkim: {
+      signatures: [
+        { signingDomain: 'example.com', selector: 's', privateKey: TEST_DKIM_PRIVATE_KEY },
+      ],
+    },
   }),
   new SmtpTransport({
     host: 'smtp.example.com',
@@ -64,10 +72,12 @@ test('Secrets: no transport shows its credentials to util.inspect() or JSON.stri
   for (const transport of transports()) {
     const inspected = inspect(transport, { depth: Infinity });
     assert.ok(!inspected.includes(SECRET), inspected);
+    assert.ok(!inspected.includes(KEY_LINE), inspected);
     assert.ok(inspected.startsWith(`${transport.constructor.name} `), inspected);
     assert.match(inspected, /\[REDACTED\]/);
     const json = JSON.stringify(transport);
     assert.ok(!json.includes(SECRET), json);
+    assert.ok(!json.includes(KEY_LINE), json);
   }
 });
 

From c551c29202b05160a9e820a3f1447ca8541606f8 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:42:01 +0300
Subject: [PATCH 106/158] fix(retry): rethrow a bug of the wrapped transport

send turned every error the wrapped transport threw into a failed receipt,
after retrying it, so a TypeError from reading a property of undefined
was retried maxAttempts times and then reported like a delivery failure.
A TypeError, RangeError, ReferenceError or SyntaxError that
classifyReceiptError does not recognize now rejects the send at once;
one it does, such as a "fetch failed" with a reset among its causes, is
still retried.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                 |  4 ++++
 CLAUDE.md                    |  4 ++++
 docs/transports/retry.md     |  6 +++++-
 src/retry/retry-transport.js | 13 +++++++++++++
 tests/unit/retry.test.js     | 34 ++++++++++++++++++++++++++++++++++
 5 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c51e2dc..2ed88d8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -236,6 +236,10 @@ fixed ones below.
   parsed and imported for every message, and a broken one failed only at the first send. It is
   now imported once per signature configuration, and `SmtpTransport` throws a `TypeError` for
   a PEM it cannot read, unless `onSigningFailure` is `send-unsigned`.
+- **`./retry` no longer hides a bug of the transport it wraps** (an upstream bug): any thrown
+  error was retried and then turned into a failed receipt, a `TypeError` of a programming
+  mistake included. A built-in error that is no recognizable delivery failure now rejects the
+  send at once; a network failure reported by `fetch` as a `TypeError` is still retried.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index b2f55b0..419a725 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -340,6 +340,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     the first send. It is imported once per signature configuration (`resolvePrivateKey`, a
     WeakMap), and the SMTP transport reads it when it is made (`checkDkimKeys`), unless the
     configuration sends unsigned on a signing failure.
+65. retry: every error the wrapped transport threw became a failed receipt, retried first, so a
+    bug such as reading a property of `undefined` was retried and hidden. A `TypeError`,
+    `RangeError`, `ReferenceError` or `SyntaxError` that `classifyReceiptError` does not
+    recognize (category `unknown`) is rethrown at once; a fetch failure keeps being retried.
 
 ## Repository layout
 
diff --git a/docs/transports/retry.md b/docs/transports/retry.md
index 7244d59..368a307 100644
--- a/docs/transports/retry.md
+++ b/docs/transports/retry.md
@@ -89,7 +89,11 @@ none, so that a duplicate can be told apart.
 If a wrapped transport throws a transient error instead of returning a failed
 receipt, retry transport retries it using the same classifier used by
 *@alexify/mailer*.  After all attempts are exhausted, thrown delivery failures are
-converted into a failed receipt.  Caller cancellation errors are rethrown.
+converted into a failed receipt.  Caller cancellation errors are rethrown, and so
+is a bug of the wrapped transport: a `TypeError`, `RangeError`, `ReferenceError`
+or `SyntaxError` that is no recognizable delivery failure (such as reading a
+property of `undefined`) rejects the send at once, without a retry, while a
+network failure that `fetch` reports as a `TypeError` is still retried.
 
 You can override classification with `shouldRetry` when a provider needs
 application-specific logic:
diff --git a/src/retry/retry-transport.js b/src/retry/retry-transport.js
index d7a5b2d..9498c11 100644
--- a/src/retry/retry-transport.js
+++ b/src/retry/retry-transport.js
@@ -13,6 +13,16 @@ const { createRetryConfig } = require('./config.js');
 /**
  * Transport decorator that retries transient delivery failures.
  */
+// The built-in errors of a bug in code, such as reading a property of
+// undefined, as opposed to a failure of delivery.  A network failure is also
+// a TypeError under fetch ("fetch failed"), but its causes classify it.
+const PROGRAMMER_ERRORS = [TypeError, RangeError, ReferenceError, SyntaxError];
+
+const isProgrammerError = (error) => {
+  if (!PROGRAMMER_ERRORS.some((type) => error instanceof type)) return false;
+  return classifyReceiptError(error).category === 'unknown';
+};
+
 class RetryTransport {
   id;
 
@@ -57,6 +67,9 @@ class RetryTransport {
         receipt = await this.wrappedTransport.send(pinned, options);
       } catch (error) {
         options?.signal?.throwIfAborted();
+        // A bug of the wrapped transport is not a delivery failure to retry
+        // or to hide in a receipt.
+        if (isProgrammerError(error)) throw error;
 
         lastThrownError = error;
         if (
diff --git a/tests/unit/retry.test.js b/tests/unit/retry.test.js
index 0067ed7..90ff296 100644
--- a/tests/unit/retry.test.js
+++ b/tests/unit/retry.test.js
@@ -172,3 +172,37 @@ test('Retry: onRetry hears the retries of the decorator and reaches the wrapped
   ]);
   assert.deepStrictEqual(seen, [onRetry, onRetry, onRetry]);
 });
+
+test('Retry: a bug of the wrapped transport rejects, a network TypeError is retried', async () => {
+  let calls = 0;
+  const bug = new TypeError("Cannot read properties of undefined (reading 'address')");
+  const buggy = {
+    id: 'base',
+    send: async () => {
+      calls++;
+      throw bug;
+    },
+    async *sendMany() {},
+  };
+  const options = { maxAttempts: 3, wait: async () => {} };
+  await assert.rejects(
+    new RetryTransport(buggy, options).send(message()),
+    (error) => error === bug,
+  );
+  assert.strictEqual(calls, 1);
+
+  calls = 0;
+  const network = new TypeError('fetch failed', {
+    cause: Object.assign(new Error('read ECONNRESET'), { code: 'ECONNRESET' }),
+  });
+  const flaky = {
+    ...buggy,
+    send: async () => {
+      calls++;
+      throw network;
+    },
+  };
+  const receipt = await new RetryTransport(flaky, options).send(message());
+  assert.strictEqual(receipt.successful, false);
+  assert.strictEqual(calls, 3);
+});

From 055ad1c14e1e8c6f9a4a82adcddea1f0a38818dc Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:44:00 +0300
Subject: [PATCH 107/158] fix(pool): dispose of every transport once and report
 the failures

Disposal ignored the errors of the transports, synchronous ones with
catch {} and asynchronous ones with allSettled, stopped at a transport
whose asyncDispose threw before returning a promise, and disposed of a
transport listed twice twice. Each transport is now disposed of once,
tracked in a WeakSet, all of them whatever fails, and the failures reject
the disposal together as an AggregateError. The flat test that pinned the
swallowed error now pins this instead. The pool, 0.1 KB under its budget
before, crosses 2 KB with it, so the budget rises to 2.5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml   |  2 +-
 CHANGELOG.md               |  4 +++
 CLAUDE.md                  |  4 +++
 docs/transports/pool.md    |  4 ++-
 src/pool/index.d.ts        |  2 ++
 src/pool/pool-transport.js | 42 +++++++++++++++++------------
 tests/unit/pool.test.js    | 54 ++++++++++++++++++++++++++++++++------
 7 files changed, 85 insertions(+), 27 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6a17fc7..2945b2c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 8 --max-gzip-mime 6.5 --max-gzip-smtp 18.5 --max-gzip-jmap 10.5 --max-gzip-ses 5 --max-gzip-resend 4.5 --max-gzip-sendgrid 4.5 --max-gzip-mailgun 4 --max-gzip-mailtrap 5.5 --max-gzip-maileroo 5 --max-gzip-lettermint 5 --max-gzip-plunk 4.5 --max-gzip-pool 2 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
+      - run: pnpm size --max-gzip 8 --max-gzip-mime 6.5 --max-gzip-smtp 18.5 --max-gzip-jmap 10.5 --max-gzip-ses 5 --max-gzip-resend 4.5 --max-gzip-sendgrid 4.5 --max-gzip-mailgun 4 --max-gzip-mailtrap 5.5 --max-gzip-maileroo 5 --max-gzip-lettermint 5 --max-gzip-plunk 4.5 --max-gzip-pool 2.5 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
 
   types:
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2ed88d8..7435035 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -240,6 +240,10 @@ fixed ones below.
   error was retried and then turned into a failed receipt, a `TypeError` of a programming
   mistake included. A built-in error that is no recognizable delivery failure now rejects the
   send at once; a network failure reported by `fetch` as a `TypeError` is still retried.
+- **`./pool` disposes of every transport and reports what failed** (an upstream bug): disposal
+  dropped the errors of the transports, stopped at one that threw at once, and disposed of a
+  transport listed twice twice. Each transport is now disposed of once, all of them whatever
+  fails, and the failures reject the disposal as an `AggregateError`.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 419a725..8ac1703 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -344,6 +344,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     bug such as reading a property of `undefined` was retried and hidden. A `TypeError`,
     `RangeError`, `ReferenceError` or `SyntaxError` that `classifyReceiptError` does not
     recognize (category `unknown`) is rethrown at once; a fetch failure keeps being retried.
+66. pool: dispose swallowed the errors of the transports (`catch {}`, `allSettled`), stopped at a
+    transport whose async dispose threw before returning a promise, and disposed of a transport
+    listed twice twice. Each is disposed of once (a WeakSet), all of them whatever fails, and
+    the failures reject together as an `AggregateError`.
 
 ## Repository layout
 
diff --git a/docs/transports/pool.md b/docs/transports/pool.md
index 7fc8ef2..19f969c 100644
--- a/docs/transports/pool.md
+++ b/docs/transports/pool.md
@@ -455,7 +455,9 @@ try {
 ```
 
 The pool ensures that all underlying transports are properly cleaned up,
-preventing connection leaks and ensuring graceful shutdown.
+preventing connection leaks and ensuring graceful shutdown. Each transport is
+disposed of once, even when it is listed twice, and one that fails stops no
+other: the disposal rejects afterwards with an `AggregateError` of the failures.
 
 ## Testing with pools
 
diff --git a/src/pool/index.d.ts b/src/pool/index.d.ts
index 4e162f1..139f46a 100644
--- a/src/pool/index.d.ts
+++ b/src/pool/index.d.ts
@@ -237,6 +237,8 @@ export declare class PoolTransport<TProviderId extends string = string>
    *
    * This method is called automatically when using the `await using` syntax.
    * It ensures proper cleanup of resources held by the underlying transports.
+   * Each transport is disposed of once, whichever of them fails.
+   * @throws {AggregateError} With the errors of the transports that failed.
    */
   [Symbol.asyncDispose](): Promise<void>;
 }
diff --git a/src/pool/pool-transport.js b/src/pool/pool-transport.js
index 072862f..aaafe54 100644
--- a/src/pool/pool-transport.js
+++ b/src/pool/pool-transport.js
@@ -238,27 +238,25 @@ class PoolTransport {
    * It ensures proper cleanup of resources held by the underlying transports.
    */
   async [Symbol.asyncDispose]() {
-    const disposalPromises = [];
-
+    const disposals = [];
+    // A transport listed twice is disposed of once.
+    const seen = new WeakSet();
     for (const entry of this.config.transports) {
       const transport = entry.transport;
-
-      // Check for AsyncDisposable
-      if (typeof transport[Symbol.asyncDispose] === 'function') {
-        const asyncDispose = transport[Symbol.asyncDispose]();
-        disposalPromises.push(Promise.resolve(asyncDispose));
-      } // Check for Disposable
-      else if (typeof transport[Symbol.dispose] === 'function') {
-        try {
-          transport[Symbol.dispose]();
-        } catch {
-          // Ignore disposal errors
-        }
-      }
+      if (seen.has(transport)) continue;
+      seen.add(transport);
+      disposals.push(dispose(transport));
     }
 
-    // Wait for all async disposals to complete
-    await Promise.allSettled(disposalPromises);
+    // Every transport is disposed of, whichever fails; the failures come
+    // together afterwards rather than being dropped.
+    const errors = [];
+    for (const result of await Promise.allSettled(disposals)) {
+      if (result.status === 'rejected') errors.push(result.reason);
+    }
+    if (errors.length > 0) {
+      throw new AggregateError(errors, `Failed to dispose of ${errors.length} pooled transports.`);
+    }
   }
 
   /**
@@ -428,4 +426,14 @@ const hasMessageRejection = (errors) => {
   return false;
 };
 
+// Disposes of a transport, asynchronously or not; an error it throws at once
+// rejects rather than stopping the disposal of the others.
+const dispose = async (transport) => {
+  if (typeof transport[Symbol.asyncDispose] === 'function') {
+    await transport[Symbol.asyncDispose]();
+  } else if (typeof transport[Symbol.dispose] === 'function') {
+    transport[Symbol.dispose]();
+  }
+};
+
 module.exports = { PoolTransport };
diff --git a/tests/unit/pool.test.js b/tests/unit/pool.test.js
index ebda8c5..c9e66a5 100644
--- a/tests/unit/pool.test.js
+++ b/tests/unit/pool.test.js
@@ -52,20 +52,58 @@ test('Pool: a timeout applies without a caller signal, and retries stop at the l
   assert.strictEqual(failing.getSentMessagesCount(), 1);
 });
 
-test('Pool: a transport whose dispose throws does not fail the disposal', async () => {
-  const throwing = {
-    id: 'sync',
+test('Pool: every transport is disposed of once, and the failures come together', async () => {
+  const disposed = [];
+  const transport = (id, dispose) => ({
+    id,
     send: async () => ({ successful: true, messageId: 'x' }),
     async *sendMany() {},
-    [Symbol.dispose]() {
-      throw new Error('dispose failed');
+    ...dispose,
+  });
+  const syncError = new Error('sync dispose failed');
+  const asyncError = new Error('async dispose failed');
+  const shared = transport('shared', {
+    async [Symbol.asyncDispose]() {
+      disposed.push('shared');
     },
-  };
+  });
   const pool = new PoolTransport({
     strategy: 'round-robin',
-    transports: [{ transport: throwing }],
+    transports: [
+      {
+        transport: transport('sync', {
+          [Symbol.dispose]() {
+            disposed.push('sync');
+            throw syncError;
+          },
+        }),
+      },
+      // Throws before it returns a promise.
+      {
+        transport: transport('eager', {
+          [Symbol.asyncDispose]() {
+            disposed.push('eager');
+            throw asyncError;
+          },
+        }),
+      },
+      { transport: shared },
+      { transport: shared },
+      {
+        transport: transport('last', {
+          [Symbol.dispose]() {
+            disposed.push('last');
+          },
+        }),
+      },
+    ],
+  });
+  await assert.rejects(pool[Symbol.asyncDispose](), (error) => {
+    assert.ok(error instanceof AggregateError);
+    assert.deepStrictEqual(error.errors, [syncError, asyncError]);
+    return true;
   });
-  await pool[Symbol.asyncDispose]();
+  assert.deepStrictEqual(disposed, ['sync', 'eager', 'shared', 'last']);
 });
 
 const failing = (receipt, sent = []) => ({

From 64b7a1116d983a98a869d8d6655d4822e0c4f312 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:45:01 +0300
Subject: [PATCH 108/158] fix(logger): keep a throwing logger from losing a
 receipt

sendOne logged the receipt inside the try that wrapped the send, so a
logger that threw after a successful send went to the catch, which logged
again and rethrew: the caller saw a rejection for a message that had gone
out, and could send it again. A logger that threw before the send stopped
it. log() now catches the error of the logger and emits it as a process
warning with the code MAILER_LOGGER_FAILED; the send and its receipt go
on unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                   |  5 +++++
 CLAUDE.md                      |  4 ++++
 docs/transports/logger.md      |  5 +++++
 src/logger/logger-transport.js | 13 +++++++++++--
 tests/unit/logger.test.js      | 30 ++++++++++++++++++++++++++++++
 5 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7435035..315ccce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -244,6 +244,11 @@ fixed ones below.
   dropped the errors of the transports, stopped at one that threw at once, and disposed of a
   transport listed twice twice. Each transport is now disposed of once, all of them whatever
   fails, and the failures reject the disposal as an `AggregateError`.
+- **A logger that throws no longer loses a receipt** (an upstream bug): when the logger of
+  `./logger` threw after a successful send, the send rejected, and a caller could send the
+  message again; one that threw before stopped the send. The failure of the logger is now
+  emitted as a process warning with the code `MAILER_LOGGER_FAILED`, and the send and its
+  receipt go on.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index 8ac1703..ee775cf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -348,6 +348,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     transport whose async dispose threw before returning a promise, and disposed of a transport
     listed twice twice. Each is disposed of once (a WeakSet), all of them whatever fails, and
     the failures reject together as an `AggregateError`.
+67. logger: a logger that threw after a successful send turned the send into a rejection, so
+    the receipt was lost and a caller could send the message again; one that threw before
+    stopped the send. `log()` catches it and emits a process warning
+    (`MAILER_LOGGER_FAILED`); the send and its receipt go on.
 
 ## Repository layout
 
diff --git a/docs/transports/logger.md b/docs/transports/logger.md
index 63c1839..ae58804 100644
--- a/docs/transports/logger.md
+++ b/docs/transports/logger.md
@@ -89,6 +89,11 @@ to disposable wrapped transports. Completion logs are emitted as callers consume
 receipts. If a caller stops reading a batch early, the wrapped iterator is closed
 without being drained so the logging layer does not start additional delivery work.
 
+A logger that throws changes nothing of the delivery: the message is still sent,
+its receipt still comes back, and the failure is emitted as a process warning
+with the code `MAILER_LOGGER_FAILED` (`process.on('warning', …)`), since losing
+the receipt could make the caller send the message again.
+
 The retries of the wrapped transport, those an HTTP provider makes on its own and
 those of a `./retry` inside the logger transport, are logged as `email.retrying`
 events, with the attempt that failed, the wait in milliseconds, the text of the
diff --git a/src/logger/logger-transport.js b/src/logger/logger-transport.js
index ddd6331..673de67 100644
--- a/src/logger/logger-transport.js
+++ b/src/logger/logger-transport.js
@@ -317,9 +317,18 @@ class LoggerTransport {
     return `${lifecycleMessage}\n\nSubject: ${message.subject}\n\n${content}`;
   }
 
-  // The properties first and the message second, as pino takes them.
+  // The properties first and the message second, as pino takes them.  A
+  // logger that throws changes nothing of the send: the message still goes,
+  // its receipt still comes back (losing it could have the caller send it
+  // again), and the failure becomes a process warning rather than vanishing.
   log(level, message, properties) {
-    this.logger[level](properties, message);
+    try {
+      this.logger[level](properties, message);
+    } catch (error) {
+      process.emitWarning(`The logger of LoggerTransport threw: ${describe(error)}`, {
+        code: 'MAILER_LOGGER_FAILED',
+      });
+    }
   }
 }
 
diff --git a/tests/unit/logger.test.js b/tests/unit/logger.test.js
index 8bc6ecc..a63bc9c 100644
--- a/tests/unit/logger.test.js
+++ b/tests/unit/logger.test.js
@@ -150,3 +150,33 @@ test('Logger: a retry of the wrapped transport is logged, and still reaches onRe
     'base',
   );
 });
+
+test('Logger: a logger that throws loses no receipt and stops no send', async (t) => {
+  const warnings = t.mock.method(process, 'emitWarning', () => {});
+  const broken = () => {
+    throw new Error('Log sink is down');
+  };
+  const logger = { debug: broken, info: broken, warn: broken, error: broken };
+  let sent = 0;
+  const base = {
+    id: 'base',
+    send: async () => {
+      sent++;
+      return { successful: true, messageId: 'm1' };
+    },
+    async *sendMany(messages) {
+      for await (const sentMessage of messages) yield await base.send(sentMessage);
+    },
+  };
+  const transport = new LoggerTransport({ transport: base, logger });
+  assert.deepStrictEqual(await transport.send(message()), { successful: true, messageId: 'm1' });
+  for await (const receipt of transport.sendMany([message()])) {
+    assert.strictEqual(receipt.successful, true);
+  }
+  assert.strictEqual(sent, 2);
+  assert.ok(warnings.mock.callCount() >= 4);
+  assert.deepStrictEqual(warnings.mock.calls[0].arguments, [
+    'The logger of LoggerTransport threw: Error: Log sink is down',
+    { code: 'MAILER_LOGGER_FAILED' },
+  ]);
+});

From 0fe4087cb562687b0705c91583116a257f7d5472 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:46:34 +0300
Subject: [PATCH 109/158] refactor: give the abortable sleep a module of its
 own

The sleep that rejects with the reason of its signal, and abortReason,
lived in internal/http.js beside the retry loop, so a decorator that only
waits would bundle the whole of it. They move to internal/sleep.js, which
http.js requires and still exports, and the default wait of ./retry uses
it instead of its own copy of the same promise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/internal/http.js  | 36 +-----------------------------------
 src/internal/sleep.js | 40 ++++++++++++++++++++++++++++++++++++++++
 src/retry/config.js   | 27 +++------------------------
 3 files changed, 44 insertions(+), 59 deletions(-)
 create mode 100644 src/internal/sleep.js

diff --git a/src/internal/http.js b/src/internal/http.js
index 1de5666..6942b00 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -5,44 +5,10 @@
 const { combineSignals } = require('../core/abort-signal.js');
 const { markDeliveryUnknown } = require('./delivery-unknown.js');
 const { isUnsentRequestError } = require('./unsent.js');
+const { abortReason, sleep } = require('./sleep.js');
 
 const isAbortError = (error) => error instanceof Error && error.name === 'AbortError';
 
-/**
- * The reason of an aborted signal, or an `AbortError` when it has none.
- *
- * @param signal The aborted signal.
- * @returns The value to reject or throw with.
- * @internal
- */
-const abortReason = (signal) =>
-  signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
-
-/**
- * Waits, and stops waiting when the signal aborts, rejecting with its reason.
- *
- * @param milliseconds How long to wait.
- * @param signal The caller's signal.
- * @returns A promise settled when the wait ends.
- * @internal
- */
-const sleep = (milliseconds, signal) =>
-  new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(abortReason(signal));
-      return;
-    }
-    const onAbort = () => {
-      clearTimeout(timer);
-      reject(abortReason(signal));
-    };
-    const timer = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort);
-      resolve();
-    }, milliseconds);
-    signal?.addEventListener('abort', onAbort, { once: true });
-  });
-
 /**
  * The delay before retry `attempt` (from 0): one second, doubled each time.
  *
diff --git a/src/internal/sleep.js b/src/internal/sleep.js
new file mode 100644
index 0000000..8743ea1
--- /dev/null
+++ b/src/internal/sleep.js
@@ -0,0 +1,40 @@
+// Not ported from upyo: the wait of a retry or a delay, which upstream wrote in
+// five ways, some deaf to the AbortSignal or rejecting with an error of their
+// own instead of its reason.
+
+/**
+ * The reason of an aborted signal, or an `AbortError` when it has none.
+ *
+ * @param signal The aborted signal.
+ * @returns The value to reject or throw with.
+ * @internal
+ */
+const abortReason = (signal) =>
+  signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+
+/**
+ * Waits, and stops waiting when the signal aborts, rejecting with its reason.
+ *
+ * @param milliseconds How long to wait.
+ * @param signal The caller's signal.
+ * @returns A promise settled when the wait ends.
+ * @internal
+ */
+const sleep = (milliseconds, signal) =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, milliseconds);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+
+module.exports = { abortReason, sleep };
diff --git a/src/retry/config.js b/src/retry/config.js
index ff76cc1..8d63a8e 100644
--- a/src/retry/config.js
+++ b/src/retry/config.js
@@ -1,6 +1,8 @@
 // Ported from upyo v0.7.0 (packages/retry/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { sleep } = require('../internal/sleep.js');
+
 /**
  * Creates a resolved retry configuration.
  *
@@ -44,26 +46,7 @@ const createRetryConfig = (config = {}) => {
 const defaultWait = async (context, signal) => {
   signal?.throwIfAborted();
   if (context.delayMilliseconds <= 0) return;
-
-  await new Promise((resolve, reject) => {
-    const cleanup = () => signal?.removeEventListener('abort', abort);
-    const timeout = setTimeout(() => {
-      cleanup();
-      resolve();
-    }, context.delayMilliseconds);
-    const abort = () => {
-      clearTimeout(timeout);
-      cleanup();
-      reject(signal?.reason ?? createAbortError());
-    };
-
-    if (signal?.aborted) {
-      abort();
-      return;
-    }
-
-    signal?.addEventListener('abort', abort, { once: true });
-  });
+  await sleep(context.delayMilliseconds, signal);
 };
 
 const assertIntegerAtLeast = (value, minimum, name) => {
@@ -78,8 +61,4 @@ const assertFiniteAtLeast = (value, minimum, name) => {
   }
 };
 
-const createAbortError = () => {
-  return new DOMException('The operation was aborted.', 'AbortError');
-};
-
 module.exports = { createRetryConfig };

From cd2f4ce51b65571eb581c8e4527f5d657c69bfbf Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:47:54 +0300
Subject: [PATCH 110/158] fix(mock): end the simulated delay when the signal
 aborts

applyDelay waited on a bare setTimeout, so a send with a delay ran to its
end whatever its signal said, and the checks around it threw a new
AbortError instead of the reason of the signal. The delay is now the
abortable sleep of internal/sleep.js, and send and sendMany check the
signal with throwIfAborted, so an abort ends the wait at once and rejects
with its reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  3 +++
 CLAUDE.md                  |  3 +++
 docs/transports/mock.md    |  6 ++++--
 src/mock/mock-transport.js | 22 +++++++---------------
 tests/unit/mock.test.js    | 12 ++++++++++++
 5 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 315ccce..4c8084b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -249,6 +249,9 @@ fixed ones below.
   message again; one that threw before stopped the send. The failure of the logger is now
   emitted as a process warning with the code `MAILER_LOGGER_FAILED`, and the send and its
   receipt go on.
+- **`./mock` honors an abort during its delay** (an upstream bug): the simulated delay ran to its
+  end whatever the signal said, and an abort rejected with a new `AbortError`. An abort now ends
+  the delay at once, and the send rejects with the reason of the signal.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index ee775cf..a570adf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -352,6 +352,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     the receipt was lost and a caller could send the message again; one that threw before
     stopped the send. `log()` catches it and emits a process warning
     (`MAILER_LOGGER_FAILED`); the send and its receipt go on.
+68. mock: the simulated delay ignored the `AbortSignal`, and an abort rejected with a new
+    `AbortError` instead of the reason of the signal. The delay is the abortable sleep of
+    `internal/sleep.js`, and every abort rejects with the reason.
 
 ## Repository layout
 
diff --git a/docs/transports/mock.md b/docs/transports/mock.md
index c288808..84c040e 100644
--- a/docs/transports/mock.md
+++ b/docs/transports/mock.md
@@ -102,8 +102,10 @@ try {
 ```
 
 Delay simulation helps test timeout handling and ensures your application
-can handle slower network conditions. Failure simulation verifies that your
-error handling code works correctly when email services are unavailable.
+can handle slower network conditions: an `AbortSignal` passed to the send ends
+the delay at once, and the send rejects with the reason of the signal, as a
+real transport does. Failure simulation verifies that your error handling code
+works correctly when email services are unavailable.
 
 ## Testing specific failure scenarios
 
diff --git a/src/mock/mock-transport.js b/src/mock/mock-transport.js
index 8d6e039..4e99188 100644
--- a/src/mock/mock-transport.js
+++ b/src/mock/mock-transport.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/mock/src/mock-transport.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { sleep } = require('../internal/sleep.js');
 const { createFailedReceipt } = require('../core/receipt.js');
 const { createMockConfig } = require('./config.js');
 
@@ -46,17 +47,10 @@ class MockTransport {
    */
   async send(message, options) {
     // Check for cancellation
-    if (options?.signal?.aborted) {
-      throw new DOMException('The operation was aborted.', 'AbortError');
-    }
-
-    // Apply delay if configured
-    await this.applyDelay();
+    options?.signal?.throwIfAborted();
 
-    // Check for cancellation after delay
-    if (options?.signal?.aborted) {
-      throw new DOMException('The operation was aborted.', 'AbortError');
-    }
+    // Apply delay if configured; an abort ends it with the signal's reason.
+    await this.applyDelay(options?.signal);
 
     // Store the message
     this.sentMessages.push(message);
@@ -80,9 +74,7 @@ class MockTransport {
    */
   async *sendMany(messages, options) {
     for await (const message of messages) {
-      if (options?.signal?.aborted) {
-        throw new DOMException('The operation was aborted.', 'AbortError');
-      }
+      options?.signal?.throwIfAborted();
       yield await this.send(message, options);
     }
   }
@@ -323,7 +315,7 @@ class MockTransport {
     this.messageIdCounter = 1;
   }
 
-  async applyDelay() {
+  async applyDelay(signal) {
     let delayMs = this.config.delay;
 
     if (
@@ -335,7 +327,7 @@ class MockTransport {
     }
 
     if (delayMs > 0) {
-      await new Promise((resolve) => setTimeout(resolve, delayMs));
+      await sleep(delayMs, signal);
     }
   }
 
diff --git a/tests/unit/mock.test.js b/tests/unit/mock.test.js
index ebe29c1..0069037 100644
--- a/tests/unit/mock.test.js
+++ b/tests/unit/mock.test.js
@@ -71,3 +71,15 @@ test('Mock: waiting for messages times out', async () => {
     { message: 'Timeout waiting for message' },
   );
 });
+
+test('Mock: an abort ends the configured delay, with the reason of the signal', async () => {
+  const transport = new MockTransport({ delay: 5000 });
+  const controller = new AbortController();
+  const reason = new Error('Stop.');
+  const started = performance.now();
+  const sending = transport.send(message('Hello'), { signal: controller.signal });
+  setTimeout(() => controller.abort(reason), 20);
+  await assert.rejects(sending, (error) => error === reason);
+  assert.ok(performance.now() - started < 1000);
+  assert.strictEqual(transport.getSentMessagesCount(), 0);
+});

From 62f1d465c66ebc0c938437731b8e7855f7946b23 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:48:37 +0300
Subject: [PATCH 111/158] fix(pool): reject an aborted send with the reason of
 the signal

send and sendMany checked signal.aborted and threw a new AbortError, so a
caller that aborted with a reason of its own, such as a timeout error or
a shutdown, got a different error back than from every other transport.
Both now call throwIfAborted, which rejects with the reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  2 ++
 CLAUDE.md                  |  2 ++
 src/pool/pool-transport.js |  8 ++------
 tests/unit/pool.test.js    | 13 +++++++++++++
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4c8084b..134cfba 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -252,6 +252,8 @@ fixed ones below.
 - **`./mock` honors an abort during its delay** (an upstream bug): the simulated delay ran to its
   end whatever the signal said, and an abort rejected with a new `AbortError`. An abort now ends
   the delay at once, and the send rejects with the reason of the signal.
+- **`./pool` rejects an aborted send with the reason of the signal** (an upstream bug), not with
+  a new `AbortError`, like the other transports.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index a570adf..c7f9fea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -355,6 +355,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 68. mock: the simulated delay ignored the `AbortSignal`, and an abort rejected with a new
     `AbortError` instead of the reason of the signal. The delay is the abortable sleep of
     `internal/sleep.js`, and every abort rejects with the reason.
+69. pool: a send or a batch aborted by the caller rejected with a new `AbortError` rather than
+    the reason of the signal. It rejects with the reason.
 
 ## Repository layout
 
diff --git a/src/pool/pool-transport.js b/src/pool/pool-transport.js
index aaafe54..8e68bdf 100644
--- a/src/pool/pool-transport.js
+++ b/src/pool/pool-transport.js
@@ -108,9 +108,7 @@ class PoolTransport {
 
     for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
       // Check for cancellation
-      if (options?.signal?.aborted) {
-        throw new DOMException('The operation was aborted.', 'AbortError');
-      }
+      options?.signal?.throwIfAborted();
 
       // Select a transport
       const selection = this.strategy.select(pinned, this.config.transports, attemptedIndices);
@@ -223,9 +221,7 @@ class PoolTransport {
     this.strategy.reset();
 
     for await (const message of messages) {
-      if (options?.signal?.aborted) {
-        throw new DOMException('The operation was aborted.', 'AbortError');
-      }
+      options?.signal?.throwIfAborted();
 
       yield await this.send(message, options);
     }
diff --git a/tests/unit/pool.test.js b/tests/unit/pool.test.js
index c9e66a5..157b7a2 100644
--- a/tests/unit/pool.test.js
+++ b/tests/unit/pool.test.js
@@ -161,3 +161,16 @@ test('Pool: every transport of a failover sends the same Message-ID', async () =
   assert.ok(sent[0].messageId);
   assert.strictEqual(sent[0].messageId, sent[1].messageId);
 });
+
+test('Pool: an abort rejects with the reason of the signal', async () => {
+  const controller = new AbortController();
+  const reason = new Error('Stop.');
+  controller.abort(reason);
+  const pool = new PoolTransport({
+    strategy: 'round-robin',
+    transports: [{ transport: failing({ successful: true, messageId: 'x' }) }],
+  });
+  await assert.rejects(pool.send(message(), { signal: controller.signal }), (e) => e === reason);
+  const batch = pool.sendMany([message()], { signal: controller.signal });
+  await assert.rejects(batch[Symbol.asyncIterator]().next(), (e) => e === reason);
+});

From b9833f609848b84b6fd34979d6cc64647efc01d3 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:50:23 +0300
Subject: [PATCH 112/158] fix(mime): draw a boundary from crypto.randomUUID

generateBoundary joined Date.now() with six characters of Math.random(),
through the deprecated substr, so two messages composed in the same
millisecond could share a boundary, and content that guessed it could end
a part early and add one of its own. A boundary is now boundary- and a
random UUID, which no message text is expected to contain.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  3 +++
 CLAUDE.md               |  3 +++
 src/mime/message.js     |  4 +++-
 tests/unit/mime.test.js | 18 ++++++++++++++++++
 4 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 134cfba..026c342 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -55,6 +55,9 @@ fixed ones below.
 
 ### Security
 
+- **A MIME boundary can no longer be guessed** (an upstream bug): it was built from the clock and
+  `Math.random()`, so content that knew it could close a part early and add one of its own. It
+  now comes from `crypto.randomUUID()`.
 - **A DKIM setting can no longer add a header field** (an upstream bug): the signing domain,
   the selector, the signed field names, the algorithm and the canonicalization went into the
   `DKIM-Signature` field as given, so a domain such as `example.com\r\nBcc: …` added a Bcc to
diff --git a/CLAUDE.md b/CLAUDE.md
index c7f9fea..f805d08 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -357,6 +357,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     `internal/sleep.js`, and every abort rejects with the reason.
 69. pool: a send or a batch aborted by the caller rejected with a new `AbortError` rather than
     the reason of the signal. It rejects with the reason.
+70. mime: a boundary was `Date.now()` and six characters of `Math.random()` (with the
+    deprecated `substr`), which two messages in one millisecond can share and an attacker can
+    guess to end a part early with text of their own. It is `boundary-` and `crypto.randomUUID()`.
 
 ## Repository layout
 
diff --git a/src/mime/message.js b/src/mime/message.js
index 66d2e70..f8354a6 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -404,8 +404,10 @@ const hasNonAsciiText = (headers, parts) => {
   return false;
 };
 
+// A boundary must not occur in the parts it separates, which nothing checks,
+// so it is unguessable rather than derived from the clock and Math.random.
 const generateBoundary = () => {
-  return `boundary-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  return `boundary-${crypto.randomUUID()}`;
 };
 
 /**
diff --git a/tests/unit/mime.test.js b/tests/unit/mime.test.js
index b93e69a..409dc3f 100644
--- a/tests/unit/mime.test.js
+++ b/tests/unit/mime.test.js
@@ -180,3 +180,21 @@ test('MIME: a DKIM failure throws, or sends unsigned when asked to', async (t) =
     message: 'Expected DKIM bodyMode to be buffered or streaming.',
   });
 });
+
+test('MIME: a boundary is random, not derived from the clock and Math.random', async (t) => {
+  t.mock.method(Math, 'random', () => 0.5);
+  t.mock.timers.enable({ apis: ['Date'], now: 0 });
+  const boundaries = new Set();
+  for (let i = 0; i < 2; i++) {
+    const text = await wire(
+      createMessage({ ...base, subject: 'Hi', content: { text: 'Hi', html: '<p>Hi</p>' } }),
+    );
+    const boundary = /boundary="([^"]+)"/.exec(text)[1];
+    assert.match(
+      boundary,
+      /^boundary-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+    boundaries.add(boundary);
+  }
+  assert.strictEqual(boundaries.size, 2);
+});

From 8dcf2590e5514fd91f784f4acd89965d74a6a222 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:51:28 +0300
Subject: [PATCH 113/158] fix(resend): draw an idempotency key from
 crypto.randomUUID

generateIdempotencyKey joined the clock with two Math.random() strings,
so two sends could share a key, and Resend answers a repeated key with
the answer to the first request: the second message would never go out,
reported as sent (known upstream bug 11). A key is now a random UUID.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                    |  3 +++
 CLAUDE.md                       |  5 ++++-
 docs/guide/known-issues.md      |  1 -
 src/resend/message-converter.js | 13 ++++---------
 tests/unit/resend.test.js       |  9 +++++++++
 5 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 026c342..19ed363 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -257,6 +257,9 @@ fixed ones below.
   the delay at once, and the send rejects with the reason of the signal.
 - **`./pool` rejects an aborted send with the reason of the signal** (an upstream bug), not with
   a new `AbortError`, like the other transports.
+- **`./resend` draws its idempotency key from `crypto.randomUUID()`** (known upstream bug 11): it
+  came from the clock and `Math.random()`, and two sends that shared a key by chance would get
+  the first one's answer, the second never going out.
 - **`./retry` no longer retries sooner than a server asks** (an upstream bug): a `Retry-After`
   longer than `maxDelayMilliseconds` was cut to it, so the retry most likely met the same rate
   limit. The failed receipt is returned at once, with its delay.
diff --git a/CLAUDE.md b/CLAUDE.md
index f805d08..470dc29 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -141,7 +141,7 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
 10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
-11. resend: the `Idempotency-Key` comes from `Math.random`.
+11. (fixed, see 71) resend: the `Idempotency-Key` came from `Math.random`.
 12. `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of `process.emitWarning` or
     an injected logger.
 13. mime: the first encoded word of a header shares its line with the field name
@@ -360,6 +360,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 70. mime: a boundary was `Date.now()` and six characters of `Math.random()` (with the
     deprecated `substr`), which two messages in one millisecond can share and an attacker can
     guess to end a part early with text of their own. It is `boundary-` and `crypto.randomUUID()`.
+71. resend (known bug 11): a generated `Idempotency-Key` was the clock and two `Math.random()`
+    strings, which two sends could share, and Resend answers a repeated key with its first
+    answer, so one of them would not go. It is `crypto.randomUUID()`.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 807cc74..09389b5 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -21,7 +21,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 - `validateSsl` is accepted and never read (SES, Resend, SendGrid, Mailgun, Mailtrap, Plunk).
 - Mailgun sends an inline attachment under its file name rather than its `contentId`, so a
   `cid:` in the HTML does not match it.
-- Resend's `Idempotency-Key` comes from `Math.random`.
 - SES: custom and threading headers are not sent.
 - Plunk: an attachment that cannot be read is left out with a `console.warn`.
 - JMAP does not report its retries through `onRetry`.
diff --git a/src/resend/message-converter.js b/src/resend/message-converter.js
index a3688fd..f0985f1 100644
--- a/src/resend/message-converter.js
+++ b/src/resend/message-converter.js
@@ -220,17 +220,12 @@ const isStandardHeader = (headerName) => {
 };
 
 /**
- * Generates a random idempotency key for request deduplication.
+ * Generates a random idempotency key for request deduplication: a UUID from
+ * crypto.randomUUID, since Resend answers a repeated key with the first
+ * answer, and two sends sharing a key by chance would lose one of them.
  *
  * @returns A unique string suitable for use as an idempotency key
  */
-const generateIdempotencyKey = () => {
-  // Generate a UUID-like string
-  const timestamp = Date.now().toString(36);
-  const random1 = Math.random().toString(36).substring(2, 15);
-  const random2 = Math.random().toString(36).substring(2, 15);
-
-  return `${timestamp}-${random1}${random2}`;
-};
+const generateIdempotencyKey = () => crypto.randomUUID();
 
 module.exports = { convertMessage, convertMessagesBatch, generateIdempotencyKey };
diff --git a/tests/unit/resend.test.js b/tests/unit/resend.test.js
index abbfb55..8964cbe 100644
--- a/tests/unit/resend.test.js
+++ b/tests/unit/resend.test.js
@@ -116,3 +116,12 @@ test('Resend: an abort during the wait between attempts ends the send at once',
   );
   assert.ok(performance.now() - started < 500);
 });
+
+test('Resend: an idempotency key is random, not derived from the clock and Math.random', (t) => {
+  const { generateIdempotencyKey } = require('../../src/resend/message-converter.js');
+  t.mock.method(Math, 'random', () => 0.5);
+  t.mock.timers.enable({ apis: ['Date'], now: 0 });
+  const first = generateIdempotencyKey();
+  assert.notStrictEqual(first, generateIdempotencyKey());
+  assert.match(first, /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+});

From 2525bbeba4cc2320069f51164be8390f58de2af7 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:53:41 +0300
Subject: [PATCH 114/158] feat(core): let the application generate the
 identifiers

Message-IDs and Content-IDs came from crypto.randomUUID() with no way for
an application to use the identifiers of its own records (cuid2, ULID,
nanoid) or deterministic ones in tests. An IdGenerator, (kind) => string,
now makes them where it is passed: generateMessageId and createMessage
take { generateId }, as does the internal pinMessageId. It returns the
left half of a Message-ID or a Content-ID, and src/core/id.js checks what
it returns, dot-atom-text for those kinds and printable ASCII of at most
256 characters for every kind, since a line break or an angle bracket
would end the field it goes into.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |  5 ++++
 index.d.ts                  | 43 +++++++++++++++++++++++++++---
 src/core/id.js              | 53 +++++++++++++++++++++++++++++++++++++
 src/core/message-id.js      | 30 ++++++++++++++-------
 src/core/message.js         | 10 ++++---
 tests/types/index.test-d.ts |  8 ++++++
 tests/unit/core.test.js     | 40 ++++++++++++++++++++++++++++
 7 files changed, 172 insertions(+), 17 deletions(-)
 create mode 100644 src/core/id.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 19ed363..9405108 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,11 @@ fixed ones below.
 - **`onRetry` in the options of a send:** the HTTP providers and `./retry` call it before each
   retry with the attempt, the wait and the error, and the decorators pass it on, so one callback
   hears every level (not yet from `./jmap`).
+- **`generateId` for the identifiers the library makes:** an `IdGenerator` (`(kind) => string`,
+  with `IdKind` one of `message-id`, `content-id`, `idempotency-key` and `receipt-id`) can
+  replace `crypto.randomUUID()`, such as a cuid2, a ULID or a nanoid. `generateMessageId` and
+  `createMessage` take it in their options; it gives the left half of a Message-ID or a
+  Content-ID, and what it returns is checked (a `TypeError` otherwise).
 - **`./logger` logs retries** as `email.retrying` events, at the new level `levels.retrying`
   (`warn` by default), with the attempt, the wait, the redacted error text and its status code.
   With a wrapped transport, the logger needs a method for that level.
diff --git a/index.d.ts b/index.d.ts
index 3869f6a..d6dea2d 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -663,6 +663,8 @@ export interface MessageConstructor {
  * @param constructor The constructor parameters for the message. Uses more
  *                    user-friendly types like accepting strings for email
  *                    addresses and `File` objects for attachments.
+ * @param options `generateId`, which makes the left half of the Content-ID of
+ *                a `File` attachment instead of a UUID.
  * @returns A new {@link Message} object with all properties normalized and
  *          validated.
  * @throws {TypeError} When any email address string cannot be parsed, when an
@@ -671,9 +673,13 @@ export interface MessageConstructor {
  *                     object is invalid, when a message identifier is not
  *                     valid, when the date is not one RFC 5322 can express, or
  *                     when the calendar content is not a single well-formed
- *                     iCalendar object declaring one supported method.
+ *                     iCalendar object declaring one supported method, or when
+ *                     `generateId` returns no dot-atom-text.
  */
-export declare function createMessage(constructor: MessageConstructor): Message;
+export declare function createMessage(
+  constructor: MessageConstructor,
+  options?: IdOptions,
+): Message;
 
 /**
  * Generates a globally unique message identifier rooted in a domain.
@@ -698,10 +704,39 @@ export declare function createMessage(constructor: MessageConstructor): Message;
  * ```
  *
  * @param domain The domain the identifier is rooted in.
+ * @param options `generateId`, which makes the left half instead of a UUID.
  * @returns A bare message identifier, without angle brackets.
- * @throws {TypeError} If the domain is not a valid identifier right-hand side.
+ * @throws {TypeError} If the domain is not a valid identifier right-hand side,
+ *                     or `generateId` returns no dot-atom-text.
  */
-export declare function generateMessageId(domain: string): string;
+export declare function generateMessageId(domain: string, options?: IdOptions): string;
+
+/**
+ * What an identifier the library generates is for: the left half of a
+ * Message-ID or a Content-ID, the idempotency key of a request, or the
+ * message ID of a receipt that a provider did not give one for.
+ */
+export type IdKind = 'message-id' | 'content-id' | 'idempotency-key' | 'receipt-id';
+/**
+ * Makes the identifiers the library would otherwise draw from
+ * `crypto.randomUUID()`, such as a cuid2, a ULID or a nanoid, to correlate
+ * them with the records of the application.  For a Message-ID or a
+ * Content-ID it returns the left half only, and the library adds `@` and the
+ * domain.  What it returns is checked: dot-atom-text for those two kinds, and
+ * printable ASCII without spaces, at most 256 characters, for every kind;
+ * anything else is a `TypeError` before a message is sent.
+ */
+export type IdGenerator = (kind: IdKind) => string;
+/**
+ * Options of the functions and transports that generate identifiers.
+ */
+export interface IdOptions {
+  /**
+   * The generator of the identifiers.
+   * @default () => crypto.randomUUID()
+   */
+  readonly generateId?: IdGenerator;
+}
 /**
  * Parses a message identifier, with or without the enclosing angle brackets,
  * into its bare form.
diff --git a/src/core/id.js b/src/core/id.js
new file mode 100644
index 0000000..8d8dacc
--- /dev/null
+++ b/src/core/id.js
@@ -0,0 +1,53 @@
+// Not ported from upyo: the identifiers the library generates, from a generator
+// the application may pass in (cuid2, ulid, nanoid, ...) to correlate them with
+// its own records, checked before they reach a header field or a request.
+
+const { isDotAtomText } = require('./text.js');
+
+const MAX_ID_LENGTH = 256;
+
+/**
+ * The generator used when none is passed in: a random UUID for every kind.
+ *
+ * @returns A random UUID.
+ * @internal
+ */
+const defaultIdGenerator = () => crypto.randomUUID();
+
+const isPrintableAscii = (value) => {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < 0x21 || code > 0x7e) return false;
+  }
+  return true;
+};
+
+/**
+ * Generates an identifier of a kind and checks it.  The left part of a
+ * Message-ID or a Content-ID must be dot-atom-text (RFC 5322 §3.2.3), and
+ * every kind printable ASCII without spaces, at most 256 characters: a value
+ * with a line break or an angle bracket would end the field it goes into.
+ *
+ * @param kind `message-id`, `content-id`, `idempotency-key` or `receipt-id`.
+ * @param generator The generator of the application, or the default one.
+ * @returns The identifier.
+ * @throws {TypeError} If the generator returns anything else.
+ * @internal
+ */
+const generateId = (kind, generator = defaultIdGenerator) => {
+  const value = generator(kind);
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.length > MAX_ID_LENGTH ||
+    !isPrintableAscii(value) ||
+    ((kind === 'message-id' || kind === 'content-id') && !isDotAtomText(value))
+  ) {
+    throw new TypeError(
+      `Invalid ${kind} from generateId: ${JSON.stringify(String(value).slice(0, 100))}.`,
+    );
+  }
+  return value;
+};
+
+module.exports = { defaultIdGenerator, generateId };
diff --git a/src/core/message-id.js b/src/core/message-id.js
index 579c029..2500544 100644
--- a/src/core/message-id.js
+++ b/src/core/message-id.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/core/src/message-id.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { generateId } = require('./id.js');
 const { isDotAtomText, isDtextBetween } = require('./text.js');
 
 /**
@@ -26,11 +27,14 @@ const { isDotAtomText, isDtextBetween } = require('./text.js');
  * ```
  *
  * @param domain The domain the identifier is rooted in.
+ * @param options `generateId`, which makes the left half instead of a UUID.
  * @returns A bare message identifier, without angle brackets.
- * @throws {TypeError} If the domain is not a valid identifier right-hand side.
+ * @throws {TypeError} If the domain is not a valid identifier right-hand side,
+ *                     or `generateId` returns no dot-atom-text.
  */
-const generateMessageId = (domain) => {
-  return `${crypto.randomUUID()}@${normalizeIdRight(domain)}`;
+const generateMessageId = (domain, options) => {
+  const right = normalizeIdRight(domain);
+  return `${generateId('message-id', options?.generateId)}@${right}`;
 };
 
 /**
@@ -231,19 +235,24 @@ const resolveThreadingHeaders = (message) => {
  * `parseAddress()` accepts spellings the identifier grammar does not, such as
  * the trailing dot of a fully qualified name, which is dropped here.  A domain
  * the grammar still refuses falls back to `localhost` rather than failing the
- * send.  Uniqueness holds either way: the left half is a UUID.
+ * send.  Uniqueness holds either way: the left half is a UUID, or what the
+ * generator of the application makes.
  *
  * @param address The sender's address.
+ * @param generator Optional generator of the left half.
  * @returns A bare message identifier.
+ * @throws {TypeError} If the generator returns no dot-atom-text.
  * @internal
  */
-const generateSenderMessageId = (address) => {
-  const domain = domainOf(address).replace(/\.$/, '');
+const generateSenderMessageId = (address, generator) => {
+  const left = generateId('message-id', generator);
+  let right;
   try {
-    return generateMessageId(domain);
+    right = normalizeIdRight(domainOf(address).replace(/\.$/, ''));
   } catch {
-    return generateMessageId('localhost');
+    right = 'localhost';
   }
+  return `${left}@${right}`;
 };
 
 /**
@@ -277,19 +286,20 @@ const pinnedMessages = new WeakMap();
  * an ambiguous failure would not read as one to its recipients' servers.
  *
  * @param message The message to send.
+ * @param generator Optional generator of the left half of the identifier.
  * @returns The message itself when it has a Message-ID, either as
  * `messageId` or as a custom header; otherwise a copy carrying a generated
  * one, the same copy on every call for the same message.
  * @internal
  */
-const pinMessageId = (message) => {
+const pinMessageId = (message, generator) => {
   if (typeof message !== 'object' || message === null || message.sender == null) return message;
   if (message.messageId !== undefined || message.headers?.get('Message-ID') != null) {
     return message;
   }
   let pinned = pinnedMessages.get(message);
   if (pinned === undefined) {
-    pinned = { ...message, messageId: generateSenderMessageId(message.sender.address) };
+    pinned = { ...message, messageId: generateSenderMessageId(message.sender.address, generator) };
     pinnedMessages.set(message, pinned);
   }
   return pinned;
diff --git a/src/core/message.js b/src/core/message.js
index 48c5a25..307bb12 100644
--- a/src/core/message.js
+++ b/src/core/message.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/core/src/message.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { generateId } = require('./id.js');
 const { parseAddress } = require('./address.js');
 const { isAttachment } = require('./attachment.js');
 const { resolveCalendarContent } = require('./calendar.js');
@@ -24,6 +25,8 @@ const { parseMessageId } = require('./message-id.js');
  * @param constructor The constructor parameters for the message. Uses more
  *                    user-friendly types like accepting strings for email
  *                    addresses and `File` objects for attachments.
+ * @param options `generateId`, which makes the left half of the Content-ID of
+ *                a `File` attachment instead of a UUID.
  * @returns A new {@link Message} object with all properties normalized and
  *          validated.
  * @throws {TypeError} When any email address string cannot be parsed, when an
@@ -32,9 +35,10 @@ const { parseMessageId } = require('./message-id.js');
  *                     object is invalid, when a message identifier is not
  *                     valid, when the date is not one RFC 5322 can express, or
  *                     when the calendar content is not a single well-formed
- *                     iCalendar object declaring one supported method.
+ *                     iCalendar object declaring one supported method, or when
+ *                     `generateId` returns no dot-atom-text.
  */
-const createMessage = (constructor) => {
+const createMessage = (constructor, options) => {
   const sender = checkAddress('sender', constructor.from);
   return {
     sender,
@@ -55,7 +59,7 @@ const createMessage = (constructor) => {
             attachment.type == null || attachment.type === ''
               ? 'application/octet-stream'
               : attachment.type,
-          contentId: `${crypto.randomUUID()}@${sender.address.replace(/^[^@]*@/, '')}`,
+          contentId: `${generateId('content-id', options?.generateId)}@${sender.address.replace(/^[^@]*@/, '')}`,
         });
       } else if (isAttachment(attachment)) {
         return checkAttachment(attachment);
diff --git a/tests/types/index.test-d.ts b/tests/types/index.test-d.ts
index 64628d4..ced8a21 100644
--- a/tests/types/index.test-d.ts
+++ b/tests/types/index.test-d.ts
@@ -3,11 +3,14 @@ import {
   createFailedReceipt,
   createMessage,
   createReceiptError,
+  generateMessageId,
   isRawTransport,
   isVerifiableTransport,
   parseAddress,
   RawMessageValidationError,
   type Address,
+  type IdGenerator,
+  type IdKind,
   type Message,
   type RawTransport,
   type Receipt,
@@ -90,3 +93,8 @@ expectType<Promise<Receipt>>(
     },
   ),
 );
+
+// generateId makes the identifiers of a kind, the left half of a Message-ID.
+const ulid: IdGenerator = (kind: IdKind) => `01J${kind.length}`;
+expectType<string>(generateMessageId('example.com', { generateId: ulid }));
+expectError(generateMessageId('example.com', { generateId: () => 42 }));
diff --git a/tests/unit/core.test.js b/tests/unit/core.test.js
index f711e49..1dabf01 100644
--- a/tests/unit/core.test.js
+++ b/tests/unit/core.test.js
@@ -312,3 +312,43 @@ test('Receipt: a failure is classified by its status, then its code, then its wo
     code: 'configuration',
   });
 });
+
+test('Core: generateId makes the identifiers, and what it returns is checked', () => {
+  const { generateMessageId } = require('../../index.js');
+  const { pinMessageId } = require('../../src/core/message-id.js');
+  const kinds = [];
+  const generateId = (kind) => {
+    kinds.push(kind);
+    return `01JABCDEF.${kinds.length}`;
+  };
+  assert.strictEqual(generateMessageId('example.com', { generateId }), '01JABCDEF.1@example.com');
+  const message = createMessage(
+    {
+      from: 'alex@example.com',
+      to: 'bob@example.com',
+      subject: 'Hi',
+      content: { text: 'Hi' },
+      attachments: [new File(['x'], 'a.txt', { type: 'text/plain' })],
+    },
+    { generateId },
+  );
+  assert.strictEqual(message.attachments[0].contentId, '01JABCDEF.2@example.com');
+  assert.strictEqual(pinMessageId(message, generateId).messageId, '01JABCDEF.3@example.com');
+  assert.deepStrictEqual(kinds, ['message-id', 'content-id', 'message-id']);
+
+  for (const wrong of [
+    'a>\r\nBcc: eve@evil.example',
+    '',
+    'a b',
+    'a..b',
+    '.a',
+    'é',
+    'x'.repeat(257),
+    42,
+  ]) {
+    assert.throws(() => generateMessageId('example.com', { generateId: () => wrong }), {
+      name: 'TypeError',
+      message: /^Invalid message-id from generateId/,
+    });
+  }
+});

From 08a706631ed3325e72d3949f95b466669e5df290 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 18:56:51 +0300
Subject: [PATCH 115/158] feat(mime,smtp): take generateId, and fetch for the
 OAuth 2.0 refresh

composeMessage takes generateId in its options and passes it down to the
Message-ID it generates. SmtpTransport takes generateId, for that
Message-ID and for the receipt ID it makes up when the server names none
(which came from Date.now and Math.random), and fetch, which reaches the
OAuth 2.0 token manager; that manager had a fetch parameter nothing
passed, and now reads the global one at each refresh rather than when it
is made. TransportDependencies in the root types gives every transport
config the two fields.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                  |  4 +++-
 docs/messages/compose.md      | 28 ++++++++++++++++++++++++
 docs/transports/smtp.md       |  8 +++++++
 index.d.ts                    | 16 ++++++++++++++
 src/mime/index.d.ts           | 10 +++++++--
 src/mime/index.js             |  2 +-
 src/mime/message.js           | 12 +++++-----
 src/smtp/config.js            |  2 ++
 src/smtp/index.d.ts           |  3 ++-
 src/smtp/message-converter.js |  3 ++-
 src/smtp/oauth2.js            |  9 ++++----
 src/smtp/smtp-connection.js   |  5 +++--
 src/smtp/smtp-transport.js    | 18 ++++++++++++---
 tests/types/mime.test-d.ts    |  2 ++
 tests/types/smtp.test-d.ts    |  8 +++++++
 tests/unit/mime.test.js       |  7 ++++++
 tests/unit/smtp.test.js       | 41 +++++++++++++++++++++++++++++++++++
 17 files changed, 157 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9405108..eeaafe5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,7 +39,9 @@ fixed ones below.
   with `IdKind` one of `message-id`, `content-id`, `idempotency-key` and `receipt-id`) can
   replace `crypto.randomUUID()`, such as a cuid2, a ULID or a nanoid. `generateMessageId` and
   `createMessage` take it in their options; it gives the left half of a Message-ID or a
-  Content-ID, and what it returns is checked (a `TypeError` otherwise).
+  Content-ID, and what it returns is checked (a `TypeError` otherwise). `composeMessage` and
+  `SmtpTransport` take it too, and `SmtpTransport` a `fetch` for the token refresh of OAuth 2.0
+  (`TransportDependencies` at the root types both).
 - **`./logger` logs retries** as `email.retrying` events, at the new level `levels.retrying`
   (`warn` by default), with the attempt, the wait, the redacted error text and its status code.
   With a wrapped transport, the logger needs a method for that level.
diff --git a/docs/messages/compose.md b/docs/messages/compose.md
index 46609e5..e205466 100644
--- a/docs/messages/compose.md
+++ b/docs/messages/compose.md
@@ -309,6 +309,34 @@ instead of throwing, which is convenient for values arriving from elsewhere.
 It parses one identifier, so an `In-Reply-To` field carrying several has to be
 split first.
 
+### Identifiers of your own
+
+The identifiers the library generates are random UUIDs: the left half of a
+Message-ID, the Content-ID of a `File` attachment, an idempotency key, and the
+message ID of a receipt a provider gave none for. Pass `generateId` to make them
+the way your records do, such as a ULID, a cuid2 or a nanoid, or to make them
+deterministic in tests. It is told the kind of identifier it makes
+(`message-id`, `content-id`, `idempotency-key` or `receipt-id`), returns the
+left half only of a Message-ID or a Content-ID, and what it returns is checked:
+dot-atom-text for those two kinds, and printable ASCII without spaces, at most
+256 characters, for every kind.
+
+```js
+const { ulid } = require('ulid');
+const { createMessage, generateMessageId } = require('@alexify/mailer');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+
+const generateId = () => ulid();
+
+const messageId = generateMessageId('example.com', { generateId });
+// "01JA7Y9Q3V2N8K4T6W0X1C5B2M@example.com"
+const message = createMessage({ ...fields, messageId }, { generateId });
+const transport = new SmtpTransport({ host: 'smtp.example.com', generateId });
+```
+
+`composeMessage()` of `./mime` takes `generateId` in its options too, and every
+transport in its configuration.
+
 ### Dropping an inherited header
 
 `inReplyTo` and `references` distinguish three states, which matters when a
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index cd4327e..967e7d9 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -171,6 +171,14 @@ with QUIT.
 > finish.  Raise `SmtpConfig.poolSize`, or use separate transports, when you
 > need more bulk streams at once.
 
+### Identifiers and `fetch`
+
+`generateId` makes the left half of the Message-ID the transport gives a message
+without one, and the message ID of a receipt the server named none for (see
+[Identifiers of your own](/messages/compose#identifiers-of-your-own)). `fetch`
+is used for the token refresh of OAuth 2.0, in place of the global one, such as
+one bound to an undici `Agent` or a proxy.
+
 ## Command pipelining
 
 When a server advertises the `PIPELINING` extension defined by [RFC 2920], @alexify/mailer
diff --git a/index.d.ts b/index.d.ts
index d6dea2d..6c9a6eb 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -727,6 +727,22 @@ export type IdKind = 'message-id' | 'content-id' | 'idempotency-key' | 'receipt-
  * anything else is a `TypeError` before a message is sent.
  */
 export type IdGenerator = (kind: IdKind) => string;
+/**
+ * What a transport may be given in place of a global of the runtime: the
+ * generator of its identifiers and, for one that makes HTTP requests, the
+ * `fetch` it makes them with.
+ */
+export interface TransportDependencies extends IdOptions {
+  /**
+   * The `fetch` of the requests, such as one bound to an undici `Agent` with
+   * keep-alive and connection limits, a `ProxyAgent` or mTLS:
+   * `(url, init) => undiciFetch(url, { ...init, dispatcher })`.  It is read at
+   * each request, so a later replacement of the global one is seen too.  It
+   * must take a streamed body with `duplex: 'half'` for the raw uploads of JMAP.
+   * @default globalThis.fetch
+   */
+  readonly fetch?: typeof globalThis.fetch;
+}
 /**
  * Options of the functions and transports that generate identifiers.
  */
diff --git a/src/mime/index.d.ts b/src/mime/index.d.ts
index dc9306b..3647fb8 100644
--- a/src/mime/index.d.ts
+++ b/src/mime/index.d.ts
@@ -1,7 +1,7 @@
 // Types ported from upyo v0.7.0 (packages/mime/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { Message, RawMessage, RawMessageValidationError } from '../../index.js';
+import type { IdGenerator, Message, RawMessage, RawMessageValidationError } from '../../index.js';
 
 /** Composition and lifetime options. @since 0.6.0 */
 export interface ComposeMessageOptions {
@@ -9,6 +9,11 @@ export interface ComposeMessageOptions {
   readonly dkim?: DkimConfig;
   /** Cancels preparation and every future content reader. */
   readonly signal?: AbortSignal;
+  /**
+   * Makes the left half of a generated Message-ID instead of a UUID.
+   * @default () => crypto.randomUUID()
+   */
+  readonly generateId?: IdGenerator;
 }
 /** Stable, replayable MIME bytes with a separate delivery envelope. @since 0.6.0 */
 export interface ComposedMessage extends RawMessage {
@@ -27,7 +32,8 @@ export interface ComposedMessage extends RawMessage {
  * @param options Signing and cancellation options.
  * @returns Replayable bytes accepted by raw-message transports.
  * @throws {RawMessageValidationError} If the derived envelope is invalid.
- * @throws {TypeError} If message metadata or signing configuration is invalid.
+ * @throws {TypeError} If message metadata or signing configuration is invalid,
+ *                     or `generateId` returns no dot-atom-text.
  * @throws {RangeError} If a MIME header exceeds the hard line-length limit.
  * @throws {Error} If signing, attachment reading, or cancellation fails.
  * Attachment errors can also occur during later content reads, after partial
diff --git a/src/mime/index.js b/src/mime/index.js
index 500f847..224f514 100644
--- a/src/mime/index.js
+++ b/src/mime/index.js
@@ -35,7 +35,7 @@ const envelopeRecipients = (message) => {
 const composeMessage = async (message, options = {}) => {
   const { signal } = options;
   // The neutral plan observes promised sources even when envelope validation fails.
-  const plan = prepareMimeMessage(message, options.dkim);
+  const plan = prepareMimeMessage(message, options.dkim, options.generateId);
   const { envelope } = createRawMessagePlan({
     envelope: {
       from: message.sender.address,
diff --git a/src/mime/message.js b/src/mime/message.js
index f8354a6..79fded0 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -26,7 +26,7 @@ const { base64, hasLineLongerThan, utf8 } = require('./bytes.js');
  * date, an address or identity header containing a carriage return or line
  * feed, or an invalid custom header field name.
  */
-const prepareMimeMessage = (message, dkimConfig) => {
+const prepareMimeMessage = (message, dkimConfig, generateId) => {
   // Observe every promise before validation can throw or an earlier reader stalls.
   for (const attachment of message.attachments) {
     if (attachment.content instanceof Promise) {
@@ -47,7 +47,7 @@ const prepareMimeMessage = (message, dkimConfig) => {
             headerFields: signature.headerFields == null ? undefined : [...signature.headerFields],
           })),
         };
-  const parts = buildMimeParts(message);
+  const parts = buildMimeParts(message, generateId);
   const first = parts[0];
   if (typeof first !== 'string') throw new TypeError('Missing MIME headers.');
   const separator = first.indexOf('\r\n\r\n') + 4;
@@ -100,7 +100,7 @@ const prepareMimeMessage = (message, dkimConfig) => {
   };
 };
 
-const buildMimeParts = (message) => {
+const buildMimeParts = (message, generateId) => {
   const lines = [];
   const boundary = generateBoundary();
   const hasAttachments = message.attachments.length > 0;
@@ -124,7 +124,7 @@ const buildMimeParts = (message) => {
   // The identity and threading fields all carry structured values, so they are
   // written verbatim rather than RFC 2047 encoded.
   lines.push(foldHeader('Date', resolveDate(message)));
-  lines.push(foldHeader('Message-ID', resolveMessageId(message)));
+  lines.push(foldHeader('Message-ID', resolveMessageId(message, generateId)));
   const threading = resolveThreadingHeaders(message);
   for (const name of ['In-Reply-To', 'References']) {
     // A field the message does not own falls back to a custom header, one it
@@ -434,13 +434,13 @@ const resolveDate = (message) => {
  * @throws {TypeError} If the message carries an invalid identifier, or a custom
  * `Message-ID` header containing a carriage return or line feed.
  */
-const resolveMessageId = (message) => {
+const resolveMessageId = (message, generateId) => {
   if (message.messageId !== undefined) {
     return formatMessageId(message.messageId);
   }
   const custom = overridden(message, 'Message-ID');
   if (custom != null) return custom;
-  return formatMessageId(generateSenderMessageId(message.sender.address));
+  return formatMessageId(generateSenderMessageId(message.sender.address, generateId));
 };
 
 const dayNames = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
diff --git a/src/smtp/config.js b/src/smtp/config.js
index e574cc5..7522c82 100644
--- a/src/smtp/config.js
+++ b/src/smtp/config.js
@@ -31,6 +31,8 @@ const createSmtpConfig = (config) => {
     pool: config.pool ?? true,
     poolSize: config.poolSize ?? 5,
     dkim: config.dkim,
+    fetch: config.fetch,
+    generateId: config.generateId,
   };
 };
 
diff --git a/src/smtp/index.d.ts b/src/smtp/index.d.ts
index 7ef6e97..5f56a1e 100644
--- a/src/smtp/index.d.ts
+++ b/src/smtp/index.d.ts
@@ -9,6 +9,7 @@ import type {
   RawMessage,
   RawTransport,
   Receipt,
+  TransportDependencies,
   TransportOptions,
   VerifiableTransport,
 } from '../../index.js';
@@ -45,7 +46,7 @@ export type {
  * };
  * ```
  */
-export interface SmtpConfig {
+export interface SmtpConfig extends TransportDependencies {
   /**
    * The SMTP server hostname or IP address.
    */
diff --git a/src/smtp/message-converter.js b/src/smtp/message-converter.js
index 4056f66..3734d4a 100644
--- a/src/smtp/message-converter.js
+++ b/src/smtp/message-converter.js
@@ -12,8 +12,9 @@ const prepareMessage = (
   dkimConfig,
   dsn,
   resolvedEnvelope = resolveSmtpEnvelope(message),
+  generateId = undefined,
 ) => {
-  const plan = prepareMimeMessage(message, dkimConfig);
+  const plan = prepareMimeMessage(message, dkimConfig, generateId);
   const envelope = { ...resolvedEnvelope, dsn };
   return {
     ...plan,
diff --git a/src/smtp/oauth2.js b/src/smtp/oauth2.js
index bf13b46..15d44c6 100644
--- a/src/smtp/oauth2.js
+++ b/src/smtp/oauth2.js
@@ -224,12 +224,12 @@ class OAuth2TokenManager {
    *
    * @param auth The OAuth 2.0 authentication configuration.
    * @param fetchFn The `fetch` implementation to use for the refresh-token
-   *                exchange.  Defaults to the global `fetch`; primarily
-   *                overridden in tests.
+   *                exchange, the `fetch` of the transport configuration.
+   *                Defaults to the global `fetch`, read at each refresh.
    * @throws {TypeError} If a refresh-token configuration has an insecure
    *                     (non-HTTPS) token endpoint.
    */
-  constructor(auth, fetchFn = fetch) {
+  constructor(auth, fetchFn) {
     if ('refreshToken' in auth) {
       assertSecureTokenEndpoint(auth.tokenEndpoint);
     }
@@ -320,7 +320,8 @@ class OAuth2TokenManager {
     // Call through a local variable so the global `fetch` is not invoked as a
     // method of this manager, which throws "Illegal invocation" in some
     // runtimes (the native `fetch` requires a `globalThis`/undefined receiver).
-    const fetchFn = this.fetchFn;
+    // Read at each refresh, so that the global one may be replaced later.
+    const fetchFn = this.fetchFn ?? globalThis.fetch;
     try {
       response = await fetchFn(auth.tokenEndpoint, {
         method: 'POST',
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index bb01c66..3238c37 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -6,6 +6,7 @@ const { Buffer } = require('node:buffer');
 const { isIP, Socket } = require('node:net');
 const { StringDecoder } = require('node:string_decoder');
 const { connect: tlsConnect, TLSSocket } = require('node:tls');
+const { generateId } = require('../core/id.js');
 const { createSmtpConfig } = require('./config.js');
 const { SmtpDsnUnsupportedError } = require('./delivery-status.js');
 const { checkSmtpPath } = require('./envelope.js');
@@ -815,7 +816,7 @@ class SmtpConnection {
    * creating a standalone manager from the auth config if none was injected.
    */
   async getOAuth2Token(auth, signal) {
-    this.tokenManager ??= new OAuth2TokenManager(auth);
+    this.tokenManager ??= new OAuth2TokenManager(auth, this.config.fetch);
     return await this.tokenManager.getAccessToken(signal);
   }
 
@@ -1131,7 +1132,7 @@ class SmtpConnection {
 
   extractMessageId(response) {
     const match = response.match(/(?:Message-ID:|id=)[\s<]*([^>\s]+)/i);
-    return match ? match[1] : `smtp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    return match ? match[1] : `smtp-${generateId('receipt-id', this.config.generateId)}`;
   }
 
   async quit(signal) {
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index 94a7a78..12b3899 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -135,7 +135,7 @@ class SmtpTransport {
     const auth = config.auth;
     this.tokenManager =
       auth != null && ('accessToken' in auth || 'refreshToken' in auth)
-        ? new OAuth2TokenManager(auth)
+        ? new OAuth2TokenManager(auth, config.fetch)
         : undefined;
   }
 
@@ -222,7 +222,13 @@ class SmtpTransport {
       const dsn = resolveSmtpDsn(envelope, options?.dsn);
       // Composed before a connection is taken: a message that cannot be
       // composed costs no connection, and fails no connection either.
-      const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
+      const smtpMessage = prepareMessage(
+        message,
+        this.config.dkim,
+        dsn,
+        envelope,
+        this.config.generateId,
+      );
 
       // Establishing the connection—including authentication, e.g. acquiring an
       // OAuth 2.0 access token—is part of delivery, so setup failures are
@@ -355,7 +361,13 @@ class SmtpTransport {
         try {
           const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
           const dsn = resolveSmtpDsn(envelope, options?.dsn);
-          smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope);
+          smtpMessage = prepareMessage(
+            message,
+            this.config.dkim,
+            dsn,
+            envelope,
+            this.config.generateId,
+          );
         } catch (error) {
           // A message that cannot be composed never reaches the connection.
           yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
diff --git a/tests/types/mime.test-d.ts b/tests/types/mime.test-d.ts
index dfd00fb..e062356 100644
--- a/tests/types/mime.test-d.ts
+++ b/tests/types/mime.test-d.ts
@@ -27,3 +27,5 @@ expectAssignable<RawMessageValidationError>(new MimeAttachmentReplayError());
 
 expectError(composeMessage({ subject: 'not a message' }));
 expectError<DkimConfig>({ signatures: [{ signingDomain: 'example.com', algorithm: 'rsa-sha1' }] });
+
+expectType<Promise<ComposedMessage>>(composeMessage(message, { generateId: () => '01JMIME' }));
diff --git a/tests/types/smtp.test-d.ts b/tests/types/smtp.test-d.ts
index 32c1499..5c83bcd 100644
--- a/tests/types/smtp.test-d.ts
+++ b/tests/types/smtp.test-d.ts
@@ -43,3 +43,11 @@ expectType<boolean>(isSmtpResponseProviderDetails(undefined));
 
 expectError(new SmtpTransport({ port: 25 }));
 expectError(new SmtpTransport({ host: 'smtp.example.com', port: '25' }));
+
+// The generator of the identifiers and the fetch of the OAuth 2.0 refresh.
+expectAssignable<SmtpConfig>({
+  host: 'smtp.example.com',
+  generateId: (kind: string) => `01J-${kind}`,
+  fetch: globalThis.fetch,
+});
+expectError(new SmtpTransport({ host: 'smtp.example.com', generateId: 'ulid' }));
diff --git a/tests/unit/mime.test.js b/tests/unit/mime.test.js
index 409dc3f..a905837 100644
--- a/tests/unit/mime.test.js
+++ b/tests/unit/mime.test.js
@@ -198,3 +198,10 @@ test('MIME: a boundary is random, not derived from the clock and Math.random', a
   }
   assert.strictEqual(boundaries.size, 2);
 });
+
+test('MIME: generateId makes the left half of a generated Message-ID', async () => {
+  const text = await wire(createMessage({ ...base, subject: 'Hi' }), {
+    generateId: (kind) => `01JMIME.${kind}`,
+  });
+  assert.match(headerBlock(text), /\r\nMessage-ID: <01JMIME\.message-id@example\.com>/);
+});
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index ecb9a26..098128c 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -688,3 +688,44 @@ test('SMTP: an idle pooled connection does not keep the process alive', async ()
     await server.stop();
   }
 });
+
+test('SMTP: generateId makes the Message-ID, and fetch refreshes the OAuth 2.0 token', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  const requests = [];
+  const fetch = async (url, init) => {
+    requests.push([String(url), init.method]);
+    return Response.json({ access_token: 'token', expires_in: 3600 });
+  };
+  try {
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port,
+      generateId: (kind) => `01JTEST.${kind}`,
+      fetch,
+      auth: {
+        type: 'oauth2',
+        user: 'alex@example.com',
+        clientId: 'id',
+        clientSecret: 'secret',
+        refreshToken: 'refresh',
+        tokenEndpoint: 'http://localhost/token',
+      },
+    });
+    const receipt = await transport.send(message());
+    await transport.closeAllConnections();
+    assert.strictEqual(receipt.successful, true);
+    assert.match(
+      server.getReceivedMessages()[0].data,
+      /\r\nMessage-ID: <01JTEST\.message-id@example\.com>\r\n/,
+    );
+    assert.deepStrictEqual(requests, [['http://localhost/token', 'POST']]);
+
+    const broken = new SmtpTransport({ host: 'localhost', port, generateId: () => 'a>b' });
+    const failed = await broken.send(message());
+    assert.strictEqual(failed.successful, false);
+    assert.match(failed.errorMessages[0], /Invalid message-id from generateId/);
+  } finally {
+    await server.stop();
+  }
+});

From c11fdc6247fa8971ce11e1dbda591e7d371ca7fe Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 19:01:18 +0300
Subject: [PATCH 116/158] feat: take fetch and generateId in every HTTP
 transport

The eight HTTP providers and JMAP called the global fetch, so an
application could not give them an undici Agent with keep-alive and
connection limits, a proxy, mTLS or an instrumented fetch. Their
configurations now pass fetch through, and each request reads
config.fetch ?? globalThis.fetch, so a later replacement of the global is
still seen. generateId makes the idempotency keys of Resend and
Lettermint, the Maileroo reference (hashed into its 24 hex digits), and
the message IDs that SES, SendGrid and Plunk made up from Date.now and
Math.random when the provider gave none. Each provider config extends
TransportDependencies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                           |  4 ++
 README.md                              |  4 ++
 docs/guide/getting-started.md          | 27 +++++++++++++
 src/jmap/blob-uploader.js              |  2 +-
 src/jmap/config.js                     |  2 +
 src/jmap/http-client.js                |  3 +-
 src/jmap/index.d.ts                    |  5 ++-
 src/jmap/raw-upload.js                 |  2 +-
 src/lettermint/config.js               |  2 +
 src/lettermint/http-client.js          |  2 +-
 src/lettermint/index.d.ts              | 25 +++++++-----
 src/lettermint/lettermint-transport.js | 14 +++++--
 src/lettermint/message-converter.js    |  6 +--
 src/maileroo/config.js                 |  2 +
 src/maileroo/http-client.js            |  2 +-
 src/maileroo/index.d.ts                | 21 +++++++---
 src/maileroo/message-converter.js      | 15 +++----
 src/mailgun/config.js                  |  2 +
 src/mailgun/http-client.js             |  3 +-
 src/mailgun/index.d.ts                 | 13 +++++--
 src/mailtrap/config.js                 |  2 +
 src/mailtrap/http-client.js            |  2 +-
 src/mailtrap/index.d.ts                | 30 ++++++++------
 src/plunk/config.js                    |  2 +
 src/plunk/http-client.js               |  2 +-
 src/plunk/index.d.ts                   | 13 +++++--
 src/plunk/plunk-transport.js           |  6 +--
 src/resend/config.js                   |  2 +
 src/resend/http-client.js              |  1 +
 src/resend/index.d.ts                  | 13 +++++--
 src/resend/message-converter.js        |  9 +++--
 src/resend/resend-transport.js         |  6 ++-
 src/sendgrid/config.js                 |  2 +
 src/sendgrid/http-client.js            |  3 +-
 src/sendgrid/index.d.ts                | 13 +++++--
 src/sendgrid/sendgrid-transport.js     |  9 ++---
 src/ses/config.js                      |  2 +
 src/ses/http-client.js                 |  2 +-
 src/ses/index.d.ts                     | 32 +++++++++------
 src/ses/ses-transport.js               |  6 +--
 tests/types/resend.test-d.ts           |  3 ++
 tests/unit/delivery.test.js            | 54 ++++++++++++++++++++++++++
 tests/unit/plunk-transport.test.js     |  8 +++-
 tests/unit/sendgrid.test.js            |  5 ++-
 tests/unit/ses.test.js                 |  5 ++-
 45 files changed, 290 insertions(+), 98 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index eeaafe5..ccb0929 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -42,6 +42,10 @@ fixed ones below.
   Content-ID, and what it returns is checked (a `TypeError` otherwise). `composeMessage` and
   `SmtpTransport` take it too, and `SmtpTransport` a `fetch` for the token refresh of OAuth 2.0
   (`TransportDependencies` at the root types both).
+- **`fetch` and `generateId` in every HTTP transport:** the eight providers and `./jmap` take a
+  `fetch`, read at each request in place of the global one (an undici `Agent`, a proxy, mTLS),
+  and a `generateId` for their idempotency keys (Resend, Lettermint, the Maileroo reference) and
+  for the message IDs they make up when the provider gives none (SES, SendGrid, Plunk).
 - **`./logger` logs retries** as `email.retrying` events, at the new level `levels.retrying`
   (`warn` by default), with the attempt, the wait, the redacted error text and its status code.
   With a wrapped transport, the logger needs a method for that level.
diff --git a/README.md b/README.md
index 5138d65..770a844 100644
--- a/README.md
+++ b/README.md
@@ -84,6 +84,10 @@ if (!receipt.successful) console.error(receipt.errorMessages);
 | `/pool`, `/retry`, `/otel`, `/logger` | decorators: failover, retries, OpenTelemetry, logging |
 | `/mock` | an in-memory transport for tests |
 
+Every transport takes `generateId` for the identifiers it makes (a ULID or a cuid2 instead of a
+UUID), and every HTTP transport a `fetch`, such as one bound to an undici `Agent` or a proxy; see
+[your own fetch and identifiers](https://mailerat.vercel.app/guide/getting-started#your-own-fetch-and-identifiers).
+
 The same names import from ESM (`import { SmtpTransport } from '@alexify/mailer/smtp'`). The
 [API reference](https://mailerat.vercel.app/api/exports) lists every member, and the
 [guide](https://mailerat.vercel.app/guide/getting-started) every transport.
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index a8bd05d..924210e 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -100,6 +100,33 @@ import { createMessage } from '@alexify/mailer';
 import { SmtpTransport } from '@alexify/mailer/smtp';
 ```
 
+## Your own `fetch` and identifiers
+
+Every transport that makes HTTP requests (the HTTP providers and JMAP) takes a
+`fetch` in its configuration, used in place of the global one at each request:
+one bound to an undici `Agent` for keep-alive and connection limits, a
+`ProxyAgent` for a corporate proxy, mTLS, or an instrumented one. The package
+still depends on nothing; undici is yours:
+
+```js
+const { Agent, fetch: undiciFetch } = require('undici');
+const { ResendTransport } = require('@alexify/mailer/resend');
+
+const dispatcher = new Agent({ connections: 16, keepAliveTimeout: 30_000 });
+const transport = new ResendTransport({
+  apiKey: process.env.RESEND_API_KEY,
+  fetch: (url, init) => undiciFetch(url, { ...init, dispatcher }),
+});
+```
+
+The JMAP transport streams its raw uploads, so its `fetch` must take a body
+stream with `duplex: 'half'`, as undici's does.
+
+Every transport also takes `generateId`, which makes the identifiers otherwise
+drawn from `crypto.randomUUID()`: a generated Message-ID, an idempotency key,
+and the message ID of a receipt the provider gave none for. See
+[identifiers of your own](/messages/compose#identifiers-of-your-own).
+
 From here, see [composing messages](/messages/compose) for HTML content, multiple
 recipients and threading, [attachments](/messages/attachments), and
 [calendar invitations](/messages/calendar).
diff --git a/src/jmap/blob-uploader.js b/src/jmap/blob-uploader.js
index 6ac3ef0..c064b83 100644
--- a/src/jmap/blob-uploader.js
+++ b/src/jmap/blob-uploader.js
@@ -51,7 +51,7 @@ const uploadBlob = async (config, uploadUrl, accountId, blob, signal) => {
   try {
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
-    const response = await fetch(url, {
+    const response = await (config.fetch ?? globalThis.fetch)(url, {
       method: 'POST',
       headers,
       body: blob,
diff --git a/src/jmap/config.js b/src/jmap/config.js
index 5b958e5..c546b4a 100644
--- a/src/jmap/config.js
+++ b/src/jmap/config.js
@@ -20,6 +20,8 @@ const createJmapConfig = (config) => {
     accountId: config.accountId ?? null,
     identityId: config.identityId ?? null,
     timeout: config.timeout ?? 30000,
+    fetch: config.fetch,
+    generateId: config.generateId,
     retries: config.retries ?? 3,
     headers: config.headers ?? {},
     sessionCacheTtl: config.sessionCacheTtl ?? 300000,
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index c5c99d4..b6db025 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -136,7 +136,8 @@ class JmapHttpClient {
 
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
-    return globalThis.fetch(url, { redirect: 'manual', ...options, headers, signal });
+    const fetch = this.config.fetch ?? globalThis.fetch;
+    return fetch(url, { redirect: 'manual', ...options, headers, signal });
   }
 }
 
diff --git a/src/jmap/index.d.ts b/src/jmap/index.d.ts
index 8c6a396..fe578f0 100644
--- a/src/jmap/index.d.ts
+++ b/src/jmap/index.d.ts
@@ -6,6 +6,7 @@ import type {
   RawMessage,
   RawTransport,
   Receipt,
+  TransportDependencies,
   TransportOptions,
   VerifiableTransport,
 } from '../../index.js';
@@ -13,7 +14,7 @@ import type {
 /**
  * Configuration interface for JMAP transport connection settings.
  */
-export interface JmapConfig {
+export interface JmapConfig extends TransportDependencies {
   /**
    * The JMAP session URL (e.g., `https://server/.well-known/jmap`).
    * This is used for session discovery per RFC 8620 Section 2.
@@ -87,7 +88,7 @@ export interface JmapConfig {
 /**
  * Resolved JMAP configuration with all fields populated.
  */
-export type ResolvedJmapConfig = {
+export type ResolvedJmapConfig = TransportDependencies & {
   readonly sessionUrl: string;
   readonly bearerToken: string | null;
   readonly basicAuth: {
diff --git a/src/jmap/raw-upload.js b/src/jmap/raw-upload.js
index b3d1135..7a1923e 100644
--- a/src/jmap/raw-upload.js
+++ b/src/jmap/raw-upload.js
@@ -156,7 +156,7 @@ const uploadRawMessage = async (config, uploadUrl, accountId, plan, signal) => {
         signal: outerSignal,
       };
       try {
-        const response = await fetch(
+        const response = await (config.fetch ?? globalThis.fetch)(
           uploadUrl.replace('{accountId}', encodeURIComponent(accountId)),
           request,
         );
diff --git a/src/lettermint/config.js b/src/lettermint/config.js
index 2664d4b..a9b4a47 100644
--- a/src/lettermint/config.js
+++ b/src/lettermint/config.js
@@ -14,6 +14,8 @@ const createLettermintConfig = (config) => {
     apiToken: config.apiToken,
     baseUrl: normalizeBaseUrl(config.baseUrl ?? 'https://api.lettermint.co'),
     timeout: config.timeout ?? 30000,
+    fetch: config.fetch,
+    generateId: config.generateId,
     retries: config.retries ?? 3,
     headers: config.headers ?? {},
     route: config.route,
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index 8e3b4b1..af18729 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -151,7 +151,7 @@ class LettermintHttpClient {
 
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
-    return globalThis.fetch(url, {
+    return (this.config.fetch ?? globalThis.fetch)(url, {
       method: 'POST',
       headers,
       body: json,
diff --git a/src/lettermint/index.d.ts b/src/lettermint/index.d.ts
index d16890d..72a6c0c 100644
--- a/src/lettermint/index.d.ts
+++ b/src/lettermint/index.d.ts
@@ -1,7 +1,13 @@
 // Types ported from upyo v0.7.0 (packages/lettermint/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type {
+  Message,
+  Receipt,
+  Transport,
+  TransportDependencies,
+  TransportOptions,
+} from '../../index.js';
 
 /**
  * Per-email Lettermint tracking settings.
@@ -33,7 +39,7 @@ export interface LettermintSettings {
  * };
  * ```
  */
-export interface LettermintConfig {
+export interface LettermintConfig extends TransportDependencies {
   /**
    * Your project-specific Lettermint sending API token.
    *
@@ -85,13 +91,14 @@ export interface LettermintConfig {
  * Resolved Lettermint configuration with defaults applied.
  */
 export type ResolvedLettermintConfig = Required<
-  Omit<LettermintConfig, 'route' | 'tag' | 'metadata' | 'settings'>
-> & {
-  readonly route?: string;
-  readonly tag?: string | null;
-  readonly metadata?: Record<string, string>;
-  readonly settings?: LettermintSettings;
-};
+  Omit<LettermintConfig, 'route' | 'tag' | 'metadata' | 'settings' | keyof TransportDependencies>
+> &
+  TransportDependencies & {
+    readonly route?: string;
+    readonly tag?: string | null;
+    readonly metadata?: Record<string, string>;
+    readonly settings?: LettermintSettings;
+  };
 /**
  * Creates a resolved Lettermint configuration by applying default values.
  *
diff --git a/src/lettermint/lettermint-transport.js b/src/lettermint/lettermint-transport.js
index ff9b72e..4b5b5a9 100644
--- a/src/lettermint/lettermint-transport.js
+++ b/src/lettermint/lettermint-transport.js
@@ -83,7 +83,10 @@ class LettermintTransport {
       options?.signal?.throwIfAborted();
 
       const emailData = await convertMessage(message, this.config, options?.signal);
-      const idempotencyKey = normalizeIdempotencyKey(message.idempotencyKey);
+      const idempotencyKey = normalizeIdempotencyKey(
+        message.idempotencyKey,
+        this.config.generateId,
+      );
 
       options?.signal?.throwIfAborted();
 
@@ -134,7 +137,10 @@ class LettermintTransport {
       return;
     }
 
-    const idempotencyKey = normalizeIdempotencyKey(messages[0]?.idempotencyKey);
+    const idempotencyKey = normalizeIdempotencyKey(
+      messages[0]?.idempotencyKey,
+      this.config.generateId,
+    );
     const batchData = [];
     const receipts = [];
 
@@ -194,10 +200,10 @@ class LettermintTransport {
   }
 }
 
-const normalizeIdempotencyKey = (idempotencyKey) => {
+const normalizeIdempotencyKey = (idempotencyKey, generator) => {
   return idempotencyKey != null && idempotencyKey !== ''
     ? idempotencyKey
-    : generateIdempotencyKey();
+    : generateIdempotencyKey(generator);
 };
 
 const hasIdempotencyKey = (message) => {
diff --git a/src/lettermint/message-converter.js b/src/lettermint/message-converter.js
index df013fb..db3ffc6 100644
--- a/src/lettermint/message-converter.js
+++ b/src/lettermint/message-converter.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/lettermint/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { generateId } = require('../core/id.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
 const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
@@ -182,10 +183,9 @@ const isStandardHeader = (headerName) => {
 /**
  * Generates a random idempotency key for request deduplication.
  *
+ * @param generator Optional generator of the application.
  * @returns A unique string suitable for use as an idempotency key.
  */
-const generateIdempotencyKey = () => {
-  return globalThis.crypto.randomUUID();
-};
+const generateIdempotencyKey = (generator) => generateId('idempotency-key', generator);
 
 module.exports = { convertMessage, generateIdempotencyKey };
diff --git a/src/maileroo/config.js b/src/maileroo/config.js
index 9d8b4ed..eaf89ec 100644
--- a/src/maileroo/config.js
+++ b/src/maileroo/config.js
@@ -14,6 +14,8 @@ const createMailerooConfig = (config) => {
     apiKey: config.apiKey,
     baseUrl: normalizeBaseUrl(config.baseUrl ?? 'https://smtp.maileroo.com/api/v2'),
     timeout: config.timeout ?? 30000,
+    fetch: config.fetch,
+    generateId: config.generateId,
     retries: config.retries ?? 3,
     headers: config.headers == null ? {} : { ...config.headers },
     tracking: config.tracking,
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index cfd6c9e..c5673e6 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -123,7 +123,7 @@ class MailerooHttpClient {
 
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
-    return globalThis.fetch(url, {
+    return (this.config.fetch ?? globalThis.fetch)(url, {
       method: 'POST',
       headers,
       body: json,
diff --git a/src/maileroo/index.d.ts b/src/maileroo/index.d.ts
index da50658..356ac44 100644
--- a/src/maileroo/index.d.ts
+++ b/src/maileroo/index.d.ts
@@ -1,7 +1,13 @@
 // Types ported from upyo v0.7.0 (packages/maileroo/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type {
+  Message,
+  Receipt,
+  Transport,
+  TransportDependencies,
+  TransportOptions,
+} from '../../index.js';
 
 /**
  * Configuration interface for Maileroo transport connection settings.
@@ -15,7 +21,7 @@ import type { Message, Receipt, Transport, TransportOptions } from '../../index.
  * };
  * ```
  */
-export interface MailerooConfig {
+export interface MailerooConfig extends TransportDependencies {
   /**
    * Your Maileroo sending key.
    *
@@ -60,10 +66,13 @@ export interface MailerooConfig {
 /**
  * Resolved Maileroo configuration with defaults applied.
  */
-export type ResolvedMailerooConfig = Required<Omit<MailerooConfig, 'tracking' | 'tags'>> & {
-  readonly tracking?: boolean;
-  readonly tags?: Record<string, string>;
-};
+export type ResolvedMailerooConfig = Required<
+  Omit<MailerooConfig, 'tracking' | 'tags' | keyof TransportDependencies>
+> &
+  TransportDependencies & {
+    readonly tracking?: boolean;
+    readonly tags?: Record<string, string>;
+  };
 /**
  * Creates a resolved Maileroo configuration by applying default values.
  *
diff --git a/src/maileroo/message-converter.js b/src/maileroo/message-converter.js
index 90edebf..fb34fb9 100644
--- a/src/maileroo/message-converter.js
+++ b/src/maileroo/message-converter.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/maileroo/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { generateId } = require('../core/id.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
 const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
@@ -48,7 +49,7 @@ const convertMessage = async (message, config, signal) => {
     from: convertAddress(message.sender),
     to: convertAddressList(message.recipients),
     subject: message.subject,
-    reference_id: createMailerooReference(message.idempotencyKey),
+    reference_id: createMailerooReference(message.idempotencyKey, config.generateId),
   };
 
   signal?.throwIfAborted();
@@ -103,12 +104,12 @@ const convertMessage = async (message, config, signal) => {
   return emailData;
 };
 
-const createMailerooReference = (idempotencyKey) => {
-  if (idempotencyKey == null || idempotencyKey === '') {
-    return crypto.getRandomValues(Buffer.allocUnsafe(12)).toString('hex');
-  }
-
-  return hashReference(idempotencyKey);
+// A reference is 24 hexadecimal digits: random ones, or the hash of the key of
+// the message or of the one the generator of the application makes.
+const createMailerooReference = (idempotencyKey, generator) => {
+  if (idempotencyKey != null && idempotencyKey !== '') return hashReference(idempotencyKey);
+  if (generator != null) return hashReference(generateId('idempotency-key', generator));
+  return crypto.getRandomValues(Buffer.allocUnsafe(12)).toString('hex');
 };
 
 // Three 32-bit FNV-1a hashes of the key with different seeds, updated together
diff --git a/src/mailgun/config.js b/src/mailgun/config.js
index de915b7..218e584 100644
--- a/src/mailgun/config.js
+++ b/src/mailgun/config.js
@@ -24,6 +24,8 @@ const createMailgunConfig = (config) => {
     region,
     baseUrl,
     timeout: config.timeout ?? 30000,
+    fetch: config.fetch,
+    generateId: config.generateId,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index 0457fde..98e0252 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -125,7 +125,8 @@ class MailgunHttpClient {
 
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
-    return globalThis.fetch(url, { ...options, headers, signal, redirect: 'manual' });
+    const fetch = this.config.fetch ?? globalThis.fetch;
+    return fetch(url, { ...options, headers, signal, redirect: 'manual' });
   }
 }
 
diff --git a/src/mailgun/index.d.ts b/src/mailgun/index.d.ts
index e941698..c235054 100644
--- a/src/mailgun/index.d.ts
+++ b/src/mailgun/index.d.ts
@@ -1,7 +1,13 @@
 // Types ported from upyo v0.7.0 (packages/mailgun/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type {
+  Message,
+  Receipt,
+  Transport,
+  TransportDependencies,
+  TransportOptions,
+} from '../../index.js';
 
 /**
  * Configuration interface for Mailgun transport connection settings.
@@ -20,7 +26,7 @@ import type { Message, Receipt, Transport, TransportOptions } from '../../index.
  * };
  * ```
  */
-export interface MailgunConfig {
+export interface MailgunConfig extends TransportDependencies {
   /**
    * Your Mailgun API key.
    *
@@ -96,7 +102,8 @@ export interface MailgunConfig {
  * This type represents the final configuration after applying defaults,
  * used internally by the Mailgun transport implementation.
  */
-type ResolvedMailgunConfig = Required<MailgunConfig>;
+type ResolvedMailgunConfig = Required<Omit<MailgunConfig, keyof TransportDependencies>> &
+  TransportDependencies;
 /**
  * Creates a resolved Mailgun configuration by applying default values to optional fields.
  *
diff --git a/src/mailtrap/config.js b/src/mailtrap/config.js
index 94924af..0f92f1d 100644
--- a/src/mailtrap/config.js
+++ b/src/mailtrap/config.js
@@ -32,6 +32,8 @@ const createMailtrapConfig = (config) => {
     metadata: config.metadata == null ? undefined : { ...config.metadata },
     userAgent: config.userAgent ?? DEFAULT_USER_AGENT,
     timeout: config.timeout ?? 30000,
+    fetch: config.fetch,
+    generateId: config.generateId,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers == null ? {} : { ...config.headers },
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index c65b5de..b396060 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -185,7 +185,7 @@ class MailtrapHttpClient {
 
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
-    return globalThis.fetch(url, {
+    return (this.config.fetch ?? globalThis.fetch)(url, {
       method: 'POST',
       headers,
       body: json,
diff --git a/src/mailtrap/index.d.ts b/src/mailtrap/index.d.ts
index 3b1373a..f43f7ec 100644
--- a/src/mailtrap/index.d.ts
+++ b/src/mailtrap/index.d.ts
@@ -1,7 +1,13 @@
 // Types ported from upyo v0.7.0 (packages/mailtrap/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type {
+  Message,
+  Receipt,
+  Transport,
+  TransportDependencies,
+  TransportOptions,
+} from '../../index.js';
 
 /**
  * Configuration interface for Mailtrap transport connection settings.
@@ -17,7 +23,7 @@ import type { Message, Receipt, Transport, TransportOptions } from '../../index.
  * };
  * ```
  */
-export interface MailtrapConfig {
+export interface MailtrapConfig extends TransportDependencies {
   /**
    * Your Mailtrap API token.
    *
@@ -104,16 +110,18 @@ export type ResolvedMailtrapConfig = Required<
     | 'userAgent'
     | 'sendBaseUrl'
     | 'sandboxBaseUrl'
+    | keyof TransportDependencies
   >
-> & {
-  readonly inboxId?: string | number;
-  readonly sandbox: boolean;
-  readonly metadata?: Record<string, string>;
-  readonly defaultCategory: string;
-  readonly userAgent: string;
-  readonly sendBaseUrl: string;
-  readonly sandboxBaseUrl: string;
-};
+> &
+  TransportDependencies & {
+    readonly inboxId?: string | number;
+    readonly sandbox: boolean;
+    readonly metadata?: Record<string, string>;
+    readonly defaultCategory: string;
+    readonly userAgent: string;
+    readonly sendBaseUrl: string;
+    readonly sandboxBaseUrl: string;
+  };
 /**
  * Creates a resolved Mailtrap configuration by applying default values.
  *
diff --git a/src/plunk/config.js b/src/plunk/config.js
index a436599..a5477f1 100644
--- a/src/plunk/config.js
+++ b/src/plunk/config.js
@@ -19,6 +19,8 @@ const createPlunkConfig = (config) => {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? 'https://next-api.useplunk.com',
     timeout: config.timeout ?? 30000,
+    fetch: config.fetch,
+    generateId: config.generateId,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index 440d40f..9212efd 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -131,7 +131,7 @@ class PlunkHttpClient {
 
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
-    return fetch(url, {
+    return (this.config.fetch ?? globalThis.fetch)(url, {
       method: 'POST',
       headers,
       body: json,
diff --git a/src/plunk/index.d.ts b/src/plunk/index.d.ts
index 466efc9..e56015f 100644
--- a/src/plunk/index.d.ts
+++ b/src/plunk/index.d.ts
@@ -1,7 +1,13 @@
 // Types ported from upyo v0.7.0 (packages/plunk/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type {
+  Message,
+  Receipt,
+  Transport,
+  TransportDependencies,
+  TransportOptions,
+} from '../../index.js';
 
 /**
  * Configuration interface for Plunk transport connection settings.
@@ -20,7 +26,7 @@ import type { Message, Receipt, Transport, TransportOptions } from '../../index.
  * };
  * ```
  */
-export interface PlunkConfig {
+export interface PlunkConfig extends TransportDependencies {
   /**
    * Your Plunk API key.
    *
@@ -68,7 +74,8 @@ export interface PlunkConfig {
  * This type represents the final configuration after applying defaults,
  * used internally by the Plunk transport implementation.
  */
-export type ResolvedPlunkConfig = Required<PlunkConfig>;
+export type ResolvedPlunkConfig = Required<Omit<PlunkConfig, keyof TransportDependencies>> &
+  TransportDependencies;
 /**
  * Creates a resolved Plunk configuration by applying default values to optional fields.
  *
diff --git a/src/plunk/plunk-transport.js b/src/plunk/plunk-transport.js
index 4cc6a68..40a9b86 100644
--- a/src/plunk/plunk-transport.js
+++ b/src/plunk/plunk-transport.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/plunk/src/plunk-transport.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { generateId } = require('../core/id.js');
 const { createFailedReceipt } = require('../core/receipt.js');
 const { createPlunkConfig } = require('./config.js');
 const { PlunkApiError, PlunkHttpClient } = require('./http-client.js');
@@ -226,10 +227,7 @@ class PlunkTransport {
     // Fallback: generate synthetic message ID.  Upstream put the first eight
     // characters of the recipient's local part into it, personal data that
     // receipts carry into logs.
-    const timestamp = Date.now();
-    const random = Math.random().toString(36).substring(2, 8);
-
-    return `plunk-${timestamp}-${random}`;
+    return `plunk-${generateId('receipt-id', this.config.generateId)}`;
   }
 }
 
diff --git a/src/resend/config.js b/src/resend/config.js
index b70846b..ba2d65d 100644
--- a/src/resend/config.js
+++ b/src/resend/config.js
@@ -19,6 +19,8 @@ const createResendConfig = (config) => {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? 'https://api.resend.com',
     timeout: config.timeout ?? 30000,
+    fetch: config.fetch,
+    generateId: config.generateId,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index 6064502..8f14693 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -196,6 +196,7 @@ class ResendHttpClient {
 
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
+    const fetch = this.config.fetch ?? globalThis.fetch;
     return fetch(url, { ...options, headers, signal, redirect: 'manual' });
   }
 }
diff --git a/src/resend/index.d.ts b/src/resend/index.d.ts
index 9b59484..c77381c 100644
--- a/src/resend/index.d.ts
+++ b/src/resend/index.d.ts
@@ -1,7 +1,13 @@
 // Types ported from upyo v0.7.0 (packages/resend/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type {
+  Message,
+  Receipt,
+  Transport,
+  TransportDependencies,
+  TransportOptions,
+} from '../../index.js';
 
 /**
  * Configuration interface for Resend transport connection settings.
@@ -18,7 +24,7 @@ import type { Message, Receipt, Transport, TransportOptions } from '../../index.
  * };
  * ```
  */
-export interface ResendConfig {
+export interface ResendConfig extends TransportDependencies {
   /**
    * Your Resend API key.
    *
@@ -62,7 +68,8 @@ export interface ResendConfig {
  * This type represents the final configuration after applying defaults,
  * used internally by the Resend transport implementation.
  */
-export type ResolvedResendConfig = Required<ResendConfig>;
+export type ResolvedResendConfig = Required<Omit<ResendConfig, keyof TransportDependencies>> &
+  TransportDependencies;
 /**
  * Creates a resolved Resend configuration by applying default values to optional fields.
  *
diff --git a/src/resend/message-converter.js b/src/resend/message-converter.js
index f0985f1..25b7b07 100644
--- a/src/resend/message-converter.js
+++ b/src/resend/message-converter.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/resend/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { generateId } = require('../core/id.js');
 const { formatMailbox: formatAddress } = require('../core/address.js');
 const { createCalendarAttachment } = require('../core/calendar.js');
 const { combineSignals } = require('../core/abort-signal.js');
@@ -221,11 +222,13 @@ const isStandardHeader = (headerName) => {
 
 /**
  * Generates a random idempotency key for request deduplication: a UUID from
- * crypto.randomUUID, since Resend answers a repeated key with the first
- * answer, and two sends sharing a key by chance would lose one of them.
+ * crypto.randomUUID, or what the generator of the application makes, since
+ * Resend answers a repeated key with the first answer, and two sends sharing
+ * a key by chance would lose one of them.
  *
+ * @param generator Optional generator of the application.
  * @returns A unique string suitable for use as an idempotency key
  */
-const generateIdempotencyKey = () => crypto.randomUUID();
+const generateIdempotencyKey = (generator) => generateId('idempotency-key', generator);
 
 module.exports = { convertMessage, convertMessagesBatch, generateIdempotencyKey };
diff --git a/src/resend/resend-transport.js b/src/resend/resend-transport.js
index 9b4cfd1..25a5f98 100644
--- a/src/resend/resend-transport.js
+++ b/src/resend/resend-transport.js
@@ -113,7 +113,8 @@ class ResendTransport {
       options?.signal?.throwIfAborted();
 
       // Use provided idempotency key or generate one for reliable delivery
-      const idempotencyKey = message.idempotencyKey ?? generateIdempotencyKey();
+      const idempotencyKey =
+        message.idempotencyKey ?? generateIdempotencyKey(this.config.generateId);
 
       const emailData = await convertMessage(message, this.config, {
         signal: options?.signal,
@@ -268,7 +269,8 @@ class ResendTransport {
 
     try {
       // Use first message's idempotency key or generate one for reliable delivery
-      const idempotencyKey = messages[0]?.idempotencyKey ?? generateIdempotencyKey();
+      const idempotencyKey =
+        messages[0]?.idempotencyKey ?? generateIdempotencyKey(this.config.generateId);
 
       const batchData = await convertMessagesBatch(messages, this.config);
 
diff --git a/src/sendgrid/config.js b/src/sendgrid/config.js
index 0715386..aed9c1d 100644
--- a/src/sendgrid/config.js
+++ b/src/sendgrid/config.js
@@ -19,6 +19,8 @@ const createSendGridConfig = (config) => {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? 'https://api.sendgrid.com/v3',
     timeout: config.timeout ?? 30000,
+    fetch: config.fetch,
+    generateId: config.generateId,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
index 84550fa..3d19b23 100644
--- a/src/sendgrid/http-client.js
+++ b/src/sendgrid/http-client.js
@@ -104,7 +104,8 @@ class SendGridHttpClient {
 
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
-    return globalThis.fetch(url, { ...options, headers, signal, redirect: 'manual' });
+    const fetch = this.config.fetch ?? globalThis.fetch;
+    return fetch(url, { ...options, headers, signal, redirect: 'manual' });
   }
 
   /**
diff --git a/src/sendgrid/index.d.ts b/src/sendgrid/index.d.ts
index b138761..cd790af 100644
--- a/src/sendgrid/index.d.ts
+++ b/src/sendgrid/index.d.ts
@@ -1,7 +1,13 @@
 // Types ported from upyo v0.7.0 (packages/sendgrid/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type {
+  Message,
+  Receipt,
+  Transport,
+  TransportDependencies,
+  TransportOptions,
+} from '../../index.js';
 
 /**
  * Configuration interface for SendGrid transport connection settings.
@@ -19,7 +25,7 @@ import type { Message, Receipt, Transport, TransportOptions } from '../../index.
  * };
  * ```
  */
-export interface SendGridConfig {
+export interface SendGridConfig extends TransportDependencies {
   /**
    * Your SendGrid API key.
    *
@@ -87,7 +93,8 @@ export interface SendGridConfig {
  * This type represents the final configuration after applying defaults,
  * used internally by the SendGrid transport implementation.
  */
-type ResolvedSendGridConfig = Required<SendGridConfig>;
+type ResolvedSendGridConfig = Required<Omit<SendGridConfig, keyof TransportDependencies>> &
+  TransportDependencies;
 /**
  * Creates a resolved SendGrid configuration by applying default values to optional fields.
  *
diff --git a/src/sendgrid/sendgrid-transport.js b/src/sendgrid/sendgrid-transport.js
index 00de745..16414ba 100644
--- a/src/sendgrid/sendgrid-transport.js
+++ b/src/sendgrid/sendgrid-transport.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/sendgrid/src/sendgrid-transport.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { generateId } = require('../core/id.js');
 const { createFailedReceipt } = require('../core/receipt.js');
 const { createSendGridConfig } = require('./config.js');
 const { SendGridApiError, SendGridHttpClient } = require('./http-client.js');
@@ -224,12 +225,8 @@ class SendGridTransport {
       return messageIdHeader;
     }
 
-    // Generate a synthetic message ID based on timestamp
-    // This follows a similar pattern to what SendGrid might use
-    const timestamp = Date.now();
-    const random = Math.random().toString(36).substring(2, 8);
-
-    return `sendgrid-${timestamp}-${random}`;
+    // A synthetic message ID, under a prefix that tells it from SendGrid's.
+    return `sendgrid-${generateId('receipt-id', this.config.generateId)}`;
   }
 }
 
diff --git a/src/ses/config.js b/src/ses/config.js
index e10611e..eda68ba 100644
--- a/src/ses/config.js
+++ b/src/ses/config.js
@@ -36,6 +36,8 @@ const createSesConfig = (config) => {
     authentication: config.authentication,
     region: config.region ?? 'us-east-1',
     timeout: config.timeout ?? 30000,
+    fetch: config.fetch,
+    generateId: config.generateId,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index 2f1c04b..e32dd4d 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -98,7 +98,7 @@ class SesHttpClient {
 
     // A redirect comes back as a response rather than being followed, so the
     // credentials in the headers never reach another origin.
-    return await globalThis.fetch(url, {
+    return await (this.config.fetch ?? globalThis.fetch)(url, {
       ...options,
       headers: this.headersToRecord(signedHeaders),
       signal,
diff --git a/src/ses/index.d.ts b/src/ses/index.d.ts
index 14ed062..37e2028 100644
--- a/src/ses/index.d.ts
+++ b/src/ses/index.d.ts
@@ -1,7 +1,13 @@
 // Types ported from upyo v0.7.0 (packages/ses/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type {
+  Message,
+  Receipt,
+  Transport,
+  TransportDependencies,
+  TransportOptions,
+} from '../../index.js';
 
 /**
  * Authentication configuration for AWS SES.
@@ -75,7 +81,7 @@ export type SesAuthentication =
  * };
  * ```
  */
-export interface SesConfig {
+export interface SesConfig extends TransportDependencies {
   /** AWS authentication configuration. */
   readonly authentication: SesAuthentication;
   /**
@@ -118,15 +124,19 @@ export interface SesConfig {
  * It ensures all required fields have values, making the transport implementation simpler.
  */
 type ResolvedSesConfig = Required<
-  Omit<SesConfig, 'configurationSetName' | 'defaultTags' | 'batchSize'>
-> & {
-  /** SES configuration set name (optional) */
-  readonly configurationSetName?: string;
-  /** Default tags to apply to all emails (always defined, may be empty) */
-  readonly defaultTags: Record<string, string>;
-  /** Maximum concurrent messages in batch operations */
-  readonly batchSize: number;
-};
+  Omit<
+    SesConfig,
+    'configurationSetName' | 'defaultTags' | 'batchSize' | keyof TransportDependencies
+  >
+> &
+  TransportDependencies & {
+    /** SES configuration set name (optional) */
+    readonly configurationSetName?: string;
+    /** Default tags to apply to all emails (always defined, may be empty) */
+    readonly defaultTags: Record<string, string>;
+    /** Maximum concurrent messages in batch operations */
+    readonly batchSize: number;
+  };
 /**
  * Creates a resolved SES configuration with default values applied.
  *
diff --git a/src/ses/ses-transport.js b/src/ses/ses-transport.js
index 0420acf..f1e9de7 100644
--- a/src/ses/ses-transport.js
+++ b/src/ses/ses-transport.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/ses/src/ses-transport.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { generateId } = require('../core/id.js');
 const { createFailedReceipt } = require('../core/receipt.js');
 const { createSesConfig } = require('./config.js');
 const { SesApiError, SesHttpClient } = require('./http-client.js');
@@ -224,10 +225,7 @@ class SesTransport {
       return messageIdHeader;
     }
 
-    const timestamp = Date.now();
-    const random = Math.random().toString(36).substring(2, 8);
-
-    return `ses-${timestamp}-${random}`;
+    return `ses-${generateId('receipt-id', this.config.generateId)}`;
   }
 }
 
diff --git a/tests/types/resend.test-d.ts b/tests/types/resend.test-d.ts
index 82d4537..fb33d0d 100644
--- a/tests/types/resend.test-d.ts
+++ b/tests/types/resend.test-d.ts
@@ -24,3 +24,6 @@ expectAssignable<ResendConfig>({ apiKey: 're_123', baseUrl: 'https://api.resend.
 declare const error: ResendApiError;
 expectType<number | undefined>(error.statusCode);
 expectError(new ResendTransport({}));
+
+// A fetch of the application, and a generator of the idempotency keys.
+expectAssignable<ResendConfig>({ apiKey: 'key', fetch: globalThis.fetch, generateId: () => 'k' });
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index 3edb348..cba5f32 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -297,3 +297,57 @@ test('Delivery: every HTTP provider tells onRetry of its retries', async (t) =>
     }),
   );
 });
+
+test('Delivery: every HTTP transport requests through the fetch it is given', async (t) => {
+  const global = t.mock.method(globalThis, 'fetch', async () => {
+    throw new Error('The global fetch was used.');
+  });
+  const jmap = (extra) =>
+    new JmapTransport({
+      sessionUrl: 'https://jmap.example.com/session',
+      bearerToken: 't',
+      ...extra,
+    });
+  for (const [name, , create] of [...providers, ['JMAP', 200, jmap]]) {
+    const urls = [];
+    const fetch = async (url) => {
+      urls.push(String(url));
+      return new Response('{"message":"No"}', { status: 400 });
+    };
+    const receipt = await create({ fetch }).send(message());
+    assert.strictEqual(receipt.successful, false, name);
+    assert.ok(urls.length > 0, name);
+  }
+  assert.strictEqual(global.mock.callCount(), 0);
+});
+
+test('Delivery: generateId makes the idempotency keys and the synthetic message IDs', async () => {
+  const generateId = (kind) => `01JKEY-${kind}`;
+  const sent = [];
+  const fetch = async (url, init) => {
+    sent.push(new Headers(init.headers));
+    return new Response('not json', { status: 200 });
+  };
+  const resend = new ResendTransport({ apiKey: 'key', retries: 0, generateId, fetch });
+  await resend.send(message());
+  assert.strictEqual(sent.at(-1).get('idempotency-key'), '01JKEY-idempotency-key');
+  const lettermint = new LettermintTransport({ apiToken: 'token', retries: 0, generateId, fetch });
+  await lettermint.send(message());
+  assert.strictEqual(sent.at(-1).get('idempotency-key'), '01JKEY-idempotency-key');
+
+  const ok = async () => new Response('{}', { status: 200 });
+  const ses = new SesTransport({
+    authentication: { type: 'credentials', accessKeyId: 'a', secretAccessKey: 'b' },
+    retries: 0,
+    generateId,
+    fetch: ok,
+  });
+  assert.strictEqual((await ses.send(message())).messageId, 'ses-01JKEY-receipt-id');
+  const sendgrid = new SendGridTransport({
+    apiKey: 'key',
+    retries: 0,
+    generateId,
+    fetch: async () => new Response(null, { status: 202 }),
+  });
+  assert.strictEqual((await sendgrid.send(message())).messageId, 'sendgrid-01JKEY-receipt-id');
+});
diff --git a/tests/unit/plunk-transport.test.js b/tests/unit/plunk-transport.test.js
index 95fab0d..fede84a 100644
--- a/tests/unit/plunk-transport.test.js
+++ b/tests/unit/plunk-transport.test.js
@@ -283,8 +283,12 @@ describe('PlunkTransport - fallback message ID', () => {
         assert.equal(receipt.successful, true);
         if (receipt.successful) {
           // Changed after the port: upstream put the start of the recipient's
-          // local part ("to") into the ID; it carries no personal data now.
-          assert.match(receipt.messageId, /^plunk-\d+-[a-z0-9]+$/);
+          // local part ("to") into the ID; it carries no personal data now,
+          // and comes from generateId (a UUID by default).
+          assert.match(
+            receipt.messageId,
+            /^plunk-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+          );
         }
       },
     );
diff --git a/tests/unit/sendgrid.test.js b/tests/unit/sendgrid.test.js
index 6440f5d..6fab20e 100644
--- a/tests/unit/sendgrid.test.js
+++ b/tests/unit/sendgrid.test.js
@@ -43,7 +43,10 @@ test('SendGrid: a 202 is a success, with the X-Message-Id or a generated id', as
   t.mock.restoreAll();
   t.mock.method(globalThis, 'fetch', async () => accepted());
   const generated = await transport.send(message());
-  assert.match(generated.messageId, /^sendgrid-\d+-\w+$/);
+  assert.match(
+    generated.messageId,
+    /^sendgrid-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+  );
 });
 
 test('SendGrid: sendMany sends arrays and async iterables one by one', async (t) => {
diff --git a/tests/unit/ses.test.js b/tests/unit/ses.test.js
index 3403f30..1f47d0e 100644
--- a/tests/unit/ses.test.js
+++ b/tests/unit/ses.test.js
@@ -108,7 +108,10 @@ test('SES: a 200 without JSON gets a generated message id', async (t) => {
   await withFetch(t, async () => new Response('not json', { status: 200 }));
   const receipt = await new SesTransport({ authentication, retries: 0 }).send(message());
   assert.strictEqual(receipt.successful, true);
-  assert.match(receipt.messageId, /^ses-\d+-\w+$/);
+  assert.match(
+    receipt.messageId,
+    /^ses-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+  );
 });
 
 test('SES: an inline attachment without a type is sent as INLINE octet-stream', async (t) => {

From 64deeb7c6ea274c75ed3c03fe0ab063571a1d298 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 19:04:48 +0300
Subject: [PATCH 117/158] feat(retry,pool,logger,mock,otel): take generateId
 and random

The decorators drew on the globals too: the Message-ID that ./retry and
./pool pin before the first attempt came from crypto.randomUUID, the
receipt of a log-only ./logger likewise, and the choices of the weighted,
priority and selector strategies, the failures and delays of ./mock and
the span sampling of ./otel from Math.random, which tests could only
replace globally. RetryConfig, PoolConfig and the logger options take
generateId, and PoolConfig, the three strategies, MockConfig and
OpenTelemetryConfig a random function. The default is read at each
choice rather than captured, as a ported pool test replaces Math.random
after making its pool.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                             |  5 +++++
 docs/transports/logger.md                |  3 +++
 docs/transports/mock.md                  |  4 ++++
 docs/transports/otel.md                  |  3 ++-
 docs/transports/pool.md                  |  8 +++++++
 docs/transports/retry.md                 |  2 +-
 src/logger/config.js                     |  1 +
 src/logger/index.d.ts                    |  4 ++--
 src/logger/logger-transport.js           |  3 ++-
 src/mock/config.js                       |  1 +
 src/mock/index.d.ts                      |  6 +++++
 src/mock/mock-transport.js               |  7 ++++--
 src/otel/config.js                       |  1 +
 src/otel/index.d.ts                      |  5 +++++
 src/otel/opentelemetry-transport.js      |  1 +
 src/otel/tracing.js                      |  5 +++--
 src/pool/config.js                       |  2 ++
 src/pool/index.d.ts                      | 24 ++++++++++++++++++--
 src/pool/pool-transport.js               |  8 +++----
 src/pool/strategies/priority-strategy.js | 10 ++++++++-
 src/pool/strategies/selector-strategy.js | 10 ++++++++-
 src/pool/strategies/weighted-strategy.js | 10 ++++++++-
 src/retry/config.js                      |  1 +
 src/retry/index.d.ts                     | 11 ++++++++--
 src/retry/retry-transport.js             |  2 +-
 tests/unit/logger.test.js                |  6 +++++
 tests/unit/mock.test.js                  |  7 ++++++
 tests/unit/otel.test.js                  | 17 ++++++++++++++
 tests/unit/pool.test.js                  | 28 ++++++++++++++++++++++++
 tests/unit/retry.test.js                 | 17 ++++++++++++++
 30 files changed, 191 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ccb0929..8110720 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -46,6 +46,11 @@ fixed ones below.
   `fetch`, read at each request in place of the global one (an undici `Agent`, a proxy, mTLS),
   and a `generateId` for their idempotency keys (Resend, Lettermint, the Maileroo reference) and
   for the message IDs they make up when the provider gives none (SES, SendGrid, Plunk).
+- **`generateId` and `random` in the decorators:** `./retry` and `./pool` take `generateId` for
+  the Message-ID they pin before the first attempt, and `./logger` for the message ID of a
+  log-only receipt; `random`, a function like `Math.random`, makes the choices of the pool
+  strategies (their constructors take it too), the simulated failures and delays of `./mock`,
+  and the span sampling of `./otel`.
 - **`./logger` logs retries** as `email.retrying` events, at the new level `levels.retrying`
   (`warn` by default), with the attempt, the wait, the redacted error text and its status code.
   With a wrapped transport, the logger needs a method for that level.
diff --git a/docs/transports/logger.md b/docs/transports/logger.md
index ae58804..e82be94 100644
--- a/docs/transports/logger.md
+++ b/docs/transports/logger.md
@@ -55,6 +55,9 @@ if (receipt.successful) {
 A log-only receipt uses the provider id `"logger"` and a generated message id, but
 it does not imply that an email was delivered outside the application.
 
+A log-only transport returns a receipt whose message ID is `logger-` and a UUID,
+or what `generateId` makes when it is given.
+
 ## Decorating another transport
 
 Pass another transport through the `transport` option to add logs around real
diff --git a/docs/transports/mock.md b/docs/transports/mock.md
index 84c040e..04255c5 100644
--- a/docs/transports/mock.md
+++ b/docs/transports/mock.md
@@ -107,6 +107,10 @@ the delay at once, and the send rejects with the reason of the signal, as a
 real transport does. Failure simulation verifies that your error handling code
 works correctly when email services are unavailable.
 
+`random`, a function like `Math.random`, decides the simulated failures of
+`failureRate` and the delays of `randomDelayRange`, so that a test can make them
+happen exactly when it wants.
+
 ## Testing specific failure scenarios
 
 For testing specific error conditions, you can configure the mock transport
diff --git a/docs/transports/otel.md b/docs/transports/otel.md
index df38685..4f1963d 100644
--- a/docs/transports/otel.md
+++ b/docs/transports/otel.md
@@ -351,7 +351,8 @@ Metrics are recorded for every operation; `tracing.samplingRate` samples
 only the spans. A sampled counter would undercount by the sampling rate, and a
 sampled count of active sends would drift, so the metrics configuration has no
 sampling rate, and setting `metrics.samplingRate` throws a `TypeError`.
-`durationBuckets` reaches the SDK as the advice `explicitBucketBoundaries` of the
+`random`, a function like `Math.random`, decides which operations get a span,
+for a deterministic sampling in tests. `durationBuckets` reaches the SDK as the advice `explicitBucketBoundaries` of the
 duration histogram (OpenTelemetry API 1.7 or later); a View of the application
 takes precedence over it.
 
diff --git a/docs/transports/pool.md b/docs/transports/pool.md
index 19f969c..67c7f9d 100644
--- a/docs/transports/pool.md
+++ b/docs/transports/pool.md
@@ -257,6 +257,14 @@ Every attempt of one `send()` carries the same `Message-ID`: a message without
 one gets a generated one before the first attempt, so a recipient's server can
 tell a duplicate apart.
 
+### Determinism and identifiers
+
+The weighted, priority and selector strategies choose at random among their
+candidates; `random`, a function like `Math.random`, makes those choices
+instead, such as a seeded one in tests. `generateId` makes the Message-ID the
+pool gives a message without one before the first attempt, so that every
+transport it tries sends the same one.
+
 ## Custom strategies
 
 For advanced use cases, you can implement custom routing strategies by
diff --git a/docs/transports/retry.md b/docs/transports/retry.md
index 368a307..adadcba 100644
--- a/docs/transports/retry.md
+++ b/docs/transports/retry.md
@@ -84,7 +84,7 @@ A receipt whose delivery is unknown (`receipt.deliveryUnknown`) is not
 retried: the message may have been accepted before the timeout or the lost
 connection, and another attempt could deliver it twice.  Every attempt carries
 the same `Message-ID`, generated before the first one when the message has
-none, so that a duplicate can be told apart.
+none, so that a duplicate can be told apart (made by `generateId`, when given).
 
 If a wrapped transport throws a transient error instead of returning a failed
 receipt, retry transport retries it using the same classifier used by
diff --git a/src/logger/config.js b/src/logger/config.js
index a9d3cbf..ebcab05 100644
--- a/src/logger/config.js
+++ b/src/logger/config.js
@@ -45,6 +45,7 @@ const resolveLoggerTransportOptions = (options) => {
     logger,
     recordMessage: options.recordMessage ?? false,
     levels,
+    generateId: options.generateId,
   };
 };
 
diff --git a/src/logger/index.d.ts b/src/logger/index.d.ts
index 3e453ef..739d44e 100644
--- a/src/logger/index.d.ts
+++ b/src/logger/index.d.ts
@@ -4,7 +4,7 @@
 
 /// <reference lib="esnext.disposable" />
 
-import type { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type { IdOptions, Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * A log level, by pino's names (LogTape's `warning` is `warn`).
@@ -68,7 +68,7 @@ export interface LoggerTransportLevels {
  *
  * @typeParam TProviderId The provider id of the wrapped transport.
  */
-export interface LoggerTransportOptions<TProviderId extends string = 'logger'> {
+export interface LoggerTransportOptions<TProviderId extends string = 'logger'> extends IdOptions {
   /**
    * The logger to write to. It must have a method for each configured level;
    * the transport checks that when it is made.
diff --git a/src/logger/logger-transport.js b/src/logger/logger-transport.js
index 673de67..28e8b6e 100644
--- a/src/logger/logger-transport.js
+++ b/src/logger/logger-transport.js
@@ -3,6 +3,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { inspect } = require('node:util');
+const { generateId } = require('../core/id.js');
 const { redactAddresses } = require('../internal/redact-addresses.js');
 const { resolveLoggerTransportOptions } = require('./config.js');
 const { PendingQueue } = require('./pending-queue.js');
@@ -191,7 +192,7 @@ class LoggerTransport {
   createSyntheticReceipt() {
     return {
       successful: true,
-      messageId: `logger-${crypto.randomUUID()}`,
+      messageId: `logger-${generateId('receipt-id', this.config.generateId)}`,
       provider: this.id,
       attempts: 1,
       timestamp: new Date().toISOString(),
diff --git a/src/mock/config.js b/src/mock/config.js
index 6b99c84..6a95fb9 100644
--- a/src/mock/config.js
+++ b/src/mock/config.js
@@ -32,6 +32,7 @@ const createMockConfig = (config = {}) => {
     randomDelayRange: config.randomDelayRange ?? { min: 0, max: 0 },
     failureRate: config.failureRate ?? 0,
     generateUniqueMessageIds: config.generateUniqueMessageIds ?? true,
+    random: config.random,
   };
 };
 
diff --git a/src/mock/index.d.ts b/src/mock/index.d.ts
index 0c74e1b..f6fe51b 100644
--- a/src/mock/index.d.ts
+++ b/src/mock/index.d.ts
@@ -52,6 +52,12 @@ export interface MockConfig {
    * @default true
    */
   readonly generateUniqueMessageIds?: boolean;
+  /**
+   * The source of the random choices, a function like `Math.random` (for
+   * tests, a deterministic one).
+   * @default Math.random, read at each choice
+   */
+  readonly random?: () => number;
 }
 /**
  * Resolved mock configuration with all optional fields filled with default values.
diff --git a/src/mock/mock-transport.js b/src/mock/mock-transport.js
index 4e99188..7239261 100644
--- a/src/mock/mock-transport.js
+++ b/src/mock/mock-transport.js
@@ -323,7 +323,7 @@ class MockTransport {
       (this.config.randomDelayRange.min > 0 || this.config.randomDelayRange.max > 0)
     ) {
       const { min, max } = this.config.randomDelayRange;
-      delayMs = Math.random() * (max - min) + min;
+      delayMs = (this.config.random ?? Math.random)() * (max - min) + min;
     }
 
     if (delayMs > 0) {
@@ -333,7 +333,10 @@ class MockTransport {
 
   getResponse() {
     // Check for random failure first
-    if (this.config.failureRate > 0 && Math.random() < this.config.failureRate) {
+    if (
+      this.config.failureRate > 0 &&
+      (this.config.random ?? Math.random)() < this.config.failureRate
+    ) {
       return createFailedReceipt('Simulated random failure', {
         provider: 'mock',
         category: 'unknown',
diff --git a/src/otel/config.js b/src/otel/config.js
index 85df26f..296caf5 100644
--- a/src/otel/config.js
+++ b/src/otel/config.js
@@ -66,6 +66,7 @@ const createOpenTelemetryConfig = (config = {}) => {
     },
     attributeExtractor: config.attributeExtractor,
     errorClassifier: config.errorClassifier,
+    random: config.random,
   };
 
   // Validate required providers
diff --git a/src/otel/index.d.ts b/src/otel/index.d.ts
index 49bf088..cc93fc4 100644
--- a/src/otel/index.d.ts
+++ b/src/otel/index.d.ts
@@ -166,6 +166,11 @@ export interface OpenTelemetryConfig {
    * Called to classify errors into categories for metrics.
    */
   readonly errorClassifier?: ErrorClassifier;
+  /**
+   * The source of the sampling of the spans, a function like `Math.random`.
+   * @default Math.random, read at each span
+   */
+  readonly random?: () => number;
 }
 /**
  * Resolved configuration with all defaults applied.
diff --git a/src/otel/opentelemetry-transport.js b/src/otel/opentelemetry-transport.js
index bde4cb1..1238c16 100644
--- a/src/otel/opentelemetry-transport.js
+++ b/src/otel/opentelemetry-transport.js
@@ -116,6 +116,7 @@ class OpenTelemetryTransport {
         this.config.tracing,
         this.transportName,
         this.transportVersion,
+        this.config.random,
       );
     }
   }
diff --git a/src/otel/tracing.js b/src/otel/tracing.js
index ca5253a..499f7ef 100644
--- a/src/otel/tracing.js
+++ b/src/otel/tracing.js
@@ -31,8 +31,9 @@ class TracingCollector {
   config;
   attributeExtractor;
 
-  constructor(tracerProvider, config, transportName, transportVersion) {
+  constructor(tracerProvider, config, transportName, transportVersion, random) {
     this.config = config;
+    this.random = random;
     this.tracer = tracerProvider.getTracer(metadata.name, metadata.version);
     this.attributeExtractor = new EmailAttributeExtractor(
       transportName,
@@ -92,7 +93,7 @@ class TracingCollector {
   }
 
   shouldSample() {
-    return Math.random() < this.config.samplingRate;
+    return (this.random ?? Math.random)() < this.config.samplingRate;
   }
 }
 
diff --git a/src/pool/config.js b/src/pool/config.js
index e471e60..2fbf258 100644
--- a/src/pool/config.js
+++ b/src/pool/config.js
@@ -43,6 +43,8 @@ const createPoolConfig = (config) => {
     maxRetries: config.maxRetries ?? enabledTransports.length - 1,
     timeout: config.timeout,
     continueOnSuccess: config.continueOnSuccess ?? false,
+    random: config.random,
+    generateId: config.generateId,
   };
 };
 
diff --git a/src/pool/index.d.ts b/src/pool/index.d.ts
index 139f46a..7cd4126 100644
--- a/src/pool/index.d.ts
+++ b/src/pool/index.d.ts
@@ -3,7 +3,7 @@
 
 /// <reference lib="esnext.disposable" />
 
-import { Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import { IdOptions, Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Result of transport selection by a strategy.
@@ -84,7 +84,7 @@ export interface TransportEntry<TProviderId extends string = string> {
 /**
  * Configuration options for the pool transport.
  */
-export interface PoolConfig<TProviderId extends string = string> {
+export interface PoolConfig<TProviderId extends string = string> extends IdOptions {
   /**
    * The strategy to use for selecting transports.
    * Can be a built-in strategy name or a custom Strategy instance.
@@ -110,6 +110,12 @@ export interface PoolConfig<TProviderId extends string = string> {
    * when using selector-based strategy. Defaults to false.
    */
   readonly continueOnSuccess?: boolean;
+  /**
+   * The source of the random choices, a function like `Math.random` (for
+   * tests, a deterministic one).
+   * @default Math.random, read at each choice
+   */
+  readonly random?: () => number;
 }
 /**
  * Resolved pool configuration with defaults applied.
@@ -120,6 +126,8 @@ export interface ResolvedPoolConfig<TProviderId extends string = string> {
   readonly maxRetries: number;
   readonly timeout?: number;
   readonly continueOnSuccess: boolean;
+  readonly random?: () => number;
+  readonly generateId?: IdOptions['generateId'];
 }
 /**
  * Resolved transport entry with defaults applied.
@@ -285,6 +293,10 @@ export declare class RoundRobinStrategy<
 export declare class WeightedStrategy<
   TProviderId extends string = string,
 > implements Strategy<TProviderId> {
+  /**
+   * @param options `random`, the source of the random choices.
+   */
+  constructor(options?: { readonly random?: () => number });
   /**
    * Selects a transport based on weighted random distribution.
    *
@@ -317,6 +329,10 @@ export declare class WeightedStrategy<
 export declare class PriorityStrategy<
   TProviderId extends string = string,
 > implements Strategy<TProviderId> {
+  /**
+   * @param options `random`, the source of the random choices.
+   */
+  constructor(options?: { readonly random?: () => number });
   /**
    * Selects the highest priority transport that hasn't been attempted.
    *
@@ -349,6 +365,10 @@ export declare class PriorityStrategy<
 export declare class SelectorStrategy<
   TProviderId extends string = string,
 > implements Strategy<TProviderId> {
+  /**
+   * @param options `random`, the source of the random choices.
+   */
+  constructor(options?: { readonly random?: () => number });
   /**
    * Selects a transport based on selector function matching.
    *
diff --git a/src/pool/pool-transport.js b/src/pool/pool-transport.js
index 8e68bdf..ca2d370 100644
--- a/src/pool/pool-transport.js
+++ b/src/pool/pool-transport.js
@@ -95,7 +95,7 @@ class PoolTransport {
    * @returns A promise that resolves to a receipt indicating success or failure.
    */
   async send(message, options) {
-    const pinned = pinMessageId(message);
+    const pinned = pinMessageId(message, this.config.generateId);
     const attemptedIndices = new Set();
     const errorMessages = [];
     const errors = [];
@@ -269,11 +269,11 @@ class PoolTransport {
       case 'round-robin':
         return new RoundRobinStrategy();
       case 'weighted':
-        return new WeightedStrategy();
+        return new WeightedStrategy({ random: this.config.random });
       case 'priority':
-        return new PriorityStrategy();
+        return new PriorityStrategy({ random: this.config.random });
       case 'selector-based':
-        return new SelectorStrategy();
+        return new SelectorStrategy({ random: this.config.random });
       default:
         throw new Error(`Unknown strategy: ${strategy}`);
     }
diff --git a/src/pool/strategies/priority-strategy.js b/src/pool/strategies/priority-strategy.js
index bcb1bbe..525d062 100644
--- a/src/pool/strategies/priority-strategy.js
+++ b/src/pool/strategies/priority-strategy.js
@@ -10,6 +10,14 @@
  * equivalent and one is selected randomly.
  */
 class PriorityStrategy {
+  /**
+   * @param options `random`, the source of the random choices; by default
+   *                `Math.random`, read at each choice.
+   */
+  constructor(options) {
+    this.random = options?.random;
+  }
+
   /**
    * Selects the highest priority transport that hasn't been attempted.
    *
@@ -41,7 +49,7 @@ class PriorityStrategy {
 
     // If multiple transports have the same priority, select randomly
     if (topPriorityTransports.length > 1) {
-      const randomIndex = Math.floor(Math.random() * topPriorityTransports.length);
+      const randomIndex = Math.floor((this.random ?? Math.random)() * topPriorityTransports.length);
       return topPriorityTransports[randomIndex];
     }
 
diff --git a/src/pool/strategies/selector-strategy.js b/src/pool/strategies/selector-strategy.js
index f823996..0ddad38 100644
--- a/src/pool/strategies/selector-strategy.js
+++ b/src/pool/strategies/selector-strategy.js
@@ -10,6 +10,14 @@
  * one is selected randomly.
  */
 class SelectorStrategy {
+  /**
+   * @param options `random`, the source of the random choices; by default
+   *                `Math.random`, read at each choice.
+   */
+  constructor(options) {
+    this.random = options?.random;
+  }
+
   /**
    * Selects a transport based on selector function matching.
    *
@@ -49,7 +57,7 @@ class SelectorStrategy {
     if (candidates.length < 1) return undefined;
 
     // Select randomly from candidates
-    const randomIndex = Math.floor(Math.random() * candidates.length);
+    const randomIndex = Math.floor((this.random ?? Math.random)() * candidates.length);
     return candidates[randomIndex];
   }
 
diff --git a/src/pool/strategies/weighted-strategy.js b/src/pool/strategies/weighted-strategy.js
index 8a0652b..f36122c 100644
--- a/src/pool/strategies/weighted-strategy.js
+++ b/src/pool/strategies/weighted-strategy.js
@@ -10,6 +10,14 @@
  * messages as a transport with weight 1.
  */
 class WeightedStrategy {
+  /**
+   * @param options `random`, the source of the random choices; by default
+   *                `Math.random`, read at each choice.
+   */
+  constructor(options) {
+    this.random = options?.random;
+  }
+
   /**
    * Selects a transport based on weighted random distribution.
    *
@@ -35,7 +43,7 @@ class WeightedStrategy {
     if (lastIndex === -1 || totalWeight <= 0) return undefined;
 
     // Random selection based on weights
-    const random = Math.random() * totalWeight;
+    const random = (this.random ?? Math.random)() * totalWeight;
     let cumulativeWeight = 0;
 
     for (let index = 0; index < transports.length; index++) {
diff --git a/src/retry/config.js b/src/retry/config.js
index 8d63a8e..605802e 100644
--- a/src/retry/config.js
+++ b/src/retry/config.js
@@ -35,6 +35,7 @@ const createRetryConfig = (config = {}) => {
     jitter: config.jitter ?? 'full',
     random: config.random ?? Math.random,
     shouldRetry: config.shouldRetry,
+    generateId: config.generateId,
     wait: config.wait ?? defaultWait,
     sendMany: {
       maxConcurrent,
diff --git a/src/retry/index.d.ts b/src/retry/index.d.ts
index e35feea..1f2a495 100644
--- a/src/retry/index.d.ts
+++ b/src/retry/index.d.ts
@@ -3,7 +3,14 @@
 
 /// <reference lib="esnext.disposable" />
 
-import type { Message, Receipt, ReceiptError, Transport, TransportOptions } from '../../index.js';
+import type {
+  IdOptions,
+  Message,
+  Receipt,
+  ReceiptError,
+  Transport,
+  TransportOptions,
+} from '../../index.js';
 
 /**
  * Jitter mode for computed retry delays.
@@ -124,7 +131,7 @@ export interface SendManyRetryConfig {
 /**
  * Configuration for the retry transport decorator.
  */
-export interface RetryConfig<TProviderId extends string = string> {
+export interface RetryConfig<TProviderId extends string = string> extends IdOptions {
   /**
    * Total number of send attempts, including the first one.
    *
diff --git a/src/retry/retry-transport.js b/src/retry/retry-transport.js
index 9498c11..aa85147 100644
--- a/src/retry/retry-transport.js
+++ b/src/retry/retry-transport.js
@@ -57,7 +57,7 @@ class RetryTransport {
   async send(message, options) {
     options?.signal?.throwIfAborted();
 
-    const pinned = pinMessageId(message);
+    const pinned = pinMessageId(message, this.config.generateId);
     let lastThrownError;
     for (let attempt = 1; attempt <= this.config.maxAttempts; attempt++) {
       options?.signal?.throwIfAborted();
diff --git a/tests/unit/logger.test.js b/tests/unit/logger.test.js
index a63bc9c..99d11c0 100644
--- a/tests/unit/logger.test.js
+++ b/tests/unit/logger.test.js
@@ -180,3 +180,9 @@ test('Logger: a logger that throws loses no receipt and stops no send', async (t
     { code: 'MAILER_LOGGER_FAILED' },
   ]);
 });
+
+test('Logger: generateId makes the message ID of a log-only receipt', async () => {
+  const logger = { debug: () => {}, info: () => {}, error: () => {} };
+  const transport = new LoggerTransport({ logger, generateId: () => '01JLOG' });
+  assert.strictEqual((await transport.send(message())).messageId, 'logger-01JLOG');
+});
diff --git a/tests/unit/mock.test.js b/tests/unit/mock.test.js
index 0069037..946ac29 100644
--- a/tests/unit/mock.test.js
+++ b/tests/unit/mock.test.js
@@ -83,3 +83,10 @@ test('Mock: an abort ends the configured delay, with the reason of the signal',
   assert.ok(performance.now() - started < 1000);
   assert.strictEqual(transport.getSentMessagesCount(), 0);
 });
+
+test('Mock: random decides the simulated failures', async () => {
+  const failing = new MockTransport({ failureRate: 0.5, random: () => 0.1 });
+  assert.strictEqual((await failing.send(message('Hi'))).successful, false);
+  const passing = new MockTransport({ failureRate: 0.5, random: () => 0.9 });
+  assert.strictEqual((await passing.send(message('Hi'))).successful, true);
+});
diff --git a/tests/unit/otel.test.js b/tests/unit/otel.test.js
index f52e20e..d04bf6a 100644
--- a/tests/unit/otel.test.js
+++ b/tests/unit/otel.test.js
@@ -436,3 +436,20 @@ test('OTel: an exception event carries the stack, its message redacted', async (
     assert.match(stacktrace, /\n {4}at /);
   }
 });
+
+test('OTel: random decides which operations get a span', async () => {
+  for (const [value, spans] of [
+    [0.9, 0],
+    [0.1, 1],
+  ]) {
+    const { tracerProvider, meterProvider } = providers();
+    const transport = new OpenTelemetryTransport(plain({}), {
+      tracerProvider,
+      meterProvider,
+      tracing: { samplingRate: 0.5 },
+      random: () => value,
+    });
+    await transport.send(createTestMessage());
+    assert.strictEqual(tracerProvider.getAllSpans().length, spans);
+  }
+});
diff --git a/tests/unit/pool.test.js b/tests/unit/pool.test.js
index 157b7a2..d3b638a 100644
--- a/tests/unit/pool.test.js
+++ b/tests/unit/pool.test.js
@@ -174,3 +174,31 @@ test('Pool: an abort rejects with the reason of the signal', async () => {
   const batch = pool.sendMany([message()], { signal: controller.signal });
   await assert.rejects(batch[Symbol.asyncIterator]().next(), (e) => e === reason);
 });
+
+test('Pool: random makes the choices, and generateId the pinned Message-ID', async () => {
+  const received = [];
+  const recording = (id) => ({
+    id,
+    send: async (sent) => {
+      received.push([id, sent.messageId]);
+      return { successful: true, messageId: id };
+    },
+    async *sendMany() {},
+  });
+  const values = [0.9, 0.1];
+  const pool = new PoolTransport({
+    strategy: 'weighted',
+    transports: [
+      { transport: recording('a'), weight: 1 },
+      { transport: recording('b'), weight: 1 },
+    ],
+    random: () => values.shift(),
+    generateId: (kind) => `01JPOOL.${kind}`,
+  });
+  await pool.send(message());
+  await pool.send(message());
+  assert.deepStrictEqual(received, [
+    ['b', '01JPOOL.message-id@example.com'],
+    ['a', '01JPOOL.message-id@example.com'],
+  ]);
+});
diff --git a/tests/unit/retry.test.js b/tests/unit/retry.test.js
index 90ff296..267f104 100644
--- a/tests/unit/retry.test.js
+++ b/tests/unit/retry.test.js
@@ -206,3 +206,20 @@ test('Retry: a bug of the wrapped transport rejects, a network TypeError is retr
   assert.strictEqual(receipt.successful, false);
   assert.strictEqual(calls, 3);
 });
+
+test('Retry: generateId makes the Message-ID pinned for every attempt', async () => {
+  const ids = [];
+  const base = sequence(failure(true), success);
+  const send = base.send;
+  base.send = (sent, options) => {
+    ids.push(sent.messageId);
+    return send(sent, options);
+  };
+  const transport = new RetryTransport(base, {
+    maxAttempts: 2,
+    wait: async () => {},
+    generateId: () => '01JRETRY',
+  });
+  await transport.send(message());
+  assert.deepStrictEqual(ids, ['01JRETRY@example.com', '01JRETRY@example.com']);
+});

From 6b627c203a4796c3a2d5a25699efff3904d93895 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 19:07:22 +0300
Subject: [PATCH 118/158] feat(core): share the logger types and add an
 internal log

Logger, LogMethod and LoggerLevel move from ./logger to the root entry,
which ./logger re-exports, with the optional child and isLevelEnabled of
pino, and TransportDependencies gains a logger option for what happens
inside a transport. src/internal/log.js makes the log of a component: the
logger bound through child(), or the bindings merged into each record,
records built only for a level that is written, and a logger that throws
turned into a process warning rather than a failed send. warnDegradation
is the one output without a logger: a console.warn for mail sent with
less protection than was asked for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 index.d.ts                  | 41 +++++++++++++++++++--
 src/internal/log.js         | 71 +++++++++++++++++++++++++++++++++++++
 src/logger/index.d.ts       | 39 +++++++-------------
 tests/unit/internal.test.js | 54 ++++++++++++++++++++++++++++
 4 files changed, 177 insertions(+), 28 deletions(-)
 create mode 100644 src/internal/log.js

diff --git a/index.d.ts b/index.d.ts
index 6c9a6eb..abaaba5 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -727,12 +727,49 @@ export type IdKind = 'message-id' | 'content-id' | 'idempotency-key' | 'receipt-
  * anything else is a `TypeError` before a message is sent.
  */
 export type IdGenerator = (kind: IdKind) => string;
+/**
+ * A log level, by pino's names.
+ */
+export type LoggerLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * A log method that takes the structured properties first and the message
+ * second, as pino's do.
+ */
+export type LogMethod = (properties: object, message: string) => unknown;
+/**
+ * A pino-like logger: a pino logger, a child of one
+ * (`logger.child({ component: 'mail' })`), or anything with the methods of the
+ * levels it is used with.  `child` and `isLevelEnabled`, which pino has, are
+ * used when present: the first to bind the transport to every record, the
+ * second to skip building one that would not be written.
+ */
+export interface Logger {
+  readonly trace?: LogMethod;
+  readonly debug?: LogMethod;
+  readonly info?: LogMethod;
+  readonly warn?: LogMethod;
+  readonly error?: LogMethod;
+  readonly fatal?: LogMethod;
+  readonly child?: (bindings: object) => Logger;
+  readonly isLevelEnabled?: (level: string) => boolean;
+}
 /**
  * What a transport may be given in place of a global of the runtime: the
- * generator of its identifiers and, for one that makes HTTP requests, the
- * `fetch` it makes them with.
+ * generator of its identifiers, its logger and, for one that makes HTTP
+ * requests, the `fetch` it makes them with.
  */
 export interface TransportDependencies extends IdOptions {
+  /**
+   * A logger for what happens inside the transport, which its receipts do
+   * not tell: the connections, upgrades and authentication of SMTP, the
+   * retries of a request, a selector that throws (`debug`, `trace` for the
+   * SMTP protocol, `warn` for a degradation).  The failures of messages are
+   * in their receipts and are not logged again.  Without a logger the
+   * transport writes nothing, except a warning through `console.warn` when it
+   * sends mail without TLS or without the DKIM signature it was asked for.
+   * Credentials and addresses are never logged.
+   */
+  readonly logger?: Logger;
   /**
    * The `fetch` of the requests, such as one bound to an undici `Agent` with
    * keep-alive and connection limits, a `ProxyAgent` or mTLS:
diff --git a/src/internal/log.js b/src/internal/log.js
new file mode 100644
index 0000000..89144ca
--- /dev/null
+++ b/src/internal/log.js
@@ -0,0 +1,71 @@
+// Not ported from upyo: the logging of what happens inside a transport, through
+// the pino-like logger the application passes in.  Without one a transport
+// writes nothing, except the warnings of warnDegradation.
+
+/**
+ * Makes the log of a component: the logger bound to `bindings` through
+ * `child()` when it has one, or with them merged into each record otherwise.
+ * A record is built only for a level the logger would write, and a logger
+ * that throws changes nothing of a send: its failure becomes a process
+ * warning.
+ *
+ * @param logger The logger of the application, if any.
+ * @param bindings The properties of every record, such as `{ transport }`.
+ * @returns The log of the component.
+ * @internal
+ */
+const createLog = (logger, bindings) => {
+  if (logger == null) return SILENT;
+  const bound = typeof logger.child === 'function' ? logger.child(bindings) : logger;
+  const merge = bound === logger;
+  const isEnabled = (level) =>
+    typeof bound[level] === 'function' && (bound.isLevelEnabled?.(level) ?? true);
+  return {
+    hasLogger: true,
+    isEnabled,
+    /**
+     * Writes a record, its properties given as an object or as a function
+     * that builds them, called only when the level is written.
+     */
+    write(level, properties, message) {
+      if (!isEnabled(level)) return;
+      const built = typeof properties === 'function' ? properties() : properties;
+      try {
+        bound[level](merge ? { ...bindings, ...built } : built, message);
+      } catch (error) {
+        process.emitWarning(`A logger passed to the mailer threw: ${error?.message ?? error}`, {
+          code: 'MAILER_LOGGER_FAILED',
+        });
+      }
+    },
+  };
+};
+
+const SILENT = Object.freeze({
+  hasLogger: false,
+  isEnabled: () => false,
+  write: () => {},
+});
+
+/**
+ * Warns that mail goes out with less protection than was asked for, such as
+ * without TLS or without its DKIM signature: through the logger when there is
+ * one, through `console.warn` otherwise, as the one thing a transport writes
+ * without a logger.
+ *
+ * @param log The log of the component.
+ * @param code The code of the warning, such as `MAILER_SMTP_PLAINTEXT`.
+ * @param message What happened.
+ * @param properties More properties of the record.
+ * @internal
+ */
+const warnDegradation = (log, code, message, properties) => {
+  if (log.hasLogger) {
+    log.write('warn', () => ({ code, ...properties }), message);
+    return;
+  }
+  // oxlint-disable-next-line no-console -- mail sent with less protection than asked, without a logger to tell
+  console.warn(`${code}: ${message}`);
+};
+
+module.exports = { createLog, warnDegradation };
diff --git a/src/logger/index.d.ts b/src/logger/index.d.ts
index 739d44e..6faae41 100644
--- a/src/logger/index.d.ts
+++ b/src/logger/index.d.ts
@@ -4,33 +4,20 @@
 
 /// <reference lib="esnext.disposable" />
 
-import type { IdOptions, Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import type {
+  IdOptions,
+  Logger,
+  LoggerLevel,
+  Message,
+  Receipt,
+  Transport,
+  TransportOptions,
+} from '../../index.js';
 
-/**
- * A log level, by pino's names (LogTape's `warning` is `warn`).
- */
-export type LoggerLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-
-/**
- * A log method that takes the structured properties first and the message
- * second, as pino's do.
- */
-export type LogMethod = (properties: object, message: string) => unknown;
-
-/**
- * The logger the transport writes to: a pino logger, a child of one
- * (`logger.child({ component: 'mail' })`), or anything with the methods of the
- * levels in use. `debug`, `info` and `error` are the default levels, and `warn`
- * when a transport is wrapped.
- */
-export interface Logger {
-  readonly trace?: LogMethod;
-  readonly debug?: LogMethod;
-  readonly info?: LogMethod;
-  readonly warn?: LogMethod;
-  readonly error?: LogMethod;
-  readonly fatal?: LogMethod;
-}
+// The logger types are those of the root entry, shared by every transport;
+// LoggerTransport writes with `debug`, `info` and `error` by default, and
+// `warn` when it wraps a transport.
+export type { Logger, LoggerLevel, LogMethod } from '../../index.js';
 
 /**
  * Log levels used for email delivery lifecycle events.
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index 3e045bc..fe0baf3 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -368,3 +368,57 @@ test('Internal: one loopback rule serves SMTP, OAuth 2.0 and the HTTP providers'
   }
   assert.throws(() => new OAuth2TokenManager(refresh('http://auth.example.com/token')), TypeError);
 });
+
+test('Internal: a log binds its component, builds records lazily, and never throws', (t) => {
+  const { createLog, warnDegradation } = require('../../src/internal/log.js');
+  const records = [];
+  const pinoLike = (bindings = {}) => ({
+    child: (more) => pinoLike({ ...bindings, ...more }),
+    isLevelEnabled: (level) => level !== 'trace',
+    debug: (properties, message) =>
+      records.push(['debug', { ...bindings, ...properties }, message]),
+    trace: () => assert.fail('trace is not enabled'),
+    warn: (properties, message) => records.push(['warn', { ...bindings, ...properties }, message]),
+  });
+  const log = createLog(pinoLike(), { transport: 'smtp' });
+  log.write('debug', { step: 'connect' }, 'Connected.');
+  log.write('trace', () => assert.fail('built for a level not written'), 'Never.');
+  log.write('info', { step: 'none' }, 'No info method.');
+  // A logger without child() gets the bindings in each record.
+  const plain = [];
+  createLog({ debug: (properties) => plain.push(properties) }, { transport: 'ses' }).write(
+    'debug',
+    { attempt: 1 },
+    'Retrying.',
+  );
+  assert.deepStrictEqual(records, [
+    ['debug', { transport: 'smtp', step: 'connect' }, 'Connected.'],
+  ]);
+  assert.deepStrictEqual(plain, [{ transport: 'ses', attempt: 1 }]);
+
+  const warnings = t.mock.method(process, 'emitWarning', () => {});
+  createLog(
+    {
+      debug: () => {
+        throw new Error('Sink down');
+      },
+    },
+    {},
+  ).write('debug', {}, 'x');
+  assert.strictEqual(warnings.mock.calls[0].arguments[1].code, 'MAILER_LOGGER_FAILED');
+
+  // A degradation goes to the logger, or to console.warn without one.
+  warnDegradation(log, 'MAILER_SMTP_PLAINTEXT', 'Sent without TLS.', { host: 'mx' });
+  assert.deepStrictEqual(records.at(-1), [
+    'warn',
+    { transport: 'smtp', code: 'MAILER_SMTP_PLAINTEXT', host: 'mx' },
+    'Sent without TLS.',
+  ]);
+  const consoleWarn = t.mock.method(console, 'warn', () => {});
+  warnDegradation(createLog(undefined, {}), 'MAILER_DKIM_UNSIGNED', 'Sent unsigned.');
+  assert.deepStrictEqual(consoleWarn.mock.calls[0].arguments, [
+    'MAILER_DKIM_UNSIGNED: Sent unsigned.',
+  ]);
+  createLog(undefined, {}).write('warn', () => assert.fail('no logger'), 'x');
+  assert.strictEqual(createLog(undefined, {}).isEnabled('warn'), false);
+});

From 838ebf4bff7dffdd081f0a5fe8b4499819988a0b Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 19:10:13 +0300
Subject: [PATCH 119/158] fix(mime): tell an unsigned DKIM send to the logger

Under onSigningFailure: 'send-unsigned', a failed signature was reported
with console.warn whatever the application logged with (known upstream
bug 12). composeMessage and SmtpTransport now take a logger, the plan of
a message carries its log, and the failure goes to it as a warn with the
code MAILER_DKIM_UNSIGNED and the error, or to console.warn only when no
logger was given. prepareMimeMessage takes { generateId, logger } in
place of its positional generateId. The id generator and the log take
mime to 6.6 KB and smtp to 18.7 KB, so their budgets rise to 7 and 19.5,
the latter with the SMTP diagnostics to come.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/npm-publish/SKILL.md |  2 +-
 .github/workflows/ci.yml            |  2 +-
 CHANGELOG.md                        |  4 ++++
 CLAUDE.md                           |  8 ++++++--
 docs/guide/known-issues.md          |  1 -
 src/mime/index.d.ts                 | 13 ++++++++++++-
 src/mime/index.js                   |  2 +-
 src/mime/message.js                 |  7 +++++--
 src/mime/stream.js                  |  9 +++++++--
 src/smtp/message-converter.js       |  4 ++--
 src/smtp/smtp-transport.js          | 16 ++--------------
 tests/unit/mime.test.js             | 13 ++++++++++++-
 12 files changed, 53 insertions(+), 28 deletions(-)

diff --git a/.claude/skills/npm-publish/SKILL.md b/.claude/skills/npm-publish/SKILL.md
index 195eb72..4d76b34 100644
--- a/.claude/skills/npm-publish/SKILL.md
+++ b/.claude/skills/npm-publish/SKILL.md
@@ -37,7 +37,7 @@ pnpm run check:dts               # tsc over the d.ts of every entry of the expor
 These are the same gates `prepublishOnly` runs. CI adds three more; run them too:
 
 ```bash
-pnpm size --max-gzip 8 --max-gzip-smtp 18.5 …                   # the budgets: copy the size step of ci.yml
+pnpm size --max-gzip 8 --max-gzip-smtp 19.5 …                   # the budgets: copy the size step of ci.yml
 pnpm docs:comparison && git diff --exit-code docs/guide/comparison.md   # the table matches docs/comparison.json
 pnpm run docs:build                                              # the docs site; a dead link fails it
 ```
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2945b2c..81e0807 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 8 --max-gzip-mime 6.5 --max-gzip-smtp 18.5 --max-gzip-jmap 10.5 --max-gzip-ses 5 --max-gzip-resend 4.5 --max-gzip-sendgrid 4.5 --max-gzip-mailgun 4 --max-gzip-mailtrap 5.5 --max-gzip-maileroo 5 --max-gzip-lettermint 5 --max-gzip-plunk 4.5 --max-gzip-pool 2.5 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
+      - run: pnpm size --max-gzip 8 --max-gzip-mime 7 --max-gzip-smtp 19.5 --max-gzip-jmap 10.5 --max-gzip-ses 5 --max-gzip-resend 4.5 --max-gzip-sendgrid 4.5 --max-gzip-mailgun 4 --max-gzip-mailtrap 5.5 --max-gzip-maileroo 5 --max-gzip-lettermint 5 --max-gzip-plunk 4.5 --max-gzip-pool 2.5 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
 
   types:
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8110720..7e78781 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -273,6 +273,10 @@ fixed ones below.
   the delay at once, and the send rejects with the reason of the signal.
 - **`./pool` rejects an aborted send with the reason of the signal** (an upstream bug), not with
   a new `AbortError`, like the other transports.
+- **A DKIM signature skipped under `send-unsigned` is told to the logger** (known upstream bug 12):
+  it went to `console.warn` whatever the application logged with. It now goes to the `logger`
+  of `composeMessage` or of the SMTP transport, as a `warn` with the code
+  `MAILER_DKIM_UNSIGNED`, and to `console.warn` only when there is no logger.
 - **`./resend` draws its idempotency key from `crypto.randomUUID()`** (known upstream bug 11): it
   came from the clock and `Math.random()`, and two sends that shared a key by chance would get
   the first one's answer, the second never going out.
diff --git a/CLAUDE.md b/CLAUDE.md
index 470dc29..2563e5c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -142,8 +142,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
 10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
 11. (fixed, see 71) resend: the `Idempotency-Key` came from `Math.random`.
-12. `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of `process.emitWarning` or
-    an injected logger.
+12. (partly fixed, see 72) `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of an
+    injected logger. Plunk still warns of a dropped attachment this way.
 13. mime: the first encoded word of a header shares its line with the field name
     (`Subject: =?UTF-8?B?…?=`, 84 characters), past the 76 that RFC 2047 allows a line with
     encoded words.
@@ -364,6 +364,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     strings, which two sends could share, and Resend answers a repeated key with its first
     answer, so one of them would not go. It is `crypto.randomUUID()`.
 
+72. mime (known bug 12): a DKIM signature that failed under `send-unsigned` was told with
+    `console.warn`, whatever the application logged with. It goes to the `logger` of
+    `composeMessage` or of the SMTP transport (`warn`, code `MAILER_DKIM_UNSIGNED`), and to
+    `console.warn` only without one (`warnDegradation` of `internal/log.js`).
 ## Repository layout
 
 ```
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 09389b5..e861619 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -10,7 +10,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
   clients show them as attachments.
 - The first encoded word of a header shares its line with the field name
   (`Subject: =?UTF-8?B?…?=`), past the 76 characters that RFC 2047 allows such a line.
-- DKIM: when signing fails and `send-unsigned` is set, the warning goes to `console.warn`.
 
 ## SMTP
 
diff --git a/src/mime/index.d.ts b/src/mime/index.d.ts
index 3647fb8..307d764 100644
--- a/src/mime/index.d.ts
+++ b/src/mime/index.d.ts
@@ -1,7 +1,13 @@
 // Types ported from upyo v0.7.0 (packages/mime/src)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-import type { IdGenerator, Message, RawMessage, RawMessageValidationError } from '../../index.js';
+import type {
+  IdGenerator,
+  Logger,
+  Message,
+  RawMessage,
+  RawMessageValidationError,
+} from '../../index.js';
 
 /** Composition and lifetime options. @since 0.6.0 */
 export interface ComposeMessageOptions {
@@ -14,6 +20,11 @@ export interface ComposeMessageOptions {
    * @default () => crypto.randomUUID()
    */
   readonly generateId?: IdGenerator;
+  /**
+   * Where a DKIM signature that failed under `onSigningFailure: 'send-unsigned'`
+   * is told (`warn`, code `MAILER_DKIM_UNSIGNED`); `console.warn` without one.
+   */
+  readonly logger?: Logger;
 }
 /** Stable, replayable MIME bytes with a separate delivery envelope. @since 0.6.0 */
 export interface ComposedMessage extends RawMessage {
diff --git a/src/mime/index.js b/src/mime/index.js
index 224f514..a352c1c 100644
--- a/src/mime/index.js
+++ b/src/mime/index.js
@@ -35,7 +35,7 @@ const envelopeRecipients = (message) => {
 const composeMessage = async (message, options = {}) => {
   const { signal } = options;
   // The neutral plan observes promised sources even when envelope validation fails.
-  const plan = prepareMimeMessage(message, options.dkim, options.generateId);
+  const plan = prepareMimeMessage(message, options.dkim, options);
   const { envelope } = createRawMessagePlan({
     envelope: {
       from: message.sender.address,
diff --git a/src/mime/message.js b/src/mime/message.js
index 79fded0..6231f6f 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -11,6 +11,7 @@ const {
   resolveThreadingHeaders,
 } = require('../core/message-id.js');
 const { resolveCalendarContent } = require('../core/calendar.js');
+const { createLog } = require('../internal/log.js');
 const { checkDkimConfig } = require('./dkim/types.js');
 const { resolvePrivateKey } = require('./dkim/sign.js');
 const { attachmentEncodedSize, encodeAttachment } = require('./mime-stream.js');
@@ -26,7 +27,7 @@ const { base64, hasLineLongerThan, utf8 } = require('./bytes.js');
  * date, an address or identity header containing a carriage return or line
  * feed, or an invalid custom header field name.
  */
-const prepareMimeMessage = (message, dkimConfig, generateId) => {
+const prepareMimeMessage = (message, dkimConfig, options = {}) => {
   // Observe every promise before validation can throw or an earlier reader stalls.
   for (const attachment of message.attachments) {
     if (attachment.content instanceof Promise) {
@@ -47,7 +48,7 @@ const prepareMimeMessage = (message, dkimConfig, generateId) => {
             headerFields: signature.headerFields == null ? undefined : [...signature.headerFields],
           })),
         };
-  const parts = buildMimeParts(message, generateId);
+  const parts = buildMimeParts(message, options.generateId);
   const first = parts[0];
   if (typeof first !== 'string') throw new TypeError('Missing MIME headers.');
   const separator = first.indexOf('\r\n\r\n') + 4;
@@ -58,6 +59,8 @@ const prepareMimeMessage = (message, dkimConfig, generateId) => {
   return {
     encoding,
     dkim,
+    // Where a signing failure under send-unsigned is told.
+    log: createLog(options.logger, { component: 'dkim' }),
     headers,
     async *body(signal, progress) {
       for (const part of parts) {
diff --git a/src/mime/stream.js b/src/mime/stream.js
index d9e10fa..69ea454 100644
--- a/src/mime/stream.js
+++ b/src/mime/stream.js
@@ -6,6 +6,7 @@ const { RawMessageValidationError } = require('../core/raw-message.js');
 const { Buffer } = require('node:buffer');
 const { base64, hasLineLongerThan, utf8 } = require('./bytes.js');
 const { BodyHasher } = require('./dkim/body-hash.js');
+const { createLog, warnDegradation } = require('../internal/log.js');
 const { signWithBodyHash } = require('./dkim/sign.js');
 
 /**
@@ -77,8 +78,12 @@ const prepareMimeStream = async (plan, options = {}) => {
   } catch (error) {
     signal?.throwIfAborted();
     if (plan.dkim?.onSigningFailure !== 'send-unsigned') throw error;
-    // oxlint-disable-next-line no-console -- upstream
-    console.warn('DKIM signing failed, sending unsigned:', error);
+    warnDegradation(
+      plan.log ?? createLog(),
+      'MAILER_DKIM_UNSIGNED',
+      'DKIM signing failed; the message is sent unsigned, as onSigningFailure asks.',
+      { error: error instanceof Error ? error.message : String(error) },
+    );
   }
   signal?.throwIfAborted();
   if (hasLineLongerThan(headers, 998)) {
diff --git a/src/smtp/message-converter.js b/src/smtp/message-converter.js
index 3734d4a..3252f63 100644
--- a/src/smtp/message-converter.js
+++ b/src/smtp/message-converter.js
@@ -12,9 +12,9 @@ const prepareMessage = (
   dkimConfig,
   dsn,
   resolvedEnvelope = resolveSmtpEnvelope(message),
-  generateId = undefined,
+  options = {},
 ) => {
-  const plan = prepareMimeMessage(message, dkimConfig, generateId);
+  const plan = prepareMimeMessage(message, dkimConfig, options);
   const envelope = { ...resolvedEnvelope, dsn };
   return {
     ...plan,
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index 12b3899..ff2ea5d 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -222,13 +222,7 @@ class SmtpTransport {
       const dsn = resolveSmtpDsn(envelope, options?.dsn);
       // Composed before a connection is taken: a message that cannot be
       // composed costs no connection, and fails no connection either.
-      const smtpMessage = prepareMessage(
-        message,
-        this.config.dkim,
-        dsn,
-        envelope,
-        this.config.generateId,
-      );
+      const smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope, this.config);
 
       // Establishing the connection—including authentication, e.g. acquiring an
       // OAuth 2.0 access token—is part of delivery, so setup failures are
@@ -361,13 +355,7 @@ class SmtpTransport {
         try {
           const envelope = resolveEnvelopeOption(message, options?.envelope, index++);
           const dsn = resolveSmtpDsn(envelope, options?.dsn);
-          smtpMessage = prepareMessage(
-            message,
-            this.config.dkim,
-            dsn,
-            envelope,
-            this.config.generateId,
-          );
+          smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope, this.config);
         } catch (error) {
           // A message that cannot be composed never reaches the connection.
           yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
diff --git a/tests/unit/mime.test.js b/tests/unit/mime.test.js
index a905837..32d310d 100644
--- a/tests/unit/mime.test.js
+++ b/tests/unit/mime.test.js
@@ -172,8 +172,19 @@ test('MIME: a DKIM failure throws, or sends unsigned when asked to', async (t) =
   t.mock.method(console, 'warn', (...args) => warnings.push(args));
   const text = await wire(message, { dkim: { signatures, onSigningFailure: 'send-unsigned' } });
   assert.doesNotMatch(headerBlock(text), /^DKIM-Signature:/m);
+  // Without a logger, the one warning a transport writes goes to console.warn.
   assert.strictEqual(warnings.length, 1);
-  assert.strictEqual(warnings[0][0], 'DKIM signing failed, sending unsigned:');
+  assert.match(warnings[0][0], /^MAILER_DKIM_UNSIGNED: DKIM signing failed/);
+
+  // With one, the warning goes to it, with the error and no console output.
+  const records = [];
+  const logger = { warn: (properties, line) => records.push([properties, line]) };
+  await wire(message, { dkim: { signatures, onSigningFailure: 'send-unsigned' }, logger });
+  assert.strictEqual(warnings.length, 1);
+  assert.strictEqual(records.length, 1);
+  assert.strictEqual(records[0][0].code, 'MAILER_DKIM_UNSIGNED');
+  assert.strictEqual(records[0][0].component, 'dkim');
+  assert.match(records[0][0].error, /Failed to import private key/);
 
   await assert.rejects(composeMessage(message, { dkim: { signatures, bodyMode: 'eager' } }), {
     name: 'TypeError',

From 66a3aadea29e08d5678e5329f9c84df33954bcf1 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 19:11:23 +0300
Subject: [PATCH 120/158] fix(plunk): fail a send whose attachment cannot be
 read

convertAttachment caught the error of reading an attachment, told it to
console.warn and returned null, so the message went out without the file
and the receipt said it was sent (known upstream bug 12). The error now
propagates and the send fails before any request, as it does on every
other provider; no warning is left to route to a logger. The ported test
of the dropped attachment says where it changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                               |  3 ++
 CLAUDE.md                                  |  7 ++--
 docs/guide/known-issues.md                 |  1 -
 src/plunk/message-converter.js             | 38 +++++++---------------
 tests/unit/plunk-message-converter.test.js |  8 ++---
 tests/unit/plunk.test.js                   | 14 ++++----
 6 files changed, 30 insertions(+), 41 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e78781..be7c124 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -277,6 +277,9 @@ fixed ones below.
   it went to `console.warn` whatever the application logged with. It now goes to the `logger`
   of `composeMessage` or of the SMTP transport, as a `warn` with the code
   `MAILER_DKIM_UNSIGNED`, and to `console.warn` only when there is no logger.
+- **`./plunk` fails a send whose attachment cannot be read** (known upstream bug 12): it left the
+  attachment out with a `console.warn` and sent the message without it, reported as sent. The
+  send now fails before any request, as on the other providers.
 - **`./resend` draws its idempotency key from `crypto.randomUUID()`** (known upstream bug 11): it
   came from the clock and `Math.random()`, and two sends that shared a key by chance would get
   the first one's answer, the second never going out.
diff --git a/CLAUDE.md b/CLAUDE.md
index 2563e5c..f49daa9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -142,8 +142,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
 10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
 11. (fixed, see 71) resend: the `Idempotency-Key` came from `Math.random`.
-12. (partly fixed, see 72) `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of an
-    injected logger. Plunk still warns of a dropped attachment this way.
+12. (fixed, see 72 and 73) `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of
+    an injected logger.
 13. mime: the first encoded word of a header shares its line with the field name
     (`Subject: =?UTF-8?B?…?=`, 84 characters), past the 76 that RFC 2047 allows a line with
     encoded words.
@@ -368,6 +368,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     `console.warn`, whatever the application logged with. It goes to the `logger` of
     `composeMessage` or of the SMTP transport (`warn`, code `MAILER_DKIM_UNSIGNED`), and to
     `console.warn` only without one (`warnDegradation` of `internal/log.js`).
+73. plunk (known bug 12): an attachment that could not be read was left out with a
+    `console.warn`, and the message went without it, reported as sent. It fails the send, as
+    on the other providers, before any request.
 ## Repository layout
 
 ```
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index e861619..75cae07 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -21,7 +21,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 - Mailgun sends an inline attachment under its file name rather than its `contentId`, so a
   `cid:` in the HTML does not match it.
 - SES: custom and threading headers are not sent.
-- Plunk: an attachment that cannot be read is left out with a `console.warn`.
 - JMAP does not report its retries through `onRetry`.
 - JMAP on Node 24: an authentication rejection (401) of a streamed request body (raw upload,
   import, raw submission) becomes a retryable network error, as Node's `fetch` reports it so.
diff --git a/src/plunk/message-converter.js b/src/plunk/message-converter.js
index bfe3dda..aa84e31 100644
--- a/src/plunk/message-converter.js
+++ b/src/plunk/message-converter.js
@@ -91,16 +91,14 @@ const convertMessage = async (message, _config, signal) => {
     );
   }
 
-  // Convert attachments (limit to 5 as per Plunk documentation)
+  // Convert attachments (limit to 5 as per Plunk documentation).  One that
+  // cannot be read fails the send, as on the other providers: upstream left
+  // it out with a console.warn, and the message went without it.
   const attachments = [];
   const maxAttachments = Math.min(sourceAttachments.length, 5);
 
   for (let i = 0; i < maxAttachments; i++) {
-    const attachment = sourceAttachments[i];
-    const convertedAttachment = await convertAttachment(attachment, signal);
-    if (convertedAttachment) {
-      attachments.push(convertedAttachment);
-    }
+    attachments.push(await convertAttachment(sourceAttachments[i], signal));
   }
 
   // Build Plunk email object
@@ -138,28 +136,16 @@ const convertMessage = async (message, _config, signal) => {
  * Converts a Upyo attachment to Plunk format.
  *
  * @param attachment - The Upyo attachment to convert
- * @returns Promise that resolves to Plunk attachment or null if conversion fails
+ * @returns Promise that resolves to Plunk attachment
+ * @throws The error of reading its content.
  */
 const convertAttachment = async (attachment, signal) => {
-  try {
-    // Get content as Uint8Array
-    const content = await readAttachmentContent(attachment.content, signal);
-
-    // Convert to base64
-    const base64Content = toBase64(content);
-
-    return {
-      filename: attachment.filename,
-      content: base64Content,
-      contentType: attachment.contentType,
-    };
-  } catch (error) {
-    signal?.throwIfAborted();
-    // Log error but don't fail the entire send operation
-    // oxlint-disable-next-line no-console -- upstream
-    console.warn(`Failed to convert attachment ${attachment.filename}:`, error);
-    return null;
-  }
+  const content = await readAttachmentContent(attachment.content, signal);
+  return {
+    filename: attachment.filename,
+    content: toBase64(content),
+    contentType: attachment.contentType,
+  };
 };
 
 module.exports = { convertMessage };
diff --git a/tests/unit/plunk-message-converter.test.js b/tests/unit/plunk-message-converter.test.js
index 30b13f8..e6975c0 100644
--- a/tests/unit/plunk-message-converter.test.js
+++ b/tests/unit/plunk-message-converter.test.js
@@ -219,11 +219,9 @@ describe('convertMessage', () => {
       ],
     });
 
-    const result = await convertMessage(message, config);
-
-    // Should only include the working attachment
-    assert.equal(result.attachments?.length, 1);
-    assert.equal(result.attachments?.[0].filename, 'working.txt');
+    // Changed after the port: an attachment that cannot be read fails the
+    // conversion, rather than being left out of a message sent without it.
+    await assert.rejects(convertMessage(message, config), { message: 'Failed to read' });
   });
 
   it('should not include optional fields when not present', async () => {
diff --git a/tests/unit/plunk.test.js b/tests/unit/plunk.test.js
index fa04c84..f46f6a0 100644
--- a/tests/unit/plunk.test.js
+++ b/tests/unit/plunk.test.js
@@ -78,10 +78,8 @@ test('Plunk: a 5xx is retried after a backoff', async (t) => {
   assert.strictEqual(receipt.successful, true);
 });
 
-test('Plunk: an attachment that cannot be read is left out with a warning', async (t) => {
-  let body;
-  t.mock.method(globalThis, 'fetch', async (url, init) => {
-    body = JSON.parse(init.body);
+test('Plunk: an attachment that cannot be read fails the send, and nothing is sent', async (t) => {
+  const fetch = t.mock.method(globalThis, 'fetch', async () => {
     return Response.json({ success: true, emails: [], timestamp: 'now' });
   });
   const warn = t.mock.method(console, 'warn', () => {});
@@ -97,9 +95,11 @@ test('Plunk: an attachment that cannot be read is left out with a warning', asyn
       contentId: '',
     },
   ];
-  await new PlunkTransport(config).send(message({ attachments }));
-  assert.strictEqual(warn.mock.callCount(), 1);
-  assert.strictEqual(body.attachments, undefined);
+  const receipt = await new PlunkTransport(config).send(message({ attachments }));
+  assert.strictEqual(receipt.successful, false);
+  assert.deepStrictEqual(receipt.errorMessages, ['Cannot read attachment']);
+  assert.strictEqual(fetch.mock.callCount(), 0);
+  assert.strictEqual(warn.mock.callCount(), 0);
 });
 
 test('Plunk: an abort during the wait between attempts ends the send at once', async (t) => {

From 6eb5b529893ec6e6a6118308b8ac626754e4ca7f Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 19:14:02 +0300
Subject: [PATCH 121/158] feat(smtp): log the connection and the protocol, and
 warn of plain text

A connection that failed or a server that dropped STARTTLS could only be
seen with tcpdump. SmtpTransport passes its logger to every connection,
which writes at debug when it connects, upgrades, authenticates, is reused
from the pool or dropped after a failed reset, and at trace the commands
and reply codes, with the argument of AUTH, the SASL exchange and every
address redacted. Mail that goes out without TLS to a host other than
this machine is a warn with the code MAILER_SMTP_PLAINTEXT, through
warnDegradation, so console.warn tells it when there is no logger.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                |   5 ++
 docs/transports/smtp.md     |  12 +++++
 src/smtp/config.js          |   1 +
 src/smtp/smtp-connection.js | 104 ++++++++++++++++++++++++++----------
 src/smtp/smtp-transport.js  |  17 +++++-
 tests/unit/smtp.test.js     |  70 ++++++++++++++++++++++++
 6 files changed, 181 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index be7c124..e821eb9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -51,6 +51,11 @@ fixed ones below.
   log-only receipt; `random`, a function like `Math.random`, makes the choices of the pool
   strategies (their constructors take it too), the simulated failures and delays of `./mock`,
   and the span sampling of `./otel`.
+- **A `logger` for what happens inside `./smtp`:** pino-like, given in the configuration like
+  `fetch` and `generateId` (`TransportDependencies`), it hears connections, STARTTLS upgrades,
+  authentication and pool reuse at `debug`, and the protocol at `trace` with credentials and
+  addresses redacted. Mail sent in plain text to another host is a `warn` with the code
+  `MAILER_SMTP_PLAINTEXT`, which goes to `console.warn` when there is no logger.
 - **`./logger` logs retries** as `email.retrying` events, at the new level `levels.retrying`
   (`warn` by default), with the attempt, the wait, the redacted error text and its status code.
   With a wrapped transport, the logger needs a method for that level.
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index 967e7d9..4b28f2a 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -179,6 +179,18 @@ without one, and the message ID of a receipt the server named none for (see
 is used for the token refresh of OAuth 2.0, in place of the global one, such as
 one bound to an undici `Agent` or a proxy.
 
+### Diagnostics
+
+A `logger`, pino-like, hears what the receipts do not tell: `debug` for a
+connection made, upgraded with STARTTLS, authenticated, reused from the pool or
+dropped after a failed reset, and `trace` for the commands and reply codes of
+the protocol, with the argument of AUTH, the SASL exchange and every address
+replaced by `[REDACTED]`. A connection that goes out in plain text to a host
+other than this machine, because the server offers no STARTTLS and `requireTls`
+is off, is a `warn` with the code `MAILER_SMTP_PLAINTEXT`; without a logger,
+that warning, and the one of a DKIM signature skipped under `send-unsigned`,
+go to `console.warn`, and nothing else is written.
+
 ## Command pipelining
 
 When a server advertises the `PIPELINING` extension defined by [RFC 2920], @alexify/mailer
diff --git a/src/smtp/config.js b/src/smtp/config.js
index 7522c82..3cbaabb 100644
--- a/src/smtp/config.js
+++ b/src/smtp/config.js
@@ -33,6 +33,7 @@ const createSmtpConfig = (config) => {
     dkim: config.dkim,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
   };
 };
 
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index 3238c37..d447f9d 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -7,6 +7,8 @@ const { isIP, Socket } = require('node:net');
 const { StringDecoder } = require('node:string_decoder');
 const { connect: tlsConnect, TLSSocket } = require('node:tls');
 const { generateId } = require('../core/id.js');
+const { createLog } = require('../internal/log.js');
+const { redactAddresses } = require('../internal/redact-addresses.js');
 const { createSmtpConfig } = require('./config.js');
 const { SmtpDsnUnsupportedError } = require('./delivery-status.js');
 const { checkSmtpPath } = require('./envelope.js');
@@ -238,6 +240,27 @@ const QUIT_TIMEOUT_MS = 5000;
 // answer with its default one.
 const serverNameOf = (host) => (isIP(host) === 0 ? host.replace(/\.$/, '') : undefined);
 
+// The commands of a trace: a SASL exchange and the argument of AUTH carry
+// credentials, and an envelope carries addresses, none of which is logged.
+const describeCommands = (commands, authenticating) => {
+  const described = [];
+  for (let i = 0; i < commands.length; i++) {
+    const command = commands[i];
+    if (command.startsWith('AUTH ')) {
+      described.push(`AUTH ${command.slice(5).split(' ')[0]} [REDACTED]`);
+    } else {
+      described.push(authenticating ? '[REDACTED]' : redactAddresses(command));
+    }
+  }
+  return described;
+};
+
+const replyCodes = (responses) => {
+  const codes = [];
+  for (let i = 0; i < responses.length; i++) codes.push(responses[i].code);
+  return codes;
+};
+
 /**
  * Whether the SMTP connection is local enough to permit cleartext
  * authentication during development.
@@ -260,6 +283,8 @@ class SmtpConnection {
   capabilities = [];
   tokenManager;
   active = false;
+  /** Whether a SASL exchange is under way, whose lines carry credentials. */
+  authenticating = false;
   /** Whether the connection sits in a pool and must be reset before reuse. */
   needsReset = false;
 
@@ -277,6 +302,15 @@ class SmtpConnection {
   constructor(config, tokenManager) {
     this.config = createSmtpConfig(config);
     this.tokenManager = tokenManager ?? null;
+    this.log = createLog(this.config.logger, { transport: 'smtp', host: this.config.host });
+  }
+
+  /**
+   * Whether the connected peer, or the host when the socket names none, is
+   * this machine, where plain text is allowed for local development.
+   */
+  isLocal() {
+    return isLoopbackConnection(this.socket, this.config.host);
   }
 
   connect(signal) {
@@ -313,6 +347,11 @@ class SmtpConnection {
 
       const onConnect = () => {
         cleanup();
+        this.log.write(
+          'debug',
+          () => ({ port: this.config.port, secure: this.config.secure }),
+          'SMTP connected',
+        );
         resolve();
       };
 
@@ -432,6 +471,7 @@ class SmtpConnection {
                 reject(new TypeError('Premature SMTP reply after DATA readiness.'));
                 return;
               }
+              this.log.write('trace', () => ({ codes: replyCodes(responses) }), 'SMTP replies');
               resolve(responses);
               return;
             }
@@ -499,6 +539,11 @@ class SmtpConnection {
       this.socket.on('close', onClose);
       signal?.addEventListener('abort', onAbort, { once: true });
       this.socket.write(commands.map((command) => `${command}\r\n`).join(''));
+      this.log.write(
+        'trace',
+        () => ({ commands: describeCommands(commands, this.authenticating) }),
+        'SMTP commands',
+      );
     });
   }
 
@@ -697,6 +742,7 @@ class SmtpConnection {
       const onSecureConnect = () => {
         cleanup();
         tlsSocket.setTimeout(this.config.socketTimeout);
+        this.log.write('debug', () => ({ protocol: tlsSocket.getProtocol() }), 'SMTP upgraded');
         resolve();
       };
       tlsSocket.once('secureConnect', onSecureConnect);
@@ -723,43 +769,47 @@ class SmtpConnection {
 
     // Refuse to send credentials over a cleartext connection.  Loopback hosts
     // are excepted for local testing and development.
-    if (
-      !(this.socket instanceof TLSSocket) &&
-      !isLoopbackConnection(this.socket, this.config.host)
-    ) {
+    if (!(this.socket instanceof TLSSocket) && !this.isLocal()) {
       throw new SmtpAuthError(
         'SMTP authentication requires a TLS-secured connection to protect ' +
           'credentials; use `secure: true` or STARTTLS.',
       );
     }
 
-    if ('accessToken' in auth || 'refreshToken' in auth) {
-      const mechanism = auth.method ?? selectOAuth2Mechanism(this.capabilities);
-      switch (mechanism) {
-        case 'xoauth2':
-          await this.authXoauth2(auth, signal);
-          break;
-        case 'oauthbearer':
-          await this.authOauthbearer(auth, signal);
-          break;
-        default:
-          throw new SmtpAuthError(`Unsupported authentication method: ${mechanism}`);
-      }
-    } else {
-      const method = auth.method ?? 'plain';
-      switch (method) {
-        case 'plain':
-          await this.authPlain(auth, signal);
-          break;
-        case 'login':
-          await this.authLogin(auth, signal);
-          break;
-        default:
-          throw new Error(`Unsupported authentication method: ${method}`);
+    let mechanism;
+    this.authenticating = true;
+    try {
+      if ('accessToken' in auth || 'refreshToken' in auth) {
+        mechanism = auth.method ?? selectOAuth2Mechanism(this.capabilities);
+        switch (mechanism) {
+          case 'xoauth2':
+            await this.authXoauth2(auth, signal);
+            break;
+          case 'oauthbearer':
+            await this.authOauthbearer(auth, signal);
+            break;
+          default:
+            throw new SmtpAuthError(`Unsupported authentication method: ${mechanism}`);
+        }
+      } else {
+        mechanism = auth.method ?? 'plain';
+        switch (mechanism) {
+          case 'plain':
+            await this.authPlain(auth, signal);
+            break;
+          case 'login':
+            await this.authLogin(auth, signal);
+            break;
+          default:
+            throw new Error(`Unsupported authentication method: ${mechanism}`);
+        }
       }
+    } finally {
+      this.authenticating = false;
     }
 
     this.authenticated = true;
+    this.log.write('debug', { mechanism }, 'SMTP authenticated');
   }
 
   async authPlain(auth, signal) {
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index ff2ea5d..362b489 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -24,6 +24,8 @@ const { SmtpDeliveryUnknownError } = require('./data-stream.js');
 const { checkDkimConfig } = require('../mime/dkim/types.js');
 const { checkDkimKeys } = require('../mime/dkim/sign.js');
 const { parseEnhancedSmtpStatusCode } = require('./smtp-status-code.js');
+const { TLSSocket } = require('node:tls');
+const { warnDegradation } = require('../internal/log.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 
 /**
@@ -528,9 +530,11 @@ class SmtpTransport {
         try {
           await pooled.reset(signal);
           pooled.needsReset = false;
+          pooled.log.write('debug', {}, 'SMTP connection reused');
           return pooled;
-        } catch {
+        } catch (error) {
           // Its state is unknown after a failed or aborted RSET.
+          pooled.log.write('debug', () => ({ error: error?.message }), 'SMTP reset failed');
           await this.discardConnection(pooled);
           signal?.throwIfAborted();
         }
@@ -650,6 +654,17 @@ class SmtpTransport {
       signal?.throwIfAborted();
     }
 
+    // Mail that goes out without TLS is told, but for local development.
+    if (!(connection.socket instanceof TLSSocket) && !connection.isLocal()) {
+      warnDegradation(
+        connection.log,
+        'MAILER_SMTP_PLAINTEXT',
+        'The SMTP connection is not encrypted: the server offers no STARTTLS and requireTls is ' +
+          'off, so messages go out in plain text.',
+        { port: connection.config.port },
+      );
+    }
+
     // Authenticate if needed
     await connection.authenticate(signal);
   }
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 098128c..acbcc22 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -729,3 +729,73 @@ test('SMTP: generateId makes the Message-ID, and fetch refreshes the OAuth 2.0 t
     await server.stop();
   }
 });
+
+test('SMTP: the logger hears the connection and the protocol, without credentials or addresses', async () => {
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  const records = [];
+  const logger = {
+    isLevelEnabled: () => true,
+    trace: (properties, text) => records.push(['trace', properties, text]),
+    debug: (properties, text) => records.push(['debug', properties, text]),
+    warn: (properties, text) => records.push(['warn', properties, text]),
+  };
+  try {
+    const transport = new SmtpTransport({
+      host: 'localhost',
+      port,
+      logger,
+      auth: { user: 'alex@example.com', pass: 'hunter2-secret' },
+    });
+    assert.strictEqual((await transport.send(message())).successful, true);
+    await transport.closeAllConnections();
+  } finally {
+    await server.stop();
+  }
+  const texts = records.map(([level, , text]) => `${level} ${text}`);
+  assert.ok(texts.includes('debug SMTP connected'));
+  assert.ok(texts.includes('debug SMTP authenticated'));
+  // A loopback server is local development: no plaintext warning.
+  assert.ok(!texts.some((text) => text.startsWith('warn')));
+  const commands = records
+    .filter(([, , text]) => text === 'SMTP commands')
+    .flatMap(([, p]) => p.commands);
+  assert.ok(commands.includes('AUTH PLAIN [REDACTED]'), JSON.stringify(commands));
+  assert.ok(commands.includes('MAIL FROM:<[REDACTED]>'), JSON.stringify(commands));
+  const logged = JSON.stringify(records);
+  for (const secret of [
+    'hunter2-secret',
+    Buffer.from('\0alex@example.com\0hunter2-secret').toString('base64'),
+    'bob@example.com',
+    'alex@example.com',
+  ]) {
+    assert.ok(!logged.includes(secret), secret);
+  }
+  assert.ok(records.every(([, properties]) => properties.transport === 'smtp'));
+});
+
+test('SMTP: mail sent in plain text to another host is warned of, to the logger or console.warn', async (t) => {
+  t.mock.method(SmtpConnection.prototype, 'isLocal', () => false);
+  const consoleWarn = t.mock.method(console, 'warn', () => {});
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  try {
+    const silent = new SmtpTransport({ host: 'localhost', port, pool: false });
+    assert.strictEqual((await silent.send(message())).successful, true);
+    assert.strictEqual(consoleWarn.mock.callCount(), 1);
+    assert.match(consoleWarn.mock.calls[0].arguments[0], /^MAILER_SMTP_PLAINTEXT: /);
+
+    const warnings = [];
+    const logged = new SmtpTransport({
+      host: 'localhost',
+      port,
+      pool: false,
+      logger: { warn: (properties) => warnings.push(properties) },
+    });
+    assert.strictEqual((await logged.send(message())).successful, true);
+    assert.strictEqual(consoleWarn.mock.callCount(), 1);
+    assert.strictEqual(warnings[0].code, 'MAILER_SMTP_PLAINTEXT');
+  } finally {
+    await server.stop();
+  }
+});

From 996360e879226272ee264bb80d504f5484161bfe Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 19:16:25 +0300
Subject: [PATCH 122/158] feat: log the retries of the HTTP transports

The HTTP providers and JMAP retried their requests out of sight of the
application's logs. Their configurations pass logger through, each client
makes a log bound to its transport, and requestWithRetry writes a debug
record before every retry with the attempt, the wait, the status and the
error text with its addresses redacted.

The injected dependencies (core/id.js, internal/log.js and the address
redaction in every provider) take the subpaths past their budgets, which
now sit about 0.4 KB above the sizes measured: the root 8.5 KB, smtp 20,
jmap 11.5, ses and mailtrap 6, resend, maileroo and lettermint 5.5,
sendgrid, mailgun and plunk 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/npm-publish/SKILL.md |  2 +-
 .github/workflows/ci.yml            |  2 +-
 CHANGELOG.md                        |  1 +
 CLAUDE.md                           |  2 +-
 docs/guide/getting-started.md       |  7 +++++++
 src/internal/http.js                | 16 ++++++++++++++--
 src/jmap/config.js                  |  1 +
 src/jmap/http-client.js             |  4 ++++
 src/lettermint/config.js            |  1 +
 src/lettermint/http-client.js       |  3 +++
 src/maileroo/config.js              |  1 +
 src/maileroo/http-client.js         |  3 +++
 src/mailgun/config.js               |  1 +
 src/mailgun/http-client.js          |  3 +++
 src/mailtrap/config.js              |  1 +
 src/mailtrap/http-client.js         |  3 +++
 src/plunk/config.js                 |  1 +
 src/plunk/http-client.js            |  3 +++
 src/resend/config.js                |  1 +
 src/resend/http-client.js           |  3 +++
 src/sendgrid/config.js              |  1 +
 src/sendgrid/http-client.js         |  3 +++
 src/ses/config.js                   |  1 +
 src/ses/http-client.js              |  3 +++
 tests/unit/delivery.test.js         | 25 +++++++++++++++++++++++++
 25 files changed, 87 insertions(+), 5 deletions(-)

diff --git a/.claude/skills/npm-publish/SKILL.md b/.claude/skills/npm-publish/SKILL.md
index 4d76b34..8b60962 100644
--- a/.claude/skills/npm-publish/SKILL.md
+++ b/.claude/skills/npm-publish/SKILL.md
@@ -37,7 +37,7 @@ pnpm run check:dts               # tsc over the d.ts of every entry of the expor
 These are the same gates `prepublishOnly` runs. CI adds three more; run them too:
 
 ```bash
-pnpm size --max-gzip 8 --max-gzip-smtp 19.5 …                   # the budgets: copy the size step of ci.yml
+pnpm size --max-gzip 8.5 --max-gzip-smtp 20 …                   # the budgets: copy the size step of ci.yml
 pnpm docs:comparison && git diff --exit-code docs/guide/comparison.md   # the table matches docs/comparison.json
 pnpm run docs:build                                              # the docs site; a dead link fails it
 ```
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 81e0807..486ee7c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm format:check
       # Smoke: keeps the bundle-size script working and fails over the
       # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 8 --max-gzip-mime 7 --max-gzip-smtp 19.5 --max-gzip-jmap 10.5 --max-gzip-ses 5 --max-gzip-resend 4.5 --max-gzip-sendgrid 4.5 --max-gzip-mailgun 4 --max-gzip-mailtrap 5.5 --max-gzip-maileroo 5 --max-gzip-lettermint 5 --max-gzip-plunk 4.5 --max-gzip-pool 2.5 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
+      - run: pnpm size --max-gzip 8.5 --max-gzip-mime 7 --max-gzip-smtp 20 --max-gzip-jmap 11.5 --max-gzip-ses 6 --max-gzip-resend 5.5 --max-gzip-sendgrid 5 --max-gzip-mailgun 5 --max-gzip-mailtrap 6 --max-gzip-maileroo 5.5 --max-gzip-lettermint 5.5 --max-gzip-plunk 5 --max-gzip-pool 2.5 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
 
   types:
     runs-on: ubuntu-latest
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e821eb9..45ada93 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -56,6 +56,7 @@ fixed ones below.
   authentication and pool reuse at `debug`, and the protocol at `trace` with credentials and
   addresses redacted. Mail sent in plain text to another host is a `warn` with the code
   `MAILER_SMTP_PLAINTEXT`, which goes to `console.warn` when there is no logger.
+  The HTTP providers and `./jmap` take one too, which hears each retry of a request at `debug`.
 - **`./logger` logs retries** as `email.retrying` events, at the new level `levels.retrying`
   (`warn` by default), with the attempt, the wait, the redacted error text and its status code.
   With a wrapped transport, the logger needs a method for that level.
diff --git a/CLAUDE.md b/CLAUDE.md
index f49daa9..ecc9dd4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,7 +42,7 @@ pnpm run test:types                # tsd: tests/types/*.test-d.ts, one file per
 pnpm run check:dts                 # tsc --noEmit --strict over the d.ts of every entry
 pnpm run lint                      # oxlint src tests scripts bench
 pnpm run format                    # oxfmt src tests scripts bench (format:check in CI)
-pnpm size [--max-gzip <KB>]        # esbuild bundle sizes; CI gates the root at 8 KB min+gzip and each subpath
+pnpm size [--max-gzip <KB>]        # esbuild bundle sizes; CI gates the root at 8.5 KB min+gzip and each subpath
 pnpm bench [filter] [--json] [--save] [--compare]   # ops/sec harness, manual only; --save writes bench/baseline.json
 pnpm docs:comparison               # renders docs/comparison.json into docs/guide/comparison.md
 pnpm run docs:dev                  # VitePress dev server for docs/ (docs:build, docs:preview)
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 924210e..df49def 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -122,6 +122,13 @@ const transport = new ResendTransport({
 The JMAP transport streams its raw uploads, so its `fetch` must take a body
 stream with `duplex: 'half'`, as undici's does.
 
+Every transport also takes a pino-like `logger` for what happens inside it and
+its receipts do not tell: the retries of an HTTP request at `debug` (with the
+attempt, the wait and the status, never an address), and for SMTP its
+connections and protocol (see [diagnostics](/transports/smtp#diagnostics)).
+Without one a transport writes nothing, except a `console.warn` for mail sent
+without TLS or without the DKIM signature it was asked for.
+
 Every transport also takes `generateId`, which makes the identifiers otherwise
 drawn from `crypto.randomUUID()`: a generated Message-ID, an idempotency key,
 and the message ID of a receipt the provider gave none for. See
diff --git a/src/internal/http.js b/src/internal/http.js
index 6942b00..a6f7b08 100644
--- a/src/internal/http.js
+++ b/src/internal/http.js
@@ -6,6 +6,7 @@ const { combineSignals } = require('../core/abort-signal.js');
 const { markDeliveryUnknown } = require('./delivery-unknown.js');
 const { isUnsentRequestError } = require('./unsent.js');
 const { abortReason, sleep } = require('./sleep.js');
+const { redactAddresses } = require('./redact-addresses.js');
 
 const isAbortError = (error) => error instanceof Error && error.name === 'AbortError';
 
@@ -102,8 +103,9 @@ const startDeadline = (timeoutMs, signal) => {
  * - optional `wrapAccepted(error, attempts)`, `isAnswer(error)` (an error that
  *   is the provider's own answer in a 2xx, such as a refusal in its body,
  *   thrown as it is rather than as of unknown delivery), `hasIdempotencyKey`,
- *   `isIdempotent`, `sleep`, and `onRetry(event)`, the `onRetry` of the
- *   caller's `TransportOptions`, told of each retry before its wait.
+ *   `isIdempotent`, `sleep`, `onRetry(event)`, the `onRetry` of the caller's
+ *   `TransportOptions`, told of each retry before its wait, and `log`, the
+ *   log of the transport, which hears the retry at `debug`.
  * The deadline of an attempt lasts until its response is read, body
  * included, so a body that never ends cannot hold a send.  Between attempts
  * it waits at least the failure's `retryAfterMilliseconds`, the server's
@@ -162,6 +164,16 @@ const requestWithRetry = async (request) => {
       (request.retryDelayMs ?? jitteredDelayMs)(attempt, failure),
       retryAfterMs,
     );
+    request.log?.write(
+      'debug',
+      () => ({
+        attempt: attempt + 1,
+        delayMilliseconds: waitMs,
+        statusCode: failure.statusCode,
+        error: redactAddresses(failure.message),
+      }),
+      'Retrying request',
+    );
     request.onRetry?.({ attempt: attempt + 1, delayMilliseconds: waitMs, error: failure });
     await wait(waitMs, signal);
   }
diff --git a/src/jmap/config.js b/src/jmap/config.js
index c546b4a..fcdddc4 100644
--- a/src/jmap/config.js
+++ b/src/jmap/config.js
@@ -22,6 +22,7 @@ const createJmapConfig = (config) => {
     timeout: config.timeout ?? 30000,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
     retries: config.retries ?? 3,
     headers: config.headers ?? {},
     sessionCacheTtl: config.sessionCacheTtl ?? 300000,
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index b6db025..f05c5aa 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -4,6 +4,7 @@
 const { parseRetryAfter } = require('../core/receipt.js');
 const { JmapApiError } = require('./errors.js');
 const { isAbortError, requestWithRetry } = require('../internal/http.js');
+const { createLog } = require('../internal/log.js');
 const { readJson, readText } = require('../internal/body.js');
 const { Buffer } = require('node:buffer');
 
@@ -20,6 +21,7 @@ class JmapHttpClient {
    */
   constructor(config, replayableRequests = true) {
     this.config = config;
+    this.log = createLog(config.logger, { transport: 'jmap' });
     this.replayableRequests = replayableRequests;
   }
 
@@ -32,6 +34,7 @@ class JmapHttpClient {
     signal?.throwIfAborted();
 
     return requestWithRetry({
+      log: this.log,
       signal,
       retries: 0,
       timeoutMs: this.config.timeout,
@@ -64,6 +67,7 @@ class JmapHttpClient {
     const json = JSON.stringify(request);
 
     return requestWithRetry({
+      log: this.log,
       signal,
       retries: this.replayableRequests ? this.config.retries : 0,
       timeoutMs: this.config.timeout,
diff --git a/src/lettermint/config.js b/src/lettermint/config.js
index a9b4a47..dd090cb 100644
--- a/src/lettermint/config.js
+++ b/src/lettermint/config.js
@@ -16,6 +16,7 @@ const createLettermintConfig = (config) => {
     timeout: config.timeout ?? 30000,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
     retries: config.retries ?? 3,
     headers: config.headers ?? {},
     route: config.route,
diff --git a/src/lettermint/http-client.js b/src/lettermint/http-client.js
index af18729..e300b48 100644
--- a/src/lettermint/http-client.js
+++ b/src/lettermint/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { createLog } = require('../internal/log.js');
 const { readText } = require('../internal/body.js');
 
 /**
@@ -71,6 +72,7 @@ class LettermintHttpClient {
    */
   constructor(config) {
     this.config = config;
+    this.log = createLog(config.logger, { transport: 'lettermint' });
   }
 
   /**
@@ -103,6 +105,7 @@ class LettermintHttpClient {
     // Serialized once rather than on every attempt.
     const json = JSON.stringify(body);
     return requestWithRetry({
+      log: this.log,
       signal,
       onRetry,
       retries: this.config.retries,
diff --git a/src/maileroo/config.js b/src/maileroo/config.js
index eaf89ec..e9372ea 100644
--- a/src/maileroo/config.js
+++ b/src/maileroo/config.js
@@ -16,6 +16,7 @@ const createMailerooConfig = (config) => {
     timeout: config.timeout ?? 30000,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
     retries: config.retries ?? 3,
     headers: config.headers == null ? {} : { ...config.headers },
     tracking: config.tracking,
diff --git a/src/maileroo/http-client.js b/src/maileroo/http-client.js
index c5673e6..a9b7f10 100644
--- a/src/maileroo/http-client.js
+++ b/src/maileroo/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { createLog } = require('../internal/log.js');
 const { readText } = require('../internal/body.js');
 
 const maxErrorMessageLength = 500;
@@ -73,6 +74,7 @@ class MailerooHttpClient {
    */
   constructor(config) {
     this.config = config;
+    this.log = createLog(config.logger, { transport: 'maileroo' });
   }
 
   /**
@@ -93,6 +95,7 @@ class MailerooHttpClient {
     // Serialized once rather than on every attempt.
     const json = JSON.stringify(body);
     return requestWithRetry({
+      log: this.log,
       signal,
       onRetry,
       retries: this.config.retries,
diff --git a/src/mailgun/config.js b/src/mailgun/config.js
index 218e584..1ca902b 100644
--- a/src/mailgun/config.js
+++ b/src/mailgun/config.js
@@ -26,6 +26,7 @@ const createMailgunConfig = (config) => {
     timeout: config.timeout ?? 30000,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index 98e0252..57d3af3 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { createLog } = require('../internal/log.js');
 const { readText } = require('../internal/body.js');
 const { Buffer } = require('node:buffer');
 
@@ -17,6 +18,7 @@ class MailgunHttpClient {
 
   constructor(config) {
     this.config = config;
+    this.log = createLog(config.logger, { transport: 'mailgun' });
   }
 
   /**
@@ -53,6 +55,7 @@ class MailgunHttpClient {
    */
   makeRequest(url, options, onRetry) {
     return requestWithRetry({
+      log: this.log,
       signal: options.signal,
       onRetry,
       retries: this.config.retries,
diff --git a/src/mailtrap/config.js b/src/mailtrap/config.js
index 0f92f1d..0a46dde 100644
--- a/src/mailtrap/config.js
+++ b/src/mailtrap/config.js
@@ -34,6 +34,7 @@ const createMailtrapConfig = (config) => {
     timeout: config.timeout ?? 30000,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers == null ? {} : { ...config.headers },
diff --git a/src/mailtrap/http-client.js b/src/mailtrap/http-client.js
index b396060..07f09c9 100644
--- a/src/mailtrap/http-client.js
+++ b/src/mailtrap/http-client.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { requestWithRetry } = require('../internal/http.js');
+const { createLog } = require('../internal/log.js');
 const { readText } = require('../internal/body.js');
 
 const maxErrorMessageLength = 500;
@@ -98,6 +99,7 @@ class MailtrapHttpClient {
    */
   constructor(config) {
     this.config = config;
+    this.log = createLog(config.logger, { transport: 'mailtrap' });
   }
 
   /**
@@ -137,6 +139,7 @@ class MailtrapHttpClient {
     // Serialized once rather than on every attempt.
     const json = JSON.stringify(body);
     return requestWithRetry({
+      log: this.log,
       signal,
       onRetry,
       retries: this.config.retries,
diff --git a/src/plunk/config.js b/src/plunk/config.js
index a5477f1..293c74a 100644
--- a/src/plunk/config.js
+++ b/src/plunk/config.js
@@ -21,6 +21,7 @@ const createPlunkConfig = (config) => {
     timeout: config.timeout ?? 30000,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/plunk/http-client.js b/src/plunk/http-client.js
index 9212efd..27cbc78 100644
--- a/src/plunk/http-client.js
+++ b/src/plunk/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { createLog } = require('../internal/log.js');
 const { readJson, readText } = require('../internal/body.js');
 
 /**
@@ -57,6 +58,7 @@ class PlunkHttpClient {
    */
   constructor(config) {
     this.config = config;
+    this.log = createLog(config.logger, { transport: 'plunk' });
   }
 
   /**
@@ -76,6 +78,7 @@ class PlunkHttpClient {
     const json = JSON.stringify(emailData);
 
     return requestWithRetry({
+      log: this.log,
       signal,
       onRetry,
       retries: this.config.retries,
diff --git a/src/resend/config.js b/src/resend/config.js
index ba2d65d..ecb2ba1 100644
--- a/src/resend/config.js
+++ b/src/resend/config.js
@@ -21,6 +21,7 @@ const createResendConfig = (config) => {
     timeout: config.timeout ?? 30000,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index 8f14693..7a50756 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { createLog } = require('../internal/log.js');
 const { readText } = require('../internal/body.js');
 
 /**
@@ -53,6 +54,7 @@ class ResendHttpClient {
 
   constructor(config) {
     this.config = config;
+    this.log = createLog(config.logger, { transport: 'resend' });
   }
 
   /**
@@ -126,6 +128,7 @@ class ResendHttpClient {
    */
   makeRequest(url, options, onRetry) {
     return requestWithRetry({
+      log: this.log,
       signal: options.signal,
       onRetry,
       retries: this.config.retries,
diff --git a/src/sendgrid/config.js b/src/sendgrid/config.js
index aed9c1d..154d332 100644
--- a/src/sendgrid/config.js
+++ b/src/sendgrid/config.js
@@ -21,6 +21,7 @@ const createSendGridConfig = (config) => {
     timeout: config.timeout ?? 30000,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/sendgrid/http-client.js b/src/sendgrid/http-client.js
index 3d19b23..21cb47c 100644
--- a/src/sendgrid/http-client.js
+++ b/src/sendgrid/http-client.js
@@ -3,6 +3,7 @@
 
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { createLog } = require('../internal/log.js');
 const { readText } = require('../internal/body.js');
 
 /**
@@ -16,6 +17,7 @@ class SendGridHttpClient {
 
   constructor(config) {
     this.config = config;
+    this.log = createLog(config.logger, { transport: 'sendgrid' });
   }
 
   /**
@@ -55,6 +57,7 @@ class SendGridHttpClient {
    */
   makeRequest(url, options, onRetry) {
     return requestWithRetry({
+      log: this.log,
       signal: options.signal,
       onRetry,
       retries: this.config.retries,
diff --git a/src/ses/config.js b/src/ses/config.js
index eda68ba..b29e69d 100644
--- a/src/ses/config.js
+++ b/src/ses/config.js
@@ -38,6 +38,7 @@ const createSesConfig = (config) => {
     timeout: config.timeout ?? 30000,
     fetch: config.fetch,
     generateId: config.generateId,
+    logger: config.logger,
     retries: config.retries ?? 3,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
diff --git a/src/ses/http-client.js b/src/ses/http-client.js
index e32dd4d..4ff649d 100644
--- a/src/ses/http-client.js
+++ b/src/ses/http-client.js
@@ -4,6 +4,7 @@
 const { createHash, createHmac } = require('node:crypto');
 const { parseRetryAfter } = require('../core/receipt.js');
 const { requestWithRetry } = require('../internal/http.js');
+const { createLog } = require('../internal/log.js');
 const { readText } = require('../internal/body.js');
 
 class SesHttpClient {
@@ -12,6 +13,7 @@ class SesHttpClient {
 
   constructor(config) {
     this.config = config;
+    this.log = createLog(config.logger, { transport: 'ses' });
   }
 
   sendMessage(messageData, signal, onRetry) {
@@ -44,6 +46,7 @@ class SesHttpClient {
    */
   makeRequest(url, options, onRetry) {
     return requestWithRetry({
+      log: this.log,
       signal: options.signal,
       onRetry,
       retries: this.config.retries,
diff --git a/tests/unit/delivery.test.js b/tests/unit/delivery.test.js
index cba5f32..b8e9f9b 100644
--- a/tests/unit/delivery.test.js
+++ b/tests/unit/delivery.test.js
@@ -351,3 +351,28 @@ test('Delivery: generateId makes the idempotency keys and the synthetic message
   });
   assert.strictEqual((await sendgrid.send(message())).messageId, 'sendgrid-01JKEY-receipt-id');
 });
+
+test('Delivery: the logger of an HTTP transport hears its retries, without addresses', async () => {
+  const records = [];
+  const logger = { debug: (properties, text) => records.push([properties, text]) };
+  let requests = 0;
+  const fetch = async () =>
+    ++requests === 1
+      ? new Response('{"message":"Mailbox of bob@example.com is busy"}', { status: 503 })
+      : new Response('{"MessageId":"m1"}', { status: 200 });
+  const ses = new SesTransport({
+    authentication: { type: 'credentials', accessKeyId: 'a', secretAccessKey: 'b' },
+    retries: 1,
+    fetch,
+    logger,
+  });
+  assert.strictEqual((await ses.send(message())).successful, true);
+  assert.strictEqual(records.length, 1);
+  const [properties, text] = records[0];
+  assert.strictEqual(text, 'Retrying request');
+  assert.strictEqual(properties.transport, 'ses');
+  assert.strictEqual(properties.attempt, 1);
+  assert.strictEqual(properties.statusCode, 503);
+  assert.ok(properties.delayMilliseconds > 0);
+  assert.ok(!JSON.stringify(records).includes('bob@example.com'), JSON.stringify(records));
+});

From e747d963334865b498fee27d003e6af75fded108 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 19:18:44 +0300
Subject: [PATCH 123/158] feat(pool,retry): log failovers, retries and a
 selector that throws

A selector that threw was skipped with an empty catch, so a bug in the
application's routing showed only as mail going elsewhere. PoolConfig
takes a logger, which hears that selector at warn (the transport is still
skipped, as upstream did) through the new onSelectorError option of
SelectorStrategy, and each failover at debug; RetryConfig takes one that
hears each retry the decorator schedules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                             |  2 ++
 docs/transports/pool.md                  |  3 +++
 docs/transports/retry.md                 |  3 ++-
 src/pool/config.js                       |  1 +
 src/pool/index.d.ts                      | 16 ++++++++++---
 src/pool/pool-transport.js               | 19 ++++++++++++++-
 src/pool/strategies/selector-strategy.js | 12 ++++++----
 src/retry/config.js                      |  1 +
 src/retry/index.d.ts                     |  5 ++++
 src/retry/retry-transport.js             |  7 ++++++
 tests/unit/pool.test.js                  | 30 ++++++++++++++++++++++++
 tests/unit/retry.test.js                 | 15 ++++++++++++
 12 files changed, 105 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 45ada93..bef4290 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -57,6 +57,8 @@ fixed ones below.
   addresses redacted. Mail sent in plain text to another host is a `warn` with the code
   `MAILER_SMTP_PLAINTEXT`, which goes to `console.warn` when there is no logger.
   The HTTP providers and `./jmap` take one too, which hears each retry of a request at `debug`.
+  `./pool` takes one for its failovers (`debug`) and a selector that throws (`warn`; it was
+  skipped in silence), and `./retry` for the retries it schedules.
 - **`./logger` logs retries** as `email.retrying` events, at the new level `levels.retrying`
   (`warn` by default), with the attempt, the wait, the redacted error text and its status code.
   With a wrapped transport, the logger needs a method for that level.
diff --git a/docs/transports/pool.md b/docs/transports/pool.md
index 67c7f9d..285850f 100644
--- a/docs/transports/pool.md
+++ b/docs/transports/pool.md
@@ -265,6 +265,9 @@ instead, such as a seeded one in tests. `generateId` makes the Message-ID the
 pool gives a message without one before the first attempt, so that every
 transport it tries sends the same one.
 
+A `logger` hears each failover at `debug`, and a selector that throws at `warn`:
+such a selector skips its transport, as before, but is no longer silent.
+
 ## Custom strategies
 
 For advanced use cases, you can implement custom routing strategies by
diff --git a/docs/transports/retry.md b/docs/transports/retry.md
index adadcba..c1626a7 100644
--- a/docs/transports/retry.md
+++ b/docs/transports/retry.md
@@ -213,7 +213,8 @@ const receipt = await transport.send(message, {
 });
 ```
 
-An error thrown by the callback rejects the send. `./otel` records these retries
+A `logger` in the configuration hears each retry the decorator schedules, at
+`debug`. An error thrown by the callback rejects the send. `./otel` records these retries
 on its span and in its metrics, and the JMAP transport does not report its own
 yet.
 
diff --git a/src/pool/config.js b/src/pool/config.js
index 2fbf258..834b280 100644
--- a/src/pool/config.js
+++ b/src/pool/config.js
@@ -45,6 +45,7 @@ const createPoolConfig = (config) => {
     continueOnSuccess: config.continueOnSuccess ?? false,
     random: config.random,
     generateId: config.generateId,
+    logger: config.logger,
   };
 };
 
diff --git a/src/pool/index.d.ts b/src/pool/index.d.ts
index 7cd4126..30154fa 100644
--- a/src/pool/index.d.ts
+++ b/src/pool/index.d.ts
@@ -3,7 +3,7 @@
 
 /// <reference lib="esnext.disposable" />
 
-import { IdOptions, Message, Receipt, Transport, TransportOptions } from '../../index.js';
+import { IdOptions, Logger, Message, Receipt, Transport, TransportOptions } from '../../index.js';
 
 /**
  * Result of transport selection by a strategy.
@@ -116,6 +116,11 @@ export interface PoolConfig<TProviderId extends string = string> extends IdOptio
    * @default Math.random, read at each choice
    */
   readonly random?: () => number;
+  /**
+   * A logger: it hears a failover at `debug`, and a selector that throws at
+   * `warn`.
+   */
+  readonly logger?: Logger;
 }
 /**
  * Resolved pool configuration with defaults applied.
@@ -366,9 +371,14 @@ export declare class SelectorStrategy<
   TProviderId extends string = string,
 > implements Strategy<TProviderId> {
   /**
-   * @param options `random`, the source of the random choices.
+   * @param options `random`, the source of the random choices, and
+   *                `onSelectorError`, told of a selector that throws (its
+   *                transport is skipped).
    */
-  constructor(options?: { readonly random?: () => number });
+  constructor(options?: {
+    readonly random?: () => number;
+    readonly onSelectorError?: (error: unknown, index: number) => void;
+  });
   /**
    * Selects a transport based on selector function matching.
    *
diff --git a/src/pool/pool-transport.js b/src/pool/pool-transport.js
index ca2d370..545a6dd 100644
--- a/src/pool/pool-transport.js
+++ b/src/pool/pool-transport.js
@@ -3,6 +3,7 @@
 
 const { combineSignals } = require('../core/abort-signal.js');
 const { pinMessageId } = require('../core/message-id.js');
+const { createLog } = require('../internal/log.js');
 const { createFailedReceipt, createReceiptError } = require('../core/receipt.js');
 const { createPoolConfig } = require('./config.js');
 const { RoundRobinStrategy } = require('./strategies/round-robin-strategy.js');
@@ -80,6 +81,7 @@ class PoolTransport {
    */
   constructor(config) {
     this.config = createPoolConfig(config);
+    this.log = createLog(this.config.logger, { transport: 'pool' });
     this.strategy = this.createStrategy(this.config.strategy);
   }
 
@@ -148,6 +150,11 @@ class PoolTransport {
         deliveryUnknown = receipt.deliveryUnknown === true;
         isRejected = hasMessageRejection(receipt.errors);
         if (deliveryUnknown || isRejected) break;
+        this.log.write(
+          'debug',
+          () => ({ attempt: attempt + 1, failed: selection.entry.transport.id }),
+          'Pool failing over',
+        );
       } catch (error) {
         // Handle transport errors
         if (abortedByCaller && isCallerAbort(error, options?.signal)) {
@@ -273,7 +280,17 @@ class PoolTransport {
       case 'priority':
         return new PriorityStrategy({ random: this.config.random });
       case 'selector-based':
-        return new SelectorStrategy({ random: this.config.random });
+        return new SelectorStrategy({
+          random: this.config.random,
+          // A selector that throws is a bug of the application: it skips its
+          // transport, as upstream did, and is told to the logger.
+          onSelectorError: (error, index) =>
+            this.log.write(
+              'warn',
+              () => ({ index, error: error instanceof Error ? error.message : String(error) }),
+              'A pool selector threw; its transport is skipped',
+            ),
+        });
       default:
         throw new Error(`Unknown strategy: ${strategy}`);
     }
diff --git a/src/pool/strategies/selector-strategy.js b/src/pool/strategies/selector-strategy.js
index 0ddad38..7508052 100644
--- a/src/pool/strategies/selector-strategy.js
+++ b/src/pool/strategies/selector-strategy.js
@@ -11,11 +11,14 @@
  */
 class SelectorStrategy {
   /**
-   * @param options `random`, the source of the random choices; by default
-   *                `Math.random`, read at each choice.
+   * @param options `random`, the source of the random choices, by default
+   *                `Math.random`, read at each choice; and `onSelectorError`,
+   *                told of a selector that throws, with the error and the
+   *                index of its transport.
    */
   constructor(options) {
     this.random = options?.random;
+    this.onSelectorError = options?.onSelectorError;
   }
 
   /**
@@ -42,8 +45,9 @@ class SelectorStrategy {
           if (entry.selector(message)) {
             withSelectors.push({ entry, index });
           }
-        } catch {
-          // If selector throws, skip this transport
+        } catch (error) {
+          // If selector throws, skip this transport, and tell whoever asked.
+          this.onSelectorError?.(error, index);
         }
       } else {
         // No selector means it accepts all messages
diff --git a/src/retry/config.js b/src/retry/config.js
index 605802e..039e969 100644
--- a/src/retry/config.js
+++ b/src/retry/config.js
@@ -36,6 +36,7 @@ const createRetryConfig = (config = {}) => {
     random: config.random ?? Math.random,
     shouldRetry: config.shouldRetry,
     generateId: config.generateId,
+    logger: config.logger,
     wait: config.wait ?? defaultWait,
     sendMany: {
       maxConcurrent,
diff --git a/src/retry/index.d.ts b/src/retry/index.d.ts
index 1f2a495..83972f1 100644
--- a/src/retry/index.d.ts
+++ b/src/retry/index.d.ts
@@ -5,6 +5,7 @@
 
 import type {
   IdOptions,
+  Logger,
   Message,
   Receipt,
   ReceiptError,
@@ -168,6 +169,10 @@ export interface RetryConfig<TProviderId extends string = string> extends IdOpti
    * Retry and throttling behavior for `sendMany()`.
    */
   readonly sendMany?: SendManyRetryConfig;
+  /**
+   * A logger: it hears each retry it schedules at `debug`.
+   */
+  readonly logger?: Logger;
 }
 /**
  * Resolved retry configuration with defaults applied.
diff --git a/src/retry/retry-transport.js b/src/retry/retry-transport.js
index aa85147..2df189a 100644
--- a/src/retry/retry-transport.js
+++ b/src/retry/retry-transport.js
@@ -8,6 +8,7 @@ const {
 } = require('../core/receipt.js');
 const { combineSignals } = require('../core/abort-signal.js');
 const { pinMessageId } = require('../core/message-id.js');
+const { createLog } = require('../internal/log.js');
 const { createRetryConfig } = require('./config.js');
 
 /**
@@ -44,6 +45,7 @@ class RetryTransport {
     this.wrappedTransport = transport;
     this.id = transport.id;
     this.config = createRetryConfig(config);
+    this.log = createLog(this.config.logger, { transport: 'retry' });
   }
 
   /**
@@ -387,6 +389,11 @@ class RetryTransport {
   }
 
   waitBeforeRetry(context, signal, onRetry) {
+    this.log.write(
+      'debug',
+      () => ({ attempt: context.attempt, delayMilliseconds: context.delayMilliseconds }),
+      'Retrying send',
+    );
     onRetry?.({
       attempt: context.attempt,
       delayMilliseconds: context.delayMilliseconds,
diff --git a/tests/unit/pool.test.js b/tests/unit/pool.test.js
index d3b638a..ed9fe18 100644
--- a/tests/unit/pool.test.js
+++ b/tests/unit/pool.test.js
@@ -202,3 +202,33 @@ test('Pool: random makes the choices, and generateId the pinned Message-ID', asy
     ['a', '01JPOOL.message-id@example.com'],
   ]);
 });
+
+test('Pool: the logger hears a selector that throws and a failover', async () => {
+  const records = [];
+  const logger = {
+    debug: (properties, text) => records.push(['debug', properties, text]),
+    warn: (properties, text) => records.push(['warn', properties, text]),
+  };
+  const refused = { successful: false, errorMessages: ['Busy'], errors: [], retryable: true };
+  const pool = new PoolTransport({
+    strategy: 'selector-based',
+    logger,
+    // The first candidate first, so that the busy one fails over.
+    random: () => 0,
+    transports: [
+      {
+        transport: failing(refused),
+        selector: () => {
+          throw new Error('Selector bug');
+        },
+      },
+      { transport: failing(refused) },
+      { transport: failing({ successful: true, messageId: 'x' }) },
+    ],
+  });
+  assert.strictEqual((await pool.send(message())).successful, true);
+  const warns = records.filter(([level]) => level === 'warn');
+  assert.ok(warns.length >= 1);
+  assert.deepStrictEqual(warns[0][1], { transport: 'pool', index: 0, error: 'Selector bug' });
+  assert.ok(records.some(([level, , text]) => level === 'debug' && text === 'Pool failing over'));
+});
diff --git a/tests/unit/retry.test.js b/tests/unit/retry.test.js
index 267f104..62566a5 100644
--- a/tests/unit/retry.test.js
+++ b/tests/unit/retry.test.js
@@ -223,3 +223,18 @@ test('Retry: generateId makes the Message-ID pinned for every attempt', async ()
   await transport.send(message());
   assert.deepStrictEqual(ids, ['01JRETRY@example.com', '01JRETRY@example.com']);
 });
+
+test('Retry: the logger hears each retry it schedules', async () => {
+  const records = [];
+  const transport = new RetryTransport(sequence(failure(true), success), {
+    maxAttempts: 2,
+    jitter: 'none',
+    backoff: { baseDelayMilliseconds: 5 },
+    wait: async () => {},
+    logger: { debug: (properties, text) => records.push([properties, text]) },
+  });
+  await transport.send(message());
+  assert.deepStrictEqual(records, [
+    [{ transport: 'retry', attempt: 1, delayMilliseconds: 5 }, 'Retrying send'],
+  ]);
+});

From 6f07a4d707464dce07264d7acc610775d67423ba Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 19:19:25 +0300
Subject: [PATCH 124/158] docs: tell the logger of a transport from the
 ./logger decorator

The logger page gains "Internal diagnostics": the decorator sees a send
from outside, while the logger option of a transport tells what happens
inside it, with child bindings, lazy records, the levels it writes, the
two console warnings without a logger and what is never logged. The
README names the option beside fetch and generateId.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                 |  3 ++-
 docs/transports/logger.md | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 770a844..c4e8a76 100644
--- a/README.md
+++ b/README.md
@@ -85,7 +85,8 @@ if (!receipt.successful) console.error(receipt.errorMessages);
 | `/mock` | an in-memory transport for tests |
 
 Every transport takes `generateId` for the identifiers it makes (a ULID or a cuid2 instead of a
-UUID), and every HTTP transport a `fetch`, such as one bound to an undici `Agent` or a proxy; see
+UUID) and a pino-like `logger` for what happens inside it, and every HTTP transport a `fetch`,
+such as one bound to an undici `Agent` or a proxy; see
 [your own fetch and identifiers](https://mailerat.vercel.app/guide/getting-started#your-own-fetch-and-identifiers).
 
 The same names import from ESM (`import { SmtpTransport } from '@alexify/mailer/smtp'`). The
diff --git a/docs/transports/logger.md b/docs/transports/logger.md
index e82be94..128f312 100644
--- a/docs/transports/logger.md
+++ b/docs/transports/logger.md
@@ -180,3 +180,36 @@ Lifecycle errors without an associated message stay on one line.
 > [redaction].
 
 [redaction]: https://getpino.io/#/docs/redaction
+
+## Internal diagnostics
+
+The decorator sees a send from the outside: it starts, it is retried, it ends
+with a receipt. What happens inside a transport is told by the `logger` option
+of the transport itself, which every transport and decorator takes:
+
+```js
+const pino = require('pino');
+const { SmtpTransport } = require('@alexify/mailer/smtp');
+const { LoggerTransport } = require('@alexify/mailer/logger');
+
+const logger = pino({ level: 'debug' }).child({ component: 'mail' });
+
+const transport = new LoggerTransport({
+  // The lifecycle of each send.
+  logger,
+  // The connections, STARTTLS, authentication and pool of SMTP.
+  transport: new SmtpTransport({ host: 'smtp.example.com', logger }),
+});
+```
+
+A transport binds its records to itself through `logger.child({ transport })`
+when the logger has `child`, and builds a record only for a level the logger
+writes (`isLevelEnabled`). It writes `debug` for its lifecycle and retries,
+`trace` for the SMTP protocol, and `warn` for a degradation: mail sent in plain
+text (`MAILER_SMTP_PLAINTEXT`), a DKIM signature skipped under `send-unsigned`
+(`MAILER_DKIM_UNSIGNED`), a pool selector that throws. It never writes a
+credential or an address, nor the failure of a message, which its receipt
+already carries. Without a logger it writes nothing but the two warnings of
+mail sent with less protection than asked, to `console.warn`; and a logger that
+throws changes nothing of a send, its failure being emitted as a process warning
+with the code `MAILER_LOGGER_FAILED`.

From 395521199269f26256f6225ee8f6cef10ff836c4 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:12:11 +0300
Subject: [PATCH 125/158] feat(scripts): keep the size budgets in one file and
 check every entry

The budgets lived only in a long line of ci.yml, one flag per subpath, and
a subpath without a flag was not gated at all. They are in
scripts/size-budgets.json, keyed like the exports map, and
`pnpm size --check` fails on an entry over its budget, on an entry
without one and on a budget for no entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/npm-publish/SKILL.md |  4 +-
 .github/workflows/ci.yml            |  7 +--
 CLAUDE.md                           | 10 ++--
 CONTRIBUTING.md                     |  8 +--
 scripts/size-budgets.json           | 19 +++++++
 scripts/size.js                     | 72 ++++++++++++++++---------
 tests/unit/scripts.test.js          | 83 ++++++++++++++++++++++-------
 7 files changed, 146 insertions(+), 57 deletions(-)
 create mode 100644 scripts/size-budgets.json

diff --git a/.claude/skills/npm-publish/SKILL.md b/.claude/skills/npm-publish/SKILL.md
index 8b60962..53bc30a 100644
--- a/.claude/skills/npm-publish/SKILL.md
+++ b/.claude/skills/npm-publish/SKILL.md
@@ -37,7 +37,7 @@ pnpm run check:dts               # tsc over the d.ts of every entry of the expor
 These are the same gates `prepublishOnly` runs. CI adds three more; run them too:
 
 ```bash
-pnpm size --max-gzip 8.5 --max-gzip-smtp 20 …                   # the budgets: copy the size step of ci.yml
+pnpm size --check                                                # the budgets of scripts/size-budgets.json
 pnpm docs:comparison && git diff --exit-code docs/guide/comparison.md   # the table matches docs/comparison.json
 pnpm run docs:build                                              # the docs site; a dead link fails it
 ```
@@ -180,7 +180,7 @@ Report the file count and the bundle size from `pnpm run size` to the user.
 Run the gates one more time after all edits:
 
 ```bash
-pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts && pnpm size <the flags of ci.yml> && pnpm run docs:build
+pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts && pnpm size --check && pnpm run docs:build
 ```
 
 Must exit 0. If it fails, fix and re-run.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 486ee7c..d458a99 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -30,9 +30,10 @@ jobs:
       - run: pnpm install --frozen-lockfile
       - run: pnpm lint
       - run: pnpm format:check
-      # Smoke: keeps the bundle-size script working and fails over the
-      # min+gzip budget, which also catches a third-party module bundled in.
-      - run: pnpm size --max-gzip 8.5 --max-gzip-mime 7 --max-gzip-smtp 20 --max-gzip-jmap 11.5 --max-gzip-ses 6 --max-gzip-resend 5.5 --max-gzip-sendgrid 5 --max-gzip-mailgun 5 --max-gzip-mailtrap 6 --max-gzip-maileroo 5.5 --max-gzip-lettermint 5.5 --max-gzip-plunk 5 --max-gzip-pool 2.5 --max-gzip-retry 3 --max-gzip-mock 2 --max-gzip-otel 5 --max-gzip-logger 2.5
+      # Fails over the min+gzip budget of an entry in scripts/size-budgets.json,
+      # which also catches a third-party module bundled in, and on an entry of
+      # the exports map without a budget.
+      - run: pnpm size --check
 
   types:
     runs-on: ubuntu-latest
diff --git a/CLAUDE.md b/CLAUDE.md
index ecc9dd4..588bbd6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,7 +42,7 @@ pnpm run test:types                # tsd: tests/types/*.test-d.ts, one file per
 pnpm run check:dts                 # tsc --noEmit --strict over the d.ts of every entry
 pnpm run lint                      # oxlint src tests scripts bench
 pnpm run format                    # oxfmt src tests scripts bench (format:check in CI)
-pnpm size [--max-gzip <KB>]        # esbuild bundle sizes; CI gates the root at 8.5 KB min+gzip and each subpath
+pnpm size [--check]                # esbuild bundle sizes; --check gates every entry by scripts/size-budgets.json
 pnpm bench [filter] [--json] [--save] [--compare]   # ops/sec harness, manual only; --save writes bench/baseline.json
 pnpm docs:comparison               # renders docs/comparison.json into docs/guide/comparison.md
 pnpm run docs:dev                  # VitePress dev server for docs/ (docs:build, docs:preview)
@@ -388,7 +388,8 @@ tests/
   fixtures/<sub>/   static fixtures (certificates)
   types/*.test-d.ts tsd assertions, one file per entry
 scripts/
-  size.js           bundle-size report and budget gates, one per subpath (CI smoke)
+  size.js           bundle-size report; --check gates each entry of the exports map
+  size-budgets.json the min+gzip budget of each entry in KB (the root, and each subpath on top)
   check-dts.js      tsc --strict over the d.ts of every entry of the exports map
   comparison.js     renders docs/comparison.json into docs/guide/comparison.md
 bench/              zero-dependency ops/sec harness; baseline.json is a snapshot for --compare
@@ -557,8 +558,9 @@ change. **This file wins** if they ever disagree.
   (minified and not) and checks its exports through the result, so the shipped files keep working
   after a consumer's bundler (a serverless function, a single-file deploy).
 - `tests/unit/dependencies.test.js` guards "Zero dependencies" above.
-- `tests/unit/scripts.test.js` runs `scripts/size.js` with a budget it always meets and one it
-  never can.
+- `tests/unit/scripts.test.js` checks that every entry of the exports map has a budget in
+  `scripts/size-budgets.json` and nothing else does, and runs `scripts/size.js --check` with
+  budgets it always meets, budgets it never can and a missing one.
 - New behavior needs a test that fails without the change. Network transports are tested
   against local fake servers (`tests/helpers/smtp/mock-smtp-server.js` on `node:net`, servers on
   `node:http`) or a stubbed `fetch` (`t.mock.method(globalThis, 'fetch', …)`), never against a
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 67585e2..a4dc6b6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -51,13 +51,13 @@ pnpm run format
 pnpm run test:coverage
 pnpm run test:types
 pnpm run check:dts
-pnpm size --max-gzip 4
+pnpm size --check
 ```
 
 `prepublishOnly` runs lint, format check, coverage, tsd and `check:dts`; CI adds the bundle-size
-gate (4 KB min+gzip), the comparison drift check and the docs build. Treat that as the merge gate.
-Coverage of `src/` is 100% with no `c8 ignore` comments: an unreachable branch is removed, not
-ignored.
+gate (a min+gzip budget per entry of the exports map, in `scripts/size-budgets.json`), the
+comparison drift check and the docs build. Treat that as the merge gate. A new subpath needs a
+budget there, or `pnpm size --check` fails.
 
 The comparison table in `docs/guide/comparison.md` is generated: edit `docs/comparison.json` and
 run `pnpm docs:comparison`.
diff --git a/scripts/size-budgets.json b/scripts/size-budgets.json
new file mode 100644
index 0000000..1eec525
--- /dev/null
+++ b/scripts/size-budgets.json
@@ -0,0 +1,19 @@
+{
+  ".": 8.5,
+  "./mime": 7,
+  "./smtp": 20,
+  "./jmap": 11.5,
+  "./ses": 6,
+  "./resend": 5.5,
+  "./sendgrid": 5,
+  "./mailgun": 5,
+  "./mailtrap": 6,
+  "./maileroo": 5.5,
+  "./lettermint": 5.5,
+  "./plunk": 5,
+  "./pool": 2.5,
+  "./retry": 3,
+  "./mock": 2,
+  "./otel": 5,
+  "./logger": 2.5
+}
diff --git a/scripts/size.js b/scripts/size.js
index ef4bcd8..2d6612b 100644
--- a/scripts/size.js
+++ b/scripts/size.js
@@ -1,9 +1,11 @@
 /**
- * Bundle-size report, run with `pnpm size`. With `--max-gzip <KB>` it also fails
- * when the root entry exceeds that min+gzip budget, and with
- * `--max-gzip-<subpath> <KB>` when a subpath of the exports map adds more than
- * that on top of the root entry (`--max-gzip-smtp` for `./smtp`). CI passes one
- * flag per subpath as a gate.
+ * Bundle-size report, run with `pnpm size`. With `--check` it also fails when an
+ * entry of the exports map goes over its min+gzip budget in
+ * `scripts/size-budgets.json` (in KB, keyed like the exports map: the root
+ * entry, and what each subpath adds on top of it), and when an entry has no
+ * budget there or a budget names no entry, so that a new subpath is gated from
+ * its first commit. `--budgets <file>` reads another file. CI and
+ * `prepublishOnly` run `--check`.
  *
  * Bundles the shipped entry points with esbuild the way a consumer's bundler
  * would (a serverless function, a single-file deploy), then reports:
@@ -23,14 +25,16 @@
  * tests/unit/dependencies.test.js.
  */
 
+const fs = require('node:fs');
 const { gzipSync } = require('node:zlib');
 const path = require('node:path');
 const esbuild = require('esbuild');
 const pkg = require('../package.json');
 
 const ROOT = path.join(__dirname, '..');
+const BUDGETS = path.join(__dirname, 'size-budgets.json');
 
-const ENTRY = { label: 'Node entry (index.js)', entry: 'index.js', platform: 'node' };
+const ENTRY = { label: 'Node entry (index.js)', entry: 'index.js', platform: 'node', key: '.' };
 
 // One row per subpath of the exports map.
 const subpathsOf = (exportsMap) =>
@@ -43,7 +47,7 @@ const subpathsOf = (exportsMap) =>
         entry: ENTRY.entry,
         platform: ENTRY.platform,
         subpath: file,
-        flag: `--max-gzip-${name}`,
+        key: subpath,
       };
     });
 
@@ -69,22 +73,28 @@ const bundle = async (entry, platform, minify, subpaths = []) => {
 
 const kb = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;
 
-const budget = (flag) => {
-  const args = process.argv.slice(2);
-  const index = args.indexOf(flag);
-  if (index === -1) return null;
-  const limit = Number(args[index + 1]);
-  if (!Number.isFinite(limit) || limit <= 0) {
-    throw new Error(`${flag} needs a positive number of kilobytes`);
+// What is wrong with a budgets file for an exports map: an entry without a
+// budget, a budget for no entry, or one that is not a positive number of KB.
+const budgetProblems = (budgets, exportsMap) => {
+  const problems = [];
+  for (const key of Object.keys(exportsMap)) {
+    if (!Object.hasOwn(budgets, key)) problems.push(`${key} has no budget`);
+  }
+  for (const [key, limit] of Object.entries(budgets)) {
+    if (!Object.hasOwn(exportsMap, key)) {
+      problems.push(`${key} has a budget but is not in the exports map`);
+    } else if (typeof limit !== 'number' || !Number.isFinite(limit) || limit <= 0) {
+      problems.push(`${key} needs a budget of a positive number of kilobytes`);
+    }
   }
-  return limit * 1024;
+  return problems;
 };
 
-const measure = async ({ label, entry, platform }, subpaths) => {
+const measure = async ({ label, key, entry, platform }, subpaths) => {
   const raw = await bundle(entry, platform, false, subpaths);
   const min = await bundle(entry, platform, true, subpaths);
   const gzip = gzipSync(min, { level: 9 });
-  return { label, raw: raw.length, min: min.length, gzip: gzip.length };
+  return { label, key, raw: raw.length, min: min.length, gzip: gzip.length };
 };
 
 const exceeded = (row, max) => {
@@ -101,7 +111,7 @@ const extrasOf = async (core, size = measure, subpaths = SUBPATHS) => {
     const both = await size(entry, [entry.subpath]);
     extras.push({
       label: entry.label,
-      max: budget(entry.flag),
+      key: entry.key,
       raw: both.raw - core.raw,
       min: both.min - core.min,
       gzip: both.gzip - core.gzip,
@@ -111,17 +121,29 @@ const extrasOf = async (core, size = measure, subpaths = SUBPATHS) => {
 };
 
 const main = async () => {
-  const maxGzip = budget('--max-gzip');
+  const args = process.argv.slice(2);
+  const index = args.indexOf('--budgets');
+  const file = index === -1 ? BUDGETS : path.resolve(args[index + 1]);
+  const budgets = args.includes('--check') ? JSON.parse(fs.readFileSync(file, 'utf8')) : null;
+  if (budgets !== null) {
+    const problems = budgetProblems(budgets, pkg.exports);
+    for (const problem of problems) console.error(`${path.relative(ROOT, file)}: ${problem}`);
+    if (problems.length > 0) {
+      process.exitCode = 1;
+      return;
+    }
+  }
   const core = await measure(ENTRY);
-  const extras = await extrasOf(core);
+  const rows = [core, ...(await extrasOf(core))];
   console.log('| Entry | raw | min | min+gzip |');
   console.log('| ----- | ---:| ---:| --------:|');
-  for (const row of [core, ...extras]) {
+  for (const row of rows) {
     console.log(`| ${row.label} | ${kb(row.raw)} | ${kb(row.min)} | ${kb(row.gzip)} |`);
   }
-  if (maxGzip !== null && core.gzip > maxGzip) exceeded(core, maxGzip);
-  for (const row of extras) {
-    if (row.max !== null && row.gzip > row.max) exceeded(row, row.max);
+  if (budgets === null) return;
+  for (const row of rows) {
+    const max = budgets[row.key] * 1024;
+    if (row.gzip > max) exceeded(row, max);
   }
 };
 
@@ -132,4 +154,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { SUBPATHS, subpathsOf, extrasOf };
+module.exports = { SUBPATHS, budgetProblems, subpathsOf, extrasOf };
diff --git a/tests/unit/scripts.test.js b/tests/unit/scripts.test.js
index 23b0bea..dda46bf 100644
--- a/tests/unit/scripts.test.js
+++ b/tests/unit/scripts.test.js
@@ -1,6 +1,8 @@
 const { test } = require('node:test');
 const assert = require('node:assert');
 const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const pkg = require('../../package.json');
 
@@ -17,10 +19,10 @@ test('Scripts: a subpath is measured on top of the root entry', async () => {
     './mime': { types: './src/mime/index.d.ts', default: './src/mime/index.js' },
   });
   assert.deepStrictEqual(
-    subpaths.map(({ label, subpath, flag }) => [label, subpath, flag]),
+    subpaths.map(({ label, subpath, key }) => [label, subpath, key]),
     [
-      ['Smtp (./smtp) on top of the Node entry', './src/smtp/index.js', '--max-gzip-smtp'],
-      ['Mime (./mime) on top of the Node entry', './src/mime/index.js', '--max-gzip-mime'],
+      ['Smtp (./smtp) on top of the Node entry', './src/smtp/index.js', './smtp'],
+      ['Mime (./mime) on top of the Node entry', './src/mime/index.js', './mime'],
     ],
   );
   // A fake measure: a size per subpath in the bundle, over a core of 1000.
@@ -33,36 +35,79 @@ test('Scripts: a subpath is measured on top of the root entry', async () => {
   const core = { label: 'core', raw: 3000, min: 2000, gzip: 1000 };
   const extras = await extrasOf(core, size, subpaths);
   assert.deepStrictEqual(
-    extras.map(({ gzip, min, raw, max }) => [gzip, min, raw, max]),
+    extras.map(({ gzip, min, raw, key }) => [gzip, min, raw, key]),
     [
-      [400, 800, 1200, null],
-      [70, 140, 210, null],
+      [400, 800, 1200, './smtp'],
+      [70, 140, 210, './mime'],
     ],
   );
 });
 
-test('Scripts: size reports the entries and enforces the gzip budgets', () => {
+test('Scripts: every entry of the exports map has a size budget, and only those', () => {
+  const { budgetProblems } = require('../../scripts/size.js');
+  assert.deepStrictEqual(
+    budgetProblems(require('../../scripts/size-budgets.json'), pkg.exports),
+    [],
+  );
+  const exportsMap = { '.': {}, './smtp': {}, './mime': {} };
+  assert.deepStrictEqual(budgetProblems({ '.': 8, './smtp': 0, './jmap': 1 }, exportsMap), [
+    './mime has no budget',
+    './smtp needs a budget of a positive number of kilobytes',
+    './jmap has a budget but is not in the exports map',
+  ]);
+  assert.deepStrictEqual(
+    budgetProblems({ '.': '8', './smtp': 1, './mime': Infinity }, exportsMap),
+    [
+      '. needs a budget of a positive number of kilobytes',
+      './mime needs a budget of a positive number of kilobytes',
+    ],
+  );
+});
+
+test('Scripts: size reports the entries and, with --check, enforces their budgets', (t) => {
   const { SUBPATHS } = require('../../scripts/size.js');
-  const budgets = ['--max-gzip', '100'];
-  for (const { flag } of SUBPATHS) budgets.push(flag, '100');
-  const ok = run('scripts/size.js', budgets);
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'mailer-size-'));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  const write = (name, budgets) => {
+    const file = path.join(directory, name);
+    fs.writeFileSync(file, JSON.stringify(budgets));
+    return file;
+  };
+  const everyEntry = (limit) => {
+    const budgets = {};
+    for (const key of Object.keys(pkg.exports)) budgets[key] = limit;
+    return budgets;
+  };
+
+  const ok = run('scripts/size.js', ['--check', '--budgets', write('ok.json', everyEntry(100))]);
   assert.strictEqual(ok.status, 0, ok.stderr);
   assert.match(ok.stdout, /\| Node entry \(index\.js\) \|/);
   for (const { label } of SUBPATHS) assert.ok(ok.stdout.includes(`| ${label} |`), label);
 
-  const over = run('scripts/size.js', ['--max-gzip', '0.01']);
+  // Without --check the budgets are not read.
+  const report = run('scripts/size.js', ['--budgets', path.join(directory, 'none.json')]);
+  assert.strictEqual(report.status, 0, report.stderr);
+
+  const over = run('scripts/size.js', [
+    '--check',
+    '--budgets',
+    write('over.json', everyEntry(0.001)),
+  ]);
   assert.strictEqual(over.status, 1);
   assert.match(over.stderr, /Bundle budget exceeded: Node entry/);
-
-  for (const { flag, label } of SUBPATHS) {
-    const subpathOver = run('scripts/size.js', [flag, '0.01']);
-    assert.strictEqual(subpathOver.status, 1, flag);
-    assert.ok(subpathOver.stderr.includes(`Bundle budget exceeded: ${label}`), flag);
+  for (const { label } of SUBPATHS) {
+    assert.ok(over.stderr.includes(`Bundle budget exceeded: ${label}`), label);
   }
 
-  const bad = run('scripts/size.js', ['--max-gzip', 'lots']);
-  assert.strictEqual(bad.status, 1);
-  assert.match(bad.stderr, /positive number of kilobytes/);
+  const { './smtp': smtp, ...missing } = everyEntry(100);
+  const unbudgeted = run('scripts/size.js', [
+    '--check',
+    '--budgets',
+    write('missing.json', missing),
+  ]);
+  assert.strictEqual(unbudgeted.status, 1);
+  assert.match(unbudgeted.stderr, /missing\.json: \.\/smtp has no budget/);
+  assert.strictEqual(unbudgeted.stdout, '');
 });
 
 test('Scripts: check-dts compiles the types of every entry of the exports map', () => {

From 71bf035cab4701cd26d699958cee4211812c4f28 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:13:57 +0300
Subject: [PATCH 126/158] chore: check the tarball and the size budgets before
 publishing

scripts/check-pack.js reads `pnpm pack --dry-run --json` and fails on a
file of the exports map, the root entry or a document missing from the
tarball, and on a file the files allowlist should keep out. It runs as
`pnpm run check:pack` in CI and, with `pnpm size --check`, in
prepublishOnly, which ran neither, so a release from a laptop skipped
both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/npm-publish/SKILL.md | 11 +++---
 .github/workflows/ci.yml            |  3 ++
 CLAUDE.md                           | 12 ++++---
 package.json                        |  3 +-
 scripts/check-pack.js               | 56 +++++++++++++++++++++++++++++
 tests/unit/scripts.test.js          | 35 ++++++++++++++++++
 6 files changed, 110 insertions(+), 10 deletions(-)
 create mode 100644 scripts/check-pack.js

diff --git a/.claude/skills/npm-publish/SKILL.md b/.claude/skills/npm-publish/SKILL.md
index 53bc30a..9b0add9 100644
--- a/.claude/skills/npm-publish/SKILL.md
+++ b/.claude/skills/npm-publish/SKILL.md
@@ -32,12 +32,13 @@ pnpm run format:check            # oxfmt
 pnpm run test:coverage           # tests under the c8 coverage gate
 pnpm run test:types              # tsd
 pnpm run check:dts               # tsc over the d.ts of every entry of the exports map
+pnpm size --check                # the budgets of scripts/size-budgets.json
+pnpm run check:pack              # the tarball: every file of the exports map, nothing else
 ```
 
-These are the same gates `prepublishOnly` runs. CI adds three more; run them too:
+These are the same gates `prepublishOnly` runs. CI adds two more; run them too:
 
 ```bash
-pnpm size --check                                                # the budgets of scripts/size-budgets.json
 pnpm docs:comparison && git diff --exit-code docs/guide/comparison.md   # the table matches docs/comparison.json
 pnpm run docs:build                                              # the docs site; a dead link fails it
 ```
@@ -163,10 +164,12 @@ Check these fields are correct:
 
 ```bash
 pnpm pack --dry-run
+pnpm run check:pack
 pnpm run size
 ```
 
-Review the file list:
+`check:pack` fails on a file of the exports map missing from the tarball or a file outside the
+`files` allowlist; review the file list anyway:
 
 - Source files (`src/`) and root entry points are included
 - Type definitions are included
@@ -180,7 +183,7 @@ Report the file count and the bundle size from `pnpm run size` to the user.
 Run the gates one more time after all edits:
 
 ```bash
-pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts && pnpm size --check && pnpm run docs:build
+pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts && pnpm size --check && pnpm run check:pack && pnpm run docs:build
 ```
 
 Must exit 0. If it fails, fix and re-run.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d458a99..287fa1d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -34,6 +34,9 @@ jobs:
       # which also catches a third-party module bundled in, and on an entry of
       # the exports map without a budget.
       - run: pnpm size --check
+      # The tarball holds every file of the exports map and nothing outside
+      # the files allowlist.
+      - run: pnpm run check:pack
 
   types:
     runs-on: ubuntu-latest
diff --git a/CLAUDE.md b/CLAUDE.md
index 588bbd6..416cfcd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,6 +40,7 @@ node --test --test-name-pattern="Bundle" tests/unit/*.test.js   # filter by name
 pnpm run test:coverage             # c8 over src/, gated at 98 lines/statements, 90 branches, 100 functions
 pnpm run test:types                # tsd: tests/types/*.test-d.ts, one file per entry
 pnpm run check:dts                 # tsc --noEmit --strict over the d.ts of every entry
+pnpm run check:pack                # the files `pnpm publish` would pack: the exports map, nothing else
 pnpm run lint                      # oxlint src tests scripts bench
 pnpm run format                    # oxfmt src tests scripts bench (format:check in CI)
 pnpm size [--check]                # esbuild bundle sizes; --check gates every entry by scripts/size-budgets.json
@@ -48,9 +49,9 @@ pnpm docs:comparison               # renders docs/comparison.json into docs/guid
 pnpm run docs:dev                  # VitePress dev server for docs/ (docs:build, docs:preview)
 ```
 
-`prepublishOnly` runs lint + format:check + test:coverage + test:types + check:dts. CI adds the
-size gate, the comparison drift check and the docs build. Treat that as the pre-merge gate. There
-is no build step.
+`prepublishOnly` runs lint + format:check + test:coverage + test:types + check:dts + the size
+gate + check:pack. CI adds the comparison drift check and the docs build. Treat that as the
+pre-merge gate. There is no build step.
 
 ## No build step: CommonJS + hand-written types
 
@@ -391,6 +392,7 @@ scripts/
   size.js           bundle-size report; --check gates each entry of the exports map
   size-budgets.json the min+gzip budget of each entry in KB (the root, and each subpath on top)
   check-dts.js      tsc --strict over the d.ts of every entry of the exports map
+  check-pack.js     the tarball holds every file of the exports map and nothing outside `files`
   comparison.js     renders docs/comparison.json into docs/guide/comparison.md
 bench/              zero-dependency ops/sec harness; baseline.json is a snapshot for --compare
 docs/               VitePress site (mailerat.vercel.app), not published
@@ -609,5 +611,5 @@ Manual, as in the sibling repositories. The `npm-publish` skill walks through it
 2. Turn `## [Unreleased]` in CHANGELOG.md into `## [X.Y.Z] - YYYY-MM-DD` and add its link
    reference.
 3. Commit, then tag `vX.Y.Z`.
-4. Run `pnpm run release` (`pnpm publish`, gated by `prepublishOnly`; `publishConfig.access` is
-   public).
+4. Run `pnpm run release` (`pnpm publish`, gated by `prepublishOnly`, which includes the size
+   gate and the tarball check; `publishConfig.access` is public).
diff --git a/package.json b/package.json
index c522c77..abaf015 100644
--- a/package.json
+++ b/package.json
@@ -111,6 +111,7 @@
     "test:coverage": "c8 --all --include 'src/**' --check-coverage --lines 98 --statements 98 --branches 90 --functions 100 --reporter text --reporter lcov node --test tests/unit/*.test.js",
     "test:types": "tsd",
     "check:dts": "node scripts/check-dts.js",
+    "check:pack": "node scripts/check-pack.js",
     "lint": "oxlint src tests scripts bench",
     "format": "oxfmt src tests scripts bench",
     "format:check": "oxfmt --check src tests scripts bench",
@@ -120,7 +121,7 @@
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "docs:comparison": "node scripts/comparison.js",
-    "prepublishOnly": "pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts",
+    "prepublishOnly": "pnpm run lint && pnpm run format:check && pnpm run test:coverage && pnpm run test:types && pnpm run check:dts && pnpm size --check && pnpm run check:pack",
     "release": "pnpm publish"
   },
   "tsd": {
diff --git a/scripts/check-pack.js b/scripts/check-pack.js
new file mode 100644
index 0000000..8591a4e
--- /dev/null
+++ b/scripts/check-pack.js
@@ -0,0 +1,56 @@
+/**
+ * Checks the files `pnpm publish` would pack, run by `prepublishOnly` and in CI:
+ * the tarball must hold the root entry, every file the exports map points to
+ * and the documents, and nothing the `files` allowlist is meant to keep out
+ * (tests, docs, scripts, bench, the repository's tooling). A mistake in `files`
+ * or in the exports map otherwise shows up only for the people who install it.
+ */
+
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const pkg = require('../package.json');
+
+const ROOT = path.join(__dirname, '..');
+const DOCUMENTS = ['package.json', 'README.md', 'CHANGELOG.md', 'LICENSE', 'SECURITY.md'];
+const ALLOWED =
+  /^(?:index\.js|index\.d\.ts|src\/.+\.(?:js|d\.ts)|package\.json|README\.md|CHANGELOG\.md|LICENSE|SECURITY\.md)$/;
+
+// What is wrong with the packed paths for a package.json: a required file
+// missing, or a file outside the allowlist.
+const packProblems = (files, manifest) => {
+  const required = new Set(DOCUMENTS);
+  required.add(path.posix.normalize(manifest.main));
+  required.add(path.posix.normalize(manifest.types));
+  for (const entry of Object.values(manifest.exports)) {
+    required.add(path.posix.normalize(entry.types));
+    required.add(path.posix.normalize(entry.default));
+  }
+  const packed = new Set(files);
+  const problems = [];
+  for (const file of required) {
+    if (!packed.has(file)) problems.push(`${file} is missing from the tarball`);
+  }
+  for (const file of files) {
+    if (!ALLOWED.test(file)) problems.push(`${file} should not be in the tarball`);
+  }
+  return problems;
+};
+
+const packedFiles = () => {
+  const output = execFileSync('pnpm', ['pack', '--dry-run', '--json'], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  return JSON.parse(output).files.map((file) => file.path);
+};
+
+if (require.main === module) {
+  const files = packedFiles();
+  const problems = packProblems(files, pkg);
+  for (const problem of problems) console.error(problem);
+  if (problems.length > 0) process.exitCode = 1;
+  else console.log(`The tarball holds the ${files.length} files it should.`);
+}
+
+module.exports = { packProblems };
diff --git a/tests/unit/scripts.test.js b/tests/unit/scripts.test.js
index dda46bf..94116b6 100644
--- a/tests/unit/scripts.test.js
+++ b/tests/unit/scripts.test.js
@@ -110,6 +110,41 @@ test('Scripts: size reports the entries and, with --check, enforces their budget
   assert.strictEqual(unbudgeted.stdout, '');
 });
 
+test('Scripts: check-pack wants every file of the exports map and nothing else', () => {
+  const { packProblems } = require('../../scripts/check-pack.js');
+  const manifest = {
+    main: 'index.js',
+    types: 'index.d.ts',
+    exports: {
+      '.': { types: './index.d.ts', default: './index.js' },
+      './smtp': { types: './src/smtp/index.d.ts', default: './src/smtp/index.js' },
+    },
+  };
+  const complete = [
+    'package.json',
+    'README.md',
+    'CHANGELOG.md',
+    'LICENSE',
+    'SECURITY.md',
+    'index.js',
+    'index.d.ts',
+    'src/smtp/index.js',
+    'src/smtp/index.d.ts',
+    'src/smtp/smtp-connection.js',
+  ];
+  assert.deepStrictEqual(packProblems(complete, manifest), []);
+  const broken = complete.filter((file) => file !== 'src/smtp/index.d.ts' && file !== 'LICENSE');
+  broken.push('tests/unit/smtp.test.js', 'docs/index.md', 'scripts/size.js', 'src/smtp/notes.md');
+  assert.deepStrictEqual(packProblems(broken, manifest), [
+    'LICENSE is missing from the tarball',
+    'src/smtp/index.d.ts is missing from the tarball',
+    'tests/unit/smtp.test.js should not be in the tarball',
+    'docs/index.md should not be in the tarball',
+    'scripts/size.js should not be in the tarball',
+    'src/smtp/notes.md should not be in the tarball',
+  ]);
+});
+
 test('Scripts: check-dts compiles the types of every entry of the exports map', () => {
   const { typesOf } = require('../../scripts/check-dts.js');
   assert.deepStrictEqual(

From c3a816cdeeb9a8297769a1813e7e5ba0a751e963 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:15:13 +0300
Subject: [PATCH 127/158] docs: loops in one pass and keyed collections in src/

CLAUDE.md and the js-conventions skill say what the review asked for:
no array iteration method anywhere in src/, loops that compute what a
collection gives in one pass, a Set or a Map built once instead of
repeated scans, and a WeakMap or WeakSet for what the library keeps
about objects it does not own. Tests, scripts and bench are exempt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/skills/js-conventions/SKILL.md | 18 +++++++++++++-----
 CLAUDE.md                              | 25 ++++++++++++++++++-------
 2 files changed, 31 insertions(+), 12 deletions(-)

diff --git a/.claude/skills/js-conventions/SKILL.md b/.claude/skills/js-conventions/SKILL.md
index d986262..832fdef 100644
--- a/.claude/skills/js-conventions/SKILL.md
+++ b/.claude/skills/js-conventions/SKILL.md
@@ -4,7 +4,8 @@ description: Apply the Alexis JavaScript style (Metarhia-derived, linted by oxli
 ---
 
 <!-- Adapted from metaskills v1.0.5 (skills/js-conventions) for the Alexis toolchain:
-     oxlint + oxfmt instead of ESLint + Prettier, pnpm instead of npm, 100 columns instead of 80. -->
+     oxlint + oxfmt instead of ESLint + Prettier, pnpm instead of npm, 100 columns instead of 80;
+     loops in one pass instead of array iteration methods in library code (src/). -->
 
 # JavaScript Code Style
 
@@ -58,15 +59,18 @@ Use following conventions for JavaScript and TypeScript code.
 - Do not mutate input parameters; avoid `arguments`
 - Keep functions small and single-purpose
 - Decompose long expressions into intermediate variables
-- Prefer explicit loops (`for`, `for..of`) in hot paths
-- Use array methods when they improve readability
+- Iterate with `for` and `for..of` loops in library code (`src/`), index loops in hot paths; no
+  array iteration methods there (`.map`, `.filter`, `.some`, `.every`, `.find`, `.findIndex`,
+  `.findLast`, `.reduce`, `.flatMap`, `.forEach`), cold paths included
+- Compute everything a collection gives in one pass with an early exit; never chain passes
+  (`.map().join()`, `Object.entries().filter()`, `Array.from().map()`), and do not build an array
+  only to iterate it (spread of an iterable, `Array.from(string)`, `split` only to test)
 - Use `===` and `!==` only
 - Keep return types consistent
 - Avoid nested ternaries and deep callback nesting
 - Self-documented and self-descriptive code: do not add
   obvious comments, code should be clear without comments
-- Use iteration methods like `.map`, `.filter`, `.reduce` if it is good for code semantic
-- Try to avoid `.forEach` if callback operates with outer context
+- Tests, scripts and benchmarks may use array iteration methods where they read better
 
 ## Optimizations
 
@@ -86,6 +90,10 @@ Use following conventions for JavaScript and TypeScript code.
 - Move reusable callbacks outside loops
 - Keep `try/catch`, spread/rest away from hot loops
 - Use `Map` for dynamic key dictionaries, plain objects for fixed schemas
+- Build a lookup once: a module-level `Set` for membership, a `Map` for keyed search, instead of
+  repeated linear scans (`.includes`, a `.find` per call)
+- Keep caches and metadata on objects you do not own (a message, a config) in a `WeakMap` or
+  `WeakSet` rather than in a property on them
 - Use `Set` for big and dynamic collections, prefer arrays for short and stable
 - Use `Object.create(null)` for pure dictionaries
 - Use typed arrays for numeric and binary workloads
diff --git a/CLAUDE.md b/CLAUDE.md
index 416cfcd..dfbb5c0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -523,8 +523,17 @@ entry with no `node:*`, and a platform test would enforce it as in protoarray.
   - module-level functions are arrow functions assigned to `const`; classes and prototype objects
     use method shorthand; no `function` declarations;
   - `Object.create(null)` for dictionaries;
-  - hot loops (MIME encoding, header folding) avoid destructuring and use index loops, not
-    `forEach`;
+  - **loops, one pass, keyed collections** (stricter than the metaskills): `src/` uses no array
+    iteration method (`map`, `filter`, `some`, `every`, `find`, `findIndex`, `findLast`, `reduce`,
+    `flatMap`, `forEach`), cold paths included, but `for` and `for…of` loops, index loops on hot
+    paths (bytes, characters, lines, the messages of a batch), with no destructuring in them;
+    whatever a collection gives is computed in one pass with an early exit, never in chained
+    passes (`.map().join()`, `Object.entries().filter()`), and no array is made only to be
+    iterated (a spread iterable, `Array.from(string)`, `split` only to test); membership goes
+    through a module-level `Set`, keyed lookups through a `Map` built once, and caches or
+    metadata on objects the library does not own (a `Message`, a config, a transport) through a
+    `WeakMap` or `WeakSet` rather than a property on them. Plain objects stay for fixed shapes,
+    and `tests/`, `scripts/` and `bench/` are exempt;
   - prefer `const`; no `var`;
   - private class members with `#`.
 - Built-ins with the `node:` prefix; relative requires always end in `.js`.
@@ -537,12 +546,14 @@ entry with no `node:*`, and a platform test would enforce it as in protoarray.
 skills: `js-conventions`, `js-data-structures`, `data-structures`, `metautil-data-structures`,
 `js-gof`, `error-handling` and `npm-publish`.
 
-- **`js-conventions` is adapted to this toolchain** (the same copy as protoarray): oxlint/oxfmt
-  instead of ESLint/Prettier, pnpm, 100 columns, plus a Modules section (CommonJS, no
-  `'use strict'`, `node:` prefix, `.js` in relative requires). Its naming, best-practice and
-  optimization rules are upstream's.
+- **`js-conventions` is adapted to this toolchain** (the same copy as protoarray, plus the rule of
+  loops, one pass and keyed collections from "Conventions", which replaces upstream's "use array
+  methods when they improve readability"): oxlint/oxfmt instead of ESLint/Prettier, pnpm, 100
+  columns, plus a Modules section (CommonJS, no `'use strict'`, `node:` prefix, `.js` in relative
+  requires). Its other naming, best-practice and optimization rules are upstream's.
 - **`npm-publish` is adapted to the release process below:** pnpm commands, the `prepublishOnly`
-  gates plus the CI ones (size, comparison drift, docs build), this CHANGELOG's format, docs and
+  gates (the size gate and the tarball check among them) plus the CI ones (comparison drift, docs
+  build), this CHANGELOG's format, docs and
   `pnpm pack` checks, and `pnpm run release`.
 - **The other five are verbatim copies.**
 

From 70e7a7c825ce7273aff62ad71b4b61531309e5d3 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:18:53 +0300
Subject: [PATCH 128/158] refactor(core): loops in one pass, a table of word
 rules, no nested ternaries

classifyReceiptError tries an ordered table of word rules instead of nine
chained ifs; createFailedReceipt builds its errors and their messages in
one pass over the input instead of three maps and a some; createMessage
checks each address list and the attachments with a loop each; the
raw-message traversal checks a window in a function of its own that
keeps its position in locals; readMethod and parseContentLine of the
calendar split their checks out. Behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/core/calendar.js    | 137 +++++++++++++----------
 src/core/message-id.js  |  18 +--
 src/core/message.js     |  77 ++++++++-----
 src/core/priority.js    |   5 +-
 src/core/raw-message.js | 144 ++++++++++++++----------
 src/core/receipt.js     | 239 +++++++++++++++++++---------------------
 6 files changed, 344 insertions(+), 276 deletions(-)

diff --git a/src/core/calendar.js b/src/core/calendar.js
index 13f2329..222296a 100644
--- a/src/core/calendar.js
+++ b/src/core/calendar.js
@@ -176,12 +176,7 @@ const normalizeLineEndings = (content) => {
 const readMethod = (content) => {
   // Check the transmitted text before unfolding: a fold between two lone
   // surrogates must not rescue them into a pair only in the parsed view.
-  for (const character of content) {
-    const code = character.codePointAt(0);
-    if (code >= 0xd800 && code <= 0xdfff) {
-      throw new TypeError('The calendar content contains an unpaired UTF-16 surrogate.');
-    }
-  }
+  checkSurrogates(content);
   const stack = [];
   let closed = false;
   let method;
@@ -202,36 +197,7 @@ const readMethod = (content) => {
     }
 
     if (name === 'BEGIN') {
-      if (closed) {
-        throw new TypeError(
-          'The calendar content holds more than one VCALENDAR object, but a ' +
-            'message carries one.',
-        );
-      }
-      if (stack.length < 1 && value !== 'VCALENDAR') {
-        throw new TypeError(
-          `The calendar content begins with ${JSON.stringify(
-            value,
-          )} rather than a VCALENDAR object.`,
-        );
-      }
-      // RFC 5545 §3.4 has no VCALENDAR inside a VCALENDAR.  A nested one
-      // balances, so nothing else in this scan would notice it, and the object
-      // would be sent as though it were the single one this API accepts.
-      if (stack.length > 0 && value === 'VCALENDAR') {
-        throw new TypeError('The calendar content nests a VCALENDAR object inside another.');
-      }
-      // A component name is an `iana-token` or an `x-name`, both of which are
-      // one or more of ALPHA, DIGIT and "-".  A malformed name balances with
-      // its END the same way a well-formed one does, so it has to be checked
-      // here or not at all.
-      if (!componentNamePattern.test(value)) {
-        throw new TypeError(
-          `The calendar content opens a component named ${JSON.stringify(
-            value,
-          )}, which is not a component name.`,
-        );
-      }
+      checkComponentStart(stack, value, closed);
       stack.push(value);
       continue;
     }
@@ -264,6 +230,53 @@ const readMethod = (content) => {
   return methods === 1 ? method : undefined;
 };
 
+const checkSurrogates = (content) => {
+  for (const character of content) {
+    const code = character.codePointAt(0);
+    if (code >= 0xd800 && code <= 0xdfff) {
+      throw new TypeError('The calendar content contains an unpaired UTF-16 surrogate.');
+    }
+  }
+};
+
+/**
+ * Checks a BEGIN line against the components open so far.
+ *
+ * @param stack The names of the open components, outermost first.
+ * @param value The name of the component the line opens.
+ * @param closed Whether a VCALENDAR object has already been closed.
+ * @throws {TypeError} If the component cannot open here.
+ */
+const checkComponentStart = (stack, value, closed) => {
+  if (closed) {
+    throw new TypeError(
+      'The calendar content holds more than one VCALENDAR object, but a message carries one.',
+    );
+  }
+  if (stack.length < 1 && value !== 'VCALENDAR') {
+    throw new TypeError(
+      `The calendar content begins with ${JSON.stringify(value)} rather than a VCALENDAR object.`,
+    );
+  }
+  // RFC 5545 §3.4 has no VCALENDAR inside a VCALENDAR.  A nested one
+  // balances, so nothing else in this scan would notice it, and the object
+  // would be sent as though it were the single one this API accepts.
+  if (stack.length > 0 && value === 'VCALENDAR') {
+    throw new TypeError('The calendar content nests a VCALENDAR object inside another.');
+  }
+  // A component name is an `iana-token` or an `x-name`, both of which are
+  // one or more of ALPHA, DIGIT and "-".  A malformed name balances with
+  // its END the same way a well-formed one does, so it has to be checked
+  // here or not at all.
+  if (!componentNamePattern.test(value)) {
+    throw new TypeError(
+      `The calendar content opens a component named ${JSON.stringify(
+        value,
+      )}, which is not a component name.`,
+    );
+  }
+};
+
 /**
  * Upper-cases the ASCII letters of a token, leaving everything else alone.
  *
@@ -325,28 +338,8 @@ const parseContentLine = (line) => {
 
     // Both paramtext and quoted-string may be empty.  A comma therefore
     // always starts another value, even immediately before ';' or ':'.
-    while (true) {
-      if (line[cursor] === '"') {
-        cursor++;
-        while (cursor < line.length && line[cursor] !== '"') cursor++;
-        if (cursor === line.length) fail('an unterminated quoted parameter');
-        cursor++;
-      } else {
-        while (
-          cursor < line.length &&
-          line[cursor] !== ',' &&
-          line[cursor] !== ';' &&
-          line[cursor] !== ':'
-        ) {
-          if (line[cursor] === '"') {
-            fail('a quote inside an unquoted parameter');
-          }
-          cursor++;
-        }
-      }
-      if (line[cursor] !== ',') break;
-      cursor++;
-    }
+    cursor = skipParameterValue(line, cursor, fail);
+    while (line[cursor] === ',') cursor = skipParameterValue(line, cursor + 1, fail);
     if (line[cursor] !== ';' && line[cursor] !== ':') {
       fail('an invalid delimiter after a parameter value');
     }
@@ -355,6 +348,34 @@ const parseContentLine = (line) => {
   return { name, value: line.slice(cursor + 1), hasParameters };
 };
 
+/**
+ * Skips one parameter value, quoted or not, from a cursor.
+ *
+ * @param line The content line.
+ * @param start Where the value starts.
+ * @param fail Throws the error of the line with a reason.
+ * @returns The cursor after the value.
+ */
+const skipParameterValue = (line, start, fail) => {
+  let cursor = start;
+  if (line[cursor] === '"') {
+    cursor++;
+    while (cursor < line.length && line[cursor] !== '"') cursor++;
+    if (cursor === line.length) fail('an unterminated quoted parameter');
+    return cursor + 1;
+  }
+  while (
+    cursor < line.length &&
+    line[cursor] !== ',' &&
+    line[cursor] !== ';' &&
+    line[cursor] !== ':'
+  ) {
+    if (line[cursor] === '"') fail('a quote inside an unquoted parameter');
+    cursor++;
+  }
+  return cursor;
+};
+
 /** Whether a code unit belongs to the iana-token / x-name character set. */
 const isTokenCharacter = (code) => {
   return (
diff --git a/src/core/message-id.js b/src/core/message-id.js
index 2500544..56b0f21 100644
--- a/src/core/message-id.js
+++ b/src/core/message-id.js
@@ -218,17 +218,19 @@ const hasNonAscii = (value) => {
  */
 const resolveThreadingHeaders = (message) => {
   const resolved = new Map();
-  const fields = [
-    ['In-Reply-To', message.inReplyTo],
-    ['References', message.references],
-  ];
-  for (const [name, ids] of fields) {
-    if (ids == null) continue;
-    resolved.set(name, ids.length < 1 ? null : ids.map(formatMessageId).join(' '));
-  }
+  if (message.inReplyTo != null) resolved.set('In-Reply-To', joinMessageIds(message.inReplyTo));
+  if (message.references != null) resolved.set('References', joinMessageIds(message.references));
   return resolved;
 };
 
+// The identifiers of a field, or `null` for an empty list, which suppresses it.
+const joinMessageIds = (ids) => {
+  if (ids.length < 1) return null;
+  let joined = formatMessageId(ids[0]);
+  for (let i = 1; i < ids.length; i++) joined += ` ${formatMessageId(ids[i])}`;
+  return joined;
+};
+
 /**
  * Generates an identifier rooted in the sender's domain.
  *
diff --git a/src/core/message.js b/src/core/message.js
index 307bb12..6058d93 100644
--- a/src/core/message.js
+++ b/src/core/message.js
@@ -42,31 +42,11 @@ const createMessage = (constructor, options) => {
   const sender = checkAddress('sender', constructor.from);
   return {
     sender,
-    recipients: ensureArray(constructor.to).map((to) => checkAddress('recipient', to)),
-    ccRecipients: ensureArray(constructor.cc).map((cc) => checkAddress('CC', cc)),
-    bccRecipients: ensureArray(constructor.bcc).map((bcc) => checkAddress('BCC', bcc)),
-    replyRecipients: ensureArray(constructor.replyTo).map((replyTo) =>
-      checkAddress('reply-to', replyTo),
-    ),
-    // oxlint-disable-next-line array-callback-return -- upstream: the last branch throws
-    attachments: ensureArray(constructor.attachments).map((attachment) => {
-      if (attachment instanceof File) {
-        return checkAttachment({
-          inline: false,
-          filename: attachment.name,
-          content: attachment,
-          contentType:
-            attachment.type == null || attachment.type === ''
-              ? 'application/octet-stream'
-              : attachment.type,
-          contentId: `${generateId('content-id', options?.generateId)}@${sender.address.replace(/^[^@]*@/, '')}`,
-        });
-      } else if (isAttachment(attachment)) {
-        return checkAttachment(attachment);
-      } else {
-        throwTypeError(`Invalid attachment: ${JSON.stringify(attachment)}`);
-      }
-    }),
+    recipients: checkAddresses('recipient', constructor.to),
+    ccRecipients: checkAddresses('CC', constructor.cc),
+    bccRecipients: checkAddresses('BCC', constructor.bcc),
+    replyRecipients: checkAddresses('reply-to', constructor.replyTo),
+    attachments: checkAttachments(constructor.attachments, sender, options),
     subject: constructor.subject,
     content: constructor.content,
     priority: constructor.priority ?? 'normal',
@@ -117,6 +97,45 @@ const checkAddress = (label, address) => {
   return parsed;
 };
 
+// One address or several, none for `null` or `undefined`, each checked.
+const checkAddresses = (label, value) => {
+  const addresses = [];
+  if (value == null) return addresses;
+  if (!Array.isArray(value)) {
+    addresses.push(checkAddress(label, value));
+    return addresses;
+  }
+  for (const address of value) addresses.push(checkAddress(label, address));
+  return addresses;
+};
+
+// One attachment or several, each a `File` (given a Content-ID on the domain
+// of the sender) or an attachment object, each checked.
+const checkAttachments = (value, sender, options) => {
+  const attachments = [];
+  for (const attachment of ensureArray(value)) {
+    if (attachment instanceof File) {
+      attachments.push(
+        checkAttachment({
+          inline: false,
+          filename: attachment.name,
+          content: attachment,
+          contentType:
+            attachment.type == null || attachment.type === ''
+              ? 'application/octet-stream'
+              : attachment.type,
+          contentId: `${generateId('content-id', options?.generateId)}@${sender.address.replace(/^[^@]*@/, '')}`,
+        }),
+      );
+    } else if (isAttachment(attachment)) {
+      attachments.push(checkAttachment(attachment));
+    } else {
+      throwTypeError(`Invalid attachment: ${JSON.stringify(attachment)}`);
+    }
+  }
+  return attachments;
+};
+
 /**
  * Rejects an attachment whose content type or content ID could forge header
  * fields.
@@ -172,7 +191,10 @@ const checkMessageId = (label, id) => {
  */
 const checkMessageIds = (label, ids) => {
   if (ids == null) return undefined;
-  return (typeof ids === 'string' ? [ids] : ids).map((id) => checkMessageId(label, id));
+  if (typeof ids === 'string') return [checkMessageId(label, ids)];
+  const checked = [];
+  for (const id of ids) checked.push(checkMessageId(label, id));
+  return checked;
 };
 
 /**
@@ -194,7 +216,8 @@ const checkDate = (date) => {
 };
 
 const ensureArray = (value) => {
-  return Array.isArray(value) ? value : value == null ? [] : [value];
+  if (Array.isArray(value)) return value;
+  return value == null ? [] : [value];
 };
 
 module.exports = { checkAttachment, createMessage };
diff --git a/src/core/priority.js b/src/core/priority.js
index b741e92..74ea4d5 100644
--- a/src/core/priority.js
+++ b/src/core/priority.js
@@ -19,7 +19,10 @@
  *         if `a` is greater than `b`, and zero if they are equal.
  */
 const comparePriority = (a, b) => {
-  return a === b ? 0 : a === 'high' ? -1 : b === 'high' ? 1 : a === 'low' ? 1 : -1;
+  if (a === b) return 0;
+  if (a === 'high') return -1;
+  if (b === 'high') return 1;
+  return a === 'low' ? 1 : -1;
 };
 
 module.exports = { comparePriority };
diff --git a/src/core/raw-message.js b/src/core/raw-message.js
index ae63b98..4dacb15 100644
--- a/src/core/raw-message.js
+++ b/src/core/raw-message.js
@@ -72,16 +72,14 @@ const createRawMessagePlan = (message) => {
   ) {
     throw new RawMessageValidationError('Expected replayable raw message bytes.', 'content');
   }
+  let size;
+  if (content instanceof Uint8Array) size = content.byteLength;
+  else if (content instanceof Blob) size = content.size;
   return {
     envelope: { from: envelope.from, to: [...envelope.to] },
     content,
     encoding: message.encoding,
-    size:
-      content instanceof Uint8Array
-        ? content.byteLength
-        : content instanceof Blob
-          ? content.size
-          : undefined,
+    size,
   };
 };
 
@@ -97,64 +95,26 @@ const createRawMessagePlan = (message) => {
  * @internal
  */
 const iterateRawMessage = async function* (plan, options = {}) {
-  let offset = 0;
-  let line = 1;
-  let column = 0;
-  let pendingCr = false;
-  let headers = true;
-  let nonAscii = false;
-  let sinceYield = 0;
   const encoding = options.encoding ?? plan.encoding;
-  const fail = (message, field = 'content') => {
-    throw new RawMessageValidationError(message, field, offset, line);
-  };
+  const scan = { offset: 0, line: 1, column: 0, pendingCr: false, headers: true, nonAscii: false };
+  let sinceYield = 0;
   for await (const chunk of iterateAttachmentContent(plan.content, options.signal)) {
-    for (let start = 0; start < chunk.length; start += 32768) {
+    for (let start = 0; start < chunk.length; start += RAW_WINDOW_BYTES) {
       options.signal?.throwIfAborted();
-      const window = chunk.subarray(start, start + 32768);
-      // An index loop: the iterator protocol of for...of costs more than the
-      // checks on each byte.
-      for (let index = 0; index < window.length; index++) {
-        const byte = window[index];
-        if (pendingCr) {
-          if (byte !== 10) fail('Expected LF after CR.');
-          if (line === 1 && column === 0) {
-            fail('Raw message headers must not be empty.');
-          }
-          if (column === 0) headers = false;
-          pendingCr = false;
-          column = 0;
-          line++;
-        } else if (byte === 13) {
-          pendingCr = true;
-        } else if (byte === 10) {
-          fail('Raw messages must use CRLF line endings.');
-        } else {
-          if (byte === 0) fail('Raw messages must not contain NUL.');
-          if (++column > 998) {
-            fail('Raw message lines must not exceed 998 octets.');
-          }
-          if (byte > 127) {
-            nonAscii = true;
-            if (encoding === '7bit' || (encoding === '8bit' && headers)) {
-              fail('Raw message bytes exceed the declared encoding.', 'encoding');
-            }
-          }
-        }
-        offset++;
-      }
-      if (options.expectedSize !== undefined && offset > options.expectedSize) {
-        fail('Raw message size changed between reads.');
+      const window = chunk.subarray(start, start + RAW_WINDOW_BYTES);
+      scanRawWindow(scan, window, encoding);
+      if (options.expectedSize !== undefined && scan.offset > options.expectedSize) {
+        throw rawError('Raw message size changed between reads.', scan.offset, scan.line);
       }
       options.onProgress?.({
-        size: offset,
-        encoding: encoding ?? (nonAscii ? 'utf8' : '7bit'),
+        size: scan.offset,
+        encoding: encoding ?? (scan.nonAscii ? 'utf8' : '7bit'),
       });
       options.signal?.throwIfAborted();
       yield window;
       options.signal?.throwIfAborted();
       sinceYield += window.length;
-      if (sinceYield >= 1024 * 1024) {
+      if (sinceYield >= RAW_YIELD_BYTES) {
         await new Promise((resolve) => setTimeout(resolve, 0));
         options.signal?.throwIfAborted();
         sinceYield = 0;
@@ -162,11 +122,79 @@ const iterateRawMessage = async function* (plan, options = {}) {
     }
   }
   options.signal?.throwIfAborted();
-  if (offset === 0) fail('Raw message headers must not be empty.');
-  if (pendingCr || column !== 0) fail('Raw messages must end with CRLF.');
-  if (options.expectedSize !== undefined && offset !== options.expectedSize) {
-    fail('Raw message size changed between reads.');
+  if (scan.offset === 0) {
+    throw rawError('Raw message headers must not be empty.', scan.offset, scan.line);
+  }
+  if (scan.pendingCr || scan.column !== 0) {
+    throw rawError('Raw messages must end with CRLF.', scan.offset, scan.line);
+  }
+  if (options.expectedSize !== undefined && scan.offset !== options.expectedSize) {
+    throw rawError('Raw message size changed between reads.', scan.offset, scan.line);
+  }
+};
+
+const RAW_WINDOW_BYTES = 32768;
+// Bytes after which the traversal lets the event loop run.
+const RAW_YIELD_BYTES = 1024 * 1024;
+
+const rawError = (message, offset, line, field = 'content') =>
+  new RawMessageValidationError(message, field, offset, line);
+
+/**
+ * Checks the bytes of one window against the wire rules and the declared
+ * encoding, carrying the position over from the window before.  The state is
+ * read into locals and written back once, so that the loop over each byte
+ * touches no object.
+ *
+ * @param scan The position and what has been seen so far, updated in place.
+ * @param window The bytes to check.
+ * @param encoding The declared encoding, if any.
+ * @throws {RawMessageValidationError} If a byte breaks a rule.
+ */
+const scanRawWindow = (scan, window, encoding) => {
+  let { offset, line, column, pendingCr, headers, nonAscii } = scan;
+  // An index loop: the iterator protocol of for...of costs more than the
+  // checks on each byte.
+  for (let index = 0; index < window.length; index++) {
+    const byte = window[index];
+    if (pendingCr) {
+      if (byte !== 10) throw rawError('Expected LF after CR.', offset, line);
+      if (line === 1 && column === 0) {
+        throw rawError('Raw message headers must not be empty.', offset, line);
+      }
+      if (column === 0) headers = false;
+      pendingCr = false;
+      column = 0;
+      line++;
+    } else if (byte === 13) {
+      pendingCr = true;
+    } else if (byte === 10) {
+      throw rawError('Raw messages must use CRLF line endings.', offset, line);
+    } else {
+      if (byte === 0) throw rawError('Raw messages must not contain NUL.', offset, line);
+      if (++column > 998) {
+        throw rawError('Raw message lines must not exceed 998 octets.', offset, line);
+      }
+      if (byte > 127) {
+        nonAscii = true;
+        if (encoding === '7bit' || (encoding === '8bit' && headers)) {
+          throw rawError(
+            'Raw message bytes exceed the declared encoding.',
+            offset,
+            line,
+            'encoding',
+          );
+        }
+      }
+    }
+    offset++;
   }
+  scan.offset = offset;
+  scan.line = line;
+  scan.column = column;
+  scan.pendingCr = pendingCr;
+  scan.headers = headers;
+  scan.nonAscii = nonAscii;
 };
 
 /**
diff --git a/src/core/receipt.js b/src/core/receipt.js
index ac2567d..3dfdc72 100644
--- a/src/core/receipt.js
+++ b/src/core/receipt.js
@@ -47,14 +47,73 @@ const NETWORK_CODES = new Set([
   'UND_ERR_SOCKET',
 ]);
 
-// Status codes in a message count as whole numbers only: "4013 octets" holds
-// no 401, nor "5000 ms" a 500.
-const hasNumber = (text, pattern) => pattern.test(text);
-const AUTH_STATUS = /\b(?:401|403)\b/;
-const RATE_LIMIT_STATUS = /\b429\b/;
-const VALIDATION_STATUS = /\b(?:400|422)\b/;
-const UNAVAILABLE_STATUS = /\b503\b/;
-const SERVER_ERROR_STATUS = /\b(?:500|502)\b/;
+// The categories the words of a message point to, tried in this order: a
+// message that names both a timeout and a host is a timeout.  Status codes in
+// a message count as whole numbers only: "4013 octets" holds no 401, nor
+// "5000 ms" a 500.
+const WORD_RULES = [
+  { category: 'timeout', retryable: true, words: ['timeout', 'timed out'] },
+  {
+    category: 'network',
+    retryable: true,
+    words: ['network', 'connect', 'fetch failed', 'dns', 'econnreset', 'econnrefused', 'enotfound'],
+    name: 'NetworkError',
+  },
+  {
+    category: 'auth',
+    retryable: false,
+    words: [
+      'authentication',
+      'authenticate',
+      'authorization',
+      'authorize',
+      'unauthorized',
+      'not authorized',
+      'forbidden',
+      'invalid api key',
+      'invalid token',
+    ],
+    pattern: /\bauth\b|\b(?:401|403)\b/,
+  },
+  {
+    category: 'rate-limit',
+    retryable: true,
+    words: ['rate limit', 'rate-limit', 'too many requests', 'quota', 'throttle'],
+    pattern: /\b429\b/,
+  },
+  {
+    category: 'validation',
+    retryable: false,
+    words: ['invalid', 'malformed', 'validation', 'bad request'],
+    pattern: /\b(?:400|422)\b/,
+  },
+  {
+    category: 'rejected',
+    retryable: false,
+    words: ['rejected', 'bounce', 'complaint', 'suppressed', 'unsubscribed'],
+  },
+  {
+    category: 'service-unavailable',
+    retryable: true,
+    words: ['service unavailable', 'temporarily unavailable'],
+    pattern: /\b503\b/,
+  },
+  {
+    category: 'server-error',
+    retryable: true,
+    words: ['internal server error', 'bad gateway'],
+    pattern: /\b(?:500|502)\b/,
+  },
+  { category: 'configuration', retryable: false, words: ['config', 'unsupported'] },
+];
+
+const matchesWordRule = (rule, text, name) => {
+  for (const word of rule.words) {
+    if (text.includes(word)) return true;
+  }
+  if (rule.pattern !== undefined && rule.pattern.test(text)) return true;
+  return rule.name !== undefined && rule.name === name;
+};
 
 // The first `code` along the chain of causes, as `fetch failed` keeps the
 // socket error behind it.
@@ -94,97 +153,10 @@ const classifyReceiptError = (error) => {
   const message = getStringProperty(error, 'message') ?? String(error);
   const name = getStringProperty(error, 'name') ?? '';
   const text = `${name} ${message}`.toLowerCase();
-
-  if (text.includes('timeout') || text.includes('timed out')) {
-    return { category: 'timeout', retryable: true, code: 'timeout' };
-  }
-  if (
-    text.includes('network') ||
-    text.includes('connect') ||
-    text.includes('fetch failed') ||
-    text.includes('dns') ||
-    text.includes('econnreset') ||
-    text.includes('econnrefused') ||
-    text.includes('enotfound') ||
-    name === 'NetworkError'
-  ) {
-    return { category: 'network', retryable: true, code: 'network' };
-  }
-  if (
-    text.includes('authentication') ||
-    text.includes('authenticate') ||
-    text.includes('authorization') ||
-    text.includes('authorize') ||
-    /\bauth\b/.test(text) ||
-    text.includes('unauthorized') ||
-    text.includes('not authorized') ||
-    text.includes('forbidden') ||
-    text.includes('invalid api key') ||
-    text.includes('invalid token') ||
-    hasNumber(text, AUTH_STATUS)
-  ) {
-    return { category: 'auth', retryable: false, code: 'auth' };
-  }
-  if (
-    text.includes('rate limit') ||
-    text.includes('rate-limit') ||
-    text.includes('too many requests') ||
-    text.includes('quota') ||
-    text.includes('throttle') ||
-    hasNumber(text, RATE_LIMIT_STATUS)
-  ) {
-    return {
-      category: 'rate-limit',
-      retryable: true,
-      code: 'rate-limit',
-    };
-  }
-  if (
-    text.includes('invalid') ||
-    text.includes('malformed') ||
-    text.includes('validation') ||
-    text.includes('bad request') ||
-    hasNumber(text, VALIDATION_STATUS)
-  ) {
-    return { category: 'validation', retryable: false, code: 'validation' };
-  }
-  if (
-    text.includes('rejected') ||
-    text.includes('bounce') ||
-    text.includes('complaint') ||
-    text.includes('suppressed') ||
-    text.includes('unsubscribed')
-  ) {
-    return { category: 'rejected', retryable: false, code: 'rejected' };
-  }
-  if (
-    text.includes('service unavailable') ||
-    text.includes('temporarily unavailable') ||
-    hasNumber(text, UNAVAILABLE_STATUS)
-  ) {
-    return {
-      category: 'service-unavailable',
-      retryable: true,
-      code: 'service-unavailable',
-    };
-  }
-  if (
-    text.includes('internal server error') ||
-    text.includes('bad gateway') ||
-    hasNumber(text, SERVER_ERROR_STATUS)
-  ) {
-    return {
-      category: 'server-error',
-      retryable: true,
-      code: 'server-error',
-    };
-  }
-  if (text.includes('config') || text.includes('unsupported')) {
-    return {
-      category: 'configuration',
-      retryable: false,
-      code: 'configuration',
-    };
+  for (const rule of WORD_RULES) {
+    if (matchesWordRule(rule, text, name)) {
+      return { category: rule.category, retryable: rule.retryable, code: rule.category };
+    }
   }
   return { category: 'unknown', retryable: false, code: 'unknown' };
 };
@@ -203,13 +175,12 @@ const createReceiptError = (message, options = {}) => {
       : classifyHttpStatus(options.statusCode);
   const category = options.category ?? classification.category;
   const retryable = options.retryable ?? classification.retryable;
-  const code =
-    options.code ??
-    (options.statusCode == null
-      ? options.category != null
-        ? category
-        : (classification.code ?? category)
-      : `http.${options.statusCode}`);
+  let code = options.code;
+  if (code == null) {
+    if (options.statusCode != null) code = `http.${options.statusCode}`;
+    else if (options.category != null) code = category;
+    else code = classification.code ?? category;
+  }
 
   return omitUndefined({
     message,
@@ -223,6 +194,42 @@ const createReceiptError = (message, options = {}) => {
   });
 };
 
+/**
+ * Gives the structured errors of a failure and its messages, in one pass over
+ * a list that mixes strings and structured errors.
+ *
+ * @param error A message, a structured error, or a list of either.
+ * @param given Structured errors given in place of those of `error`.
+ * @param errorOptions The options of the errors made from strings.
+ * @returns The structured errors and the messages.
+ */
+const describeFailure = (error, given, errorOptions) => {
+  if (typeof error === 'string') {
+    return { errors: given ?? [createReceiptError(error, errorOptions)], errorMessages: [error] };
+  }
+  if (!Array.isArray(error)) {
+    const errors = given ?? [error];
+    const errorMessages = [];
+    for (const receiptError of errors) errorMessages.push(receiptError.message);
+    return { errors, errorMessages };
+  }
+  const built = [];
+  const errorMessages = [];
+  for (const item of error) {
+    const isText = typeof item === 'string';
+    errorMessages.push(isText ? item : item.message);
+    if (given == null) built.push(isText ? createReceiptError(item, errorOptions) : item);
+  }
+  return { errors: given ?? built, errorMessages };
+};
+
+const isAnyRetryable = (errors) => {
+  for (const receiptError of errors) {
+    if (receiptError.retryable) return true;
+  }
+  return false;
+};
+
 /**
  * Creates a failed receipt with human-readable and structured errors.
  *
@@ -236,25 +243,9 @@ const createFailedReceipt = (error, options = {}) => {
   // it are retryable, whatever their classification says.
   const deliveryUnknown = options.deliveryUnknown === true ? true : undefined;
   const errorOptions = deliveryUnknown === true ? { ...options, retryable: false } : options;
-  const errors =
-    options.errors ??
-    (typeof error === 'string'
-      ? [createReceiptError(error, errorOptions)]
-      : Array.isArray(error)
-        ? error.map((item) =>
-            typeof item === 'string' ? createReceiptError(item, errorOptions) : item,
-          )
-        : [error]);
-  const errorMessages =
-    typeof error === 'string'
-      ? [error]
-      : Array.isArray(error)
-        ? error.map((item) => (typeof item === 'string' ? item : item.message))
-        : errors.map((receiptError) => receiptError.message);
+  const { errors, errorMessages } = describeFailure(error, options.errors, errorOptions);
   const retryable =
-    deliveryUnknown === true
-      ? false
-      : (options.retryable ?? errors.some((receiptError) => receiptError.retryable));
+    deliveryUnknown === true ? false : (options.retryable ?? isAnyRetryable(errors));
   const provider = options.provider ?? errors[0]?.provider;
 
   return omitUndefined({

From bf41c53fa289dcc55d5d63ef43240c073195e388 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:21:49 +0300
Subject: [PATCH 129/158] refactor(mime): split buildMimeParts and move
 whole-body DKIM out of src

buildMimeParts was 161 lines; the header fields, a single part, the
alternatives and an attachment are written by functions of their own,
the composed and priority names are module-level sets, and address lists
are joined in one loop. signMessage, computeBodyHash and the body
canonicalizers over a whole string were used by tests only, since the
library hashes a body as it streams (BodyHasher); they are the test
reference in tests/helpers/mime/dkim-reference.js. The bytes of a
signature go to base64 through Buffer. Behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mime/dkim/canonicalize.js             |  93 +-------
 src/mime/dkim/sign.js                     |  87 +-------
 src/mime/message.js                       | 250 +++++++++++-----------
 tests/helpers/mime/dkim-reference.js      | 118 ++++++++++
 tests/unit/mime-dkim-body-hash.test.js    |   4 +-
 tests/unit/mime-dkim-canonicalize.test.js |   8 +-
 tests/unit/mime-dkim-sign.test.js         |   4 +-
 tests/unit/mime-dkim.test.js              |   2 +-
 tests/unit/smtp-message-stream.test.js    |   4 +-
 9 files changed, 270 insertions(+), 300 deletions(-)
 create mode 100644 tests/helpers/mime/dkim-reference.js

diff --git a/src/mime/dkim/canonicalize.js b/src/mime/dkim/canonicalize.js
index c9ce930..14667f3 100644
--- a/src/mime/dkim/canonicalize.js
+++ b/src/mime/dkim/canonicalize.js
@@ -51,95 +51,4 @@ const canonicalizeHeaderRelaxed = (name, value) => {
   return `${canonicalName}:${canonicalValue}`;
 };
 
-/**
- * Simple body canonicalization.
- *
- * The "simple" body canonicalization algorithm:
- * - Ignores all empty lines at the end of the message body
- * - If the body is empty, a single CRLF is appended
- * - If there is no trailing CRLF on the body, a CRLF is added
- *
- * @param body - The message body
- * @returns The canonicalized body
- * @see RFC 6376 Section 3.4.3
- */
-const canonicalizeBodySimple = (body) => {
-  if (body === '') {
-    return '\r\n';
-  }
-
-  // Remove trailing empty lines (lines containing only CRLF)
-  let result = body.replace(/(\r\n)+$/, '');
-
-  // Ensure the body ends with a single CRLF
-  if (!result.endsWith('\r\n')) {
-    result += '\r\n';
-  }
-
-  return result;
-};
-
-/**
- * Relaxed body canonicalization.
- *
- * The "relaxed" body canonicalization algorithm:
- * - Reduce all sequences of WSP within a line to a single SP
- * - Remove all trailing WSP at the end of each line (before CRLF)
- * - Ignore all empty lines at the end of the message body
- * - If the body is non-empty and doesn't end with CRLF, add CRLF
- *
- * @param body - The message body
- * @returns The canonicalized body
- * @see RFC 6376 Section 3.4.4
- */
-const canonicalizeBodyRelaxed = (body) => {
-  if (body === '') {
-    return '';
-  }
-
-  // Ensure body ends with CRLF for processing
-  let processedBody = body;
-  if (!processedBody.endsWith('\r\n')) {
-    processedBody += '\r\n';
-  }
-
-  // Process each line
-  const lines = processedBody.split('\r\n');
-  const canonicalizedLines = [];
-
-  for (let i = 0; i < lines.length - 1; i++) {
-    // -1 because split creates an empty element after final CRLF
-    let line = lines[i];
-
-    // Collapse WSP sequences to single space
-    line = line.replace(/[\t ]+/g, ' ');
-
-    // Remove trailing WSP
-    line = line.replace(/[\t ]+$/, '');
-
-    canonicalizedLines.push(line);
-  }
-
-  // Remove trailing empty lines
-  while (
-    canonicalizedLines.length > 0 &&
-    canonicalizedLines[canonicalizedLines.length - 1] === ''
-  ) {
-    canonicalizedLines.pop();
-  }
-
-  // If no content remains, return empty string
-  if (canonicalizedLines.length === 0) {
-    return '';
-  }
-
-  // Join with CRLF and add final CRLF
-  return canonicalizedLines.join('\r\n') + '\r\n';
-};
-
-module.exports = {
-  canonicalizeHeaderSimple,
-  canonicalizeHeaderRelaxed,
-  canonicalizeBodySimple,
-  canonicalizeBodyRelaxed,
-};
+module.exports = { canonicalizeHeaderSimple, canonicalizeHeaderRelaxed };
diff --git a/src/mime/dkim/sign.js b/src/mime/dkim/sign.js
index ca5e86b..af73071 100644
--- a/src/mime/dkim/sign.js
+++ b/src/mime/dkim/sign.js
@@ -9,38 +9,15 @@
  * @see https://www.rfc-editor.org/rfc/rfc6376
  */
 
+const { Buffer } = require('node:buffer');
 const { createPrivateKey } = require('node:crypto');
-const {
-  canonicalizeBodyRelaxed,
-  canonicalizeBodySimple,
-  canonicalizeHeaderRelaxed,
-  canonicalizeHeaderSimple,
-} = require('./canonicalize.js');
+const { canonicalizeHeaderRelaxed, canonicalizeHeaderSimple } = require('./canonicalize.js');
 const {
   DEFAULT_ALGORITHM,
   DEFAULT_CANONICALIZATION,
   DEFAULT_SIGNED_HEADERS,
 } = require('./types.js');
 
-/**
- * Signs a raw email message with DKIM.
- *
- * @param rawMessage - The complete raw email message (headers + body)
- * @param config - DKIM signature configuration
- * @param signal Optional cancellation signal.
- * @returns The DKIM-Signature header result
- * @throws Error if signing fails (e.g., invalid private key)
- */
-const signMessage = async (rawMessage, config, signal) => {
-  signal?.throwIfAborted();
-  const { body } = parseMessage(rawMessage);
-  const bodyCanon = (config.canonicalization ?? DEFAULT_CANONICALIZATION).endsWith('/simple')
-    ? 'simple'
-    : 'relaxed';
-  const bodyHash = await computeBodyHash(body, bodyCanon);
-  return await signWithBodyHash(rawMessage, config, bodyHash, signal);
-};
-
 /**
  * Signs frozen headers using a body hash computed by the MIME reader.
  * @param rawHeaders Frozen wire headers, including earlier signatures.
@@ -56,8 +33,7 @@ const signWithBodyHash = async (rawHeaders, config, bodyHash, signal) => {
   const canonicalization = config.canonicalization ?? DEFAULT_CANONICALIZATION;
   const headerFields = config.headerFields ?? DEFAULT_SIGNED_HEADERS;
 
-  // Parse the raw message into headers and body
-  const { headers } = parseMessage(rawHeaders);
+  const headers = parseHeaders(headerSectionOf(rawHeaders));
 
   // Determine canonicalization methods
   const [headerCanon] = canonicalization.split('/');
@@ -90,27 +66,11 @@ const signWithBodyHash = async (rawHeaders, config, bodyHash, signal) => {
   };
 };
 
-/**
- * Parses a raw email message into headers and body.
- */
-const parseMessage = (rawMessage) => {
-  // Find the separator between headers and body (empty line)
-  const separatorIndex = rawMessage.indexOf('\r\n\r\n');
-  if (separatorIndex === -1) {
-    // No body, all headers
-    return {
-      headers: parseHeaders(rawMessage),
-      body: '',
-    };
-  }
-
-  const headerSection = rawMessage.substring(0, separatorIndex);
-  const body = rawMessage.substring(separatorIndex + 4); // Skip \r\n\r\n
-
-  return {
-    headers: parseHeaders(headerSection),
-    body,
-  };
+// The header section of a message, or the whole of a header block without
+// the empty line that ends it.
+const headerSectionOf = (raw) => {
+  const end = raw.indexOf('\r\n\r\n');
+  return end === -1 ? raw : raw.substring(0, end);
 };
 
 /**
@@ -244,23 +204,6 @@ const importPrivateKey = async (pem, algorithm) => {
   }
 };
 
-/**
- * Computes the body hash (bh= tag value).
- */
-const computeBodyHash = async (body, canonMethod) => {
-  // Canonicalize the body
-  const canonicalBody =
-    canonMethod === 'relaxed' ? canonicalizeBodyRelaxed(body) : canonicalizeBodySimple(body);
-
-  // Hash with SHA-256
-  const encoder = new TextEncoder();
-  const data = encoder.encode(canonicalBody);
-  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-
-  // Base64 encode
-  return arrayBufferToBase64(hashBuffer);
-};
-
 /**
  * Builds the DKIM-Signature header value without the b= signature.
  */
@@ -336,16 +279,6 @@ const signData = async (data, privateKey, algorithm) => {
   return arrayBufferToBase64(signature);
 };
 
-/**
- * Converts an ArrayBuffer to a Base64 string.
- */
-const arrayBufferToBase64 = (buffer) => {
-  const bytes = new Uint8Array(buffer);
-  let binary = '';
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]);
-  }
-  return btoa(binary);
-};
+const arrayBufferToBase64 = (buffer) => Buffer.from(buffer).toString('base64');
 
-module.exports = { checkDkimKeys, resolvePrivateKey, signMessage, signWithBodyHash };
+module.exports = { checkDkimKeys, resolvePrivateKey, signWithBodyHash };
diff --git a/src/mime/message.js b/src/mime/message.js
index 6231f6f..d75df61 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -39,15 +39,7 @@ const prepareMimeMessage = (message, dkimConfig, options = {}) => {
   const dkim =
     dkimConfig == null
       ? undefined
-      : {
-          ...dkimConfig,
-          signatures: dkimConfig.signatures.map((signature) => ({
-            ...signature,
-            // Imported once per signature configuration of the caller.
-            privateKey: resolvePrivateKey(signature),
-            headerFields: signature.headerFields == null ? undefined : [...signature.headerFields],
-          })),
-        };
+      : { ...dkimConfig, signatures: resolveSignatures(dkimConfig.signatures) };
   const parts = buildMimeParts(message, options.generateId);
   const first = parts[0];
   if (typeof first !== 'string') throw new TypeError('Missing MIME headers.');
@@ -103,25 +95,72 @@ const prepareMimeMessage = (message, dkimConfig, options = {}) => {
   };
 };
 
+// The signatures of a DKIM configuration with their keys imported, once per
+// signature configuration of the caller, and their field lists copied.
+const resolveSignatures = (signatures) => {
+  const resolved = [];
+  for (const signature of signatures) {
+    resolved.push({
+      ...signature,
+      privateKey: resolvePrivateKey(signature),
+      headerFields: signature.headerFields == null ? undefined : [...signature.headerFields],
+    });
+  }
+  return resolved;
+};
+
+// Names written by pushHeaderFields, plus Cc and Reply-To even when the
+// message carries no such recipients: a custom header there would list
+// addresses the envelope never receives.  The identity and threading names are
+// here unconditionally too, even when nothing was written: each of them has had
+// its one chance to be emitted, from the typed field or from the very custom
+// header that would otherwise be written again.
+const COMPOSED_HEADERS = new Set([
+  'from',
+  'to',
+  'cc',
+  'reply-to',
+  'subject',
+  'date',
+  'message-id',
+  'in-reply-to',
+  'references',
+]);
+const PRIORITY_HEADERS = new Set(['x-priority', 'x-msmail-priority']);
+const THREADING_FIELDS = ['In-Reply-To', 'References'];
+
 const buildMimeParts = (message, generateId) => {
   const lines = [];
-  const boundary = generateBoundary();
-  const hasAttachments = message.attachments.length > 0;
   const alternatives = buildAlternatives(message);
-  const isMultipart = hasAttachments || alternatives.length > 1;
+  pushHeaderFields(lines, message, generateId);
+  lines.push('MIME-Version: 1.0');
+  if (message.attachments.length > 0 || alternatives.length > 1) {
+    const boundary = generateBoundary();
+    lines.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
+    lines.push('');
+    lines.push('This is a multi-part message in MIME format.');
+    lines.push('');
+    lines.push(`--${boundary}`);
+    if (alternatives.length > 1) pushAlternatives(lines, alternatives);
+    else pushSinglePart(lines, alternatives[0]);
+    for (const attachment of message.attachments) pushAttachment(lines, attachment, boundary);
+    lines.push('');
+    lines.push(`--${boundary}--`);
+  } else {
+    pushSinglePart(lines, alternatives[0]);
+  }
+  return joinLines(lines);
+};
 
-  // Standard headers
+const pushHeaderFields = (lines, message, generateId) => {
   lines.push(foldHeader('From', encodeAddress(message.sender)));
-  lines.push(foldHeader('To', message.recipients.map(encodeAddress).join(', ')));
-
+  lines.push(foldHeader('To', encodeAddressList(message.recipients)));
   if (message.ccRecipients.length > 0) {
-    lines.push(foldHeader('Cc', message.ccRecipients.map(encodeAddress).join(', ')));
+    lines.push(foldHeader('Cc', encodeAddressList(message.ccRecipients)));
   }
-
   if (message.replyRecipients.length > 0) {
-    lines.push(foldHeader('Reply-To', message.replyRecipients.map(encodeAddress).join(', ')));
+    lines.push(foldHeader('Reply-To', encodeAddressList(message.replyRecipients)));
   }
-
   lines.push(foldHeader('Subject', encodeHeaderValue(message.subject, true)));
 
   // The identity and threading fields all carry structured values, so they are
@@ -129,7 +168,7 @@ const buildMimeParts = (message, generateId) => {
   lines.push(foldHeader('Date', resolveDate(message)));
   lines.push(foldHeader('Message-ID', resolveMessageId(message, generateId)));
   const threading = resolveThreadingHeaders(message);
-  for (const name of ['In-Reply-To', 'References']) {
+  for (const name of THREADING_FIELDS) {
     // A field the message does not own falls back to a custom header, one it
     // owns but left empty writes nothing at all.
     const owned = threading.get(name);
@@ -137,120 +176,76 @@ const buildMimeParts = (message, generateId) => {
     if (value != null) lines.push(foldHeader(name, value));
   }
 
-  // Names already written above, plus Cc and Reply-To even when the message
-  // carries no such recipients: a custom header there would list addresses the
-  // envelope never receives.  The identity and threading names are here
-  // unconditionally too, even when nothing was written: each of them has had
-  // its one chance to be emitted above, from the typed field or from the very
-  // custom header this loop would otherwise write again.
-  const composed = new Set([
-    'from',
-    'to',
-    'cc',
-    'reply-to',
-    'subject',
-    'date',
-    'message-id',
-    'in-reply-to',
-    'references',
-  ]);
-
-  // Priority header
-  if (message.priority !== 'normal') {
-    const priorityValue = message.priority === 'high' ? '1' : '5';
-    lines.push(`X-Priority: ${priorityValue}`);
-    lines.push(`X-MSMail-Priority: ${message.priority === 'high' ? 'High' : 'Low'}`);
-    composed.add('x-priority');
-    composed.add('x-msmail-priority');
-  }
-
-  // Custom headers
+  const hasPriority = message.priority !== 'normal';
+  if (hasPriority) {
+    const high = message.priority === 'high';
+    lines.push(`X-Priority: ${high ? '1' : '5'}`);
+    lines.push(`X-MSMail-Priority: ${high ? 'High' : 'Low'}`);
+  }
+
   for (const [key, value] of message.headers) {
     const name = key.toLowerCase();
-    if (composed.has(name) || reservedHeaders.has(name)) continue;
+    if (COMPOSED_HEADERS.has(name) || reservedHeaders.has(name)) continue;
+    if (hasPriority && PRIORITY_HEADERS.has(name)) continue;
     lines.push(foldHeader(key, encodeHeaderValue(value)));
   }
+};
 
-  // MIME headers
-  lines.push('MIME-Version: 1.0');
+const encodeAddressList = (addresses) => {
+  let list = '';
+  for (let i = 0; i < addresses.length; i++) {
+    list += i === 0 ? encodeAddress(addresses[i]) : `, ${encodeAddress(addresses[i])}`;
+  }
+  return list;
+};
 
-  if (isMultipart) {
-    lines.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
-    lines.push('');
-    lines.push('This is a multi-part message in MIME format.');
-    lines.push('');
+const pushSinglePart = (lines, alternative) => {
+  lines.push(`Content-Type: ${alternative.contentType}`);
+  lines.push(`Content-Transfer-Encoding: ${alternative.encoding}`);
+  lines.push('');
+  lines.push(alternative.body);
+};
 
-    // Content part
+const pushAlternatives = (lines, alternatives) => {
+  const boundary = generateBoundary();
+  lines.push(`Content-Type: multipart/alternative; boundary="${boundary}"`);
+  lines.push('');
+  for (const alternative of alternatives) {
     lines.push(`--${boundary}`);
-
-    if (alternatives.length > 1) {
-      const contentBoundary = generateBoundary();
-      lines.push(`Content-Type: multipart/alternative; boundary="${contentBoundary}"`);
-      lines.push('');
-
-      for (const alternative of alternatives) {
-        lines.push(`--${contentBoundary}`);
-        lines.push(`Content-Type: ${alternative.contentType}`);
-        lines.push(`Content-Transfer-Encoding: ${alternative.encoding}`);
-        lines.push('');
-        lines.push(alternative.body);
-        lines.push('');
-      }
-
-      lines.push(`--${contentBoundary}--`);
-    } else {
-      lines.push(`Content-Type: ${alternatives[0].contentType}`);
-      lines.push(`Content-Transfer-Encoding: ${alternatives[0].encoding}`);
-      lines.push('');
-      lines.push(alternatives[0].body);
-    }
-
-    // Attachments.  A message is structural input, not only one built by
-    // createMessage(), so the fields written into part headers as given are
-    // checked again here, as the addresses and the custom headers are.
-    for (const attachment of message.attachments) {
-      checkAttachment(attachment);
-      lines.push('');
-      lines.push(`--${boundary}`);
-      lines.push(
-        foldHeader(
-          'Content-Type',
-          `${attachment.contentType}; ${encodeMimeParameter('name', attachment.filename)}`,
-        ),
-      );
-      lines.push('Content-Transfer-Encoding: base64');
-
-      if (attachment.inline) {
-        lines.push(
-          foldHeader(
-            'Content-Disposition',
-            `inline; ${encodeMimeParameter('filename', attachment.filename)}`,
-          ),
-        );
-        lines.push(foldHeader('Content-ID', `<${attachment.contentId}>`));
-      } else {
-        lines.push(
-          foldHeader(
-            'Content-Disposition',
-            `attachment; ${encodeMimeParameter('filename', attachment.filename)}`,
-          ),
-        );
-      }
-
-      lines.push('');
-      lines.push({ content: attachment.content });
-    }
-
+    pushSinglePart(lines, alternative);
     lines.push('');
-    lines.push(`--${boundary}--`);
-  } else {
-    // Single part message
-    lines.push(`Content-Type: ${alternatives[0].contentType}`);
-    lines.push(`Content-Transfer-Encoding: ${alternatives[0].encoding}`);
-    lines.push('');
-    lines.push(alternatives[0].body);
   }
+  lines.push(`--${boundary}--`);
+};
 
+// A message is structural input, not only one built by createMessage(), so the
+// fields written into part headers as given are checked again here, as the
+// addresses and the custom headers are.
+const pushAttachment = (lines, attachment, boundary) => {
+  checkAttachment(attachment);
+  lines.push('');
+  lines.push(`--${boundary}`);
+  lines.push(
+    foldHeader(
+      'Content-Type',
+      `${attachment.contentType}; ${encodeMimeParameter('name', attachment.filename)}`,
+    ),
+  );
+  lines.push('Content-Transfer-Encoding: base64');
+  const disposition = attachment.inline ? 'inline' : 'attachment';
+  lines.push(
+    foldHeader(
+      'Content-Disposition',
+      `${disposition}; ${encodeMimeParameter('filename', attachment.filename)}`,
+    ),
+  );
+  if (attachment.inline) lines.push(foldHeader('Content-ID', `<${attachment.contentId}>`));
+  lines.push('');
+  lines.push({ content: attachment.content });
+};
+
+// The lines as text, each ended by CRLF, split around the attachment contents.
+const joinLines = (lines) => {
   const parts = [];
   let text = '';
   for (const line of lines) {
@@ -540,8 +535,7 @@ const encodeHeaderValue = (value, encodeLongAsciiWords = false) => {
   for (let i = 0; i < value.length;) {
     const codePoint = value.codePointAt(i);
     const characterLength = codePoint > 0xffff ? 2 : 1;
-    const characterBytes =
-      codePoint < 0x80 ? 1 : codePoint < 0x800 ? 2 : codePoint < 0x10000 ? 3 : 4;
+    const characterBytes = utf8Length(codePoint);
     if (wordBytes + characterBytes > MAX_ENCODED_WORD_BYTES) {
       words.push(encodeWord(value.slice(wordStart, i)));
       wordStart = i;
@@ -554,6 +548,12 @@ const encodeHeaderValue = (value, encodeLongAsciiWords = false) => {
   return words.join(' ');
 };
 
+const utf8Length = (codePoint) => {
+  if (codePoint < 0x80) return 1;
+  if (codePoint < 0x800) return 2;
+  return codePoint < 0x10000 ? 3 : 4;
+};
+
 // Each byte as an RFC 2231 extended value carries it: an attribute-char as it
 // is, any other byte percent-encoded.
 const EXTENDED_VALUE_BYTES = [];
diff --git a/tests/helpers/mime/dkim-reference.js b/tests/helpers/mime/dkim-reference.js
new file mode 100644
index 0000000..593aae1
--- /dev/null
+++ b/tests/helpers/mime/dkim-reference.js
@@ -0,0 +1,118 @@
+// Ported from upyo v0.7.0 (packages/mime/src/dkim/canonicalize.ts and sign.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+//
+// The body canonicalization of RFC 6376 over a whole string, and signing of a
+// whole message with it.  The library hashes a body as it streams
+// (BodyHasher), so these left src/ after the port; the tests keep them as the
+// reference the streaming hash and the signatures are checked against.
+
+const { createHash } = require('node:crypto');
+const { signWithBodyHash } = require('../../../src/mime/dkim/sign.js');
+const { DEFAULT_CANONICALIZATION } = require('../../../src/mime/dkim/types.js');
+
+/**
+ * Simple body canonicalization.
+ *
+ * The "simple" body canonicalization algorithm:
+ * - Ignores all empty lines at the end of the message body
+ * - If the body is empty, a single CRLF is appended
+ * - If there is no trailing CRLF on the body, a CRLF is added
+ *
+ * @param body - The message body
+ * @returns The canonicalized body
+ * @see RFC 6376 Section 3.4.3
+ */
+const canonicalizeBodySimple = (body) => {
+  if (body === '') {
+    return '\r\n';
+  }
+
+  // Remove trailing empty lines (lines containing only CRLF)
+  let result = body.replace(/(\r\n)+$/, '');
+
+  // Ensure the body ends with a single CRLF
+  if (!result.endsWith('\r\n')) {
+    result += '\r\n';
+  }
+
+  return result;
+};
+
+/**
+ * Relaxed body canonicalization.
+ *
+ * The "relaxed" body canonicalization algorithm:
+ * - Reduce all sequences of WSP within a line to a single SP
+ * - Remove all trailing WSP at the end of each line (before CRLF)
+ * - Ignore all empty lines at the end of the message body
+ * - If the body is non-empty and doesn't end with CRLF, add CRLF
+ *
+ * @param body - The message body
+ * @returns The canonicalized body
+ * @see RFC 6376 Section 3.4.4
+ */
+const canonicalizeBodyRelaxed = (body) => {
+  if (body === '') {
+    return '';
+  }
+
+  // Ensure body ends with CRLF for processing
+  let processedBody = body;
+  if (!processedBody.endsWith('\r\n')) {
+    processedBody += '\r\n';
+  }
+
+  // Process each line
+  const lines = processedBody.split('\r\n');
+  const canonicalizedLines = [];
+
+  for (let i = 0; i < lines.length - 1; i++) {
+    // -1 because split creates an empty element after final CRLF
+    let line = lines[i];
+
+    // Collapse WSP sequences to single space
+    line = line.replace(/[\t ]+/g, ' ');
+
+    // Remove trailing WSP
+    line = line.replace(/[\t ]+$/, '');
+
+    canonicalizedLines.push(line);
+  }
+
+  // Remove trailing empty lines
+  while (
+    canonicalizedLines.length > 0 &&
+    canonicalizedLines[canonicalizedLines.length - 1] === ''
+  ) {
+    canonicalizedLines.pop();
+  }
+
+  // If no content remains, return empty string
+  if (canonicalizedLines.length === 0) {
+    return '';
+  }
+
+  // Join with CRLF and add final CRLF
+  return canonicalizedLines.join('\r\n') + '\r\n';
+};
+
+/**
+ * Signs a raw email message with DKIM, hashing its body as a whole.
+ *
+ * @param rawMessage The complete raw email message (headers + body).
+ * @param config DKIM signature configuration.
+ * @param signal Optional cancellation signal.
+ * @returns The DKIM-Signature header result.
+ */
+const signMessage = async (rawMessage, config, signal) => {
+  signal?.throwIfAborted();
+  const separator = rawMessage.indexOf('\r\n\r\n');
+  const body = separator === -1 ? '' : rawMessage.substring(separator + 4);
+  const canonical = (config.canonicalization ?? DEFAULT_CANONICALIZATION).endsWith('/simple')
+    ? canonicalizeBodySimple(body)
+    : canonicalizeBodyRelaxed(body);
+  const bodyHash = createHash('sha256').update(canonical).digest('base64');
+  return await signWithBodyHash(rawMessage, config, bodyHash, signal);
+};
+
+module.exports = { canonicalizeBodyRelaxed, canonicalizeBodySimple, signMessage };
diff --git a/tests/unit/mime-dkim-body-hash.test.js b/tests/unit/mime-dkim-body-hash.test.js
index 351577a..2fa2e1d 100644
--- a/tests/unit/mime-dkim-body-hash.test.js
+++ b/tests/unit/mime-dkim-body-hash.test.js
@@ -5,10 +5,12 @@ const assert = require('node:assert/strict');
 const { test } = require('node:test');
 const { createHash } = require('node:crypto');
 const { BodyHasher } = require('../../src/mime/dkim/body-hash.js');
+// Changed after the port: the body canonicalization and signMessage, which src/
+// no longer uses (it hashes a body as it streams), are test references now.
 const {
   canonicalizeBodyRelaxed,
   canonicalizeBodySimple,
-} = require('../../src/mime/dkim/canonicalize.js');
+} = require('../helpers/mime/dkim-reference.js');
 
 test('incremental body hashes match canonicalization at every split', () => {
   const bodies = [
diff --git a/tests/unit/mime-dkim-canonicalize.test.js b/tests/unit/mime-dkim-canonicalize.test.js
index 945c79f..a5ba35a 100644
--- a/tests/unit/mime-dkim-canonicalize.test.js
+++ b/tests/unit/mime-dkim-canonicalize.test.js
@@ -3,12 +3,16 @@
 
 const assert = require('node:assert/strict');
 const { describe, it } = require('node:test');
+// Changed after the port: the body canonicalization and signMessage, which src/
+// no longer uses (it hashes a body as it streams), are test references now.
 const {
-  canonicalizeBodyRelaxed,
-  canonicalizeBodySimple,
   canonicalizeHeaderRelaxed,
   canonicalizeHeaderSimple,
 } = require('../../src/mime/dkim/canonicalize.js');
+const {
+  canonicalizeBodyRelaxed,
+  canonicalizeBodySimple,
+} = require('../helpers/mime/dkim-reference.js');
 
 describe('DKIM Canonicalization', () => {
   describe('canonicalizeHeaderSimple', () => {
diff --git a/tests/unit/mime-dkim-sign.test.js b/tests/unit/mime-dkim-sign.test.js
index b5e05af..24912b0 100644
--- a/tests/unit/mime-dkim-sign.test.js
+++ b/tests/unit/mime-dkim-sign.test.js
@@ -13,7 +13,9 @@ const {
   TEST_DKIM_PUBLIC_KEY,
   TEST_DKIM_SELECTOR,
 } = require('../helpers/mime/dkim-test-keys.js');
-const { signMessage } = require('../../src/mime/dkim/sign.js');
+// Changed after the port: the body canonicalization and signMessage, which src/
+// no longer uses (it hashes a body as it streams), are test references now.
+const { signMessage } = require('../helpers/mime/dkim-reference.js');
 
 describe('DKIM Signing', () => {
   const simpleMessage =
diff --git a/tests/unit/mime-dkim.test.js b/tests/unit/mime-dkim.test.js
index 9850d08..e08c071 100644
--- a/tests/unit/mime-dkim.test.js
+++ b/tests/unit/mime-dkim.test.js
@@ -10,7 +10,7 @@ const {
   TEST_DKIM_PUBLIC_KEY,
   TEST_DKIM_SELECTOR,
 } = require('../helpers/mime/dkim-test-keys.js');
-const { signMessage } = require('../../src/mime/dkim/sign.js');
+const { signMessage } = require('../helpers/mime/dkim-reference.js');
 
 const config = (extra) => ({
   signingDomain: TEST_DKIM_DOMAIN,
diff --git a/tests/unit/smtp-message-stream.test.js b/tests/unit/smtp-message-stream.test.js
index 99372a7..d2d41fb 100644
--- a/tests/unit/smtp-message-stream.test.js
+++ b/tests/unit/smtp-message-stream.test.js
@@ -10,7 +10,9 @@ const {
   prepareMessageStream,
   SmtpAttachmentReplayError,
 } = require('../../src/smtp/message-stream.js');
-const { signMessage } = require('../../src/mime/dkim/sign.js');
+// Changed after the port: the body canonicalization and signMessage, which src/
+// no longer uses (it hashes a body as it streams), are test references now.
+const { signMessage } = require('../helpers/mime/dkim-reference.js');
 const {
   TEST_DKIM_ED25519_PRIVATE_KEY,
   TEST_DKIM_PRIVATE_KEY,

From 8eb9cab655d0302a58b0809f810fdff53e25878c Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:33:02 +0300
Subject: [PATCH 130/158] refactor(smtp): split the long functions, loops
 instead of array methods

sendPreparedMessage (210 lines) is the MAIL FROM parameters, the
envelope, the pipelined envelope and DATA, each a method; sendCommands
and greeting share a reply collector and the socket listeners;
writeMessageData writes through writeToSocket and writeBody and reads
its reply with createDataReplyReader; createSmtpFailure looks local
failures up in a table; resolveSmtpDsn and OAuth 2.0's refresh are split
in parts; the capacity waiters are a Set, which drops an aborted waiter
without a scan.

convertMessage and the string form of a message it fed the connection
were used by tests only; convertMessage is a test helper, and the ported
connection tests go through the path of sendRaw(), so a test of the SIZE
of UTF-8 text now advertises SMTPUTF8 (changed after the port).
Behavior is otherwise unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/smtp/data-stream.js                       | 227 +++++---
 src/smtp/delivery-status.js                   | 142 ++---
 src/smtp/envelope.js                          |  18 +-
 src/smtp/message-converter.js                 |  23 +-
 src/smtp/oauth2.js                            | 120 ++--
 src/smtp/smtp-connection.js                   | 526 ++++++++++--------
 src/smtp/smtp-transport.js                    | 220 ++++----
 tests/helpers/smtp/convert-message.js         |  30 +
 tests/helpers/smtp/raw-smtp-message.js        |  17 +
 tests/unit/graph.test.js                      |   1 -
 .../unit/smtp-connection.integration.test.js  | 311 ++++++-----
 ...smtp-message-converter.integration.test.js |   4 +-
 tests/unit/smtp-mime-regression.test.js       |   4 +-
 tests/unit/smtp-transport.dkim.test.js        |   4 +-
 14 files changed, 902 insertions(+), 745 deletions(-)
 create mode 100644 tests/helpers/smtp/convert-message.js
 create mode 100644 tests/helpers/smtp/raw-smtp-message.js

diff --git a/src/smtp/data-stream.js b/src/smtp/data-stream.js
index c6d3ea1..f720617 100644
--- a/src/smtp/data-stream.js
+++ b/src/smtp/data-stream.js
@@ -103,36 +103,112 @@ const abortable = (promise, signal) => {
   });
 };
 
-/** Writes one DATA body with bounded transparency buffers and backpressure. */
-const writeMessageData = async (socket, source, timeoutMs, checkSize, signal) => {
-  const controller = new AbortController();
-  const combined = combineSignals(controller.signal, signal);
-  const owned = combined.signal;
-  let terminated = false;
-  let complete = false;
+/**
+ * Writes bytes to the socket and waits until it has taken them and drained,
+ * under the signal of the DATA phase.
+ *
+ * @param socket The connected socket.
+ * @param bytes The bytes to write.
+ * @param owned The signal of the DATA phase.
+ * @param progress Restarts the timeout of the phase.
+ * @returns A promise that settles once the write is done and drained.
+ */
+const writeToSocket = (socket, bytes, owned, progress) => {
+  owned.throwIfAborted();
+  return abortable(
+    new Promise((resolve, reject) => {
+      let written = false;
+      let drained = false;
+      let returned = false;
+      const cleanup = () => {
+        socket.off('drain', drain);
+        owned.removeEventListener('abort', cleanup);
+      };
+      const finish = () => {
+        if (returned && written && drained) {
+          cleanup();
+          progress();
+          resolve();
+        }
+      };
+      const drain = () => {
+        drained = true;
+        finish();
+      };
+      socket.once('drain', drain);
+      owned.addEventListener('abort', cleanup, { once: true });
+      try {
+        const accepted = socket.write(bytes, (error) => {
+          if (error != null) {
+            cleanup();
+            reject(error);
+            return;
+          }
+          written = true;
+          finish();
+        });
+        drained = accepted || drained;
+        returned = true;
+        finish();
+      } catch (error) {
+        cleanup();
+        reject(error);
+      }
+    }),
+    owned,
+  );
+};
+
+const DATA_WINDOW_BYTES = 32768;
+
+/**
+ * Writes the message from its source, dot-stuffed (RFC 5321 §4.5.2), in
+ * windows of at most 32 KiB, checking the size as it grows.
+ *
+ * @param iterator The iterator of the message bytes.
+ * @param write Writes bytes to the socket.
+ * @param owned The signal of the DATA phase.
+ * @param checkSize Throws when the size passes the limit of the server.
+ * @param progress Restarts the timeout of the phase.
+ */
+const writeBody = async (iterator, write, owned, checkSize, progress) => {
+  let lineStart = true;
+  let size = 0;
+  while (true) {
+    owned.throwIfAborted();
+    const item = await abortable(Promise.resolve(iterator.next()), owned);
+    if (item.done) return;
+    const chunk = item.value;
+    for (let offset = 0; offset < chunk.length; offset += DATA_WINDOW_BYTES) {
+      const window = chunk.subarray(offset, offset + DATA_WINDOW_BYTES);
+      size += window.length;
+      checkSize(size);
+      progress();
+      const output = stuffDots(window, lineStart);
+      lineStart = window[window.length - 1] === 0x0a;
+      await write(output);
+    }
+  }
+};
+
+const MAX_DATA_REPLY_BYTES = 65536;
+
+/**
+ * Reads the reply to the end of DATA as its bytes arrive, bounded to 64 KiB.
+ *
+ * @param isTerminated Whether the terminating dot has been written: a reply
+ * before it is premature.
+ * @param onReply Takes the reply at its final line.
+ * @param fail Takes the error of a premature or oversized reply.
+ * @returns The listener of the socket's data.
+ */
+const createDataReplyReader = (isTerminated, onReply, fail) => {
   let replyBytes = 0;
   let buffer = '';
   const lines = [];
-  let resolveReply;
-  const reply = new Promise((resolve) => (resolveReply = resolve));
-  // Once the terminating dot is on its way, a failure of the connection can
-  // no longer tell whether the server accepted the message.
-  const fail = (error) => {
-    if (!owned.aborted) {
-      controller.abort(terminated ? new SmtpDeliveryUnknownError(error) : error);
-    }
-    socket.destroy();
-  };
-  const close = () => fail(new TypeError('SMTP connection closed during DATA.'));
-  const onAbort = () => socket.destroy();
-  let timer;
-  const progress = () => {
-    clearTimeout(timer);
-    timer = setTimeout(() => fail(new TypeError('SMTP DATA timeout.')), timeoutMs);
-  };
-  const data = (chunk) => {
+  return (chunk) => {
     replyBytes += chunk.length;
-    if (replyBytes > 65536) {
+    if (replyBytes > MAX_DATA_REPLY_BYTES) {
       fail(new RangeError('SMTP DATA reply exceeds 64 KiB.'));
       return;
     }
@@ -144,10 +220,10 @@ const writeMessageData = async (socket, source, timeoutMs, checkSize, signal) =>
       lines.push(line);
       // RFC 5321 §4.2: a final line is the code alone or with a space.
       if (/^\d{3}(?: |$)/.test(line)) {
-        if (!terminated) {
+        if (!isTerminated()) {
           fail(new TypeError(`Premature SMTP DATA reply: ${line}`));
         } else {
-          resolveReply({
+          onReply({
             code: Number(line.slice(0, 3)),
             message: line.slice(4),
             raw: lines.join('\r\n'),
@@ -157,77 +233,48 @@ const writeMessageData = async (socket, source, timeoutMs, checkSize, signal) =>
       }
     }
   };
+};
+
+/** Writes one DATA body with bounded transparency buffers and backpressure. */
+const writeMessageData = async (socket, source, timeoutMs, checkSize, signal) => {
+  const controller = new AbortController();
+  const combined = combineSignals(controller.signal, signal);
+  const owned = combined.signal;
+  let terminated = false;
+  let complete = false;
+  let resolveReply;
+  const reply = new Promise((resolve) => (resolveReply = resolve));
+  // Once the terminating dot is on its way, a failure of the connection can
+  // no longer tell whether the server accepted the message.
+  const fail = (error) => {
+    if (!owned.aborted) {
+      controller.abort(terminated ? new SmtpDeliveryUnknownError(error) : error);
+    }
+    socket.destroy();
+  };
+  const close = () => fail(new TypeError('SMTP connection closed during DATA.'));
+  const onAbort = () => socket.destroy();
+  let timer;
+  const progress = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fail(new TypeError('SMTP DATA timeout.')), timeoutMs);
+  };
+  const data = createDataReplyReader(
+    () => terminated,
+    (finalReply) => resolveReply(finalReply),
+    fail,
+  );
   socket.on('error', fail);
   socket.on('close', close);
   socket.on('data', data);
   owned.addEventListener('abort', onAbort, { once: true });
   progress();
   let iterator;
-  const write = async (bytes) => {
-    owned.throwIfAborted();
-    await abortable(
-      new Promise((resolve, reject) => {
-        let written = false;
-        let drained = false;
-        let returned = false;
-        const cleanup = () => {
-          socket.off('drain', drain);
-          owned.removeEventListener('abort', cleanup);
-        };
-        const finish = () => {
-          if (returned && written && drained) {
-            cleanup();
-            progress();
-            resolve();
-          }
-        };
-        const drain = () => {
-          drained = true;
-          finish();
-        };
-        socket.once('drain', drain);
-        owned.addEventListener('abort', cleanup, { once: true });
-        try {
-          const accepted = socket.write(bytes, (error) => {
-            if (error != null) {
-              cleanup();
-              reject(error);
-              return;
-            }
-            written = true;
-            finish();
-          });
-          drained = accepted || drained;
-          returned = true;
-          finish();
-        } catch (error) {
-          cleanup();
-          reject(error);
-        }
-      }),
-      owned,
-    );
-  };
+  const write = (bytes) => writeToSocket(socket, bytes, owned, progress);
   try {
     iterator = source(owned, progress)[Symbol.asyncIterator]();
     if (socket.destroyed || !socket.writable) close();
-    let lineStart = true;
-    let size = 0;
-    while (true) {
-      owned.throwIfAborted();
-      const item = await abortable(Promise.resolve(iterator.next()), owned);
-      if (item.done) break;
-      const chunk = item.value;
-      for (let offset = 0; offset < chunk.length; offset += 32768) {
-        const window = chunk.subarray(offset, offset + 32768);
-        size += window.length;
-        checkSize(size);
-        progress();
-        const output = stuffDots(window, lineStart);
-        lineStart = window[window.length - 1] === 0x0a;
-        await write(output);
-      }
-    }
+    await writeBody(iterator, write, owned, checkSize, progress);
     owned.throwIfAborted();
     terminated = true;
     await write(Buffer.from('.\r\n'));
diff --git a/src/smtp/delivery-status.js b/src/smtp/delivery-status.js
index ed80b55..f762461 100644
--- a/src/smtp/delivery-status.js
+++ b/src/smtp/delivery-status.js
@@ -48,91 +48,101 @@ const resolveSmtpDsn = (envelope, dsn) => {
   if (typeof dsn !== 'object' || Array.isArray(dsn)) {
     throw new SmtpDsnValidationError('DSN options must be an object.');
   }
+  const mailParameters = dsnMailParameters(dsn);
+  const configuredRecipients = dsn.recipients;
+  if (
+    configuredRecipients != null &&
+    (typeof configuredRecipients !== 'object' || Array.isArray(configuredRecipients))
+  ) {
+    throw new SmtpDsnValidationError('DSN recipient options must be an object.');
+  }
+
+  const envelopeRecipients = new Set(envelope.to);
+  const serializedByAddress = new Map();
+  for (const address in configuredRecipients) {
+    if (!Object.hasOwn(configuredRecipients, address)) continue;
+    if (!envelopeRecipients.has(address)) {
+      throw new SmtpDsnValidationError(`DSN recipient ${address} is not an envelope recipient.`);
+    }
+    serializedByAddress.set(
+      address,
+      dsnRecipientParameters(address, configuredRecipients[address]),
+    );
+  }
+
+  const recipientParameters = [];
+  let requested = mailParameters.length > 0;
+  for (const address of envelope.to) {
+    const parameters = serializedByAddress.get(address) ?? [];
+    if (parameters.length > 0) requested = true;
+    recipientParameters.push(parameters);
+  }
+  return requested ? { mailParameters, recipientParameters } : undefined;
+};
 
-  const mailParameters = [];
+// RET and ENVID, the parameters of MAIL FROM (RFC 3461 §4.3 and §4.4).
+const dsnMailParameters = (dsn) => {
+  const parameters = [];
   if (dsn.return != null) {
     if (dsn.return !== 'full' && dsn.return !== 'headers') {
       throw new SmtpDsnValidationError(`Unsupported DSN return value: ${String(dsn.return)}`);
     }
-    mailParameters.push(`RET=${dsn.return === 'full' ? 'FULL' : 'HDRS'}`);
+    parameters.push(`RET=${dsn.return === 'full' ? 'FULL' : 'HDRS'}`);
   }
-
   if (dsn.envelopeId != null) {
     if (dsn.envelopeId === '') {
       throw new SmtpDsnValidationError('DSN envelope ID must not be empty.');
     }
-    const encoded = encodeXtext(dsn.envelopeId, 'DSN envelope ID');
-    const parameter = `ENVID=${encoded}`;
+    const parameter = `ENVID=${encodeXtext(dsn.envelopeId, 'DSN envelope ID')}`;
     assertParameterLength(parameter, 100, 'ENVID');
-    mailParameters.push(parameter);
+    parameters.push(parameter);
   }
+  return parameters;
+};
 
-  const envelopeRecipients = envelope.to;
-  const envelopeRecipientSet = new Set(envelopeRecipients);
-  const configuredRecipients = dsn.recipients;
-  if (
-    configuredRecipients != null &&
-    (typeof configuredRecipients !== 'object' || Array.isArray(configuredRecipients))
-  ) {
-    throw new SmtpDsnValidationError('DSN recipient options must be an object.');
+// NOTIFY and ORCPT, the parameters of a RCPT TO (RFC 3461 §4.1 and §4.2).
+const dsnRecipientParameters = (address, options) => {
+  if (options == null || typeof options !== 'object' || Array.isArray(options)) {
+    throw new SmtpDsnValidationError(`DSN options for ${address} must be an object.`);
   }
-
-  const serializedByAddress = new Map();
-  for (const [address, options] of Object.entries(configuredRecipients ?? {})) {
-    if (!envelopeRecipientSet.has(address)) {
-      throw new SmtpDsnValidationError(`DSN recipient ${address} is not an envelope recipient.`);
-    }
-    if (options == null || typeof options !== 'object' || Array.isArray(options)) {
-      throw new SmtpDsnValidationError(`DSN options for ${address} must be an object.`);
-    }
-
-    const parameters = [];
-    if (options.notify != null) {
-      const notify = options.notify;
-      if (!Array.isArray(notify) || notify.length === 0) {
-        throw new SmtpDsnValidationError(
-          `DSN notification conditions for ${address} must be a non-empty array.`,
-        );
-      }
-      for (const condition of notify) {
-        if (typeof condition !== 'string' || !NOTIFICATION_CONDITIONS.has(condition)) {
-          throw new SmtpDsnValidationError(
-            `Unsupported DSN notification condition: ${String(condition)}`,
-          );
-        }
-      }
-      if (notify.includes('never') && notify.length !== 1) {
-        throw new SmtpDsnValidationError(
-          'The DSN notification condition NEVER must appear by itself.',
-        );
-      }
-      parameters.push(`NOTIFY=${notify.map((condition) => condition.toUpperCase()).join(',')}`);
+  const parameters = [];
+  if (options.notify != null) parameters.push(notifyParameter(address, options.notify));
+  if (options.originalRecipient != null) {
+    const encoded = encodeXtext(options.originalRecipient, `DSN original recipient for ${address}`);
+    if (options.originalRecipient !== address) {
+      throw new SmtpDsnValidationError(
+        `DSN original recipient for ${address} must match the envelope recipient address.`,
+      );
     }
+    const parameter = `ORCPT=rfc822;${encoded}`;
+    assertParameterLength(parameter, 500, 'ORCPT');
+    parameters.push(parameter);
+  }
+  return parameters;
+};
 
-    if (options.originalRecipient != null) {
-      const encoded = encodeXtext(
-        options.originalRecipient,
-        `DSN original recipient for ${address}`,
+// The conditions of NOTIFY, checked and upper-cased in one pass.
+const notifyParameter = (address, notify) => {
+  if (!Array.isArray(notify) || notify.length === 0) {
+    throw new SmtpDsnValidationError(
+      `DSN notification conditions for ${address} must be a non-empty array.`,
+    );
+  }
+  let conditions = '';
+  let never = false;
+  for (const condition of notify) {
+    if (typeof condition !== 'string' || !NOTIFICATION_CONDITIONS.has(condition)) {
+      throw new SmtpDsnValidationError(
+        `Unsupported DSN notification condition: ${String(condition)}`,
       );
-      if (options.originalRecipient !== address) {
-        throw new SmtpDsnValidationError(
-          // oxlint-disable-next-line no-useless-concat -- upstream
-          `DSN original recipient for ${address} must match the envelope ` + 'recipient address.',
-        );
-      }
-      const parameter = `ORCPT=rfc822;${encoded}`;
-      assertParameterLength(parameter, 500, 'ORCPT');
-      parameters.push(parameter);
     }
-    serializedByAddress.set(address, parameters);
+    if (condition === 'never') never = true;
+    conditions += `${conditions === '' ? '' : ','}${condition.toUpperCase()}`;
   }
-
-  const recipientParameters = envelopeRecipients.map(
-    (address) => serializedByAddress.get(address) ?? [],
-  );
-  const requested =
-    mailParameters.length > 0 || recipientParameters.some((parameters) => parameters.length > 0);
-  return requested ? { mailParameters, recipientParameters } : undefined;
+  if (never && notify.length !== 1) {
+    throw new SmtpDsnValidationError('The DSN notification condition NEVER must appear by itself.');
+  }
+  return `NOTIFY=${conditions}`;
 };
 
 const encodeXtext = (value, name) => {
diff --git a/src/smtp/envelope.js b/src/smtp/envelope.js
index a228717..ebee135 100644
--- a/src/smtp/envelope.js
+++ b/src/smtp/envelope.js
@@ -18,6 +18,15 @@ class SmtpEnvelopeValidationError extends TypeError {
   }
 }
 
+// The addresses of To, Cc and Bcc, in that order.
+const recipientAddresses = (message) => {
+  const addresses = [];
+  for (const recipient of message.recipients) addresses.push(recipient.address);
+  for (const recipient of message.ccRecipients) addresses.push(recipient.address);
+  for (const recipient of message.bccRecipients) addresses.push(recipient.address);
+  return addresses;
+};
+
 /**
  * Resolves and validates the SMTP envelope for a message.
  *
@@ -43,14 +52,7 @@ const resolveSmtpEnvelope = (message, override) => {
     );
   }
 
-  const recipients =
-    override?.to === undefined
-      ? [
-          ...message.recipients.map((recipient) => recipient.address),
-          ...message.ccRecipients.map((recipient) => recipient.address),
-          ...message.bccRecipients.map((recipient) => recipient.address),
-        ]
-      : override.to;
+  const recipients = override?.to === undefined ? recipientAddresses(message) : override.to;
   if (!Array.isArray(recipients)) {
     throw new SmtpEnvelopeValidationError('SMTP envelope recipients must be an array.');
   }
diff --git a/src/smtp/message-converter.js b/src/smtp/message-converter.js
index 3252f63..f50b289 100644
--- a/src/smtp/message-converter.js
+++ b/src/smtp/message-converter.js
@@ -1,9 +1,7 @@
 // Ported from upyo v0.7.0 (packages/smtp/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { readAttachmentContent } = require('../core/attachment.js');
 const { prepareMimeMessage } = require('../mime/message.js');
-const { prepareMimeStream } = require('../mime/stream.js');
 const { hasNonAsciiAddress, resolveSmtpEnvelope } = require('./envelope.js');
 
 /** Snapshots MIME metadata and preserves the effective SMTP envelope. */
@@ -22,23 +20,4 @@ const prepareMessage = (
     requiresSmtpUtf8: plan.encoding === 'utf8' || hasNonAsciiAddress(envelope),
   };
 };
-/** Collects the shared stream using the historical internal trailing-CRLF convention. */
-const convertMessage = async (
-  message,
-  dkimConfig,
-  dsn,
-  resolvedEnvelope = resolveSmtpEnvelope(message),
-  signal,
-) => {
-  const plan = prepareMessage(message, dkimConfig, dsn, resolvedEnvelope);
-  const stream = await prepareMimeStream(plan, { signal });
-  // oxlint-disable-next-line no-shadow -- upstream
-  const bytes = await readAttachmentContent((signal) => stream.read(signal), signal);
-  return {
-    envelope: plan.envelope,
-    raw: new TextDecoder().decode(bytes).slice(0, -2),
-    requiresSmtpUtf8: plan.requiresSmtpUtf8 || stream.encoding === 'utf8',
-  };
-};
-
-module.exports = { prepareMessage, convertMessage };
+module.exports = { prepareMessage };
diff --git a/src/smtp/oauth2.js b/src/smtp/oauth2.js
index 15d44c6..0a483a5 100644
--- a/src/smtp/oauth2.js
+++ b/src/smtp/oauth2.js
@@ -97,7 +97,13 @@ const escapeSaslName = (name) => {
  * @returns The selected mechanism, either `"xoauth2"` or `"oauthbearer"`.
  */
 const selectOAuth2Mechanism = (capabilities) => {
-  const authLine = capabilities.find((cap) => cap.toUpperCase().startsWith('AUTH'));
+  let authLine;
+  for (const capability of capabilities) {
+    if (capability.toUpperCase().startsWith('AUTH')) {
+      authLine = capability;
+      break;
+    }
+  }
   // Normalize "=" to whitespace so the older `AUTH=XOAUTH2 ...` form (where the
   // first mechanism is glued to the AUTH keyword) is parsed like `AUTH XOAUTH2`.
   const mechanisms =
@@ -138,7 +144,7 @@ const REFRESH_SAFETY_MARGIN_MS = 60_000;
  * The default access token lifetime (in seconds) assumed when the token
  * endpoint omits `expires_in`.
  */
-const DEFAULT_EXPIRES_IN = 3600;
+const DEFAULT_EXPIRES_IN_SECONDS = 3600;
 
 /**
  * How long to wait for the token endpoint before aborting the request, so a
@@ -272,11 +278,11 @@ class OAuth2TokenManager {
         // a duplicate refresh.  Refresh slightly before expiry; cap the safety
         // margin at half the lifetime so short-lived tokens are not treated as
         // already expired (which would refresh on every connection).
-        const lifetimeMs = result.expiresIn * 1000;
-        const safetyMargin = Math.min(REFRESH_SAFETY_MARGIN_MS, lifetimeMs / 2);
+        const lifetimeMs = result.expiresInSeconds * 1000;
+        const safetyMarginMs = Math.min(REFRESH_SAFETY_MARGIN_MS, lifetimeMs / 2);
         this.cached = {
           accessToken: result.accessToken,
-          expiresAt: Date.now() + lifetimeMs - safetyMargin,
+          expiresAt: Date.now() + lifetimeMs - safetyMarginMs,
         };
         return result;
       })
@@ -300,6 +306,13 @@ class OAuth2TokenManager {
    * @throws {SmtpAuthError} If the request fails or the response is invalid.
    */
   async refresh(auth) {
+    const { response, text } = await this.requestToken(auth);
+    return readTokenResponse(response, text);
+  }
+
+  // The token request and its body, bounded by an internal timeout so that a
+  // stalled endpoint cannot leave the shared `pending` promise unresolved.
+  async requestToken(auth) {
     const body = new URLSearchParams({
       grant_type: 'refresh_token',
       client_id: auth.clientId,
@@ -308,22 +321,17 @@ class OAuth2TokenManager {
     if (auth.clientSecret != null) body.set('client_secret', auth.clientSecret);
     if (auth.scope != null) body.set('scope', auth.scope);
 
-    // Bound the request with an internal timeout so a stalled endpoint cannot
-    // leave the shared `pending` promise unresolved forever.
     const controller = new AbortController();
-    const timeout = setTimeout(() => {
+    const timer = setTimeout(() => {
       controller.abort(new Error('OAuth 2.0 token request timed out'));
     }, TOKEN_REQUEST_TIMEOUT_MS);
-
-    let response;
-    let text;
     // Call through a local variable so the global `fetch` is not invoked as a
     // method of this manager, which throws "Illegal invocation" in some
     // runtimes (the native `fetch` requires a `globalThis`/undefined receiver).
     // Read at each refresh, so that the global one may be replaced later.
     const fetchFn = this.fetchFn ?? globalThis.fetch;
     try {
-      response = await fetchFn(auth.tokenEndpoint, {
+      const response = await fetchFn(auth.tokenEndpoint, {
         method: 'POST',
         headers: {
           'content-type': 'application/x-www-form-urlencoded',
@@ -337,59 +345,59 @@ class OAuth2TokenManager {
       });
       // Read the body under the same timeout: an endpoint that returns headers
       // but stalls on the body must not leave `pending` unresolved forever.
-      text = await readText(response);
-    } catch (cause) {
+      return { response, text: await readText(response) };
+    } catch (error) {
       throw new SmtpAuthError(
         `Failed to request an OAuth 2.0 access token from ` +
           `${auth.tokenEndpoint}: ` +
-          `${cause instanceof Error ? cause.message : String(cause)}`,
+          `${error instanceof Error ? error.message : String(error)}`,
       );
     } finally {
-      clearTimeout(timeout);
-    }
-
-    const safeText = truncateErrorBody(text);
-    if (!response.ok) {
-      throw new SmtpAuthError(
-        `OAuth 2.0 token endpoint responded with HTTP ${response.status}: ${safeText}`,
-      );
+      clearTimeout(timer);
     }
-
-    let json;
-    try {
-      json = JSON.parse(text);
-    } catch {
-      throw new SmtpAuthError(`OAuth 2.0 token endpoint returned a non-JSON response: ${safeText}`);
-    }
-
-    if (typeof json !== 'object' || json == null || typeof json.access_token !== 'string') {
-      throw new SmtpAuthError(
-        `OAuth 2.0 token endpoint response did not include an access_token: ${safeText}`,
-      );
-    }
-
-    const record = json;
-    // Accept `expires_in` only as a finite, non-negative number of seconds.
-    // Some providers send it as a numeric string; `Number()` (unlike
-    // `parseInt`) rejects partial parses like "100abc".  Negative, NaN, and
-    // Infinity values fall back to the default lifetime.
-    const rawExpiresIn = record.expires_in;
-    let parsedExpiresIn;
-    if (typeof rawExpiresIn === 'number') {
-      parsedExpiresIn = rawExpiresIn;
-    } else if (typeof rawExpiresIn === 'string' && rawExpiresIn.trim() !== '') {
-      parsedExpiresIn = Number(rawExpiresIn);
-    } else {
-      parsedExpiresIn = NaN;
-    }
-    const expiresIn =
-      Number.isFinite(parsedExpiresIn) && parsedExpiresIn >= 0
-        ? parsedExpiresIn
-        : DEFAULT_EXPIRES_IN;
-    return { accessToken: record.access_token, expiresIn };
   }
 }
 
+/**
+ * Reads the access token and its lifetime from the answer of a token endpoint.
+ *
+ * @param response The response of the token request.
+ * @param text Its body.
+ * @returns The access token and its lifetime in seconds.
+ * @throws {SmtpAuthError} If the endpoint failed or answered without a token.
+ */
+const readTokenResponse = (response, text) => {
+  const safeText = truncateErrorBody(text);
+  if (!response.ok) {
+    throw new SmtpAuthError(
+      `OAuth 2.0 token endpoint responded with HTTP ${response.status}: ${safeText}`,
+    );
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new SmtpAuthError(`OAuth 2.0 token endpoint returned a non-JSON response: ${safeText}`);
+  }
+  if (typeof json !== 'object' || json == null || typeof json.access_token !== 'string') {
+    throw new SmtpAuthError(
+      `OAuth 2.0 token endpoint response did not include an access_token: ${safeText}`,
+    );
+  }
+  return { accessToken: json.access_token, expiresInSeconds: readExpiresIn(json.expires_in) };
+};
+
+// Accepts `expires_in` only as a finite, non-negative number of seconds.  Some
+// providers send it as a numeric string; `Number()` (unlike `parseInt`)
+// rejects partial parses like "100abc".  Negative, NaN, and Infinity values
+// fall back to the default lifetime.
+const readExpiresIn = (value) => {
+  let seconds = NaN;
+  if (typeof value === 'number') seconds = value;
+  else if (typeof value === 'string' && value.trim() !== '') seconds = Number(value);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds : DEFAULT_EXPIRES_IN_SECONDS;
+};
+
 module.exports = {
   SmtpAuthError,
   formatXoauth2,
diff --git a/src/smtp/smtp-connection.js b/src/smtp/smtp-connection.js
index d447f9d..fb57f22 100644
--- a/src/smtp/smtp-connection.js
+++ b/src/smtp/smtp-connection.js
@@ -72,6 +72,111 @@ const createReplyReader = () => {
   };
 };
 
+/**
+ * Gathers the lines of one reply at a time.
+ *
+ * @returns A collector whose `add()` gives the reply at its final line, `null`
+ * once a reply has more than {@link MAX_REPLY_LINES} lines, and `undefined`
+ * while the reply goes on.
+ */
+const createReplyCollector = () => {
+  let lines = [];
+  return {
+    add(line) {
+      lines.push(line);
+      if (!isFinalReplyLine(line)) return lines.length > MAX_REPLY_LINES ? null : undefined;
+      const reply = {
+        code: parseInt(line.substring(0, 3), 10),
+        message: line.substring(4),
+        raw: lines.join('\r\n'),
+      };
+      lines = [];
+      return reply;
+    },
+  };
+};
+
+/**
+ * Listens to the data, the errors and the close of a socket and to the abort
+ * of a signal.
+ *
+ * @returns The function that stops listening to all of them.
+ */
+const listenToSocket = (socket, signal, onData, onError, onClose, onAbort) => {
+  socket.on('data', onData);
+  socket.on('error', onError);
+  socket.on('close', onClose);
+  signal?.addEventListener('abort', onAbort, { once: true });
+  return () => {
+    socket.off('data', onData);
+    socket.off('error', onError);
+    socket.off('close', onClose);
+    signal?.removeEventListener('abort', onAbort);
+  };
+};
+
+// Each command ended by CRLF, for one write.
+const joinCommands = (commands) => {
+  let text = '';
+  for (const command of commands) text += `${command}\r\n`;
+  return text;
+};
+
+/**
+ * Tells why a connection closed before every command had its reply: a reply
+ * that ended the pipeline (421, or a failure of the first command), or else
+ * the failures among the replies that came.
+ *
+ * @param commands The commands written.
+ * @param responses The replies read before the close.
+ * @returns The error to reject with.
+ */
+const closedBeforeReplies = (commands, responses) => {
+  let failures = '';
+  for (let index = 0; index < responses.length; index++) {
+    const response = responses[index];
+    if (response.code === 421 || (index === 0 && response.code >= 400)) {
+      return new SmtpPipelineTerminatedError(index, response);
+    }
+    if (response.code >= 400) {
+      failures += `${failures === '' ? '' : '; '}${commands[index]}: ${response.code} ${response.message}`;
+    }
+  }
+  const details = failures === '' ? '' : ` Completed failures: ${failures}.`;
+  return new Error(`Connection closed before all command responses.${details}`);
+};
+
+// A recipient the server refused, with whether a retry may take it.
+const describeRejection = (recipient, response) => {
+  const enhancedStatusCode = parseEnhancedSmtpStatusCode(response.code, response.message);
+  return {
+    recipient,
+    code: response.code,
+    response: response.message,
+    retryable: response.code >= 400 && response.code < 500,
+    ...(enhancedStatusCode == null ? {} : { enhancedStatusCode }),
+  };
+};
+
+// The error of an envelope whose every recipient was refused: its reply is the
+// first temporary refusal, or the first refusal when all are permanent.
+const everyRecipientRejected = (rejectedRecipients) => {
+  let rejection;
+  let details = '';
+  for (const item of rejectedRecipients) {
+    if (rejection === undefined && item.retryable) rejection = item;
+    details += `${details === '' ? '' : '; '}${item.recipient}: ${item.code} ${item.response}`;
+  }
+  rejection ??= rejectedRecipients[0];
+  return new SmtpResponseError(
+    `RCPT TO failed for every recipient: ${details}`,
+    rejection.code,
+    'RCPT TO',
+    rejection.response,
+    rejectedRecipients,
+  );
+};
+
 /**
  * Error thrown when a message exceeds the fixed limit advertised through the
  * SMTP SIZE extension.
@@ -128,8 +233,7 @@ class SmtpUtf8UnsupportedError extends Error {
     super(
       missingCapability === 'SMTPUTF8'
         ? 'The SMTP server does not advertise SMTPUTF8.'
-        : // oxlint-disable-next-line no-useless-concat -- upstream
-          'The SMTP server advertises SMTPUTF8 without the required ' + '8BITMIME capability.',
+        : 'The SMTP server advertises SMTPUTF8 without the required 8BITMIME capability.',
     );
     this.name = 'SmtpUtf8UnsupportedError';
     this.missingCapability = missingCapability;
@@ -325,13 +429,13 @@ class SmtpConnection {
     const establishedEvent = this.config.secure ? 'secureConnect' : 'connect';
 
     return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
+      const timer = setTimeout(() => {
         onError(new TypeError('Connection timeout.'));
         this.socket?.destroy();
       }, this.config.connectionTimeout);
 
       const cleanup = () => {
-        clearTimeout(timeout);
+        clearTimeout(timer);
         this.socket?.off(establishedEvent, onConnect);
         this.socket?.off('error', onError);
         this.socket?.off('close', onClose);
@@ -421,17 +525,24 @@ class SmtpConnection {
 
     return new Promise((resolve, reject) => {
       const reader = createReplyReader();
-      let responseLines = [];
+      const collector = createReplyCollector();
       const responses = [];
-      const startTimeout = () =>
+      const startTimer = () =>
         setTimeout(() => {
           cleanup();
           reject(new Error('Command timeout'));
         }, this.config.socketTimeout);
-      let timeout = startTimeout();
-      const resetTimeout = () => {
-        clearTimeout(timeout);
-        timeout = startTimeout();
+      let timer = startTimer();
+
+      const finish = (moreLines) => {
+        cleanup();
+        if (commands[0] === 'DATA' && (moreLines || reader.pending.length > 0)) {
+          this.socket?.destroy();
+          reject(new TypeError('Premature SMTP reply after DATA readiness.'));
+          return;
+        }
+        this.log.write('trace', () => ({ codes: replyCodes(responses) }), 'SMTP replies');
+        resolve(responses);
       };
 
       const onData = (data) => {
@@ -440,50 +551,25 @@ class SmtpConnection {
           failOnLimit();
           return;
         }
-
         for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
-          const line = lines[lineIndex];
-          responseLines.push(line);
-          if (!isFinalReplyLine(line)) {
-            if (responseLines.length > MAX_REPLY_LINES) {
-              failOnLimit();
-              return;
-            }
-          } else {
-            const code = parseInt(line.substring(0, 3), 10);
-            const message = line.substring(4);
-            const response = {
-              code,
-              message,
-              raw: responseLines.join('\r\n'),
-            };
-            const responseIndex = responses.length;
-            responses.push(response);
-            responseLines = [];
-
-            if (responses.length === commands.length) {
-              cleanup();
-              if (
-                commands[0] === 'DATA' &&
-                (lineIndex + 1 < lines.length || reader.pending.length > 0)
-              ) {
-                this.socket?.destroy();
-                reject(new TypeError('Premature SMTP reply after DATA readiness.'));
-                return;
-              }
-              this.log.write('trace', () => ({ codes: replyCodes(responses) }), 'SMTP replies');
-              resolve(responses);
-              return;
-            }
-
-            if (response.code === 421) {
-              cleanup();
-              reject(new SmtpPipelineTerminatedError(responseIndex, response));
-              return;
-            }
-
-            resetTimeout();
+          const response = collector.add(lines[lineIndex]);
+          if (response === null) {
+            failOnLimit();
+            return;
+          }
+          if (response === undefined) continue;
+          responses.push(response);
+          if (responses.length === commands.length) {
+            finish(lineIndex + 1 < lines.length);
+            return;
           }
+          if (response.code === 421) {
+            cleanup();
+            reject(new SmtpPipelineTerminatedError(responses.length - 1, response));
+            return;
+          }
+          clearTimeout(timer);
+          timer = startTimer();
         }
       };
 
@@ -500,53 +586,32 @@ class SmtpConnection {
 
       const onClose = () => {
         cleanup();
-        const responseIndex = responses.findIndex(
-          (response, index) => response.code === 421 || (index === 0 && response.code >= 400),
-        );
-        if (responseIndex >= 0) {
-          reject(new SmtpPipelineTerminatedError(responseIndex, responses[responseIndex]));
-          return;
-        }
-        const completedFailures = responses.flatMap((response, index) =>
-          response.code >= 400 ? [`${commands[index]}: ${response.code} ${response.message}`] : [],
-        );
-        const failureDetails =
-          completedFailures.length > 0
-            ? ` Completed failures: ${completedFailures.join('; ')}.`
-            : '';
-        reject(new Error(`Connection closed before all command responses.${failureDetails}`));
+        reject(closedBeforeReplies(commands, responses));
       };
 
       const onAbort = () => {
         cleanup();
-        try {
-          signal?.throwIfAborted();
-        } catch (error) {
-          reject(error);
-        }
+        reject(signal.reason);
       };
 
+      const stopListening = listenToSocket(this.socket, signal, onData, onError, onClose, onAbort);
       const cleanup = () => {
-        clearTimeout(timeout);
-        this.socket?.off('data', onData);
-        this.socket?.off('error', onError);
-        this.socket?.off('close', onClose);
-        signal?.removeEventListener('abort', onAbort);
+        clearTimeout(timer);
+        stopListening();
       };
-
-      this.socket.on('data', onData);
-      this.socket.on('error', onError);
-      this.socket.on('close', onClose);
-      signal?.addEventListener('abort', onAbort, { once: true });
-      this.socket.write(commands.map((command) => `${command}\r\n`).join(''));
-      this.log.write(
-        'trace',
-        () => ({ commands: describeCommands(commands, this.authenticating) }),
-        'SMTP commands',
-      );
+      this.socket.write(joinCommands(commands));
+      this.traceCommands(commands);
     });
   }
 
+  traceCommands(commands) {
+    this.log.write(
+      'trace',
+      () => ({ commands: describeCommands(commands, this.authenticating) }),
+      'SMTP commands',
+    );
+  }
+
   greeting(signal) {
     if (!this.socket) {
       throw new Error('Not connected');
@@ -556,8 +621,8 @@ class SmtpConnection {
 
     return new Promise((resolve, reject) => {
       const reader = createReplyReader();
-      const replyLines = [];
-      const timeout = setTimeout(() => {
+      const collector = createReplyCollector();
+      const timer = setTimeout(() => {
         onError(new Error('Greeting timeout.'));
       }, this.config.socketTimeout);
 
@@ -572,21 +637,17 @@ class SmtpConnection {
         }
 
         for (let i = 0; i < lines.length; i++) {
-          const line = lines[i];
-          replyLines.push(line);
-          if (isFinalReplyLine(line)) {
-            const code = parseInt(line.substring(0, 3), 10);
-            const message = line.substring(4);
-
-            cleanup();
-            resolve({ code, message, raw: replyLines.join('\r\n') });
-            return;
-          }
-          if (replyLines.length > MAX_REPLY_LINES) {
+          const reply = collector.add(lines[i]);
+          if (reply === null) {
             this.socket?.destroy();
             onError(createReplyLimitError());
             return;
           }
+          if (reply !== undefined) {
+            cleanup();
+            resolve(reply);
+            return;
+          }
         }
       };
 
@@ -601,18 +662,11 @@ class SmtpConnection {
         this.socket?.destroy();
         reject(signal?.reason);
       };
+      const stopListening = listenToSocket(this.socket, signal, onData, onError, onClose, onAbort);
       const cleanup = () => {
-        clearTimeout(timeout);
-        this.socket?.off('data', onData);
-        this.socket?.off('error', onError);
-        this.socket?.off('close', onClose);
-        signal?.removeEventListener('abort', onAbort);
+        clearTimeout(timer);
+        stopListening();
       };
-
-      this.socket.on('data', onData);
-      this.socket.on('error', onError);
-      this.socket.on('close', onClose);
-      signal?.addEventListener('abort', onAbort, { once: true });
       if (signal?.aborted) onAbort();
     });
   }
@@ -718,12 +772,12 @@ class SmtpConnection {
     this.socket = tlsSocket;
     this.observeSocket(tlsSocket);
     return new Promise((resolve, reject) => {
-      const timeout = setTimeout(
+      const timer = setTimeout(
         () => fail(new Error('STARTTLS upgrade timeout.')),
         this.config.connectionTimeout,
       );
       const cleanup = () => {
-        clearTimeout(timeout);
+        clearTimeout(timer);
         tlsSocket.off('secureConnect', onSecureConnect);
         tlsSocket.off('error', fail);
         tlsSocket.off('close', onClose);
@@ -973,35 +1027,69 @@ class SmtpConnection {
     signal?.throwIfAborted();
     checkSmtpPath(message.envelope.from ?? '');
     for (const recipient of message.envelope.to) checkSmtpPath(recipient);
+    const mail = this.mailParameters(message);
+    if (!this.socket || !this.usable) {
+      throw new TypeError('SMTP connection is closed.');
+    }
+    const stream = await prepareOnSocket(
+      this.socket,
+      this.config.socketTimeout,
+      // oxlint-disable-next-line no-shadow -- upstream
+      (signal, progress) =>
+        'rawMessage' in message
+          ? prepareRawSmtpStream(
+              message.rawMessage,
+              mail.negotiate,
+              mail.checkSize,
+              progress,
+              signal,
+            )
+          : prepareMessageStream(message, mail.checkSize, progress, signal),
+      signal,
+    );
+    mail.negotiate(stream.encoding);
+    if (stream.size != null) mail.checkSize(stream.size);
+    const rejectedRecipients = await this.sendEnvelope(
+      message.envelope,
+      mail.command(stream.size),
+      signal,
+    );
+    const finalResponse = await this.sendData(stream, mail.checkSize, signal);
+    const messageId = this.extractMessageId(finalResponse.message);
+    return { messageId, rejectedRecipients };
+  }
 
-    let smtpUtf8Parameters = '';
+  /**
+   * Works out the parameters of MAIL FROM from the extensions of the server
+   * as the encoding and the size of a message become known.
+   *
+   * @param message The prepared message.
+   * @returns `negotiate(encoding)`, which asks for 8BITMIME and SMTPUTF8 as
+   * the encoding needs them, `checkSize(size, phase)` against SIZE, and
+   * `command(size)`, the MAIL FROM command.
+   * @throws {Error} If the server lacks an extension the message needs.
+   */
+  mailParameters(message) {
+    let bodyParameters = '';
     const negotiate = (encoding) => {
-      const supports = (name) => this.hasCapability(name);
       if (message.requiresSmtpUtf8 || encoding === 'utf8') {
-        if (!supports('SMTPUTF8')) {
-          throw new SmtpUtf8UnsupportedError('SMTPUTF8');
-        }
-        if (!supports('8BITMIME')) {
-          throw new SmtpUtf8UnsupportedError('8BITMIME');
-        }
-        smtpUtf8Parameters = ' BODY=8BITMIME SMTPUTF8';
+        if (!this.hasCapability('SMTPUTF8')) throw new SmtpUtf8UnsupportedError('SMTPUTF8');
+        if (!this.hasCapability('8BITMIME')) throw new SmtpUtf8UnsupportedError('8BITMIME');
+        bodyParameters = ' BODY=8BITMIME SMTPUTF8';
       } else if (encoding === '8bit') {
-        if (!supports('8BITMIME')) throw new Smtp8BitMimeUnsupportedError();
-        smtpUtf8Parameters = ' BODY=8BITMIME';
+        if (!this.hasCapability('8BITMIME')) throw new Smtp8BitMimeUnsupportedError();
+        bodyParameters = ' BODY=8BITMIME';
       }
     };
     negotiate('rawMessage' in message ? message.rawMessage.encoding : undefined);
 
     const sizeCapability = parseSizeCapability(this.capabilityLine('SIZE'));
-    let sizeParameter = '';
-
     const dsn = message.envelope.dsn;
     if (dsn != null && !/^DSN[ \t]*$/i.test(this.capabilityLine('DSN') ?? '')) {
       throw new SmtpDsnUnsupportedError();
     }
-    const mailDsnParameters =
+    const dsnParameters =
       dsn == null || dsn.mailParameters.length === 0 ? '' : ` ${dsn.mailParameters.join(' ')}`;
-
     const checkSize = (size, phase = 'preflight') => {
       if (!Number.isSafeInteger(size)) {
         throw new RangeError('Message size exceeds the safe integer range.');
@@ -1010,89 +1098,39 @@ class SmtpConnection {
         throw new SmtpMessageSizeError(size, sizeCapability.maximum, phase);
       }
     };
-    if (!this.socket || !this.usable) {
-      throw new TypeError('SMTP connection is closed.');
-    }
-    const stream =
-      'rawMessage' in message
-        ? await prepareOnSocket(
-            this.socket,
-            this.config.socketTimeout,
-            // oxlint-disable-next-line no-shadow -- upstream
-            (signal, progress) =>
-              prepareRawSmtpStream(message.rawMessage, negotiate, checkSize, progress, signal),
-            signal,
-          )
-        : 'raw' in message
-          ? {
-              size: Buffer.byteLength(message.raw) + 2,
-              // oxlint-disable-next-line no-shadow -- upstream
-              async *read(signal) {
-                signal?.throwIfAborted();
-                yield Buffer.from(message.raw + '\r\n');
-              },
-            }
-          : await prepareOnSocket(
-              this.socket,
-              this.config.socketTimeout,
-              // oxlint-disable-next-line no-shadow -- upstream
-              (signal, progress) => prepareMessageStream(message, checkSize, progress, signal),
-              signal,
-            );
-    negotiate(stream.encoding);
-    if (stream.size != null) {
-      checkSize(stream.size);
-      if (sizeCapability != null) sizeParameter = ` SIZE=${stream.size}`;
-    }
+    const command = (size) => {
+      const sizeParameter = size != null && sizeCapability != null ? ` SIZE=${size}` : '';
+      return (
+        `MAIL FROM:<${message.envelope.from ?? ''}>` +
+        `${sizeParameter}${bodyParameters}${dsnParameters}`
+      );
+    };
+    return { negotiate, checkSize, command };
+  }
 
-    const mailCommand =
-      `MAIL FROM:<${message.envelope.from ?? ''}>` +
-      `${sizeParameter}${smtpUtf8Parameters}${mailDsnParameters}`;
-    const recipientCommands = message.envelope.to.map((recipient, index) => {
-      const parameters = dsn?.recipientParameters[index] ?? [];
+  /**
+   * Sends MAIL FROM and a RCPT TO per recipient, pipelined when the server
+   * allows it.
+   *
+   * @param envelope The envelope, with its DSN parameters.
+   * @param mailCommand The MAIL FROM command.
+   * @param signal Cancellation signal.
+   * @returns The recipients the server refused while it took others.
+   * @throws {SmtpResponseError} If MAIL FROM fails, a reply is 421, or every
+   * recipient is refused.
+   */
+  async sendEnvelope(envelope, mailCommand, signal) {
+    const recipientCommands = [];
+    for (let index = 0; index < envelope.to.length; index++) {
+      const parameters = envelope.dsn?.recipientParameters[index] ?? [];
       const suffix = parameters.length === 0 ? '' : ` ${parameters.join(' ')}`;
-      return `RCPT TO:<${recipient}>${suffix}`;
-    });
-    const pipelining = this.hasCapability('PIPELINING');
-
-    let mailResponse;
-    let recipientResponses;
-    if (pipelining) {
-      try {
-        const envelopeResponses = await this.sendCommands(
-          [mailCommand, ...recipientCommands],
-          signal,
-        );
-        mailResponse = envelopeResponses[0];
-        recipientResponses = envelopeResponses.slice(1);
-      } catch (error) {
-        if (!(error instanceof SmtpPipelineTerminatedError)) {
-          throw error;
-        }
-
-        const { response, responseIndex } = error;
-        if (responseIndex === 0) {
-          throw new SmtpResponseError(
-            `MAIL FROM failed: ${response.message}`,
-            response.code,
-            'MAIL FROM',
-            response.message,
-          );
-        }
-
-        const recipient = message.envelope.to[responseIndex - 1];
-        throw new SmtpResponseError(
-          `RCPT TO failed for ${recipient}: ${response.message}`,
-          response.code,
-          'RCPT TO',
-          response.message,
-        );
-      }
-    } else {
-      mailResponse = await this.sendCommand(mailCommand, signal);
-      recipientResponses = [];
+      recipientCommands.push(`RCPT TO:<${envelope.to[index]}>${suffix}`);
     }
-
+    const pipelining = this.hasCapability('PIPELINING');
+    const replies = pipelining
+      ? await this.sendPipelinedEnvelope(envelope, mailCommand, recipientCommands, signal)
+      : [await this.sendCommand(mailCommand, signal)];
+    const mailResponse = replies[0];
     if (mailResponse.code !== 250) {
       throw new SmtpResponseError(
         `MAIL FROM failed: ${mailResponse.message}`,
@@ -1102,12 +1140,12 @@ class SmtpConnection {
       );
     }
 
-    // RCPT TO
     const rejectedRecipients = [];
-    for (const [index, recipient] of message.envelope.to.entries()) {
+    for (let index = 0; index < envelope.to.length; index++) {
       signal?.throwIfAborted();
+      const recipient = envelope.to[index];
       const rcptResponse = pipelining
-        ? recipientResponses[index]
+        ? replies[index + 1]
         : await this.sendCommand(recipientCommands[index], signal);
       if (rcptResponse.code === 421) {
         throw new SmtpResponseError(
@@ -1118,35 +1156,52 @@ class SmtpConnection {
         );
       }
       if (rcptResponse.code !== 250 && rcptResponse.code !== 251) {
-        const enhancedStatusCode = parseEnhancedSmtpStatusCode(
-          rcptResponse.code,
-          rcptResponse.message,
-        );
-        rejectedRecipients.push({
-          recipient,
-          code: rcptResponse.code,
-          response: rcptResponse.message,
-          retryable: rcptResponse.code >= 400 && rcptResponse.code < 500,
-          ...(enhancedStatusCode == null ? {} : { enhancedStatusCode }),
-        });
+        rejectedRecipients.push(describeRejection(recipient, rcptResponse));
       }
     }
+    if (rejectedRecipients.length > 0 && rejectedRecipients.length === envelope.to.length) {
+      throw everyRecipientRejected(rejectedRecipients);
+    }
+    return rejectedRecipients;
+  }
 
-    if (rejectedRecipients.length > 0 && rejectedRecipients.length === message.envelope.to.length) {
-      const rejection = rejectedRecipients.find((item) => item.retryable) ?? rejectedRecipients[0];
-      const details = rejectedRecipients
-        .map((item) => `${item.recipient}: ${item.code} ${item.response}`)
-        .join('; ');
+  // The replies to MAIL FROM and every RCPT TO, written at once (RFC 2920).
+  async sendPipelinedEnvelope(envelope, mailCommand, recipientCommands, signal) {
+    try {
+      return await this.sendCommands([mailCommand, ...recipientCommands], signal);
+    } catch (error) {
+      if (!(error instanceof SmtpPipelineTerminatedError)) {
+        throw error;
+      }
+      const { response, responseIndex } = error;
+      if (responseIndex === 0) {
+        throw new SmtpResponseError(
+          `MAIL FROM failed: ${response.message}`,
+          response.code,
+          'MAIL FROM',
+          response.message,
+        );
+      }
+      const recipient = envelope.to[responseIndex - 1];
       throw new SmtpResponseError(
-        `RCPT TO failed for every recipient: ${details}`,
-        rejection.code,
+        `RCPT TO failed for ${recipient}: ${response.message}`,
+        response.code,
         'RCPT TO',
-        rejection.response,
-        rejectedRecipients,
+        response.message,
       );
     }
+  }
 
-    // DATA
+  /**
+   * Sends DATA and the message, and reads the reply to its end.
+   *
+   * @param stream The prepared message stream.
+   * @param checkSize The SIZE check, for a source of unknown size.
+   * @param signal Cancellation signal.
+   * @returns The reply to the end of the data.
+   * @throws {SmtpResponseError} If the server refuses DATA or the message.
+   */
+  async sendData(stream, checkSize, signal) {
     const dataResponse = await this.sendCommand('DATA', signal);
     if (dataResponse.code !== 354) {
       throw new SmtpResponseError(
@@ -1156,8 +1211,6 @@ class SmtpConnection {
         dataResponse.message,
       );
     }
-
-    // Message content
     const finalResponse = await writeMessageData(
       this.socket,
       // oxlint-disable-next-line no-shadow -- upstream
@@ -1174,10 +1227,7 @@ class SmtpConnection {
         finalResponse.message,
       );
     }
-
-    // Extract message ID from response
-    const messageId = this.extractMessageId(finalResponse.message);
-    return { messageId, rejectedRecipients };
+    return finalResponse;
   }
 
   extractMessageId(response) {
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index 362b489..c3cb519 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -96,7 +96,9 @@ class SmtpTransport {
   /**
    * Callers waiting for a connection to become available, in arrival order.
    */
-  capacityWaiters = [];
+  // Callers waiting for a slot, oldest first: a Set keeps the order of
+  // insertion and drops an aborted waiter without a scan.
+  capacityWaiters = new Set();
 
   /** The current shutdown barrier; new callers wait until it completes. */
   closing;
@@ -241,12 +243,7 @@ class SmtpTransport {
       // Cleared so the catch below cannot hand the same connection back twice.
       connection = undefined;
 
-      return {
-        successful: true,
-        messageId: result.messageId,
-        provider: 'smtp',
-        rejectedRecipients: result.rejectedRecipients,
-      };
+      return sentReceipt(result);
     } catch (error) {
       if (connection != null) {
         if (connection.usable && isReusableLocalFailure(error)) {
@@ -259,7 +256,7 @@ class SmtpTransport {
       // Cancellation rejects rather than producing a receipt.
       options?.signal?.throwIfAborted();
 
-      return createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+      return failureOf(error);
     }
   }
 
@@ -288,12 +285,7 @@ class SmtpTransport {
       );
       await this.returnConnection(connection);
       connection = undefined;
-      return {
-        successful: true,
-        provider: 'smtp',
-        messageId: result.messageId,
-        rejectedRecipients: result.rejectedRecipients,
-      };
+      return sentReceipt(result);
     } catch (error) {
       if (connection != null) {
         if (connection.usable && isReusableLocalFailure(error)) {
@@ -303,7 +295,7 @@ class SmtpTransport {
         }
       }
       options?.signal?.throwIfAborted();
-      return createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+      return failureOf(error);
     }
   }
 
@@ -360,14 +352,12 @@ class SmtpTransport {
           smtpMessage = prepareMessage(message, this.config.dkim, dsn, envelope, this.config);
         } catch (error) {
           // A message that cannot be composed never reaches the connection.
-          yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+          yield failureOf(error);
           continue;
         }
 
         if (setupError !== undefined) {
-          const errorMessage =
-            setupError instanceof Error ? setupError.message : String(setupError);
-          yield createSmtpFailure(errorMessage, setupError);
+          yield failureOf(setupError);
           continue;
         }
 
@@ -383,7 +373,7 @@ class SmtpTransport {
             // Cancellation rejects rather than producing receipts.
             options?.signal?.throwIfAborted();
             setupError = error;
-            yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+            yield failureOf(error);
             continue;
           }
         }
@@ -392,12 +382,7 @@ class SmtpTransport {
           options?.signal?.throwIfAborted();
           const result = await connection.sendMessage(smtpMessage, options?.signal);
 
-          yield {
-            successful: true,
-            messageId: result.messageId,
-            provider: 'smtp',
-            rejectedRecipients: result.rejectedRecipients,
-          };
+          yield sentReceipt(result);
         } catch (error) {
           // Cancellation rejects rather than producing a receipt.
           options?.signal?.throwIfAborted();
@@ -406,7 +391,7 @@ class SmtpTransport {
             connectionValid = false;
           }
 
-          yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+          yield failureOf(error);
         }
       }
     } catch (error) {
@@ -577,8 +562,7 @@ class SmtpTransport {
       const onAbort = () => {
         // Dropping the waiter from the queue before rejecting keeps it from
         // consuming a wake-up meant for someone still waiting.
-        const index = waiters.indexOf(waiter);
-        if (index >= 0) waiters.splice(index, 1);
+        waiters.delete(waiter);
         waiter.reject(signal?.reason);
       };
       const waiter = {
@@ -592,13 +576,16 @@ class SmtpTransport {
         },
       };
       signal?.addEventListener('abort', onAbort, { once: true });
-      waiters.push(waiter);
+      waiters.add(waiter);
     });
   }
 
   /** Wakes the caller that has been waiting longest, if there is one. */
   wakeCapacityWaiter() {
-    this.capacityWaiters.shift()?.resolve();
+    const waiter = this.capacityWaiters.values().next().value;
+    if (waiter === undefined) return;
+    this.capacityWaiters.delete(waiter);
+    waiter.resolve();
   }
 
   /**
@@ -751,7 +738,9 @@ class SmtpTransport {
 
     // Slots remain reserved until their sockets close.  Previously admitted
     // capacity waiters may then send, but must discard their connections too.
-    await Promise.all(connections.map((connection) => this.discardConnection(connection)));
+    const discarding = [];
+    for (const connection of connections) discarding.push(this.discardConnection(connection));
+    await Promise.all(discarding);
     this.notifyDrained();
     await closing;
   }
@@ -777,6 +766,16 @@ class SmtpTransport {
   }
 }
 
+const sentReceipt = (result) => ({
+  successful: true,
+  messageId: result.messageId,
+  provider: 'smtp',
+  rejectedRecipients: result.rejectedRecipients,
+});
+
+const failureOf = (error) =>
+  createSmtpFailure(error instanceof Error ? error.message : String(error), error);
+
 const createSmtpFailure = (message, error) => {
   if (error instanceof SmtpDeliveryUnknownError) {
     return createFailedReceipt(message, {
@@ -796,105 +795,78 @@ const createSmtpFailure = (message, error) => {
       code: error.field === 'envelope' ? 'smtp.envelope-invalid' : 'smtp.raw-message-invalid',
     });
   }
-  if (error instanceof Smtp8BitMimeUnsupportedError) {
-    return createFailedReceipt(message, {
-      provider: 'smtp',
-      category: 'configuration',
-      retryable: false,
-      attempts: 1,
-      code: 'smtp.8bitmime-unsupported',
-      providerDetails: { missingCapability: '8BITMIME' },
-    });
-  }
-  if (error instanceof SmtpEnvelopeValidationError) {
-    return createFailedReceipt(message, {
-      provider: 'smtp',
-      code: 'smtp.envelope-invalid',
-      category: 'validation',
-      retryable: false,
-      attempts: 1,
-    });
-  }
-
-  if (error instanceof SmtpDsnValidationError) {
-    return createFailedReceipt(message, {
-      provider: 'smtp',
-      code: 'smtp.dsn-invalid',
-      category: 'validation',
-      retryable: false,
-      attempts: 1,
-    });
-  }
-
-  if (error instanceof SmtpDsnUnsupportedError) {
-    return createFailedReceipt(message, {
-      provider: 'smtp',
-      code: 'smtp.dsn-unsupported',
-      category: 'configuration',
-      retryable: false,
-      attempts: 1,
-    });
-  }
-
-  if (error instanceof SmtpAttachmentReplayError) {
-    return createFailedReceipt(message, {
-      provider: 'smtp',
-      code: 'smtp.attachment-replay-mismatch',
-      category: 'validation',
-      retryable: false,
-      attempts: 1,
-    });
-  }
-
-  if (error instanceof SmtpMessageSizeError) {
-    return createFailedReceipt(message, {
-      provider: 'smtp',
-      code: 'smtp.message-size-exceeded',
-      category: 'rejected',
-      retryable: false,
-      attempts: 1,
-      providerDetails: {
-        actualSize: error.actualSize,
-        maximumSize: error.maximumSize.toString(),
-      },
-    });
-  }
-
-  if (error instanceof SmtpUtf8UnsupportedError) {
-    return createFailedReceipt(message, {
-      provider: 'smtp',
-      code: 'smtp.smtputf8-unsupported',
-      category: 'configuration',
-      retryable: false,
-      attempts: 1,
-      providerDetails: {
-        missingCapability: error.missingCapability,
-      },
-    });
+  for (const failure of LOCAL_FAILURES) {
+    if (error instanceof failure.type) {
+      return createFailedReceipt(message, {
+        provider: 'smtp',
+        code: failure.code,
+        category: failure.category,
+        retryable: false,
+        attempts: 1,
+        providerDetails: failure.details?.(error),
+      });
+    }
   }
-
   if (error instanceof SmtpResponseError || error instanceof SmtpAuthResponseError) {
-    const enhancedStatusCode = parseEnhancedSmtpStatusCode(error.code, error.response);
-    const classification = classifySmtpReply(error.code, enhancedStatusCode);
-    return createFailedReceipt(message, {
-      provider: 'smtp',
-      code: `smtp.${error.code}`,
-      category: classification.category,
-      retryable: classification.retryable,
-      attempts: 1,
-      providerDetails: {
-        command: error.command,
-        response: error.response,
-        rejectedRecipients:
-          error instanceof SmtpResponseError ? error.rejectedRecipients : undefined,
-        ...(enhancedStatusCode == null ? {} : { enhancedStatusCode }),
-      },
-    });
+    return createReplyFailure(message, error);
   }
+  return createFailedReceipt(message, {
+    provider: 'smtp',
+    attempts: 1,
+  });
+};
 
+// Failures found before or without a reply of the server, which no retry
+// fixes: the code and category of each, and what the receipt tells of it.
+const LOCAL_FAILURES = [
+  {
+    type: Smtp8BitMimeUnsupportedError,
+    code: 'smtp.8bitmime-unsupported',
+    category: 'configuration',
+    details: () => ({ missingCapability: '8BITMIME' }),
+  },
+  { type: SmtpEnvelopeValidationError, code: 'smtp.envelope-invalid', category: 'validation' },
+  { type: SmtpDsnValidationError, code: 'smtp.dsn-invalid', category: 'validation' },
+  { type: SmtpDsnUnsupportedError, code: 'smtp.dsn-unsupported', category: 'configuration' },
+  {
+    type: SmtpAttachmentReplayError,
+    code: 'smtp.attachment-replay-mismatch',
+    category: 'validation',
+  },
+  {
+    type: SmtpMessageSizeError,
+    code: 'smtp.message-size-exceeded',
+    category: 'rejected',
+    details: (error) => ({
+      actualSize: error.actualSize,
+      maximumSize: error.maximumSize.toString(),
+    }),
+  },
+  {
+    type: SmtpUtf8UnsupportedError,
+    code: 'smtp.smtputf8-unsupported',
+    category: 'configuration',
+    details: (error) => ({ missingCapability: error.missingCapability }),
+  },
+];
+
+// A failure the server replied with, classified by its reply code and the
+// enhanced status code in its text.
+const createReplyFailure = (message, error) => {
+  const enhancedStatusCode = parseEnhancedSmtpStatusCode(error.code, error.response);
+  const classification = classifySmtpReply(error.code, enhancedStatusCode);
   return createFailedReceipt(message, {
     provider: 'smtp',
+    code: `smtp.${error.code}`,
+    category: classification.category,
+    retryable: classification.retryable,
     attempts: 1,
+    providerDetails: {
+      command: error.command,
+      response: error.response,
+      rejectedRecipients: error instanceof SmtpResponseError ? error.rejectedRecipients : undefined,
+      ...(enhancedStatusCode == null ? {} : { enhancedStatusCode }),
+    },
   });
 };
 
diff --git a/tests/helpers/smtp/convert-message.js b/tests/helpers/smtp/convert-message.js
new file mode 100644
index 0000000..d520bd2
--- /dev/null
+++ b/tests/helpers/smtp/convert-message.js
@@ -0,0 +1,30 @@
+// Ported from upyo v0.7.0 (packages/smtp/src/message-converter.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+//
+// A message composed whole into a string, with the envelope SMTP would use.
+// The transport streams a message instead, so this left src/ after the port;
+// the tests read composed messages through it.
+
+const { readAttachmentContent } = require('../../../src/core/attachment.js');
+const { prepareMimeStream } = require('../../../src/mime/stream.js');
+const { resolveSmtpEnvelope } = require('../../../src/smtp/envelope.js');
+const { prepareMessage } = require('../../../src/smtp/message-converter.js');
+
+const convertMessage = async (
+  message,
+  dkimConfig,
+  dsn,
+  resolvedEnvelope = resolveSmtpEnvelope(message),
+  signal,
+) => {
+  const plan = prepareMessage(message, dkimConfig, dsn, resolvedEnvelope);
+  const stream = await prepareMimeStream(plan, { signal });
+  const bytes = await readAttachmentContent((readSignal) => stream.read(readSignal), signal);
+  return {
+    envelope: plan.envelope,
+    raw: new TextDecoder().decode(bytes).slice(0, -2),
+    requiresSmtpUtf8: plan.requiresSmtpUtf8 || stream.encoding === 'utf8',
+  };
+};
+
+module.exports = { convertMessage };
diff --git a/tests/helpers/smtp/raw-smtp-message.js b/tests/helpers/smtp/raw-smtp-message.js
new file mode 100644
index 0000000..ba3023e
--- /dev/null
+++ b/tests/helpers/smtp/raw-smtp-message.js
@@ -0,0 +1,17 @@
+// A message for SmtpConnection.sendMessage() from a raw string, the form the
+// ported connection tests write their messages in.  It goes through the path of
+// sendRaw(), with the trailing CRLF the connection used to add to such a string
+// itself before the form left src/.
+
+const { createRawMessagePlan } = require('../../../src/core/raw-message.js');
+
+const rawSmtpMessage = ({ envelope, raw, requiresSmtpUtf8 = false }) => ({
+  envelope,
+  rawMessage: createRawMessagePlan({
+    envelope: { from: envelope.from ?? null, to: envelope.to },
+    content: new TextEncoder().encode(`${raw}\r\n`),
+  }),
+  requiresSmtpUtf8,
+});
+
+module.exports = { rawSmtpMessage };
diff --git a/tests/unit/graph.test.js b/tests/unit/graph.test.js
index 2fe0c4a..1d40cdf 100644
--- a/tests/unit/graph.test.js
+++ b/tests/unit/graph.test.js
@@ -87,7 +87,6 @@ const SUBPATHS = Object.keys(pkg.exports)
 const SUBPATH_EDGES = [
   'smtp/config.js -> mime/dkim/types.js',
   'smtp/message-converter.js -> mime/message.js',
-  'smtp/message-converter.js -> mime/stream.js',
   'smtp/message-stream.js -> mime/stream.js',
   // The transport checks the DKIM keys when it is made.
   'smtp/smtp-transport.js -> mime/dkim/sign.js',
diff --git a/tests/unit/smtp-connection.integration.test.js b/tests/unit/smtp-connection.integration.test.js
index 2c19e06..476905d 100644
--- a/tests/unit/smtp-connection.integration.test.js
+++ b/tests/unit/smtp-connection.integration.test.js
@@ -12,6 +12,9 @@ const {
 } = require('../../src/smtp/smtp-connection.js');
 const { SmtpAuthError } = require('../../src/smtp/oauth2.js');
 const { MockSmtpServer } = require('../helpers/smtp/mock-smtp-server.js');
+// Changed after the port: a message from a raw string goes through sendRaw()'s
+// path, as src/ no longer takes the string form.
+const { rawSmtpMessage } = require('../helpers/smtp/raw-smtp-message.js');
 
 describe('SMTP Connection Integration Tests', () => {
   const setupTest = async (configOverrides = {}, signal) => {
@@ -610,14 +613,16 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        await connection.sendMessage({
-          envelope: {
-            from: 'josé@example.com',
-            to: ['用户@example.com'],
-          },
-          raw: 'From: josé@example.com\r\n\r\nMessage',
-          requiresSmtpUtf8: true,
-        });
+        await connection.sendMessage(
+          rawSmtpMessage({
+            envelope: {
+              from: 'josé@example.com',
+              to: ['用户@example.com'],
+            },
+            raw: 'From: josé@example.com\r\n\r\nMessage',
+            requiresSmtpUtf8: true,
+          }),
+        );
 
         assert.ok(
           server
@@ -638,14 +643,16 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.ehlo();
 
         await assert.rejects(
-          connection.sendMessage({
-            envelope: {
-              from: 'josé@example.com',
-              to: ['recipient@example.com'],
-            },
-            raw: 'Internationalized message',
-            requiresSmtpUtf8: true,
-          }),
+          connection.sendMessage(
+            rawSmtpMessage({
+              envelope: {
+                from: 'josé@example.com',
+                to: ['recipient@example.com'],
+              },
+              raw: 'Internationalized message',
+              requiresSmtpUtf8: true,
+            }),
+          ),
           SmtpUtf8UnsupportedError,
         );
         assert.ok(
@@ -665,14 +672,16 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.ehlo();
 
         await assert.rejects(
-          connection.sendMessage({
-            envelope: {
-              from: 'sender@example.com',
-              to: ['用户@example.com'],
-            },
-            raw: 'Internationalized message',
-            requiresSmtpUtf8: true,
-          }),
+          connection.sendMessage(
+            rawSmtpMessage({
+              envelope: {
+                from: 'sender@example.com',
+                to: ['用户@example.com'],
+              },
+              raw: 'Internationalized message',
+              requiresSmtpUtf8: true,
+            }),
+          ),
           /8BITMIME/,
         );
         assert.ok(
@@ -688,23 +697,27 @@ describe('SMTP Connection Integration Tests', () => {
       const raw = 'Subject: SIZE test\r\n\r\n.안녕하세요';
       const messageSize = new TextEncoder().encode(`${raw}\r\n`).byteLength;
       try {
-        server.setCapabilities([`sIzE ${messageSize}`]);
+        // Changed after the port: the raw path negotiates the UTF-8 text it
+        // finds, which the string form sent without asking for.
+        server.setCapabilities([`sIzE ${messageSize}`, '8BITMIME', 'SMTPUTF8']);
         await connection.connect();
         await connection.greeting();
         await connection.ehlo();
 
-        await connection.sendMessage({
-          envelope: {
-            from: 'sender@example.com',
-            to: ['recipient@example.com'],
-          },
-          raw,
-        });
+        await connection.sendMessage(
+          rawSmtpMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['recipient@example.com'],
+            },
+            raw,
+          }),
+        );
 
         assert.ok(
           server
             .getReceivedCommands()
-            .includes(`MAIL FROM:<sender@example.com> SIZE=${messageSize}`),
+            .includes(`MAIL FROM:<sender@example.com> SIZE=${messageSize} BODY=8BITMIME SMTPUTF8`),
         );
       } finally {
         await teardownTest(server, connection);
@@ -722,13 +735,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.ehlo();
 
         await assert.rejects(
-          connection.sendMessage({
-            envelope: {
-              from: 'sender@example.com',
-              to: ['recipient@example.com'],
-            },
-            raw,
-          }),
+          connection.sendMessage(
+            rawSmtpMessage({
+              envelope: {
+                from: 'sender@example.com',
+                to: ['recipient@example.com'],
+              },
+              raw,
+            }),
+          ),
           new SmtpMessageSizeError(messageSize, BigInt(messageSize - 1)),
         );
         assert.ok(
@@ -749,13 +764,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        await connection.sendMessage({
-          envelope: {
-            from: 'sender@example.com',
-            to: ['recipient@example.com'],
-          },
-          raw,
-        });
+        await connection.sendMessage(
+          rawSmtpMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['recipient@example.com'],
+            },
+            raw,
+          }),
+        );
 
         assert.ok(
           server
@@ -777,13 +794,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        await connection.sendMessage({
-          envelope: {
-            from: 'sender@example.com',
-            to: ['recipient@example.com'],
-          },
-          raw,
-        });
+        await connection.sendMessage(
+          rawSmtpMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['recipient@example.com'],
+            },
+            raw,
+          }),
+        );
 
         assert.ok(
           server
@@ -803,13 +822,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        await connection.sendMessage({
-          envelope: {
-            from: 'sender@example.com',
-            to: ['recipient@example.com'],
-          },
-          raw: 'Message for a server without SIZE',
-        });
+        await connection.sendMessage(
+          rawSmtpMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['recipient@example.com'],
+            },
+            raw: 'Message for a server without SIZE',
+          }),
+        );
 
         assert.ok(server.getReceivedCommands().includes('MAIL FROM:<sender@example.com>'));
       } finally {
@@ -826,13 +847,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const sending = connection.sendMessage({
-          envelope: {
-            from: 'sender@example.com',
-            to: ['first@example.com', 'second@example.com'],
-          },
-          raw: 'Pipelined message',
-        });
+        const sending = connection.sendMessage(
+          rawSmtpMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['first@example.com', 'second@example.com'],
+            },
+            raw: 'Pipelined message',
+          }),
+        );
         // oxlint-disable-next-line no-void -- upstream
         void sending.catch(() => undefined);
 
@@ -863,13 +886,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const sending = connection.sendMessage({
-          envelope: {
-            from: 'sender@example.com',
-            to: ['first@example.com', 'second@example.com'],
-          },
-          raw: 'Sequential message',
-        });
+        const sending = connection.sendMessage(
+          rawSmtpMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['first@example.com', 'second@example.com'],
+            },
+            raw: 'Sequential message',
+          }),
+        );
         await waitForCommandCount(server, 2);
         assert.deepStrictEqual(server.getReceivedCommands().slice(-1), [
           'MAIL FROM:<sender@example.com>',
@@ -900,13 +925,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const result = await connection.sendMessage({
-          envelope: {
-            from: 'sender@example.com',
-            to: ['first@example.com', 'rejected@example.com', 'forwarded@example.com'],
-          },
-          raw: 'Mixed recipient message',
-        });
+        const result = await connection.sendMessage(
+          rawSmtpMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['first@example.com', 'rejected@example.com', 'forwarded@example.com'],
+            },
+            raw: 'Mixed recipient message',
+          }),
+        );
 
         assert.deepStrictEqual(result.rejectedRecipients, [
           {
@@ -944,13 +971,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.ehlo();
 
         await assert.rejects(
-          connection.sendMessage({
-            envelope: {
-              from: 'sender@example.com',
-              to: ['first@example.com', 'second@example.com'],
-            },
-            raw: 'Connection failure message',
-          }),
+          connection.sendMessage(
+            rawSmtpMessage({
+              envelope: {
+                from: 'sender@example.com',
+                to: ['first@example.com', 'second@example.com'],
+              },
+              raw: 'Connection failure message',
+            }),
+          ),
           (error) => {
             assert.ok(error instanceof SmtpResponseError);
             assert.strictEqual(error.code, 421);
@@ -978,13 +1007,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.ehlo();
 
         await assert.rejects(
-          connection.sendMessage({
-            envelope: {
-              from: 'sender@example.com',
-              to: ['first@example.com', 'second@example.com'],
-            },
-            raw: 'Connection failure message',
-          }),
+          connection.sendMessage(
+            rawSmtpMessage({
+              envelope: {
+                from: 'sender@example.com',
+                to: ['first@example.com', 'second@example.com'],
+              },
+              raw: 'Connection failure message',
+            }),
+          ),
           (error) => {
             assert.ok(error instanceof SmtpResponseError);
             assert.strictEqual(error.code, 421);
@@ -1012,13 +1043,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.ehlo();
 
         await assert.rejects(
-          connection.sendMessage({
-            envelope: {
-              from: 'blocked@example.com',
-              to: ['first@example.com', 'second@example.com'],
-            },
-            raw: 'Blocked sender message',
-          }),
+          connection.sendMessage(
+            rawSmtpMessage({
+              envelope: {
+                from: 'blocked@example.com',
+                to: ['first@example.com', 'second@example.com'],
+              },
+              raw: 'Blocked sender message',
+            }),
+          ),
           (error) => {
             assert.ok(error instanceof SmtpResponseError);
             assert.strictEqual(error.code, 550);
@@ -1050,13 +1083,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.ehlo();
 
         await assert.rejects(
-          connection.sendMessage({
-            envelope: {
-              from: 'sender@example.com',
-              to: ['first@example.com', 'second@example.com', 'third@example.com'],
-            },
-            raw: 'Connection failure message',
-          }),
+          connection.sendMessage(
+            rawSmtpMessage({
+              envelope: {
+                from: 'sender@example.com',
+                to: ['first@example.com', 'second@example.com', 'third@example.com'],
+              },
+              raw: 'Connection failure message',
+            }),
+          ),
           (error) => {
             assert.ok(error instanceof SmtpResponseError);
             assert.strictEqual(error.code, 421);
@@ -1080,13 +1115,15 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const sending = connection.sendMessage({
-          envelope: {
-            from: 'sender@example.com',
-            to: ['first@example.com', 'second@example.com'],
-          },
-          raw: 'Slow replies message',
-        });
+        const sending = connection.sendMessage(
+          rawSmtpMessage({
+            envelope: {
+              from: 'sender@example.com',
+              to: ['first@example.com', 'second@example.com'],
+            },
+            raw: 'Slow replies message',
+          }),
+        );
         // oxlint-disable-next-line no-void -- upstream
         void sending.catch(() => undefined);
 
@@ -1111,13 +1148,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'sender@example.com',
             to: ['recipient@example.com'],
           },
           raw: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Test\r\n\r\nHello World!',
-        };
+        });
 
         const result = await connection.sendMessage(testMessage);
 
@@ -1146,13 +1183,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'sender@example.com',
             to: ['forwarded@example.com'],
           },
           raw: 'From: sender@example.com\r\nTo: forwarded@example.com\r\nSubject: Forwarded\r\n\r\nTest message',
-        };
+        });
 
         const result = await connection.sendMessage(testMessage);
 
@@ -1170,13 +1207,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'sender@example.com',
             to: ['recipient1@example.com', 'recipient2@example.com', 'recipient3@example.com'],
           },
           raw: 'From: sender@example.com\r\nTo: recipient1@example.com\r\nSubject: Multi-recipient\r\n\r\nMultiple recipients test',
-        };
+        });
 
         const result = await connection.sendMessage(testMessage);
         assert.ok(result.messageId.length > 0);
@@ -1201,13 +1238,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'blocked@example.com',
             to: ['recipient@example.com'],
           },
           raw: 'From: blocked@example.com\r\nTo: recipient@example.com\r\nSubject: Test\r\n\r\nTest message',
-        };
+        });
 
         await assert.rejects(
           connection.sendMessage(testMessage),
@@ -1230,13 +1267,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'sender@example.com',
             to: ['invalid@example.com'],
           },
           raw: 'From: sender@example.com\r\nTo: invalid@example.com\r\nSubject: Test\r\n\r\nTest message',
-        };
+        });
 
         await assert.rejects(
           connection.sendMessage(testMessage),
@@ -1256,13 +1293,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'sender@example.com',
             to: ['recipient@example.com'],
           },
           raw: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Rejected\r\n\r\nThis will be rejected',
-        };
+        });
 
         await assert.rejects(connection.sendMessage(testMessage), /DATA failed.*Message rejected/);
       } finally {
@@ -1284,13 +1321,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'sender@example.com',
             to: ['recipient@example.com'],
           },
           raw: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Test\r\n\r\nTest message',
-        };
+        });
 
         const result = await connection.sendMessage(testMessage);
         assert.strictEqual(result.messageId, 'abc123def456@mail.example.com');
@@ -1311,13 +1348,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'sender@example.com',
             to: ['recipient@example.com'],
           },
           raw: 'Simple message',
-        };
+        });
 
         const result = await connection.sendMessage(testMessage);
 
@@ -1338,13 +1375,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.ehlo();
 
         // Send a message first
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'sender@example.com',
             to: ['recipient@example.com'],
           },
           raw: 'Test message',
-        };
+        });
 
         await connection.sendMessage(testMessage);
 
@@ -1447,13 +1484,13 @@ describe('SMTP Connection Integration Tests', () => {
         await connection.greeting();
         await connection.ehlo();
 
-        const testMessage = {
+        const testMessage = rawSmtpMessage({
           envelope: {
             from: 'sender@example.com',
             to: ['recipient@example.com'],
           },
           raw: 'From: sender@example.com\r\nTo: recipient@example.com\r\nSubject: Dot Test\r\n\r\nLine 1\r\n.Hidden line\r\nLine 3',
-        };
+        });
 
         await connection.sendMessage(testMessage);
 
diff --git a/tests/unit/smtp-message-converter.integration.test.js b/tests/unit/smtp-message-converter.integration.test.js
index 101a14d..cd4de2d 100644
--- a/tests/unit/smtp-message-converter.integration.test.js
+++ b/tests/unit/smtp-message-converter.integration.test.js
@@ -4,7 +4,9 @@
 const assert = require('node:assert/strict');
 const { Buffer } = require('node:buffer');
 const { describe, test } = require('node:test');
-const { convertMessage } = require('../../src/smtp/message-converter.js');
+// Changed after the port: convertMessage, which src/ no longer uses (it streams
+// a message), is a test helper now.
+const { convertMessage } = require('../helpers/smtp/convert-message.js');
 
 describe('Message Converter Integration Tests', () => {
   const createTestMessage = (overrides = {}) => ({
diff --git a/tests/unit/smtp-mime-regression.test.js b/tests/unit/smtp-mime-regression.test.js
index f2a7d2f..c6d2069 100644
--- a/tests/unit/smtp-mime-regression.test.js
+++ b/tests/unit/smtp-mime-regression.test.js
@@ -4,7 +4,9 @@
 const assert = require('node:assert/strict');
 const { test } = require('node:test');
 const { createMessage } = require('../../src/core/message.js');
-const { convertMessage } = require('../../src/smtp/message-converter.js');
+// Changed after the port: convertMessage, which src/ no longer uses (it streams
+// a message), is a test helper now.
+const { convertMessage } = require('../helpers/smtp/convert-message.js');
 
 for (const text of ['first\r\nsecond', 'a'.repeat(150), ('x'.repeat(60) + '\n').repeat(20)]) {
   test(`quoted-printable physical lines: ${JSON.stringify(text.slice(0, 20))}`, async () => {
diff --git a/tests/unit/smtp-transport.dkim.test.js b/tests/unit/smtp-transport.dkim.test.js
index 27ce1cb..6478860 100644
--- a/tests/unit/smtp-transport.dkim.test.js
+++ b/tests/unit/smtp-transport.dkim.test.js
@@ -3,7 +3,9 @@
 
 const assert = require('node:assert/strict');
 const { describe, test } = require('node:test');
-const { convertMessage } = require('../../src/smtp/message-converter.js');
+// Changed after the port: convertMessage, which src/ no longer uses (it streams
+// a message), is a test helper now.
+const { convertMessage } = require('../helpers/smtp/convert-message.js');
 const {
   TEST_DKIM_DOMAIN,
   TEST_DKIM_PRIVATE_KEY,

From 7680c987445ea7beee18f469c9a1b68a35a0770a Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:37:40 +0300
Subject: [PATCH 131/158] refactor(jmap): one pass over the method responses,
 raw delivery in steps

The results of Email/set and EmailSubmission/set are found in one pass
per batch instead of two finds per message; the single response of a
call id, the capable account, the drafts mailbox and the identity checks
are loops; deliverRawMessage (161 lines) is import, the existing Email
and submission, each a function; uploadRawMessage (146 lines) builds its
body, headers and result in functions of their own; the request that
submits a message and the failure of a batch lose their nested
ternaries. Behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/jmap/jmap-transport.js    | 300 ++++++++++++++++-----------------
 src/jmap/message-converter.js |  24 ++-
 src/jmap/raw-delivery.js      | 303 ++++++++++++++++++----------------
 src/jmap/raw-upload.js        | 301 ++++++++++++++++++---------------
 4 files changed, 489 insertions(+), 439 deletions(-)

diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index 9e9ba65..f3b7098 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -4,7 +4,7 @@
 const { combineSignals } = require('../core/abort-signal.js');
 const { createRawMessagePlan, RawMessageValidationError } = require('../core/raw-message.js');
 const { deliverRawMessage, rawDiscoveryResult } = require('./raw-delivery.js');
-const { isRecord, rawOperation } = require('./raw-upload.js');
+const { findOnlyResponse, isRecord, rawOperation } = require('./raw-upload.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { createFailedReceipt } = require('../core/receipt.js');
 const { uploadBlob } = require('./blob-uploader.js');
@@ -89,7 +89,7 @@ class JmapTransport {
       if (this.config.baseUrl) session = this.rewriteSessionUrls(session);
       validateVerificationApiUrl(session.apiUrl);
       checkSessionUrls(session, this.config);
-      if (!Object.values(JMAP_CAPABILITIES).every((cap) => cap in session.capabilities)) {
+      if (!hasRequiredCapabilities(session.capabilities)) {
         throw new JmapApiError('JMAP session lacks core, mail, or submission capability.');
       }
       const accountId = this.config.accountId ?? findMailAccount(session);
@@ -127,7 +127,7 @@ class JmapTransport {
         return verificationResult(response, method, accountId);
       };
       const mailboxes = await get('Mailbox/get', { properties: ['id', 'role'] }, signal);
-      if (!mailboxes.list.some((mailbox) => mailbox.role === 'drafts')) {
+      if (findDraftsMailbox(mailboxes.list, false) === undefined) {
         throw new JmapApiError(`No drafts mailbox found in JMAP account: ${accountId}`);
       }
       const identityId = this.config.identityId;
@@ -142,9 +142,7 @@ class JmapTransport {
       if (
         identities.notFound.length > 0 ||
         identities.list.length === 0 ||
-        !identities.list.every(
-          (identity) => typeof identity.email === 'string' && identity.email.length > 0,
-        ) ||
+        !haveEmails(identities.list) ||
         (identityId != null &&
           (identities.list.length !== 1 || identities.list[0].id !== identityId))
       ) {
@@ -216,32 +214,7 @@ class JmapTransport {
       const response = await executeSubmission(
         this.submissionClient,
         session.apiUrl,
-        {
-          using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.mail, JMAP_CAPABILITIES.submission],
-          methodCalls: [
-            [
-              'Email/set',
-              {
-                accountId,
-                create: { draft: emailCreate },
-              },
-              'c0',
-            ],
-            [
-              'EmailSubmission/set',
-              {
-                accountId,
-                create: {
-                  submission: {
-                    identityId,
-                    emailId: '#draft',
-                  },
-                },
-              },
-              'c1',
-            ],
-          ],
-        },
+        submissionRequest(accountId, emailCreate, identityId),
         signal,
       );
 
@@ -298,11 +271,11 @@ class JmapTransport {
           JMAP_CAPABILITIES.submission in account.accountCapabilities
         );
       };
-      const accountId = this.config.accountId ?? Object.keys(session.accounts).find(capable);
+      const accountId = this.config.accountId ?? findAccount(session.accounts, capable);
       if (
         accountId == null ||
         !capable(accountId) ||
-        !Object.values(JMAP_CAPABILITIES).every((capability) => capability in session.capabilities)
+        !hasRequiredCapabilities(session.capabilities)
       ) {
         return createJmapFailure('No writable mail and submission account found.', undefined, {
           category: 'configuration',
@@ -501,9 +474,10 @@ class JmapTransport {
         signal,
       );
 
-      // Parse batch response and yield individual receipts
+      // The results of the sets are found once for the whole batch.
+      const results = setResultsOf(response);
       for (let i = 0; i < batch.length; i++) {
-        yield this.parseBatchResponseForIndex(response, i);
+        yield this.parseBatchResponseForIndex(results, i);
       }
     } catch (error) {
       for (const failure of this.failBatch(
@@ -539,14 +513,10 @@ class JmapTransport {
 
     // For any error during batch processing, yield failure for all messages
     // with detailed stage information
-    const baseMessage =
-      error instanceof Error && error.name === 'AbortError'
-        ? `Request aborted: ${error.message}`
-        : error instanceof JmapApiError
-          ? error.message
-          : error instanceof Error
-            ? error.message
-            : String(error);
+    let baseMessage = error instanceof Error ? error.message : String(error);
+    if (error instanceof Error && error.name === 'AbortError') {
+      baseMessage = `Request aborted: ${error.message}`;
+    }
 
     // Build detailed error message with stage and progress info
     let detailedMessage = `Failed during ${processingStage}: ${baseMessage}`;
@@ -657,7 +627,7 @@ class JmapTransport {
 
     const mailboxResponse = strict
       ? rawDiscoveryResult(response, 'Mailbox/get', accountId)
-      : response.methodResponses.find((r) => r[0] === 'Mailbox/get')?.[1];
+      : findMethodResponse(response.methodResponses, 'Mailbox/get')?.[1];
 
     if (!mailboxResponse) {
       throw new JmapApiError('No Mailbox/get response received');
@@ -669,17 +639,7 @@ class JmapTransport {
       throw new JmapApiError('No mailboxes found');
     }
 
-    if (
-      strict &&
-      (!Array.isArray(mailboxes) ||
-        !mailboxes.every(
-          (mailbox) => isRecord(mailbox) && typeof mailbox.id === 'string' && mailbox.id.length > 0,
-        ))
-    ) {
-      throw new JmapApiError('Invalid mailbox identifiers in raw discovery.');
-    }
-    // Find drafts mailbox
-    const drafts = mailboxes.find((m) => m.role === 'drafts');
+    const drafts = findDraftsMailbox(mailboxes, strict);
 
     if (!drafts) {
       throw new JmapApiError('No drafts mailbox found');
@@ -744,7 +704,7 @@ class JmapTransport {
 
     const identityResponse = strict
       ? rawDiscoveryResult(response, 'Identity/get', accountId)
-      : response.methodResponses.find((r) => r[0] === 'Identity/get')?.[1];
+      : findMethodResponse(response.methodResponses, 'Identity/get')?.[1];
 
     if (!identityResponse) {
       throw new JmapApiError('No Identity/get response received');
@@ -756,21 +716,14 @@ class JmapTransport {
       throw new JmapApiError('No identities found');
     }
 
-    if (
-      strict &&
-      (!Array.isArray(identities) ||
-        !identities.every(
-          (identity) =>
-            isRecord(identity) &&
-            typeof identity.id === 'string' &&
-            identity.id.length > 0 &&
-            typeof identity.email === 'string',
-        ))
-    ) {
+    if (strict && !Array.isArray(identities)) {
       throw new JmapApiError('Invalid identity identifiers in raw discovery.');
     }
     const identityMap = new Map();
     for (const identity of identities) {
+      if (strict && !isIdentity(identity)) {
+        throw new JmapApiError('Invalid identity identifiers in raw discovery.');
+      }
       identityMap.set(identity.email.toLowerCase(), identity.id);
     }
 
@@ -818,48 +771,15 @@ class JmapTransport {
    */
   parseResponse(response) {
     const errors = [];
-
-    // Check Email/set response
-    const emailResponse = response.methodResponses.find((r) => r[0] === 'Email/set');
-
-    if (emailResponse) {
-      const emailResult = emailResponse[1];
-
-      if (emailResult.notCreated) {
-        for (const [key, error] of Object.entries(emailResult.notCreated)) {
-          errors.push(
-            `Email creation failed (${key}): ${error.type}${
-              error.description ? ` - ${error.description}` : ''
-            }`,
-          );
-        }
-      }
+    const { email, submission } = setResultsOf(response);
+    for (const key in email?.notCreated) {
+      errors.push(describeSetError(`Email creation failed (${key})`, email.notCreated[key]));
     }
-
-    // Check EmailSubmission/set response
-    const submissionResponse = response.methodResponses.find((r) => r[0] === 'EmailSubmission/set');
-
-    if (submissionResponse) {
-      const submissionResult = submissionResponse[1];
-
-      if (submissionResult.notCreated) {
-        for (const [key, error] of Object.entries(submissionResult.notCreated)) {
-          errors.push(
-            `Email submission failed (${key}): ${error.type}${
-              error.description ? ` - ${error.description}` : ''
-            }`,
-          );
-        }
-      }
-
-      // Success case
-      if (submissionResult.created?.submission) {
-        return {
-          successful: true,
-          messageId: submissionResult.created.submission.id,
-          provider: 'jmap',
-        };
-      }
+    for (const key in submission?.notCreated) {
+      errors.push(describeSetError(`Email submission failed (${key})`, submission.notCreated[key]));
+    }
+    if (submission?.created?.submission) {
+      return { successful: true, messageId: submission.created.submission.id, provider: 'jmap' };
     }
 
     // If no errors but no success either, something is wrong
@@ -876,55 +796,24 @@ class JmapTransport {
   }
 
   /**
-   * Parses the JMAP batch response to extract receipt for a specific index.
-   * @param response The JMAP response.
+   * Gives the receipt of one message of a batch from the results of its sets.
+   * @param results The Email/set and EmailSubmission/set results of the batch.
    * @param index The message index in the batch.
    * @returns A receipt indicating success or failure for that message.
    */
-  parseBatchResponseForIndex(response, index) {
+  parseBatchResponseForIndex(results, index) {
     const errors = [];
     const draftKey = `draft${index}`;
     const subKey = `sub${index}`;
-
-    // Check Email/set response
-    const emailResponse = response.methodResponses.find((r) => r[0] === 'Email/set');
-
-    if (emailResponse) {
-      const emailResult = emailResponse[1];
-
-      if (emailResult.notCreated?.[draftKey]) {
-        const error = emailResult.notCreated[draftKey];
-        errors.push(
-          `Email creation failed: ${error.type}${
-            error.description ? ` - ${error.description}` : ''
-          }`,
-        );
-      }
+    const { email, submission } = results;
+    if (email?.notCreated?.[draftKey]) {
+      errors.push(describeSetError('Email creation failed', email.notCreated[draftKey]));
     }
-
-    // Check EmailSubmission/set response
-    const submissionResponse = response.methodResponses.find((r) => r[0] === 'EmailSubmission/set');
-
-    if (submissionResponse) {
-      const submissionResult = submissionResponse[1];
-
-      if (submissionResult.notCreated?.[subKey]) {
-        const error = submissionResult.notCreated[subKey];
-        errors.push(
-          `Email submission failed: ${error.type}${
-            error.description ? ` - ${error.description}` : ''
-          }`,
-        );
-      }
-
-      // Success case
-      if (submissionResult.created?.[subKey]) {
-        return {
-          successful: true,
-          messageId: submissionResult.created[subKey].id,
-          provider: 'jmap',
-        };
-      }
+    if (submission?.notCreated?.[subKey]) {
+      errors.push(describeSetError('Email submission failed', submission.notCreated[subKey]));
+    }
+    if (submission?.created?.[subKey]) {
+      return { successful: true, messageId: submission.created[subKey].id, provider: 'jmap' };
     }
 
     // If no errors but no success either
@@ -941,6 +830,100 @@ class JmapTransport {
   }
 }
 
+const REQUIRED_CAPABILITIES = [
+  JMAP_CAPABILITIES.core,
+  JMAP_CAPABILITIES.mail,
+  JMAP_CAPABILITIES.submission,
+];
+
+const hasRequiredCapabilities = (capabilities) => {
+  for (const capability of REQUIRED_CAPABILITIES) {
+    if (!(capability in capabilities)) return false;
+  }
+  return true;
+};
+
+// The first account, in the order of the Session, that `capable` accepts.
+const findAccount = (accounts, capable) => {
+  for (const id in accounts) {
+    if (Object.hasOwn(accounts, id) && capable(id)) return id;
+  }
+  return undefined;
+};
+
+const findMethodResponse = (methodResponses, method) => {
+  for (const entry of methodResponses) {
+    if (entry[0] === method) return entry;
+  }
+  return undefined;
+};
+
+// The results of the first Email/set and EmailSubmission/set of a response,
+// found in one pass.
+const setResultsOf = (response) => {
+  let email;
+  let submission;
+  for (const entry of response.methodResponses) {
+    if (entry[0] === 'Email/set') email ??= entry[1];
+    else if (entry[0] === 'EmailSubmission/set') submission ??= entry[1];
+  }
+  return { email, submission };
+};
+
+const describeSetError = (prefix, error) =>
+  `${prefix}: ${error.type}${error.description ? ` - ${error.description}` : ''}`;
+
+/**
+ * Finds the drafts mailbox, checking every mailbox of a raw discovery.
+ *
+ * @param mailboxes The mailboxes of the account.
+ * @param strict Whether each mailbox must carry an identifier.
+ * @returns The first mailbox with the drafts role, if any.
+ * @throws {JmapApiError} If a strict discovery has an invalid mailbox.
+ */
+const findDraftsMailbox = (mailboxes, strict) => {
+  if (strict && !Array.isArray(mailboxes)) {
+    throw new JmapApiError('Invalid mailbox identifiers in raw discovery.');
+  }
+  let drafts;
+  for (const mailbox of mailboxes) {
+    if (strict && !(isRecord(mailbox) && typeof mailbox.id === 'string' && mailbox.id !== '')) {
+      throw new JmapApiError('Invalid mailbox identifiers in raw discovery.');
+    }
+    if (drafts === undefined && mailbox.role === 'drafts') {
+      drafts = mailbox;
+      if (!strict) break;
+    }
+  }
+  return drafts;
+};
+
+const haveEmails = (identities) => {
+  for (const identity of identities) {
+    if (typeof identity.email !== 'string' || identity.email.length === 0) return false;
+  }
+  return true;
+};
+
+const isIdentity = (identity) =>
+  isRecord(identity) &&
+  typeof identity.id === 'string' &&
+  identity.id.length > 0 &&
+  typeof identity.email === 'string';
+
+// The request that creates the draft of one message and submits it.
+const submissionRequest = (accountId, emailCreate, identityId) => ({
+  using: REQUIRED_CAPABILITIES,
+  methodCalls: [
+    ['Email/set', { accountId, create: { draft: emailCreate } }, 'c0'],
+    [
+      'EmailSubmission/set',
+      { accountId, create: { submission: { identityId, emailId: '#draft' } } },
+      'c1',
+    ],
+  ],
+});
+
 // Sends the request that creates and submits emails.  A failure without an
 // answer from the server, unless the connection was never made, leaves it
 // unknown whether the server submitted them.
@@ -1104,13 +1087,10 @@ const verificationResult = (response, method, accountId) => {
   if (!isRecord(response) || !Array.isArray(response.methodResponses)) {
     throw new JmapApiError('Invalid JMAP verification response.');
   }
-  const matches = response.methodResponses.filter(
-    (entry) => Array.isArray(entry) && entry[2] === 'verify',
-  );
-  if (matches.length !== 1) {
+  const entry = findOnlyResponse(response.methodResponses, 'verify');
+  if (entry === undefined) {
     throw new JmapApiError('Missing or duplicate JMAP verification response.');
   }
-  const entry = matches[0];
   if (!Array.isArray(entry) || entry.length !== 3 || !isRecord(entry[1])) {
     throw new JmapApiError('Invalid JMAP verification method response.');
   }
@@ -1138,10 +1118,12 @@ const verificationResult = (response, method, accountId) => {
   }
   const list = [];
   const ids = new Set();
+  let roles = true;
   for (const item of result.list) {
     if (!isRecord(item) || typeof item.id !== 'string' || !item.id || ids.has(item.id)) {
       throw new JmapApiError(`Invalid JMAP discovery identifiers: ${method}`);
     }
+    if (item.role != null && typeof item.role !== 'string') roles = false;
     ids.add(item.id);
     list.push(item);
   }
@@ -1153,11 +1135,7 @@ const verificationResult = (response, method, accountId) => {
     ids.add(id);
     notFound.push(id);
   }
-  if (
-    method === 'Mailbox/get' &&
-    (notFound.length > 0 ||
-      !list.every((item) => item.role == null || typeof item.role === 'string'))
-  ) {
+  if (method === 'Mailbox/get' && (notFound.length > 0 || !roles)) {
     throw new JmapApiError('Invalid JMAP mailbox discovery result.');
   }
   return { list, notFound };
diff --git a/src/jmap/message-converter.js b/src/jmap/message-converter.js
index 604bbf8..92bc534 100644
--- a/src/jmap/message-converter.js
+++ b/src/jmap/message-converter.js
@@ -275,16 +275,16 @@ const convertMessage = (message, draftMailboxId, uploadedBlobs) => {
     bodyStructure,
     bodyValues,
     ...(message.recipients.length > 0 && {
-      to: message.recipients.map(formatAddress),
+      to: formatAddresses(message.recipients),
     }),
     ...(message.ccRecipients.length > 0 && {
-      cc: message.ccRecipients.map(formatAddress),
+      cc: formatAddresses(message.ccRecipients),
     }),
     ...(message.bccRecipients.length > 0 && {
-      bcc: message.bccRecipients.map(formatAddress),
+      bcc: formatAddresses(message.bccRecipients),
     }),
     ...(message.replyRecipients.length > 0 && {
-      replyTo: message.replyRecipients.map(formatAddress),
+      replyTo: formatAddresses(message.replyRecipients),
     }),
     ...identity.properties,
     ...headerProperties,
@@ -293,6 +293,18 @@ const convertMessage = (message, draftMailboxId, uploadedBlobs) => {
   return email;
 };
 
+const formatAddresses = (addresses) => {
+  const formatted = [];
+  for (const address of addresses) formatted.push(formatAddress(address));
+  return formatted;
+};
+
+const checkMessageIds = (ids) => {
+  const checked = [];
+  for (const id of ids) checked.push(checkMessageId(id));
+  return checked;
+};
+
 /**
  * Works out the identity and threading properties of an `Email` from the typed
  * fields of a message.
@@ -329,13 +341,13 @@ const resolveIdentity = (message) => {
   if (message.inReplyTo != null) {
     owned.add('in-reply-to');
     if (message.inReplyTo.length > 0) {
-      properties.inReplyTo = message.inReplyTo.map(checkMessageId);
+      properties.inReplyTo = checkMessageIds(message.inReplyTo);
     }
   }
   if (message.references != null) {
     owned.add('references');
     if (message.references.length > 0) {
-      properties.references = message.references.map(checkMessageId);
+      properties.references = checkMessageIds(message.references);
     }
   }
 
diff --git a/src/jmap/raw-delivery.js b/src/jmap/raw-delivery.js
index 0fe6dd9..690507e 100644
--- a/src/jmap/raw-delivery.js
+++ b/src/jmap/raw-delivery.js
@@ -5,7 +5,7 @@ const { createFailedReceipt } = require('../core/receipt.js');
 const { RawMessageValidationError } = require('../core/raw-message.js');
 const { JMAP_ERROR_TYPES, JmapApiError } = require('./errors.js');
 const { JmapHttpClient } = require('./http-client.js');
-const { isRecord, rawOperation, uploadRawMessage } = require('./raw-upload.js');
+const { findOnlyResponse, isRecord, rawOperation, uploadRawMessage } = require('./raw-upload.js');
 
 const using = [
   'urn:ietf:params:jmap:core',
@@ -14,14 +14,13 @@ const using = [
 ];
 
 const failure = (message, stage, retryable, unknown = false, error) => {
+  let category;
+  if (unknown) category = 'unknown';
+  else if (error?.statusCode === undefined && !retryable) category = 'rejected';
   return createFailedReceipt(message, {
     provider: 'jmap',
     code: `jmap.raw_${stage}_${unknown ? 'unknown' : 'failed'}`,
-    category: unknown
-      ? 'unknown'
-      : error?.statusCode !== undefined || retryable
-        ? undefined
-        : 'rejected',
+    category,
     statusCode: error?.statusCode,
     retryAfterMilliseconds: error?.retryAfterMilliseconds,
     providerDetails: error
@@ -39,13 +38,10 @@ const methodResult = (response, name, id, accountId) => {
   if (!isRecord(response) || !Array.isArray(response.methodResponses)) {
     throw new JmapApiError('Invalid raw JMAP method response.');
   }
-  const matches = response.methodResponses.filter(
-    (entry) => Array.isArray(entry) && entry[2] === id,
-  );
-  if (matches.length !== 1) {
+  const result = findOnlyResponse(response.methodResponses, id);
+  if (result === undefined) {
     throw new JmapApiError('Missing or contradictory raw JMAP method response.');
   }
-  const result = matches[0];
   if (
     !Array.isArray(result) ||
     result.length !== 3 ||
@@ -136,146 +132,167 @@ const deliverRawMessage = async (
     const uploaded = await uploadRawMessage(config, session.uploadUrl, accountId, plan, signal);
     signal?.throwIfAborted();
     stage = 'import';
-    const imported = methodResult(
-      await execute({
-        using,
-        methodCalls: [
-          [
-            'Email/import',
-            {
-              accountId,
-              emails: {
-                raw: {
-                  blobId: uploaded.blobId,
-                  mailboxIds: { [draftsMailboxId]: true },
-                },
-              },
-            },
-            'raw-import',
-          ],
-        ],
-      }),
-      'Email/import',
-      'raw-import',
-      accountId,
-    );
-    if (imported.name === 'error') {
-      return failure(
-        errorDescription(imported.args),
-        'import',
-        imported.args.type === 'serverPartialFail',
-      );
-    }
-    const { created, rejected } = creation(imported.args);
-    let emailId;
-    if (created && typeof created.id === 'string') emailId = created.id;
-    else if (
-      rejected?.type === 'alreadyExists' &&
-      typeof rejected.existingId === 'string' &&
-      rejected.existingId
-    ) {
-      const existing = methodResult(
-        await execute({
-          using,
-          methodCalls: [
-            [
-              'Email/get',
-              {
-                accountId,
-                ids: [rejected.existingId],
-                properties: ['id', 'blobId'],
-              },
-              'raw-existing',
-            ],
-          ],
-        }),
-        'Email/get',
-        'raw-existing',
-        accountId,
-      );
-      const list = existing.args.list;
-      if (
-        existing.name === 'error' ||
-        !Array.isArray(list) ||
-        list.length !== 1 ||
-        !isRecord(list[0]) ||
-        list[0].id !== rejected.existingId ||
-        list[0].blobId !== uploaded.blobId
-      ) {
-        return failure('Existing Email does not match the uploaded raw blob.', 'import', false);
-      }
-      emailId = rejected.existingId;
-    } else {
-      return failure(errorDescription(rejected ?? { type: 'invalidResult' }), 'import', false);
-    }
+    const emailId = await importRawEmail(execute, accountId, draftsMailboxId, uploaded.blobId);
+    if (typeof emailId !== 'string') return emailId;
     signal?.throwIfAborted();
     stage = 'submission';
-    const submitted = methodResult(
-      await execute({
-        using,
-        methodCalls: [
-          [
-            'EmailSubmission/set',
-            {
-              accountId,
-              create: {
-                raw: {
-                  emailId,
-                  identityId,
-                  envelope: {
-                    mailFrom: { email: plan.envelope.from ?? '' },
-                    rcptTo: plan.envelope.to.map((email) => ({ email })),
-                  },
-                },
+    const receipt = await submitRawEmail(execute, accountId, emailId, identityId, plan.envelope);
+    if (receipt.successful) signal?.throwIfAborted();
+    return receipt;
+  } catch (error) {
+    signal?.throwIfAborted();
+    return rawDeliveryFailure(error, stage);
+  }
+};
+
+/**
+ * Imports the uploaded blob into the drafts mailbox, or finds the Email the
+ * server already holds for it.
+ *
+ * @returns The id of the Email, or the receipt of a failure.
+ */
+const importRawEmail = async (execute, accountId, draftsMailboxId, blobId) => {
+  const imported = methodResult(
+    await execute({
+      using,
+      methodCalls: [
+        [
+          'Email/import',
+          {
+            accountId,
+            emails: { raw: { blobId, mailboxIds: { [draftsMailboxId]: true } } },
+          },
+          'raw-import',
+        ],
+      ],
+    }),
+    'Email/import',
+    'raw-import',
+    accountId,
+  );
+  if (imported.name === 'error') {
+    return failure(
+      errorDescription(imported.args),
+      'import',
+      imported.args.type === 'serverPartialFail',
+    );
+  }
+  const { created, rejected } = creation(imported.args);
+  if (created && typeof created.id === 'string') return created.id;
+  if (
+    rejected?.type === 'alreadyExists' &&
+    typeof rejected.existingId === 'string' &&
+    rejected.existingId
+  ) {
+    return existingEmailId(execute, accountId, rejected.existingId, blobId);
+  }
+  return failure(errorDescription(rejected ?? { type: 'invalidResult' }), 'import', false);
+};
+
+// The Email the server already holds, if it is the one of the uploaded blob.
+const existingEmailId = async (execute, accountId, existingId, blobId) => {
+  const existing = methodResult(
+    await execute({
+      using,
+      methodCalls: [
+        [
+          'Email/get',
+          { accountId, ids: [existingId], properties: ['id', 'blobId'] },
+          'raw-existing',
+        ],
+      ],
+    }),
+    'Email/get',
+    'raw-existing',
+    accountId,
+  );
+  const list = existing.args.list;
+  if (
+    existing.name === 'error' ||
+    !Array.isArray(list) ||
+    list.length !== 1 ||
+    !isRecord(list[0]) ||
+    list[0].id !== existingId ||
+    list[0].blobId !== blobId
+  ) {
+    return failure('Existing Email does not match the uploaded raw blob.', 'import', false);
+  }
+  return existingId;
+};
+
+/**
+ * Submits the imported Email once with the envelope of the plan.
+ *
+ * @returns The receipt of the submission.
+ * @throws {JmapApiError} If the server answers without a submission id.
+ */
+const submitRawEmail = async (execute, accountId, emailId, identityId, envelope) => {
+  const rcptTo = [];
+  for (const email of envelope.to) rcptTo.push({ email });
+  const submitted = methodResult(
+    await execute({
+      using,
+      methodCalls: [
+        [
+          'EmailSubmission/set',
+          {
+            accountId,
+            create: {
+              raw: {
+                emailId,
+                identityId,
+                envelope: { mailFrom: { email: envelope.from ?? '' }, rcptTo },
               },
             },
-            'raw-submit',
-          ],
+          },
+          'raw-submit',
         ],
-      }),
-      'EmailSubmission/set',
-      'raw-submit',
-      accountId,
-    );
-    if (submitted.name === 'error') {
-      // RFC 8620 permits partial state changes for serverPartialFail.
-      return failure(
-        errorDescription(submitted.args),
-        'submission',
-        false,
-        submitted.args.type === 'serverPartialFail',
-      );
-    }
-    const result = creation(submitted.args);
-    if (result.rejected) {
-      return failure(errorDescription(result.rejected), 'submission', false);
-    }
-    if (!result.created || typeof result.created.id !== 'string') {
-      throw new JmapApiError('Missing raw submission ID.');
-    }
-    signal?.throwIfAborted();
-    return { successful: true, provider: 'jmap', messageId: result.created.id };
-  } catch (error) {
-    signal?.throwIfAborted();
-    const message = error instanceof Error ? error.message : String(error);
-    if (error instanceof RawMessageValidationError) {
-      return createFailedReceipt(message, {
-        provider: 'jmap',
-        code: 'jmap.raw_message_invalid',
-        category: 'validation',
-        retryable: false,
-        attempts: 1,
-      });
-    }
-    const definite = isRequestRejection(error);
+      ],
+    }),
+    'EmailSubmission/set',
+    'raw-submit',
+    accountId,
+  );
+  if (submitted.name === 'error') {
+    // RFC 8620 permits partial state changes for serverPartialFail.
     return failure(
-      message,
-      stage,
-      stage !== 'submission' && !definite,
-      stage === 'submission' && !definite,
-      error instanceof JmapApiError ? error : undefined,
+      errorDescription(submitted.args),
+      'submission',
+      false,
+      submitted.args.type === 'serverPartialFail',
     );
   }
+  const result = creation(submitted.args);
+  if (result.rejected) {
+    return failure(errorDescription(result.rejected), 'submission', false);
+  }
+  if (!result.created || typeof result.created.id !== 'string') {
+    throw new JmapApiError('Missing raw submission ID.');
+  }
+  return { successful: true, provider: 'jmap', messageId: result.created.id };
+};
+
+// A failure of a stage that threw: a definite rejection before submission may
+// be retried, and a submission without a definite answer may have gone.
+const rawDeliveryFailure = (error, stage) => {
+  const message = error instanceof Error ? error.message : String(error);
+  if (error instanceof RawMessageValidationError) {
+    return createFailedReceipt(message, {
+      provider: 'jmap',
+      code: 'jmap.raw_message_invalid',
+      category: 'validation',
+      retryable: false,
+      attempts: 1,
+    });
+  }
+  const definite = isRequestRejection(error);
+  return failure(
+    message,
+    stage,
+    stage !== 'submission' && !definite,
+    stage === 'submission' && !definite,
+    error instanceof JmapApiError ? error : undefined,
+  );
 };
 
 /** Validates raw discovery responses before accepting delivery identifiers. @internal */
diff --git a/src/jmap/raw-upload.js b/src/jmap/raw-upload.js
index 7a1923e..bf9f3ca 100644
--- a/src/jmap/raw-upload.js
+++ b/src/jmap/raw-upload.js
@@ -51,6 +51,18 @@ const isRecord = (value) => {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 };
 
+// The one method response with a call id, or `undefined` when there is none
+// or more than one.
+const findOnlyResponse = (methodResponses, id) => {
+  let found;
+  for (const entry of methodResponses) {
+    if (!Array.isArray(entry) || entry[2] !== id) continue;
+    if (found !== undefined) return undefined;
+    found = entry;
+  }
+  return found;
+};
+
 /** Streams validated MIME bytes without relying on fetch to cancel its body. @internal */
 const uploadRawMessage = async (config, uploadUrl, accountId, plan, signal) => {
   return await rawOperation(
@@ -61,147 +73,178 @@ const uploadRawMessage = async (config, uploadUrl, accountId, plan, signal) => {
           ? await analyzeRawMessage(plan, outerSignal, progress)
           : { encoding: plan.encoding, size: plan.size };
       outerSignal.throwIfAborted();
-      const controller = new AbortController();
-      const combined = combineSignals(controller.signal, outerSignal);
-      const owned = combined.signal;
-      const iterator = iterateRawMessage(plan, {
-        signal: owned,
-        encoding: analysis.encoding,
-        expectedSize: analysis.size,
-        onProgress: progress,
-      })[Symbol.asyncIterator]();
-      let closed = false;
-      let eof = false;
-      let size = 0;
-      let sourceError;
-      let hasSourceError = false;
-      let bodyController;
-      const close = (reason) => {
-        if (closed) return;
-        closed = true;
-        controller.abort(reason);
-        if (!eof) {
-          try {
-            Promise.resolve(iterator.return?.()).catch(() => {});
-          } catch {
-            /* Preserve the original failure. */
-          }
-        }
-      };
-      const abort = () => {
-        try {
-          bodyController?.error(owned.reason);
-        } catch {
-          /* Already closed. */
-        }
-        close(owned.reason);
-      };
-      const body = new ReadableStream(
-        {
-          start(stream) {
-            bodyController = stream;
-            owned.addEventListener('abort', abort, { once: true });
-            if (owned.aborted) abort();
-          },
-          async pull(stream) {
-            try {
-              owned.throwIfAborted();
-              const item = await iterator.next();
-              owned.throwIfAborted();
-              if (item.done) {
-                eof = true;
-                progress();
-                stream.close();
-              } else {
-                size += item.value.length;
-                stream.enqueue(new Uint8Array(item.value));
-              }
-            } catch (error) {
-              if (!owned.aborted && !hasSourceError) {
-                hasSourceError = true;
-                sourceError = error;
-              }
-              try {
-                stream.error(error);
-              } catch {
-                /* Already closed. */
-              }
-              close(error);
-            }
-          },
-          cancel: close,
-        },
-        { highWaterMark: 0 },
-      );
-      const headers = new Headers(config.headers);
-      if (!headers.has('Authorization')) {
-        if (config.bearerToken) {
-          headers.set('Authorization', `Bearer ${config.bearerToken}`);
-        } else if (config.basicAuth) {
-          headers.set(
-            'Authorization',
-            `Basic ${Buffer.from(`${config.basicAuth.username}:${config.basicAuth.password}`).toString('base64')}`,
-          );
-        }
-      }
-      headers.set('Content-Type', 'message/rfc822');
-      const request = {
-        method: 'POST',
-        headers,
-        body,
-        duplex: 'half',
-        redirect: 'error',
-        // Runtime cancellation of the request body must not discard a response.
-        // The owned signal stops source reads; the outer signal controls HTTP.
-        signal: outerSignal,
-      };
+      const source = createRawUploadBody(plan, analysis, outerSignal, progress);
       try {
         const response = await (config.fetch ?? globalThis.fetch)(
           uploadUrl.replace('{accountId}', encodeURIComponent(accountId)),
-          request,
+          {
+            method: 'POST',
+            headers: uploadHeaders(config),
+            body: source.body,
+            duplex: 'half',
+            redirect: 'error',
+            // Runtime cancellation of the request body must not discard a
+            // response. The owned signal stops source reads; the outer signal
+            // controls HTTP.
+            signal: outerSignal,
+          },
         );
         outerSignal.throwIfAborted();
-        if (!response.ok) {
-          throw new JmapApiError(
-            `Raw upload failed: ${response.status}`,
-            response.status,
-            await readText(response),
-            undefined,
-            parseRetryAfter(response.headers.get('Retry-After')),
-          );
-        }
-        if (!eof) {
-          throw new JmapApiError('Raw upload responded before validated EOF.');
-        }
-        const result = await readJson(response);
-        outerSignal.throwIfAborted();
-        if (
-          !isRecord(result) ||
-          result.accountId !== accountId ||
-          typeof result.blobId !== 'string' ||
-          !result.blobId ||
-          result.size !== size
-        ) {
-          throw new JmapApiError('Invalid raw upload response.');
-        }
-        return {
-          accountId,
-          blobId: result.blobId,
-          size,
-          type: typeof result.type === 'string' ? result.type : 'message/rfc822',
-        };
+        return await readUploadResult(response, accountId, source.state, outerSignal);
       } catch (error) {
         outerSignal.throwIfAborted();
-        if (hasSourceError) throw sourceError;
+        if (source.state.hasSourceError) throw source.state.sourceError;
         throw error;
       } finally {
-        owned.removeEventListener('abort', abort);
-        close();
-        combined.cleanup();
+        source.dispose();
       }
     },
     signal,
   );
 };
 
-module.exports = { rawOperation, isRecord, uploadRawMessage };
+/**
+ * Gives the validated bytes of a plan as a request body that fetch pulls one
+ * chunk at a time, under a signal of its own, so that reading the source stops
+ * whether or not fetch cancels the body.
+ *
+ * @returns The `body`, its `state` (whether the source reached its end, the
+ * bytes it gave and the error it failed with) and `dispose()`, which stops it.
+ */
+const createRawUploadBody = (plan, analysis, outerSignal, progress) => {
+  const controller = new AbortController();
+  const combined = combineSignals(controller.signal, outerSignal);
+  const owned = combined.signal;
+  const iterator = iterateRawMessage(plan, {
+    signal: owned,
+    encoding: analysis.encoding,
+    expectedSize: analysis.size,
+    onProgress: progress,
+  })[Symbol.asyncIterator]();
+  const state = { eof: false, size: 0, sourceError: undefined, hasSourceError: false };
+  let closed = false;
+  let bodyController;
+  const close = (reason) => {
+    if (closed) return;
+    closed = true;
+    controller.abort(reason);
+    if (!state.eof) {
+      try {
+        Promise.resolve(iterator.return?.()).catch(() => {});
+      } catch {
+        /* Preserve the original failure. */
+      }
+    }
+  };
+  const abort = () => {
+    try {
+      bodyController?.error(owned.reason);
+    } catch {
+      /* Already closed. */
+    }
+    close(owned.reason);
+  };
+  const body = new ReadableStream(
+    {
+      start(stream) {
+        bodyController = stream;
+        owned.addEventListener('abort', abort, { once: true });
+        if (owned.aborted) abort();
+      },
+      async pull(stream) {
+        try {
+          owned.throwIfAborted();
+          const item = await iterator.next();
+          owned.throwIfAborted();
+          if (item.done) {
+            state.eof = true;
+            progress();
+            stream.close();
+          } else {
+            state.size += item.value.length;
+            stream.enqueue(new Uint8Array(item.value));
+          }
+        } catch (error) {
+          if (!owned.aborted && !state.hasSourceError) {
+            state.hasSourceError = true;
+            state.sourceError = error;
+          }
+          try {
+            stream.error(error);
+          } catch {
+            /* Already closed. */
+          }
+          close(error);
+        }
+      },
+      cancel: close,
+    },
+    { highWaterMark: 0 },
+  );
+  const dispose = () => {
+    owned.removeEventListener('abort', abort);
+    close();
+    combined.cleanup();
+  };
+  return { body, state, dispose };
+};
+
+const uploadHeaders = (config) => {
+  const headers = new Headers(config.headers);
+  if (!headers.has('Authorization')) {
+    if (config.bearerToken) {
+      headers.set('Authorization', `Bearer ${config.bearerToken}`);
+    } else if (config.basicAuth) {
+      const credentials = `${config.basicAuth.username}:${config.basicAuth.password}`;
+      headers.set('Authorization', `Basic ${Buffer.from(credentials).toString('base64')}`);
+    }
+  }
+  headers.set('Content-Type', 'message/rfc822');
+  return headers;
+};
+
+/**
+ * Reads the answer to a raw upload, which must come after the source reached
+ * its end and name the blob of the bytes sent.
+ *
+ * @returns The uploaded blob.
+ * @throws {JmapApiError} If the upload failed or its answer does not match.
+ */
+const readUploadResult = async (response, accountId, state, outerSignal) => {
+  if (!response.ok) {
+    throw new JmapApiError(
+      `Raw upload failed: ${response.status}`,
+      response.status,
+      await readText(response),
+      undefined,
+      parseRetryAfter(response.headers.get('Retry-After')),
+    );
+  }
+  if (!state.eof) {
+    throw new JmapApiError('Raw upload responded before validated EOF.');
+  }
+  const result = await readJson(response);
+  outerSignal.throwIfAborted();
+  if (
+    !isRecord(result) ||
+    result.accountId !== accountId ||
+    typeof result.blobId !== 'string' ||
+    !result.blobId ||
+    result.size !== state.size
+  ) {
+    throw new JmapApiError('Invalid raw upload response.');
+  }
+  return {
+    accountId,
+    blobId: result.blobId,
+    size: state.size,
+    type: typeof result.type === 'string' ? result.type : 'message/rfc822',
+  };
+};
+
+module.exports = {
+  findOnlyResponse,
+  rawOperation,
+  isRecord,
+  uploadRawMessage,
+};

From 3ca8a0db90e3ddacb669a52c71ebb2b73a593ceb Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:44:06 +0300
Subject: [PATCH 132/158] refactor: share the converter code of the HTTP
 providers in internal/provider.js

The calendar attachment put first, the attachments converted in parallel
under a signal of their own, the custom and threading headers and the
address lists had a copy in each of the eight converters; they are
withCalendarAttachment, convertAttachments, visitCustomHeaders,
collectCustomHeaders and formatAddresses of internal/provider.js. The
SendGrid converter (118 lines) builds its content and tracking settings
in functions of their own, the priority maps are module constants, and
the converters and transports use loops instead of array methods.
Behavior is unchanged; each provider's bundle grows by 0.1 to 0.3 KB, as
the shared module goes whole into each.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/internal/provider.js               | 109 ++++++++++++++
 src/lettermint/lettermint-transport.js |   9 +-
 src/lettermint/message-converter.js    |  78 +++-------
 src/maileroo/message-converter.js      |  77 +++-------
 src/mailgun/message-converter.js       |  45 ++----
 src/mailtrap/message-converter.js      |  72 +++-------
 src/plunk/message-converter.js         |  43 ++----
 src/resend/message-converter.js        |  95 +++++--------
 src/resend/resend-transport.js         |  20 +--
 src/sendgrid/message-converter.js      | 188 ++++++++-----------------
 src/ses/message-converter.js           |  80 +++++------
 src/ses/ses-transport.js               |   6 +-
 12 files changed, 344 insertions(+), 478 deletions(-)
 create mode 100644 src/internal/provider.js

diff --git a/src/internal/provider.js b/src/internal/provider.js
new file mode 100644
index 0000000..bdc0886
--- /dev/null
+++ b/src/internal/provider.js
@@ -0,0 +1,109 @@
+// Not ported from upyo: what the message converters of the HTTP providers
+// share, once in place of a copy in each provider.
+
+const { combineSignals } = require('../core/abort-signal.js');
+const { createCalendarAttachment } = require('../core/calendar.js');
+const { resolveThreadingHeaders } = require('../core/message-id.js');
+const { lowerCaseNames } = require('./headers.js');
+
+/**
+ * The attachments a provider sends.  A provider that cannot compose a
+ * `text/calendar` alternative carries the scheduling payload as an
+ * *invite.ics* part instead, ahead of the caller's own files, so that a
+ * client looking for the first calendar part finds it.
+ *
+ * @param message The message being converted.
+ * @returns The attachments, the calendar part first if there is one.
+ * @internal
+ */
+const withCalendarAttachment = (message) => {
+  if (message.calendar == null) return message.attachments;
+  const attachments = [createCalendarAttachment(message.calendar)];
+  for (const attachment of message.attachments) attachments.push(attachment);
+  return attachments;
+};
+
+/**
+ * Converts attachments in parallel, under a signal that stops the others as
+ * soon as one fails or the caller aborts.
+ *
+ * @param attachments The attachments to convert.
+ * @param convert Converts one attachment under a signal.
+ * @param signal The caller's signal, if any.
+ * @returns The converted attachments, in order.
+ * @internal
+ */
+const convertAttachments = async (attachments, convert, signal) => {
+  const cancellation = new AbortController();
+  const combined = combineSignals(cancellation.signal, signal);
+  try {
+    const converting = [];
+    for (const attachment of attachments) converting.push(convert(attachment, combined.signal));
+    return await Promise.all(converting);
+  } finally {
+    cancellation.abort();
+    combined.cleanup();
+  }
+};
+
+/**
+ * Visits the headers a provider sends as they are: the custom headers of a
+ * message that the provider does not take through a field of its own and that
+ * the typed threading fields do not own, then the threading fields the message
+ * sets.  A threading field the message owns but left empty writes nothing,
+ * which is how a caller drops an inherited header.
+ *
+ * @param message The message being converted.
+ * @param isStandardHeader Whether the provider takes a header through a field.
+ * @param visit Takes the name and the value of each header sent.
+ * @internal
+ */
+const visitCustomHeaders = (message, isStandardHeader, visit) => {
+  const threading = resolveThreadingHeaders(message);
+  const ownedHeaders = lowerCaseNames(threading.keys());
+  if (message.headers != null) {
+    for (const [name, value] of message.headers) {
+      if (!isStandardHeader(name) && !ownedHeaders.has(name.toLowerCase())) visit(name, value);
+    }
+  }
+  for (const [name, value] of threading) {
+    if (value != null) visit(name, value);
+  }
+};
+
+/**
+ * The headers {@link visitCustomHeaders} visits, as an object.
+ *
+ * @returns The headers by name, or `undefined` when there are none.
+ * @internal
+ */
+const collectCustomHeaders = (message, isStandardHeader) => {
+  let headers;
+  visitCustomHeaders(message, isStandardHeader, (name, value) => {
+    headers ??= {};
+    headers[name] = value;
+  });
+  return headers;
+};
+
+/**
+ * Formats each address of a list for a provider.
+ *
+ * @param addresses The addresses.
+ * @param format Formats one address.
+ * @returns The formatted addresses, in order.
+ * @internal
+ */
+const formatAddresses = (addresses, format) => {
+  const formatted = [];
+  for (const address of addresses) formatted.push(format(address));
+  return formatted;
+};
+
+module.exports = {
+  collectCustomHeaders,
+  convertAttachments,
+  formatAddresses,
+  visitCustomHeaders,
+  withCalendarAttachment,
+};
diff --git a/src/lettermint/lettermint-transport.js b/src/lettermint/lettermint-transport.js
index 4b5b5a9..d7f40fe 100644
--- a/src/lettermint/lettermint-transport.js
+++ b/src/lettermint/lettermint-transport.js
@@ -130,7 +130,7 @@ class LettermintTransport {
   async *sendBatch(messages, options) {
     if (messages.length === 0) return;
 
-    if (messages.some(hasIdempotencyKey)) {
+    if (anyHasIdempotencyKey(messages)) {
       for (const message of messages) {
         yield await this.send(message, options);
       }
@@ -210,6 +210,13 @@ const hasIdempotencyKey = (message) => {
   return message.idempotencyKey != null && message.idempotencyKey !== '';
 };
 
+const anyHasIdempotencyKey = (messages) => {
+  for (const message of messages) {
+    if (hasIdempotencyKey(message)) return true;
+  }
+  return false;
+};
+
 const responseToReceipt = (response) => {
   if (response?.message_id == null || response.message_id === '') {
     return createFailedReceipt('Lettermint response is missing a message ID.', {
diff --git a/src/lettermint/message-converter.js b/src/lettermint/message-converter.js
index db3ffc6..9847238 100644
--- a/src/lettermint/message-converter.js
+++ b/src/lettermint/message-converter.js
@@ -2,12 +2,14 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { generateId } = require('../core/id.js');
-const { createCalendarAttachment } = require('../core/calendar.js');
-const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
-const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
-const { lowerCaseNames } = require('../internal/headers.js');
+const {
+  convertAttachments,
+  formatAddresses,
+  visitCustomHeaders,
+  withCalendarAttachment,
+} = require('../internal/provider.js');
 
 const STANDARD_HEADERS = new Set([
   'from',
@@ -24,6 +26,8 @@ const STANDARD_HEADERS = new Set([
   'x-priority',
 ]);
 
+const PRIORITIES = { high: '1', normal: '3', low: '5' };
+
 /**
  * Converts an Upyo message to Lettermint API JSON format.
  *
@@ -38,30 +42,20 @@ const convertMessage = async (message, config, signal) => {
     throw new RangeError('Lettermint supports at most one tag per message.');
   }
 
-  // A transport that cannot compose a `text/calendar` alternative carries the
-  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
-  // own files so that a client looking for the first calendar part finds it.
-  const attachments =
-    message.calendar == null
-      ? message.attachments
-      : [createCalendarAttachment(message.calendar), ...message.attachments];
-
+  const attachments = withCalendarAttachment(message);
   const emailData = {
     from: formatAddress(message.sender),
-    to: message.recipients.map(formatAddress),
+    to: formatAddresses(message.recipients, formatAddress),
     subject: message.subject,
   };
-
   if (message.ccRecipients.length > 0) {
-    emailData.cc = message.ccRecipients.map(formatAddress);
+    emailData.cc = formatAddresses(message.ccRecipients, formatAddress);
   }
-
   if (message.bccRecipients.length > 0) {
-    emailData.bcc = message.bccRecipients.map(formatAddress);
+    emailData.bcc = formatAddresses(message.bccRecipients, formatAddress);
   }
-
   if (message.replyRecipients.length > 0) {
-    emailData.reply_to = message.replyRecipients.map(formatAddress);
+    emailData.reply_to = formatAddresses(message.replyRecipients, formatAddress);
   }
 
   if ('html' in message.content) {
@@ -92,46 +86,16 @@ const convertMessage = async (message, config, signal) => {
     emailData.settings = settings;
   }
 
-  const headers = {};
-  if (message.priority !== 'normal') {
-    const priorityMap = {
-      high: '1',
-      normal: '3',
-      low: '5',
-    };
-    headers['X-Priority'] = priorityMap[message.priority];
-  }
-
-  // Reply threading comes from the typed fields when the message defines them,
-  // and from a custom header otherwise.  A field the message owns but left
-  // empty writes nothing, which is how a caller drops an inherited header.
-  const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = lowerCaseNames(threading.keys());
-
-  for (const [key, value] of message.headers.entries()) {
-    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
-      headers[key] = value;
-    }
-  }
-  for (const [name, value] of threading) {
-    if (value != null) headers[name] = value;
-  }
-
-  if (Object.keys(headers).length > 0) {
-    emailData.headers = headers;
-  }
+  let headers;
+  if (message.priority !== 'normal') headers = { 'X-Priority': PRIORITIES[message.priority] };
+  visitCustomHeaders(message, isStandardHeader, (name, value) => {
+    headers ??= {};
+    headers[name] = value;
+  });
+  if (headers !== undefined) emailData.headers = headers;
 
   if (attachments.length > 0) {
-    const cancellation = new AbortController();
-    const combined = combineSignals(cancellation.signal, signal);
-    try {
-      emailData.attachments = await Promise.all(
-        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
-      );
-    } finally {
-      cancellation.abort();
-      combined.cleanup();
-    }
+    emailData.attachments = await convertAttachments(attachments, convertAttachment, signal);
   }
 
   return emailData;
diff --git a/src/maileroo/message-converter.js b/src/maileroo/message-converter.js
index fb34fb9..4d47883 100644
--- a/src/maileroo/message-converter.js
+++ b/src/maileroo/message-converter.js
@@ -2,12 +2,14 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { generateId } = require('../core/id.js');
-const { createCalendarAttachment } = require('../core/calendar.js');
-const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
-const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
-const { lowerCaseNames } = require('../internal/headers.js');
+const {
+  convertAttachments,
+  formatAddresses,
+  visitCustomHeaders,
+  withCalendarAttachment,
+} = require('../internal/provider.js');
 
 const STANDARD_HEADERS = new Set([
   'from',
@@ -37,13 +39,7 @@ const STANDARD_HEADERS = new Set([
 const convertMessage = async (message, config, signal) => {
   signal?.throwIfAborted();
 
-  // A transport that cannot compose a `text/calendar` alternative carries the
-  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
-  // own files so that a client looking for the first calendar part finds it.
-  const attachments =
-    message.calendar == null
-      ? message.attachments
-      : [createCalendarAttachment(message.calendar), ...message.attachments];
+  const attachments = withCalendarAttachment(message);
 
   const emailData = {
     from: convertAddress(message.sender),
@@ -82,21 +78,10 @@ const convertMessage = async (message, config, signal) => {
   }
 
   const headers = convertHeaders(message);
-  if (Object.keys(headers).length > 0) {
-    emailData.headers = headers;
-  }
+  if (headers !== undefined) emailData.headers = headers;
 
   if (attachments.length > 0) {
-    const cancellation = new AbortController();
-    const combined = combineSignals(cancellation.signal, signal);
-    try {
-      emailData.attachments = await Promise.all(
-        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
-      );
-    } finally {
-      cancellation.abort();
-      combined.cleanup();
-    }
+    emailData.attachments = await convertAttachments(attachments, convertAttachment, signal);
   }
 
   signal?.throwIfAborted();
@@ -139,8 +124,9 @@ const convertAddress = (address) => {
 };
 
 const convertAddressList = (addresses) => {
-  const converted = addresses.map(convertAddress);
-  return converted.length === 1 ? converted[0] : converted;
+  return addresses.length === 1
+    ? convertAddress(addresses[0])
+    : formatAddresses(addresses, convertAddress);
 };
 
 const convertOptionalAddressList = (addresses) => {
@@ -150,43 +136,26 @@ const convertOptionalAddressList = (addresses) => {
 const convertTags = (message, config) => {
   const tags = config.tags == null ? {} : { ...config.tags };
 
-  for (const [index, tag] of message.tags.entries()) {
-    tags[`tag${index + 1}`] = tag;
+  for (let index = 0; index < message.tags.length; index++) {
+    tags[`tag${index + 1}`] = message.tags[index];
   }
 
   return tags;
 };
 
+// The priority and the custom headers, or `undefined` when there are none.
 const convertHeaders = (message) => {
-  const headers = {};
-
-  if (message.priority !== 'normal') {
-    const priorityMap = {
-      high: '1',
-      normal: '3',
-      low: '5',
-    };
-    headers['X-Priority'] = priorityMap[message.priority];
-  }
-
-  // Reply threading comes from the typed fields when the message defines them,
-  // and from a custom header otherwise.  A field the message owns but left
-  // empty writes nothing, which is how a caller drops an inherited header.
-  const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = lowerCaseNames(threading.keys());
-
-  for (const [key, value] of message.headers.entries()) {
-    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
-      headers[key] = value;
-    }
-  }
-  for (const [name, value] of threading) {
-    if (value != null) headers[name] = value;
-  }
-
+  let headers;
+  if (message.priority !== 'normal') headers = { 'X-Priority': PRIORITIES[message.priority] };
+  visitCustomHeaders(message, isStandardHeader, (name, value) => {
+    headers ??= {};
+    headers[name] = value;
+  });
   return headers;
 };
 
+const PRIORITIES = { high: '1', normal: '3', low: '5' };
+
 const convertAttachment = async (attachment, signal) => {
   signal?.throwIfAborted();
   const content = await readAttachmentContent(attachment.content, signal);
diff --git a/src/mailgun/message-converter.js b/src/mailgun/message-converter.js
index d376aec..9820b7a 100644
--- a/src/mailgun/message-converter.js
+++ b/src/mailgun/message-converter.js
@@ -2,10 +2,10 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { formatQuotedMailbox: formatAddress } = require('../core/address.js');
-const { createCalendarAttachment } = require('../core/calendar.js');
 const { readAttachmentContent } = require('../core/attachment.js');
-const { resolveThreadingHeaders } = require('../core/message-id.js');
-const { lowerCaseNames } = require('../internal/headers.js');
+const { visitCustomHeaders, withCalendarAttachment } = require('../internal/provider.js');
+
+const PRIORITIES = { high: '1', normal: '3', low: '5' };
 
 /**
  * Converts a Upyo Message to Mailgun API FormData format.
@@ -26,13 +26,7 @@ const { lowerCaseNames } = require('../internal/headers.js');
  */
 const convertMessage = async (message, config, signal) => {
   const formData = new FormData();
-  // A transport that cannot compose a `text/calendar` alternative carries the
-  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
-  // own files so that a client looking for the first calendar part finds it.
-  const attachments =
-    message.calendar == null
-      ? message.attachments
-      : [createCalendarAttachment(message.calendar), ...message.attachments];
+  const attachments = withCalendarAttachment(message);
 
   // Required fields
   formData.append('from', formatAddress(message.sender));
@@ -54,7 +48,10 @@ const convertMessage = async (message, config, signal) => {
 
   // Reply-to
   if (message.replyRecipients.length > 0) {
-    const replyTo = message.replyRecipients.map(formatAddress).join(', ');
+    let replyTo = '';
+    for (const recipient of message.replyRecipients) {
+      replyTo += `${replyTo === '' ? '' : ', '}${formatAddress(recipient)}`;
+    }
     formData.append('h:Reply-To', replyTo);
   }
 
@@ -73,12 +70,7 @@ const convertMessage = async (message, config, signal) => {
 
   // Priority
   if (message.priority !== 'normal') {
-    const priorityMap = {
-      high: '1',
-      normal: '3',
-      low: '5',
-    };
-    formData.append('h:X-Priority', priorityMap[message.priority]);
+    formData.append('h:X-Priority', PRIORITIES[message.priority]);
   }
 
   // Tags
@@ -86,22 +78,9 @@ const convertMessage = async (message, config, signal) => {
     formData.append('o:tag', tag);
   }
 
-  // Reply threading comes from the typed fields when the message defines them,
-  // and from a custom header otherwise.  A field the message owns but left
-  // empty writes nothing, which is how a caller drops an inherited header.
-  const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = lowerCaseNames(threading.keys());
-
-  // Custom headers
-  for (const [key, value] of message.headers.entries()) {
-    // Skip standard headers that are handled separately
-    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
-      formData.append(`h:${key}`, value);
-    }
-  }
-  for (const [name, value] of threading) {
-    if (value != null) formData.append(`h:${name}`, value);
-  }
+  visitCustomHeaders(message, isStandardHeader, (name, value) => {
+    formData.append(`h:${name}`, value);
+  });
 
   // Attachments
   for (const attachment of attachments) {
diff --git a/src/mailtrap/message-converter.js b/src/mailtrap/message-converter.js
index 9fed84d..29b35c4 100644
--- a/src/mailtrap/message-converter.js
+++ b/src/mailtrap/message-converter.js
@@ -1,12 +1,14 @@
 // Ported from upyo v0.7.0 (packages/mailtrap/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { createCalendarAttachment } = require('../core/calendar.js');
-const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
-const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
-const { lowerCaseNames } = require('../internal/headers.js');
+const {
+  convertAttachments,
+  formatAddresses,
+  visitCustomHeaders,
+  withCalendarAttachment,
+} = require('../internal/provider.js');
 
 const STANDARD_HEADERS = new Set([
   'from',
@@ -23,6 +25,8 @@ const STANDARD_HEADERS = new Set([
   'x-priority',
 ]);
 
+const PRIORITIES = { high: '1', normal: '3', low: '5' };
+
 /**
  * Converts an Upyo message to Mailtrap API JSON format.
  *
@@ -37,27 +41,21 @@ const STANDARD_HEADERS = new Set([
 const convertMessage = async (message, config, signal) => {
   signal?.throwIfAborted();
 
-  // A transport that cannot compose a `text/calendar` alternative carries the
-  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
-  // own files so that a client looking for the first calendar part finds it.
-  const attachments =
-    message.calendar == null
-      ? message.attachments
-      : [createCalendarAttachment(message.calendar), ...message.attachments];
+  const attachments = withCalendarAttachment(message);
 
   const emailData = {
     from: formatAddress(message.sender),
-    to: message.recipients.map(formatAddress),
+    to: formatAddresses(message.recipients, formatAddress),
     subject: message.subject,
     category: resolveCategory(message.tags, config.defaultCategory),
   };
 
   if (message.ccRecipients.length > 0) {
-    emailData.cc = message.ccRecipients.map(formatAddress);
+    emailData.cc = formatAddresses(message.ccRecipients, formatAddress);
   }
 
   if (message.bccRecipients.length > 0) {
-    emailData.bcc = message.bccRecipients.map(formatAddress);
+    emailData.bcc = formatAddresses(message.bccRecipients, formatAddress);
   }
 
   if (message.replyRecipients.length > 0) {
@@ -82,46 +80,16 @@ const convertMessage = async (message, config, signal) => {
     emailData.custom_variables = customVariables;
   }
 
-  const headers = {};
-  if (message.priority !== 'normal') {
-    const priorityMap = {
-      high: '1',
-      normal: '3',
-      low: '5',
-    };
-    headers['X-Priority'] = priorityMap[message.priority];
-  }
-
-  // Reply threading comes from the typed fields when the message defines them,
-  // and from a custom header otherwise.  A field the message owns but left
-  // empty writes nothing, which is how a caller drops an inherited header.
-  const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = lowerCaseNames(threading.keys());
-
-  for (const [key, value] of message.headers.entries()) {
-    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
-      headers[key] = value;
-    }
-  }
-  for (const [name, value] of threading) {
-    if (value != null) headers[name] = value;
-  }
-
-  if (Object.keys(headers).length > 0) {
-    emailData.headers = headers;
-  }
+  let headers;
+  if (message.priority !== 'normal') headers = { 'X-Priority': PRIORITIES[message.priority] };
+  visitCustomHeaders(message, isStandardHeader, (name, value) => {
+    headers ??= {};
+    headers[name] = value;
+  });
+  if (headers !== undefined) emailData.headers = headers;
 
   if (attachments.length > 0) {
-    const cancellation = new AbortController();
-    const combined = combineSignals(cancellation.signal, signal);
-    try {
-      emailData.attachments = await Promise.all(
-        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
-      );
-    } finally {
-      cancellation.abort();
-      combined.cleanup();
-    }
+    emailData.attachments = await convertAttachments(attachments, convertAttachment, signal);
   }
 
   signal?.throwIfAborted();
diff --git a/src/plunk/message-converter.js b/src/plunk/message-converter.js
index aa84e31..08e1af3 100644
--- a/src/plunk/message-converter.js
+++ b/src/plunk/message-converter.js
@@ -2,10 +2,8 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { readAttachmentContent } = require('../core/attachment.js');
-const { resolveThreadingHeaders } = require('../core/message-id.js');
-const { createCalendarAttachment } = require('../core/calendar.js');
 const { toBase64 } = require('../internal/base64.js');
-const { lowerCaseNames } = require('../internal/headers.js');
+const { collectCustomHeaders, withCalendarAttachment } = require('../internal/provider.js');
 
 /**
  * Converts a Upyo message to Plunk API format.
@@ -25,11 +23,17 @@ const { lowerCaseNames } = require('../internal/headers.js');
  */
 // The headers that have fields of their own in a Plunk request.
 const DEDICATED_HEADERS = new Set(['to', 'from', 'reply-to', 'subject', 'content-type']);
+const isDedicatedHeader = (name) => DEDICATED_HEADERS.has(name.toLowerCase());
+
+const addressesOf = (message) => {
+  const addresses = [];
+  for (const recipient of message.recipients) addresses.push(recipient.address);
+  return addresses;
+};
 
 const convertMessage = async (message, _config, signal) => {
   // Convert recipients - Plunk accepts either string or array
-  const recipients = message.recipients.map((addr) => addr.address);
-  const to = recipients.length === 1 ? recipients[0] : recipients;
+  const to = message.recipients.length === 1 ? message.recipients[0].address : addressesOf(message);
 
   // Convert sender information
   const senderName = message.sender.name;
@@ -49,36 +53,15 @@ const convertMessage = async (message, _config, signal) => {
     body = '';
   }
 
-  // Reply threading comes from the typed fields when the message defines them,
-  // and from a custom header otherwise.  A field the message owns but left
-  // empty writes nothing, which is how a caller drops an inherited header.
-  const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = lowerCaseNames(threading.keys());
-
-  // Convert headers - merge custom headers but exclude standard ones
-  const customHeaders = {};
-  if (message.headers) {
-    for (const [key, value] of message.headers.entries()) {
-      // Skip headers that are handled by dedicated fields
-      const lowerKey = key.toLowerCase();
-      if (!DEDICATED_HEADERS.has(lowerKey) && !ownedHeaders.has(lowerKey)) {
-        customHeaders[lowerKey] = value;
-      }
-    }
-  }
-  for (const [name, value] of threading) {
-    if (value != null) customHeaders[name] = value;
-  }
+  // The names of the custom headers come lower-cased from Headers.
+  const customHeaders = collectCustomHeaders(message, isDedicatedHeader);
 
   // A transport that cannot compose a `text/calendar` alternative carries the
   // scheduling payload as an *invite.ics* part instead, ahead of the caller's
   // own files so that a client looking for the first calendar part finds it.
   // Built here rather than inside the loop below, whose error handling drops a
   // part it cannot convert: an invitation must not disappear that quietly.
-  const sourceAttachments =
-    message.calendar == null
-      ? message.attachments
-      : [createCalendarAttachment(message.calendar), ...message.attachments];
+  const sourceAttachments = withCalendarAttachment(message);
 
   // Plunk documents a limit of five attachments, and quietly sending the first
   // five is only acceptable while nothing important is at the end.  Once the
@@ -121,7 +104,7 @@ const convertMessage = async (message, _config, signal) => {
     plunkEmail.reply = replyTo;
   }
 
-  if (Object.keys(customHeaders).length > 0) {
+  if (customHeaders !== undefined) {
     plunkEmail.headers = customHeaders;
   }
 
diff --git a/src/resend/message-converter.js b/src/resend/message-converter.js
index 25b7b07..8675459 100644
--- a/src/resend/message-converter.js
+++ b/src/resend/message-converter.js
@@ -3,12 +3,16 @@
 
 const { generateId } = require('../core/id.js');
 const { formatMailbox: formatAddress } = require('../core/address.js');
-const { createCalendarAttachment } = require('../core/calendar.js');
-const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
-const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
-const { lowerCaseNames } = require('../internal/headers.js');
+const {
+  convertAttachments,
+  formatAddresses,
+  visitCustomHeaders,
+  withCalendarAttachment,
+} = require('../internal/provider.js');
+
+const PRIORITIES = { high: '1', normal: '3', low: '5' };
 
 /**
  * Converts a Upyo Message to Resend API JSON format.
@@ -33,31 +37,25 @@ const { lowerCaseNames } = require('../internal/headers.js');
  * ```
  */
 const convertMessage = async (message, _config, options = {}) => {
-  // A transport that cannot compose a `text/calendar` alternative carries the
-  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
-  // own files so that a client looking for the first calendar part finds it.
-  const attachments =
-    message.calendar == null
-      ? message.attachments
-      : [createCalendarAttachment(message.calendar), ...message.attachments];
+  const attachments = withCalendarAttachment(message);
 
   const emailData = {
     from: formatAddress(message.sender),
     to:
       message.recipients.length === 1
         ? formatAddress(message.recipients[0])
-        : message.recipients.map(formatAddress),
+        : formatAddresses(message.recipients, formatAddress),
     subject: message.subject,
   };
 
   // CC recipients
   if (message.ccRecipients.length > 0) {
-    emailData.cc = message.ccRecipients.map(formatAddress);
+    emailData.cc = formatAddresses(message.ccRecipients, formatAddress);
   }
 
   // BCC recipients
   if (message.bccRecipients.length > 0) {
-    emailData.bcc = message.bccRecipients.map(formatAddress);
+    emailData.bcc = formatAddresses(message.bccRecipients, formatAddress);
   }
 
   // Reply-to
@@ -78,59 +76,30 @@ const convertMessage = async (message, _config, options = {}) => {
 
   // Attachments
   if (attachments.length > 0) {
-    const cancellation = new AbortController();
-    const combined = combineSignals(cancellation.signal, options.signal);
-    try {
-      emailData.attachments = await Promise.all(
-        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
-      );
-    } finally {
-      cancellation.abort();
-      combined.cleanup();
-    }
+    emailData.attachments = await convertAttachments(
+      attachments,
+      convertAttachment,
+      options.signal,
+    );
   }
 
   // Tags - Resend uses different format than Upyo
   if (message.tags.length > 0) {
-    emailData.tags = message.tags.map((tag, index) => ({
-      name: `tag${index + 1}`, // Resend requires name-value pairs
-      value: tag,
-    }));
-  }
-
-  // Custom headers
-  const headers = {};
-
-  // Priority
-  if (message.priority !== 'normal') {
-    const priorityMap = {
-      high: '1',
-      normal: '3',
-      low: '5',
-    };
-    headers['X-Priority'] = priorityMap[message.priority];
-  }
-
-  // Custom headers from message
-  // Reply threading comes from the typed fields when the message defines them,
-  // and from a custom header otherwise.  A field the message owns but left
-  // empty writes nothing, which is how a caller drops an inherited header.
-  const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = lowerCaseNames(threading.keys());
-
-  for (const [key, value] of message.headers.entries()) {
-    // Skip standard headers that are handled separately
-    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
-      headers[key] = value;
+    // Resend requires name-value pairs.
+    const tags = [];
+    for (let index = 0; index < message.tags.length; index++) {
+      tags.push({ name: `tag${index + 1}`, value: message.tags[index] });
     }
-  }
-  for (const [name, value] of threading) {
-    if (value != null) headers[name] = value;
+    emailData.tags = tags;
   }
 
-  if (Object.keys(headers).length > 0) {
-    emailData.headers = headers;
-  }
+  let headers;
+  if (message.priority !== 'normal') headers = { 'X-Priority': PRIORITIES[message.priority] };
+  visitCustomHeaders(message, isStandardHeader, (name, value) => {
+    headers ??= {};
+    headers[name] = value;
+  });
+  if (headers !== undefined) emailData.headers = headers;
 
   // Scheduled sending
   if (options.scheduledAt) {
@@ -170,9 +139,9 @@ const convertMessagesBatch = async (messages, _config) => {
     }
   }
 
-  const batchData = await Promise.all(messages.map((message) => convertMessage(message, _config)));
-
-  return batchData;
+  const converting = [];
+  for (const message of messages) converting.push(convertMessage(message, _config));
+  return await Promise.all(converting);
 };
 
 /**
diff --git a/src/resend/resend-transport.js b/src/resend/resend-transport.js
index 25a5f98..921f3b2 100644
--- a/src/resend/resend-transport.js
+++ b/src/resend/resend-transport.js
@@ -317,16 +317,16 @@ class ResendTransport {
    * @returns True if all messages are suitable for batch API
    */
   canUseBatchApi(messages) {
-    return messages.every(
-      (message) =>
-        message.attachments.length === 0 &&
-        message.tags.length === 0 &&
-        // A calendar becomes an attachment during conversion, which the batch
-        // API forbids, and `sendBatch()` fails a whole chunk on one conversion
-        // error.  Sending these individually keeps the failure — or the success
-        // — confined to the message it belongs to.
-        message.calendar == null,
-    );
+    for (const message of messages) {
+      // A calendar becomes an attachment during conversion, which the batch
+      // API forbids, and `sendBatch()` fails a whole chunk on one conversion
+      // error.  Sending these individually keeps the failure — or the success
+      // — confined to the message it belongs to.
+      if (message.attachments.length > 0 || message.tags.length > 0 || message.calendar != null) {
+        return false;
+      }
+    }
+    return true;
   }
 
   /**
diff --git a/src/sendgrid/message-converter.js b/src/sendgrid/message-converter.js
index e9e2aaf..8e07415 100644
--- a/src/sendgrid/message-converter.js
+++ b/src/sendgrid/message-converter.js
@@ -1,12 +1,14 @@
 // Ported from upyo v0.7.0 (packages/sendgrid/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { createCalendarAttachment } = require('../core/calendar.js');
-const { combineSignals } = require('../core/abort-signal.js');
 const { readAttachmentContent } = require('../core/attachment.js');
-const { resolveThreadingHeaders } = require('../core/message-id.js');
 const { toBase64 } = require('../internal/base64.js');
-const { lowerCaseNames } = require('../internal/headers.js');
+const {
+  collectCustomHeaders,
+  convertAttachments,
+  formatAddresses,
+  withCalendarAttachment,
+} = require('../internal/provider.js');
 
 /**
  * Converts a Upyo Message to SendGrid API JSON format.
@@ -26,163 +28,89 @@ const { lowerCaseNames } = require('../internal/headers.js');
  * ```
  */
 const convertMessage = async (message, config, signal) => {
-  // A transport that cannot compose a `text/calendar` alternative carries the
-  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
-  // own files so that a client looking for the first calendar part finds it.
-  const attachments =
-    message.calendar == null
-      ? message.attachments
-      : [createCalendarAttachment(message.calendar), ...message.attachments];
-
-  const sendGridMail = {
-    personalizations: [],
-    from: formatAddress(message.sender),
-  };
-
-  // Create personalization object
+  const attachments = withCalendarAttachment(message);
   const personalization = {
-    to: message.recipients.map(formatAddress),
+    to: formatAddresses(message.recipients, formatAddress),
     subject: message.subject,
   };
-
-  // Add CC recipients if any
   if (message.ccRecipients.length > 0) {
-    personalization.cc = message.ccRecipients.map(formatAddress);
+    personalization.cc = formatAddresses(message.ccRecipients, formatAddress);
   }
-
-  // Add BCC recipients if any
   if (message.bccRecipients.length > 0) {
-    personalization.bcc = message.bccRecipients.map(formatAddress);
-  }
-
-  sendGridMail.personalizations.push(personalization);
-
-  // Reply-to handling
-  if (message.replyRecipients.length > 0) {
-    if (message.replyRecipients.length === 1) {
-      sendGridMail.reply_to = formatAddress(message.replyRecipients[0]);
-    } else {
-      sendGridMail.reply_to_list = message.replyRecipients.map(formatAddress);
-    }
+    personalization.bcc = formatAddresses(message.bccRecipients, formatAddress);
   }
+  const sendGridMail = {
+    personalizations: [personalization],
+    from: formatAddress(message.sender),
+  };
 
-  // Content
-  const content = [];
-
-  if ('html' in message.content) {
-    if (message.content.text) {
-      content.push({
-        type: 'text/plain',
-        value: message.content.text,
-      });
-    }
-    content.push({
-      type: 'text/html',
-      value: message.content.html,
-    });
-  } else {
-    content.push({
-      type: 'text/plain',
-      value: message.content.text,
-    });
+  if (message.replyRecipients.length === 1) {
+    sendGridMail.reply_to = formatAddress(message.replyRecipients[0]);
+  } else if (message.replyRecipients.length > 1) {
+    sendGridMail.reply_to_list = formatAddresses(message.replyRecipients, formatAddress);
   }
 
-  sendGridMail.content = content;
+  sendGridMail.content = contentOf(message);
 
-  // Priority handling (using custom headers)
+  // Priority goes in custom headers, then the caller's own.
   if (message.priority !== 'normal') {
-    const headers = {};
-
-    switch (message.priority) {
-      case 'high':
-        headers['X-Priority'] = '1';
-        headers['X-MSMail-Priority'] = 'High';
-        headers['Importance'] = 'High';
-        break;
-      case 'low':
-        headers['X-Priority'] = '5';
-        headers['X-MSMail-Priority'] = 'Low';
-        headers['Importance'] = 'Low';
-        break;
-    }
-
-    sendGridMail.headers = { ...sendGridMail.headers, ...headers };
+    sendGridMail.headers = { ...sendGridMail.headers, ...PRIORITY_HEADERS[message.priority] };
   }
-
-  // Tags (categories in SendGrid)
   if (message.tags.length > 0) {
+    // Categories in SendGrid.
     sendGridMail.categories = [...message.tags];
   }
-
-  // Custom headers
-  const customHeaders = {};
-  // Reply threading comes from the typed fields when the message defines them,
-  // and from a custom header otherwise.  A field the message owns but left
-  // empty writes nothing, which is how a caller drops an inherited header.
-  const threading = resolveThreadingHeaders(message);
-  const ownedHeaders = lowerCaseNames(threading.keys());
-
-  for (const [key, value] of message.headers.entries()) {
-    // Skip standard headers that are handled separately
-    if (!isStandardHeader(key) && !ownedHeaders.has(key.toLowerCase())) {
-      customHeaders[key] = value;
-    }
-  }
-  for (const [name, value] of threading) {
-    if (value != null) customHeaders[name] = value;
-  }
-
-  if (Object.keys(customHeaders).length > 0) {
+  const customHeaders = collectCustomHeaders(message, isStandardHeader);
+  if (customHeaders !== undefined) {
     sendGridMail.headers = { ...sendGridMail.headers, ...customHeaders };
   }
 
-  // Attachments
   if (attachments.length > 0) {
-    const cancellation = new AbortController();
-    const combined = combineSignals(cancellation.signal, signal);
-    try {
-      sendGridMail.attachments = await Promise.all(
-        attachments.map((attachment) => convertAttachment(attachment, combined.signal)),
-      );
-    } finally {
-      cancellation.abort();
-      combined.cleanup();
-    }
+    sendGridMail.attachments = await convertAttachments(attachments, convertAttachment, signal);
   }
 
-  // Tracking settings
-  const trackingSettings = {};
+  const trackingSettings = trackingSettingsOf(config);
+  if (trackingSettings !== undefined) sendGridMail.tracking_settings = trackingSettings;
 
-  if (config.clickTracking !== undefined) {
-    trackingSettings.click_tracking = {
-      enable: config.clickTracking,
-      enable_text: config.clickTracking,
-    };
+  return sendGridMail;
+};
+
+const PRIORITY_HEADERS = {
+  high: { 'X-Priority': '1', 'X-MSMail-Priority': 'High', Importance: 'High' },
+  low: { 'X-Priority': '5', 'X-MSMail-Priority': 'Low', Importance: 'Low' },
+};
+
+// The plain text part, unless the message has only HTML, then the HTML part.
+const contentOf = (message) => {
+  if (!('html' in message.content)) {
+    return [{ type: 'text/plain', value: message.content.text }];
   }
+  const content = [];
+  if (message.content.text) content.push({ type: 'text/plain', value: message.content.text });
+  content.push({ type: 'text/html', value: message.content.html });
+  return content;
+};
 
+// The tracking settings the configuration sets, or `undefined` for none.
+const trackingSettingsOf = (config) => {
+  let settings;
+  if (config.clickTracking !== undefined) {
+    settings ??= {};
+    settings.click_tracking = { enable: config.clickTracking, enable_text: config.clickTracking };
+  }
   if (config.openTracking !== undefined) {
-    trackingSettings.open_tracking = {
-      enable: config.openTracking,
-    };
+    settings ??= {};
+    settings.open_tracking = { enable: config.openTracking };
   }
-
   if (config.subscriptionTracking !== undefined) {
-    trackingSettings.subscription_tracking = {
-      enable: config.subscriptionTracking,
-    };
+    settings ??= {};
+    settings.subscription_tracking = { enable: config.subscriptionTracking };
   }
-
   if (config.googleAnalytics !== undefined) {
-    trackingSettings.ganalytics = {
-      enable: config.googleAnalytics,
-    };
-  }
-
-  if (Object.keys(trackingSettings).length > 0) {
-    sendGridMail.tracking_settings = trackingSettings;
+    settings ??= {};
+    settings.ganalytics = { enable: config.googleAnalytics };
   }
-
-  return sendGridMail;
+  return settings;
 };
 
 /**
diff --git a/src/ses/message-converter.js b/src/ses/message-converter.js
index f8436b3..e33b661 100644
--- a/src/ses/message-converter.js
+++ b/src/ses/message-converter.js
@@ -1,25 +1,28 @@
 // Ported from upyo v0.7.0 (packages/ses/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { combineSignals } = require('../core/abort-signal.js');
 const { formatQuotedMailbox: formatAddress } = require('../core/address.js');
 const { readAttachmentContent } = require('../core/attachment.js');
-const { createCalendarAttachment } = require('../core/calendar.js');
 const { toBase64 } = require('../internal/base64.js');
+const {
+  convertAttachments,
+  formatAddresses,
+  withCalendarAttachment,
+} = require('../internal/provider.js');
 
 const convertMessage = async (message, config, signal) => {
   const destination = {};
 
   if (message.recipients.length > 0) {
-    destination.ToAddresses = message.recipients.map(formatAddress);
+    destination.ToAddresses = formatAddresses(message.recipients, formatAddress);
   }
 
   if (message.ccRecipients.length > 0) {
-    destination.CcAddresses = message.ccRecipients.map(formatAddress);
+    destination.CcAddresses = formatAddresses(message.ccRecipients, formatAddress);
   }
 
   if (message.bccRecipients.length > 0) {
-    destination.BccAddresses = message.bccRecipients.map(formatAddress);
+    destination.BccAddresses = formatAddresses(message.bccRecipients, formatAddress);
   }
 
   const sesMessage = {
@@ -29,7 +32,7 @@ const convertMessage = async (message, config, signal) => {
   };
 
   if (message.replyRecipients.length > 0) {
-    sesMessage.ReplyToAddresses = message.replyRecipients.map(formatAddress);
+    sesMessage.ReplyToAddresses = formatAddresses(message.replyRecipients, formatAddress);
   }
 
   if (config.configurationSetName) {
@@ -50,8 +53,10 @@ const convertMessage = async (message, config, signal) => {
     tags.push({ Name: 'priority', Value: message.priority });
   }
 
-  for (const [name, value] of Object.entries(config.defaultTags)) {
-    tags.push({ Name: name, Value: value });
+  for (const name in config.defaultTags) {
+    if (Object.hasOwn(config.defaultTags, name)) {
+      tags.push({ Name: name, Value: config.defaultTags[name] });
+    }
   }
 
   if (tags.length > 0) {
@@ -89,47 +94,32 @@ const createSimpleContent = async (message, signal) => {
     };
   }
 
-  // A transport that cannot compose a `text/calendar` alternative carries the
-  // scheduling payload as an *invite.ics* part instead, ahead of the caller's
-  // own files so that a client looking for the first calendar part finds it.
-  const attachments =
-    message.calendar == null
-      ? message.attachments
-      : [createCalendarAttachment(message.calendar), ...message.attachments];
+  const attachments = withCalendarAttachment(message);
 
   if (attachments.length > 0) {
-    const cancellation = new AbortController();
-    const combined = combineSignals(cancellation.signal, signal);
-    try {
-      content.Attachments = await Promise.all(
-        attachments.map(async (attachment) => {
-          const contentBytes = await readAttachmentContent(attachment.content, combined.signal);
-          const base64Content = toBase64(contentBytes);
-
-          const converted = {
-            FileName: attachment.filename,
-            ContentType: attachment.contentType || 'application/octet-stream',
-            ContentDisposition: attachment.inline ? 'INLINE' : 'ATTACHMENT',
-            ContentTransferEncoding: 'BASE64',
-            RawContent: base64Content,
-          };
-          // An empty content ID is how Upyo spells "this part has none", so it
-          // is left out rather than sent as an empty header value.
-          if (attachment.contentId !== '') {
-            converted.ContentId = attachment.contentId;
-          }
-          return converted;
-        }),
-      );
-    } finally {
-      cancellation.abort();
-      combined.cleanup();
-    }
+    content.Attachments = await convertAttachments(attachments, convertAttachment, signal);
   }
 
   return content;
 };
 
+const convertAttachment = async (attachment, signal) => {
+  const contentBytes = await readAttachmentContent(attachment.content, signal);
+  const converted = {
+    FileName: attachment.filename,
+    ContentType: attachment.contentType || 'application/octet-stream',
+    ContentDisposition: attachment.inline ? 'INLINE' : 'ATTACHMENT',
+    ContentTransferEncoding: 'BASE64',
+    RawContent: toBase64(contentBytes),
+  };
+  // An empty content ID is how Upyo spells "this part has none", so it is left
+  // out rather than sent as an empty header value.
+  if (attachment.contentId !== '') {
+    converted.ContentId = attachment.contentId;
+  }
+  return converted;
+};
+
 // Dead upstream: nothing calls it (CLAUDE.md, known upstream bugs).
 /* c8 ignore start */
 const convertMessagesToBulk = async (messages, config, signal) => {
@@ -164,13 +154,13 @@ const convertMessagesToBulk = async (messages, config, signal) => {
     const destination = {};
 
     if (message.recipients.length > 0) {
-      destination.ToAddresses = message.recipients.map(formatAddress);
+      destination.ToAddresses = formatAddresses(message.recipients, formatAddress);
     }
     if (message.ccRecipients.length > 0) {
-      destination.CcAddresses = message.ccRecipients.map(formatAddress);
+      destination.CcAddresses = formatAddresses(message.ccRecipients, formatAddress);
     }
     if (message.bccRecipients.length > 0) {
-      destination.BccAddresses = message.bccRecipients.map(formatAddress);
+      destination.BccAddresses = formatAddresses(message.bccRecipients, formatAddress);
     }
 
     const entry = {
diff --git a/src/ses/ses-transport.js b/src/ses/ses-transport.js
index f1e9de7..537f43c 100644
--- a/src/ses/ses-transport.js
+++ b/src/ses/ses-transport.js
@@ -201,9 +201,9 @@ class SesTransport {
   async sendConcurrent(messages, options) {
     options?.signal?.throwIfAborted();
 
-    const sendPromises = messages.map((message) => this.send(message, options));
-
-    return await Promise.all(sendPromises);
+    const sending = [];
+    for (const message of messages) sending.push(this.send(message, options));
+    return await Promise.all(sending);
   }
 
   extractMessageId(response) {

From 5f41279fe65e3045319cffeb3659d80c03cc58ae Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:44:46 +0300
Subject: [PATCH 133/158] refactor(ses): remove convertMessagesToBulk, dead
 upstream

Nothing called it, upstream or here; it was kept under c8 ignore with the
known upstream bug 10. CLAUDE.md now says that code dead upstream is
removed rather than ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                    |   6 +--
 src/ses/message-converter.js | 101 +----------------------------------
 2 files changed, 4 insertions(+), 103 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index dfbb5c0..7651b54 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -117,8 +117,7 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
   over lines in a test goes through a variable (`no-unexpected-multiline`).
 - **Coverage keeps the gates of the package.** Paths that upstream reached only end to end get flat
   suites against fakes (`tests/unit/<subpath>.test.js`); `/* c8 ignore */` marks only code that is
-  dead upstream (`convertMessagesToBulk`) or unreachable on Node, each with its
-  reason. Upstream tests of a runtime without `AbortSignal.any` are left out with a comment.
+  unreachable on Node, each with its reason; code that is dead upstream is removed. Upstream tests of a runtime without `AbortSignal.any` are left out with a comment.
 - Ported test suites keep upstream's `describe`/`it`, so they can be compared with upyo's; new
   suites use the flat style of "Testing notes". Tests for paths that upstream's suites leave out go
   into a new flat suite (`tests/unit/core.test.js` for `src/core/`).
@@ -141,7 +140,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
    as a substring.
 9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
-10. ses: custom and threading headers are not sent; `convertMessagesToBulk` is dead code.
+10. ses: custom and threading headers are not sent. (`convertMessagesToBulk`, which nothing
+    called, is removed.)
 11. (fixed, see 71) resend: the `Idempotency-Key` came from `Math.random`.
 12. (fixed, see 72 and 73) `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of
     an injected logger.
diff --git a/src/ses/message-converter.js b/src/ses/message-converter.js
index e33b661..9834da8 100644
--- a/src/ses/message-converter.js
+++ b/src/ses/message-converter.js
@@ -120,103 +120,4 @@ const convertAttachment = async (attachment, signal) => {
   return converted;
 };
 
-// Dead upstream: nothing calls it (CLAUDE.md, known upstream bugs).
-/* c8 ignore start */
-const convertMessagesToBulk = async (messages, config, signal) => {
-  if (messages.length === 0) {
-    throw new Error('Cannot convert empty message array to bulk email');
-  }
-
-  const firstMessage = messages[0];
-  const defaultContent = await createSimpleContent(firstMessage, signal);
-
-  const defaultTags = [];
-  for (const [name, value] of Object.entries(config.defaultTags)) {
-    defaultTags.push({ Name: name, Value: value });
-  }
-
-  const bulkMessage = {
-    FromEmailAddress: formatAddress(firstMessage.sender),
-    DefaultContent: { Simple: defaultContent },
-    DefaultEmailTags: defaultTags.length > 0 ? defaultTags : undefined,
-    BulkEmailEntries: [],
-  };
-
-  if (firstMessage.replyRecipients.length > 0) {
-    bulkMessage.ReplyToAddresses = firstMessage.replyRecipients.map(formatAddress);
-  }
-
-  if (config.configurationSetName) {
-    bulkMessage.ConfigurationSetName = config.configurationSetName;
-  }
-
-  for (const message of messages) {
-    const destination = {};
-
-    if (message.recipients.length > 0) {
-      destination.ToAddresses = formatAddresses(message.recipients, formatAddress);
-    }
-    if (message.ccRecipients.length > 0) {
-      destination.CcAddresses = formatAddresses(message.ccRecipients, formatAddress);
-    }
-    if (message.bccRecipients.length > 0) {
-      destination.BccAddresses = formatAddresses(message.bccRecipients, formatAddress);
-    }
-
-    const entry = {
-      Destination: destination,
-    };
-
-    const isContentDifferent =
-      message.subject !== firstMessage.subject ||
-      JSON.stringify(message.content) !== JSON.stringify(firstMessage.content) ||
-      JSON.stringify(message.calendar) !== JSON.stringify(firstMessage.calendar) ||
-      message.attachments.length !== firstMessage.attachments.length ||
-      (message.attachments.length > 0 &&
-        JSON.stringify(
-          message.attachments.map((a) => ({
-            filename: a.filename,
-            contentType: a.contentType,
-            contentId: a.contentId,
-            inline: a.inline,
-          })),
-        ) !==
-          JSON.stringify(
-            firstMessage.attachments.map((a) => ({
-              filename: a.filename,
-              contentType: a.contentType,
-              contentId: a.contentId,
-              inline: a.inline,
-            })),
-          ));
-
-    if (isContentDifferent) {
-      const messageContent = await createSimpleContent(message, signal);
-      entry.ReplacementEmailContent = { Simple: messageContent };
-    }
-
-    const messageTags = [];
-
-    if (message.tags.length > 0) {
-      for (const tag of message.tags) {
-        messageTags.push({ Name: 'category', Value: tag });
-      }
-    }
-
-    if (message.priority !== 'normal') {
-      messageTags.push({ Name: 'priority', Value: message.priority });
-    }
-
-    if (messageTags.length > 0) {
-      entry.ReplacementTags = messageTags;
-    }
-
-    bulkMessage.BulkEmailEntries.push(entry);
-  }
-
-  return bulkMessage;
-};
-
-/* c8 ignore stop */
-
-module.exports = { convertMessage, convertMessagesToBulk };
+module.exports = { convertMessage };

From ab9e9fca58ec0728a95f95a01d22d39f687b05b8 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:47:46 +0300
Subject: [PATCH 134/158] refactor(pool): an attempt per method and a failure
 gathered in one record

send (92 lines) keeps the loop over transports; one attempt, recording a
failed receipt or a throw into one record, is attempt() and recordThrown,
and the receipt errors are appended in loops instead of spread pushes and
maps. The configuration resolves its entries and counts the enabled ones
and the valid weights in one pass instead of a filter, a map and a some.
Behavior is unchanged.

The budget of ./pool goes from 2.5 to 3 KB: it was at 2547 of 2560
bytes, the property names of the record add 76, and round-robin across
batches and the health of Phase 2 come next.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 scripts/size-budgets.json  |   2 +-
 src/pool/config.js         |  41 ++++----
 src/pool/pool-transport.js | 206 ++++++++++++++++++-------------------
 3 files changed, 126 insertions(+), 123 deletions(-)

diff --git a/scripts/size-budgets.json b/scripts/size-budgets.json
index 1eec525..8ee6a33 100644
--- a/scripts/size-budgets.json
+++ b/scripts/size-budgets.json
@@ -11,7 +11,7 @@
   "./maileroo": 5.5,
   "./lettermint": 5.5,
   "./plunk": 5,
-  "./pool": 2.5,
+  "./pool": 3,
   "./retry": 3,
   "./mock": 2,
   "./otel": 5,
diff --git a/src/pool/config.js b/src/pool/config.js
index 834b280..28a9873 100644
--- a/src/pool/config.js
+++ b/src/pool/config.js
@@ -13,34 +13,37 @@ const createPoolConfig = (config) => {
     throw new Error('Pool must have at least one transport');
   }
 
-  const enabledTransports = config.transports.filter((entry) => entry.enabled !== false);
+  // One pass resolves the entries and counts what the checks need.
+  const resolvedTransports = [];
+  let enabledCount = 0;
+  let hasValidWeights = false;
+  for (const entry of config.transports) {
+    const resolved = {
+      transport: entry.transport,
+      weight: entry.weight ?? 1,
+      priority: entry.priority ?? 0,
+      selector: entry.selector,
+      enabled: entry.enabled ?? true,
+    };
+    if (entry.enabled !== false) enabledCount++;
+    if (resolved.enabled && resolved.weight > 0) hasValidWeights = true;
+    resolvedTransports.push(resolved);
+  }
 
-  if (enabledTransports.length === 0) {
+  if (enabledCount === 0) {
     throw new Error('Pool must have at least one enabled transport');
   }
-
-  const resolvedTransports = config.transports.map((entry) => ({
-    transport: entry.transport,
-    weight: entry.weight ?? 1,
-    priority: entry.priority ?? 0,
-    selector: entry.selector,
-    enabled: entry.enabled ?? true,
-  }));
-
   // Validate weights for weighted strategy
-  if (config.strategy === 'weighted') {
-    const hasValidWeights = resolvedTransports.some((entry) => entry.enabled && entry.weight > 0);
-    if (!hasValidWeights) {
-      throw new Error(
-        'Weighted strategy requires at least one enabled transport with positive weight',
-      );
-    }
+  if (config.strategy === 'weighted' && !hasValidWeights) {
+    throw new Error(
+      'Weighted strategy requires at least one enabled transport with positive weight',
+    );
   }
 
   return {
     strategy: config.strategy,
     transports: resolvedTransports,
-    maxRetries: config.maxRetries ?? enabledTransports.length - 1,
+    maxRetries: config.maxRetries ?? enabledCount - 1,
     timeout: config.timeout,
     continueOnSuccess: config.continueOnSuccess ?? false,
     random: config.random,
diff --git a/src/pool/pool-transport.js b/src/pool/pool-transport.js
index 545a6dd..6913716 100644
--- a/src/pool/pool-transport.js
+++ b/src/pool/pool-transport.js
@@ -99,120 +99,84 @@ class PoolTransport {
   async send(message, options) {
     const pinned = pinMessageId(message, this.config.generateId);
     const attemptedIndices = new Set();
-    const errorMessages = [];
-    const errors = [];
-    let checkCallerAbortBeforeFailure = false;
     // Failover stops when another transport could only deliver the message a
     // second time (delivery unknown) or would refuse it too (the message
     // itself was rejected).
-    let deliveryUnknown = false;
-    let isRejected = false;
+    const failure = {
+      errorMessages: [],
+      errors: [],
+      checkCallerAbort: false,
+      deliveryUnknown: false,
+      isRejected: false,
+    };
 
     for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
-      // Check for cancellation
       options?.signal?.throwIfAborted();
-
-      // Select a transport
       const selection = this.strategy.select(pinned, this.config.transports, attemptedIndices);
-
-      if (!selection) {
-        // No more transports available
-        break;
-      }
-
+      // No more transports available
+      if (!selection) break;
       attemptedIndices.add(selection.index);
 
-      let abortedByCaller = false;
-      try {
-        // Apply timeout if configured
-        const sendOptions = this.createSendOptions(options);
-
-        let receipt;
-        try {
-          receipt = await selection.entry.transport.send(pinned, sendOptions.options);
-        } catch (error) {
-          if (sendOptions.abortedByCaller() && isCallerAbort(error, options?.signal)) {
-            abortedByCaller = true;
-          }
-          throw error;
-        } finally {
-          sendOptions.cleanup();
-        }
-
-        if (receipt.successful) {
-          return receipt;
-        }
-
-        // Collect error messages for failed attempts
-        errorMessages.push(...receipt.errorMessages);
-        errors.push(...getReceiptErrors(receipt, selection.entry.transport.id));
-        checkCallerAbortBeforeFailure = true;
-        deliveryUnknown = receipt.deliveryUnknown === true;
-        isRejected = hasMessageRejection(receipt.errors);
-        if (deliveryUnknown || isRejected) break;
+      const receipt = await this.attempt(selection, pinned, options, failure);
+      if (receipt?.successful) return receipt;
+      if (failure.deliveryUnknown || failure.isRejected) break;
+      if (receipt !== undefined) {
         this.log.write(
           'debug',
           () => ({ attempt: attempt + 1, failed: selection.entry.transport.id }),
           'Pool failing over',
         );
-      } catch (error) {
-        // Handle transport errors
-        if (abortedByCaller && isCallerAbort(error, options?.signal)) {
-          throw error;
-        }
-
-        const thrownErrors = getThrownReceiptErrors(error, selection.entry.transport.id);
-        if (thrownErrors.length > 0) {
-          errorMessages.push(...thrownErrors.map((item) => item.message));
-          errors.push(...thrownErrors);
-          checkCallerAbortBeforeFailure = true;
-          isRejected = hasMessageRejection(thrownErrors);
-          if (isRejected) break;
-          continue;
-        }
-
-        const timeoutMessage = 'Transport send timed out.';
-        const abortError = isAbortError(error);
-        const errorMessage = abortError
-          ? timeoutMessage
-          : error instanceof Error
-            ? error.message
-            : String(error);
-        errorMessages.push(errorMessage);
-        errors.push(
-          createReceiptError(errorMessage, {
-            provider: selection.entry.transport.id,
-            category: abortError ? 'timeout' : undefined,
-            retryable: abortError ? false : undefined,
-          }),
-        );
-        checkCallerAbortBeforeFailure ||= !abortError;
-        // A send cut short by the pool's timeout may already have been
-        // accepted: switching transports could deliver the message twice.
-        if (abortError) {
-          deliveryUnknown = true;
-          break;
-        }
       }
     }
-
     // All attempts failed
-    if (checkCallerAbortBeforeFailure) {
-      options?.signal?.throwIfAborted();
-    }
-
+    if (failure.checkCallerAbort) options?.signal?.throwIfAborted();
+    const { errorMessages, errors } = failure;
     return createFailedReceipt(
       errorMessages.length > 0 ? errorMessages : ['All transports failed to send the message.'],
       {
         provider: 'pool',
         errors: errors.length > 0 ? errors : undefined,
         attempts: attemptedIndices.size,
-        deliveryUnknown,
-        retryable: isRejected ? false : undefined,
+        deliveryUnknown: failure.deliveryUnknown,
+        retryable: failure.isRejected ? false : undefined,
       },
     );
   }
 
+  /**
+   * Sends a message through the selected transport once, under the pool's
+   * timeout, and records a failure.
+   *
+   * @param selection The selected transport and its index.
+   * @param pinned The message, with its Message-ID pinned.
+   * @param options The options of the caller.
+   * @param failure What the failed attempts have gathered, updated in place.
+   * @returns The receipt of the transport, or `undefined` when it threw.
+   * @throws The caller's abort reason when the caller aborts.
+   */
+  async attempt(selection, pinned, options, failure) {
+    const transportId = selection.entry.transport.id;
+    const sendOptions = this.createSendOptions(options);
+    let receipt;
+    try {
+      receipt = await selection.entry.transport.send(pinned, sendOptions.options);
+    } catch (error) {
+      if (sendOptions.abortedByCaller() && isCallerAbort(error, options?.signal)) throw error;
+      recordThrown(failure, error, transportId);
+      return undefined;
+    } finally {
+      sendOptions.cleanup();
+    }
+    if (!receipt.successful) {
+      for (const text of receipt.errorMessages) failure.errorMessages.push(text);
+      appendReceiptErrors(failure.errors, receipt, transportId);
+      failure.checkCallerAbort = true;
+      failure.deliveryUnknown = receipt.deliveryUnknown === true;
+      failure.isRejected = hasMessageRejection(receipt.errors);
+    }
+    return receipt;
+  }
+
   /**
    * Sends multiple email messages using the pool strategy.
    *
@@ -367,29 +331,65 @@ const isCallerAbort = (error, signal) => {
   return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
 };
 
-const getReceiptErrors = (receipt, provider) => {
+// Appends the structured errors of a failed receipt, or ones made from its
+// messages, each naming the transport.
+const appendReceiptErrors = (target, receipt, provider) => {
   if (receipt.errors != null && receipt.errors.length > 0) {
-    return receipt.errors.map((error) => withReceiptErrorProvider(error, provider));
+    for (const error of receipt.errors) target.push(withReceiptErrorProvider(error, provider));
+    return;
+  }
+  for (const message of receipt.errorMessages) {
+    target.push(
+      createReceiptError(message, {
+        provider: receipt.provider ?? provider,
+        retryable: receipt.retryable,
+      }),
+    );
   }
-
-  return receipt.errorMessages.map((message) =>
-    createReceiptError(message, {
-      provider: receipt.provider ?? provider,
-      retryable: receipt.retryable,
-    }),
-  );
 };
 
 const getThrownReceiptErrors = (error, provider) => {
-  if (isReceiptError(error)) {
-    return [withReceiptErrorProvider(error, provider)];
-  }
+  const errors = [];
+  if (isReceiptError(error)) errors.push(withReceiptErrorProvider(error, provider));
+  else if (isFailedReceipt(error)) appendReceiptErrors(errors, error, provider);
+  return errors;
+};
 
-  if (isFailedReceipt(error)) {
-    return getReceiptErrors(error, provider);
+/**
+ * Records what a transport threw: a receipt error or a failed receipt as it
+ * is, anything else as an error of its own, and the pool's timeout as a send
+ * whose delivery is unknown.
+ *
+ * @param failure What the failed attempts have gathered, updated in place.
+ * @param error What the transport threw.
+ * @param transportId The id of the transport.
+ */
+const recordThrown = (failure, error, transportId) => {
+  const thrownErrors = getThrownReceiptErrors(error, transportId);
+  if (thrownErrors.length > 0) {
+    for (const item of thrownErrors) {
+      failure.errorMessages.push(item.message);
+      failure.errors.push(item);
+    }
+    failure.checkCallerAbort = true;
+    failure.isRejected = hasMessageRejection(thrownErrors);
+    return;
   }
-
-  return [];
+  const abortError = isAbortError(error);
+  let errorMessage = 'Transport send timed out.';
+  if (!abortError) errorMessage = error instanceof Error ? error.message : String(error);
+  failure.errorMessages.push(errorMessage);
+  failure.errors.push(
+    createReceiptError(errorMessage, {
+      provider: transportId,
+      category: abortError ? 'timeout' : undefined,
+      retryable: abortError ? false : undefined,
+    }),
+  );
+  failure.checkCallerAbort ||= !abortError;
+  // A send cut short by the pool's timeout may already have been accepted:
+  // switching transports could deliver the message twice.
+  if (abortError) failure.deliveryUnknown = true;
 };
 
 const withReceiptErrorProvider = (error, provider) => {

From 473178d29c4fc0ad9b533e93f09c369719d7d042 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:47:46 +0300
Subject: [PATCH 135/158] refactor(mock): find sent messages with loops

getMessagesTo looked through a spread of the three recipient lists for
each message; it checks each list in place. findMessageBy, findMessagesBy
and getMessagesBySubject are loops. Behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mock/mock-transport.js | 29 ++++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)

diff --git a/src/mock/mock-transport.js b/src/mock/mock-transport.js
index 7239261..94bed9c 100644
--- a/src/mock/mock-transport.js
+++ b/src/mock/mock-transport.js
@@ -5,6 +5,13 @@ const { sleep } = require('../internal/sleep.js');
 const { createFailedReceipt } = require('../core/receipt.js');
 const { createMockConfig } = require('./config.js');
 
+const hasAddress = (addresses, email) => {
+  for (const address of addresses) {
+    if (address.address === email) return true;
+  }
+  return false;
+};
+
 /**
  * A mock transport implementation for testing purposes.
  *
@@ -206,7 +213,10 @@ class MockTransport {
    * @returns The first matching message, or undefined if none found.
    */
   findMessageBy(predicate) {
-    return this.sentMessages.find(predicate);
+    for (const message of this.sentMessages) {
+      if (predicate(message)) return message;
+    }
+    return undefined;
   }
 
   /**
@@ -216,7 +226,11 @@ class MockTransport {
    * @returns An array of all matching messages.
    */
   findMessagesBy(predicate) {
-    return this.sentMessages.filter(predicate);
+    const found = [];
+    for (const message of this.sentMessages) {
+      if (predicate(message)) found.push(message);
+    }
+    return found;
   }
 
   /**
@@ -229,10 +243,11 @@ class MockTransport {
    * @returns An array of messages sent to the specified address.
    */
   getMessagesTo(email) {
-    return this.sentMessages.filter((message) =>
-      [...message.recipients, ...message.ccRecipients, ...message.bccRecipients].some(
-        (addr) => addr.address === email,
-      ),
+    return this.findMessagesBy(
+      (message) =>
+        hasAddress(message.recipients, email) ||
+        hasAddress(message.ccRecipients, email) ||
+        hasAddress(message.bccRecipients, email),
     );
   }
 
@@ -243,7 +258,7 @@ class MockTransport {
    * @returns An array of messages with the specified subject.
    */
   getMessagesBySubject(subject) {
-    return this.sentMessages.filter((message) => message.subject === subject);
+    return this.findMessagesBy((message) => message.subject === subject);
   }
 
   /**

From f3cbe0e707eb22143aa12e919ca74f4e1238857f Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:49:58 +0300
Subject: [PATCH 136/158] refactor(mime): prepareMimeStream reads, signs and
 replays in parts

prepareMimeStream (94 lines) hashes the body once in hashBody, signs the
headers in signHeaders, which keeps the signatures made before one that
fails under send-unsigned, and checks a streamed replay in replayBody.
Behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mime/stream.js | 120 ++++++++++++++++++++++++++++-----------------
 1 file changed, 74 insertions(+), 46 deletions(-)

diff --git a/src/mime/stream.js b/src/mime/stream.js
index 69ea454..89380a5 100644
--- a/src/mime/stream.js
+++ b/src/mime/stream.js
@@ -46,14 +46,52 @@ const prepareMimeStream = async (plan, options = {}) => {
     };
   }
   const buffered = plan.dkim?.bodyMode !== 'streaming';
-  const chunks = [];
-  const hashes = new Map();
-  for (const sig of signatures) {
-    const mode = sig.canonicalization?.endsWith('/simple') ? 'simple' : 'relaxed';
-    if (!hashes.has(mode)) hashes.set(mode, new BodyHasher(mode));
+  const body = await hashBody(plan, signatures, buffered, checkSize, signal, progress);
+  const headers = await signHeaders(plan, signatures, body.hashes, signal);
+  signal?.throwIfAborted();
+  if (hasLineLongerThan(headers, 998)) {
+    throw new RangeError('Signed MIME header exceeds the RFC 5322 line limit.');
+  }
+  const size = Buffer.byteLength(headers) + body.length;
+  checkSize(size);
+  return {
+    size,
+    encoding: plan.encoding === 'utf8' || /[\u0080-\uffff]/.test(headers) ? 'utf8' : '7bit',
+    // oxlint-disable-next-line no-shadow -- upstream
+    async *read(signal, progress) {
+      signal?.throwIfAborted();
+      yield utf8(headers);
+      if (buffered) {
+        for (const chunk of body.chunks) {
+          signal?.throwIfAborted();
+          yield chunk.slice();
+        }
+        return;
+      }
+      yield* replayBody(plan, body, signal, progress);
+    },
+  };
+};
+
+const canonicalizationOf = (signature) =>
+  signature.canonicalization?.endsWith('/simple') ? 'simple' : 'relaxed';
+
+/**
+ * Reads the body once, hashing it for each body canonicalization the
+ * signatures use, and keeping its chunks when it is buffered or the digest a
+ * streamed replay is checked against.
+ *
+ * @returns The `hashes` by canonicalization, the `length`, and the `chunks`
+ * or the `digest`.
+ */
+const hashBody = async (plan, signatures, buffered, checkSize, signal, progress) => {
+  const hashers = new Map();
+  for (const signature of signatures) {
+    const mode = canonicalizationOf(signature);
+    if (!hashers.has(mode)) hashers.set(mode, new BodyHasher(mode));
   }
-  // The digest that a streamed replay is checked against; a buffered body is
-  // replayed from its own chunks and needs none.
+  const chunks = [];
+  // A buffered body is replayed from its own chunks and needs no digest.
   const rawHash = buffered ? undefined : createHash('sha256');
   let length = 0;
   const headerLength = Buffer.byteLength(plan.headers);
@@ -63,16 +101,23 @@ const prepareMimeStream = async (plan, options = {}) => {
     if (chunk.length > 0) progress();
     if (buffered) chunks.push(chunk.slice());
     rawHash?.update(chunk);
-    for (const hash of hashes.values()) hash.update(chunk);
+    for (const hasher of hashers.values()) hasher.update(chunk);
   }
-  const expectedDigest = rawHash == null ? undefined : base64(rawHash.digest());
-  const bodyHashes = new Map();
-  for (const [mode, hash] of hashes) bodyHashes.set(mode, hash.digest());
+  const hashes = new Map();
+  for (const [mode, hasher] of hashers) hashes.set(mode, hasher.digest());
+  const digest = rawHash == null ? undefined : base64(rawHash.digest());
+  return { hashes, length, chunks, digest };
+};
+
+// The headers with a DKIM-Signature per signature on top, the last one first.
+// When a signature fails and the configuration sends unsigned, the ones made
+// before it stay.
+const signHeaders = async (plan, signatures, hashes, signal) => {
   let headers = plan.headers;
   try {
-    for (const sig of signatures) {
-      const mode = sig.canonicalization?.endsWith('/simple') ? 'simple' : 'relaxed';
-      const result = await signWithBodyHash(headers, sig, bodyHashes.get(mode), signal);
+    for (const signature of signatures) {
+      const bodyHash = hashes.get(canonicalizationOf(signature));
+      const result = await signWithBodyHash(headers, signature, bodyHash, signal);
       headers = `${result.headerName}: ${result.signature}\r\n${headers}`;
     }
   } catch (error) {
@@ -85,39 +130,22 @@ const prepareMimeStream = async (plan, options = {}) => {
       { error: error instanceof Error ? error.message : String(error) },
     );
   }
-  signal?.throwIfAborted();
-  if (hasLineLongerThan(headers, 998)) {
-    throw new RangeError('Signed MIME header exceeds the RFC 5322 line limit.');
+  return headers;
+};
+
+// Reads a streamed body again and checks it is the one that was signed.
+const replayBody = async function* (plan, body, signal, progress) {
+  const replayHash = createHash('sha256');
+  let replayLength = 0;
+  for await (const chunk of plan.body(signal, progress)) {
+    replayLength += chunk.length;
+    if (replayLength > body.length) throw new MimeAttachmentReplayError();
+    replayHash.update(chunk);
+    yield chunk;
+  }
+  if (replayLength !== body.length || base64(replayHash.digest()) !== body.digest) {
+    throw new MimeAttachmentReplayError();
   }
-  const size = Buffer.byteLength(headers) + length;
-  checkSize(size);
-  return {
-    size,
-    encoding: plan.encoding === 'utf8' || /[\u0080-\uffff]/.test(headers) ? 'utf8' : '7bit',
-    // oxlint-disable-next-line no-shadow -- upstream
-    async *read(signal, progress) {
-      signal?.throwIfAborted();
-      yield utf8(headers);
-      if (buffered) {
-        for (const chunk of chunks) {
-          signal?.throwIfAborted();
-          yield chunk.slice();
-        }
-        return;
-      }
-      const replayHash = createHash('sha256');
-      let replayLength = 0;
-      for await (const chunk of plan.body(signal, progress)) {
-        replayLength += chunk.length;
-        if (replayLength > length) throw new MimeAttachmentReplayError();
-        replayHash.update(chunk);
-        yield chunk;
-      }
-      if (replayLength !== length || base64(replayHash.digest()) !== expectedDigest) {
-        throw new MimeAttachmentReplayError();
-      }
-    },
-  };
 };
 
 module.exports = { MimeAttachmentReplayError, prepareMimeStream };

From ab16ab076c181f1295faf02e3d11e0a565afc18c Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:49:58 +0300
Subject: [PATCH 137/158] refactor(retry,otel): loops instead of some and find,
 a flatter batch loop

isProgrammerError, hasRetryableError and getRetryAfterMilliseconds of
./retry are loops; the batch loop of ./otel keeps the messages of a
failed receipt through keepErrorMessages, four blocks deep at most.
Behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/otel/opentelemetry-transport.js | 14 +++++++++++---
 src/retry/retry-transport.js        | 19 ++++++++++++++-----
 2 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/src/otel/opentelemetry-transport.js b/src/otel/opentelemetry-transport.js
index 1238c16..d34a7e9 100644
--- a/src/otel/opentelemetry-transport.js
+++ b/src/otel/opentelemetry-transport.js
@@ -261,9 +261,7 @@ class OpenTelemetryTransport {
           successCount++;
         } else {
           failureCount++;
-          for (const errorMessage of receipt.errorMessages) {
-            if (errorMessageCount++ < MAX_RECORDED_ERROR_MESSAGES) errorMessages.push(errorMessage);
-          }
+          errorMessageCount = keepErrorMessages(errorMessages, errorMessageCount, receipt);
         }
 
         yield receipt;
@@ -446,4 +444,14 @@ class OpenTelemetryTransport {
   }
 }
 
+// Keeps the messages of a failed receipt while fewer than the bound are kept,
+// and counts all of them.
+const keepErrorMessages = (kept, count, receipt) => {
+  let total = count;
+  for (const errorMessage of receipt.errorMessages) {
+    if (total++ < MAX_RECORDED_ERROR_MESSAGES) kept.push(errorMessage);
+  }
+  return total;
+};
+
 module.exports = { OpenTelemetryTransport };
diff --git a/src/retry/retry-transport.js b/src/retry/retry-transport.js
index 2df189a..4d6adc1 100644
--- a/src/retry/retry-transport.js
+++ b/src/retry/retry-transport.js
@@ -20,8 +20,10 @@ const { createRetryConfig } = require('./config.js');
 const PROGRAMMER_ERRORS = [TypeError, RangeError, ReferenceError, SyntaxError];
 
 const isProgrammerError = (error) => {
-  if (!PROGRAMMER_ERRORS.some((type) => error instanceof type)) return false;
-  return classifyReceiptError(error).category === 'unknown';
+  for (const type of PROGRAMMER_ERRORS) {
+    if (error instanceof type) return classifyReceiptError(error).category === 'unknown';
+  }
+  return false;
 };
 
 class RetryTransport {
@@ -350,7 +352,11 @@ class RetryTransport {
   }
 
   hasRetryableError(errors) {
-    return errors?.some((error) => error.retryable) ?? false;
+    if (errors == null) return false;
+    for (const error of errors) {
+      if (error.retryable) return true;
+    }
+    return false;
   }
 
   // A server that asks to wait longer than the longest delay is not asked
@@ -467,8 +473,11 @@ const createRetryTransport = (baseTransport, config = {}) => {
 const getRetryAfterMilliseconds = (failure) => {
   if (failure == null) return undefined;
   if (isReceiptError(failure)) return failure.retryAfterMilliseconds;
-  return failure.errors?.find((error) => error.retryAfterMilliseconds != null)
-    ?.retryAfterMilliseconds;
+  if (failure.errors == null) return undefined;
+  for (const error of failure.errors) {
+    if (error.retryAfterMilliseconds != null) return error.retryAfterMilliseconds;
+  }
+  return undefined;
 };
 
 const toAsyncIterator = (values) => {

From 20628b9d076274aed0f3fc6af8fed3334c0c187d Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:49:58 +0300
Subject: [PATCH 138/158] refactor(mailgun,resend): name the caught error error

The JSON parse failures were caught as jsonError and parseError, against
the catch (error) of the code style.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/mailgun/http-client.js | 6 +++---
 src/resend/http-client.js  | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/mailgun/http-client.js b/src/mailgun/http-client.js
index 57d3af3..8c767e1 100644
--- a/src/mailgun/http-client.js
+++ b/src/mailgun/http-client.js
@@ -65,12 +65,12 @@ class MailgunHttpClient {
         const text = await readText(response);
         try {
           return JSON.parse(text);
-        } catch (jsonError) {
+        } catch (error) {
           // This handles cases where the request was successful (e.g., 2xx status)
           // but the response body is not valid JSON.
           throw new Error(
-            `Successfully received response but failed to parse JSON: ${jsonError.message}`,
-            { cause: jsonError },
+            `Successfully received response but failed to parse JSON: ${error.message}`,
+            { cause: error },
           );
         }
       },
diff --git a/src/resend/http-client.js b/src/resend/http-client.js
index 7a50756..4cbdadb 100644
--- a/src/resend/http-client.js
+++ b/src/resend/http-client.js
@@ -140,12 +140,12 @@ class ResendHttpClient {
         const text = await readText(response);
         try {
           return JSON.parse(text);
-        } catch (parseError) {
+        } catch (error) {
           throw new Error(
             `Invalid JSON response from Resend API: ${
-              parseError instanceof Error ? parseError.message : String(parseError)
+              error instanceof Error ? error.message : String(error)
             }`,
-            { cause: parseError },
+            { cause: error },
           );
         }
       },

From 750a97138f6ee40d09670564f6d830a8a7db3143 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:54:35 +0300
Subject: [PATCH 139/158] chore(lint): enforce the conventions in oxlint

func-style (expressions), no-nested-ternary and max-depth 4 apply
everywhere; in src/, no-restricted-properties refuses the array iteration
methods, the unicorn rules no-array-for-each, no-array-reduce,
no-useless-spread and prefer-set-has apply, and max-lines-per-function
warns over 80 lines; pnpm lint fails on an unused disable directive.
no-console is off only for scripts, bench and the opt-in suites, as
CLAUDE.md says, no longer for every test.

The tests follow: function declarations become expressions, nested
ternaries become ifs or tables, a JMAP fetch stub reads its URL through
tests/helpers/jmap/request-url.js, two unit tests stop logging, and a
property access split over lines goes through a variable. Four helpers of
src/ that captured nothing move to module scope.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .oxlintrc.json                                | 89 ++++++++++++++++++-
 CLAUDE.md                                     |  9 +-
 package.json                                  |  2 +-
 src/mime/message.js                           |  3 +-
 src/pool/pool-transport.js                    |  6 +-
 src/ses/ses-transport.js                      |  3 +-
 tests/e2e/jmap-transport.e2e.test.js          | 12 +--
 tests/e2e/plunk-transport.e2e.test.js         | 16 ++--
 tests/e2e/resend-transport.e2e.test.js        | 12 +--
 tests/helpers/jmap/request-url.js             |  9 ++
 tests/helpers/mailgun/test-config.js          |  4 +-
 tests/helpers/otel/mock-otel-providers.js     |  9 +-
 tests/helpers/plunk/test-config.js            |  4 +-
 tests/helpers/sendgrid/test-config.js         |  4 +-
 tests/helpers/smtp/test-config.js             |  7 +-
 tests/unit/jmap-blob-uploader.test.js         |  4 +-
 .../unit/jmap-raw-message.integration.test.js |  8 +-
 tests/unit/jmap-retry-attempts.test.js        |  4 +-
 tests/unit/jmap-send-error.test.js            |  4 +-
 tests/unit/jmap-send-success.test.js          |  4 +-
 tests/unit/jmap-sendmany.test.js              | 10 +--
 tests/unit/jmap-verify.test.js                |  8 +-
 tests/unit/lettermint-transport.test.js       |  4 +-
 tests/unit/logger-transport.test.js           |  8 +-
 tests/unit/mailgun-transport.test.js          |  4 -
 tests/unit/mime-compose.test.js               | 30 +++----
 tests/unit/retry-transport.test.js            | 32 +++----
 .../smtp-large-attachment.integration.test.js | 35 +++++---
 tests/unit/smtp-oauth2.test.js                |  4 +-
 .../smtp-transport.pool.integration.test.js   |  6 +-
 tests/unit/smtp-transport.test.js             |  9 +-
 tests/unit/smtp-verify.integration.test.js    |  7 +-
 32 files changed, 233 insertions(+), 137 deletions(-)
 create mode 100644 tests/helpers/jmap/request-url.js

diff --git a/.oxlintrc.json b/.oxlintrc.json
index 47f0d88..2897f0f 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -255,14 +255,99 @@
     "no-setter-return": "error",
     "no-unused-private-class-members": "error",
     "no-constant-binary-expression": "error",
-    "no-console": "error"
+    "no-console": "error",
+    "func-style": [
+      "error",
+      "expression"
+    ],
+    "no-nested-ternary": "error",
+    "max-depth": [
+      "error",
+      {
+        "max": 4
+      }
+    ]
   },
   "overrides": [
+    {
+      "files": [
+        "src/**"
+      ],
+      "plugins": [
+        "unicorn"
+      ],
+      "rules": {
+        "no-restricted-properties": [
+          "error",
+          {
+            "property": "map",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "filter",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "some",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "every",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "find",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "findIndex",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "findLast",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "findLastIndex",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "reduce",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "reduceRight",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "flatMap",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          },
+          {
+            "property": "forEach",
+            "message": "src/ iterates with loops in one pass (CLAUDE.md, Conventions)."
+          }
+        ],
+        "max-lines-per-function": [
+          "warn",
+          {
+            "max": 80,
+            "skipBlankLines": true,
+            "skipComments": true
+          }
+        ],
+        "unicorn/no-array-for-each": "error",
+        "unicorn/no-array-reduce": "error",
+        "unicorn/no-useless-spread": "error",
+        "unicorn/prefer-set-has": "error"
+      }
+    },
     {
       "files": [
         "scripts/**",
         "bench/**",
-        "tests/**"
+        "tests/e2e/**",
+        "tests/helpers/**"
       ],
       "rules": {
         "no-console": "off"
diff --git a/CLAUDE.md b/CLAUDE.md
index 7651b54..cf7f0ad 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -517,8 +517,13 @@ entry with no `node:*`, and a platform test would enforce it as in protoarray.
 - Formatting: 2 spaces, single quotes, semicolons, trailing commas, **100 columns**, LF
   (`.oxfmtrc.json`, `.editorconfig`). Lint: `.oxlintrc.json` (shared with protoarray: the explicit
   rule list, plus the `correctness` and `suspicious` categories as errors and `no-console`
-  everywhere but `scripts/` and `bench/`). Suppress a rule only for an intentional construct, with
-  a targeted `// oxlint-disable-next-line <rule>`.
+  everywhere but `scripts/`, `bench/` and the opt-in suites, `tests/e2e/` and `tests/helpers/`).
+  The code style below is enforced where a rule exists: `func-style` (expressions),
+  `no-nested-ternary` and `max-depth` 4 everywhere; in `src/`, `no-restricted-properties` on the
+  array iteration methods, the unicorn rules `no-array-for-each`, `no-array-reduce`,
+  `no-useless-spread` and `prefer-set-has`, and `max-lines-per-function` 80 as a warning.
+  Suppress a rule only for an intentional construct, with a targeted
+  `// oxlint-disable-next-line <rule>`; `pnpm lint` fails on a directive that suppresses nothing.
 - Code style:
   - module-level functions are arrow functions assigned to `const`; classes and prototype objects
     use method shorthand; no `function` declarations;
diff --git a/package.json b/package.json
index abaf015..6ec5c8a 100644
--- a/package.json
+++ b/package.json
@@ -112,7 +112,7 @@
     "test:types": "tsd",
     "check:dts": "node scripts/check-dts.js",
     "check:pack": "node scripts/check-pack.js",
-    "lint": "oxlint src tests scripts bench",
+    "lint": "oxlint --report-unused-disable-directives-severity=error src tests scripts bench",
     "format": "oxfmt src tests scripts bench",
     "format:check": "oxfmt --check src tests scripts bench",
     "size": "node scripts/size.js",
diff --git a/src/mime/message.js b/src/mime/message.js
index d75df61..8acf1a8 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -458,6 +458,8 @@ const monthNames = [
   'Dec',
 ];
 
+const pad = (value) => value.toString().padStart(2, '0');
+
 /**
  * Formats a date as an RFC 5322 §3.3 `date-time` in UTC.
  *
@@ -475,7 +477,6 @@ const formatDate = (date) => {
   if (Number.isNaN(time) || year < 1900) {
     throw new TypeError(`Invalid date: ${JSON.stringify(date)}`);
   }
-  const pad = (value) => value.toString().padStart(2, '0');
   return (
     `${dayNames[date.getUTCDay()]}, ${pad(date.getUTCDate())} ` +
     `${monthNames[date.getUTCMonth()]} ${year.toString().padStart(4, '0')} ` +
diff --git a/src/pool/pool-transport.js b/src/pool/pool-transport.js
index 6913716..5b1f33f 100644
--- a/src/pool/pool-transport.js
+++ b/src/pool/pool-transport.js
@@ -279,9 +279,9 @@ class PoolTransport {
       abortSource ??= 'timeout';
       timeoutController.abort(createAbortError());
     }, this.config.timeout);
-    let cleanupAbortSource = () => {};
+    let cleanupAbortSource = noop;
     let signal = timeoutController.signal;
-    let cleanupCombinedSignal = () => {};
+    let cleanupCombinedSignal = noop;
 
     // Combine with existing signal if present
     if (options?.signal) {
@@ -323,6 +323,8 @@ class PoolTransport {
   }
 }
 
+const noop = () => {};
+
 const createAbortError = () => {
   return new DOMException('The operation was aborted.', 'AbortError');
 };
diff --git a/src/ses/ses-transport.js b/src/ses/ses-transport.js
index 537f43c..e856e6f 100644
--- a/src/ses/ses-transport.js
+++ b/src/ses/ses-transport.js
@@ -229,6 +229,8 @@ class SesTransport {
   }
 }
 
+const isFilled = (value) => typeof value === 'string' && value !== '';
+
 // A wrong authentication is refused when the transport is made: found at the
 // first send, it was retried like an outage before it failed.
 const checkAuthentication = (authentication) => {
@@ -236,7 +238,6 @@ const checkAuthentication = (authentication) => {
   if (type !== 'credentials' && type !== 'session') {
     throw new TypeError(`Unsupported authentication type: ${type}`);
   }
-  const isFilled = (value) => typeof value === 'string' && value !== '';
   if (!isFilled(authentication.accessKeyId) || !isFilled(authentication.secretAccessKey)) {
     throw new TypeError('SES authentication needs an accessKeyId and a secretAccessKey.');
   }
diff --git a/tests/e2e/jmap-transport.e2e.test.js b/tests/e2e/jmap-transport.e2e.test.js
index b44a2ca..b716342 100644
--- a/tests/e2e/jmap-transport.e2e.test.js
+++ b/tests/e2e/jmap-transport.e2e.test.js
@@ -201,7 +201,7 @@ describe('JmapTransport E2E Tests', { skip: !isStalwartTestingEnabled(), concurr
    * Extracts and decodes the `text/calendar` part of a composed message,
    * whichever transfer encoding the server chose for it.
    */
-  function decodeCalendarPart(mime) {
+  const decodeCalendarPart = (mime) => {
     const marker = mime.search(/^Content-Type:\s*text\/calendar/im);
     assert.ok(marker >= 0, 'no text/calendar part');
     const headerEnd = mime.indexOf('\r\n\r\n', marker);
@@ -233,7 +233,7 @@ describe('JmapTransport E2E Tests', { skip: !isStalwartTestingEnabled(), concurr
       return new TextDecoder().decode(Uint8Array.from(bytes));
     }
     return payload;
-  }
+  };
 
   it('should send an email with attachment', async () => {
     const config = getTestConfig();
@@ -425,7 +425,7 @@ describe('JmapTransport E2E Tests', { skip: !isStalwartTestingEnabled(), concurr
    * Downloads the RFC 5322 message the server composed for a subject, which
    * is the only way to see whether a part header survived `Email/set`.
    */
-  async function downloadComposedMime(config, subject) {
+  const downloadComposedMime = async (config, subject) => {
     const { sessionUrl, basicAuth, bearerToken, baseUrl } = config.jmap;
     const authorization =
       bearerToken == null
@@ -484,13 +484,13 @@ describe('JmapTransport E2E Tests', { skip: !isStalwartTestingEnabled(), concurr
     });
     assert.ok(download.ok, `download failed: ${download.status}`);
     return await download.text();
-  }
+  };
 
   /**
    * Reads back the stored Email with a given subject through raw JMAP, so
    * that an assertion sees the server's own representation.
    */
-  async function fetchStoredEmail(config, subject) {
+  const fetchStoredEmail = async (config, subject) => {
     const { sessionUrl, basicAuth, bearerToken, baseUrl } = config.jmap;
     const authorization =
       bearerToken == null
@@ -539,5 +539,5 @@ describe('JmapTransport E2E Tests', { skip: !isStalwartTestingEnabled(), concurr
       `no stored Email found for subject ${JSON.stringify(subject)}`,
     );
     return emails[0];
-  }
+  };
 });
diff --git a/tests/e2e/plunk-transport.e2e.test.js b/tests/e2e/plunk-transport.e2e.test.js
index d7d9ff8..d0e675b 100644
--- a/tests/e2e/plunk-transport.e2e.test.js
+++ b/tests/e2e/plunk-transport.e2e.test.js
@@ -237,26 +237,26 @@ describe('PlunkTransport E2E quota helpers', () => {
   });
 });
 
-function assertSuccessful(receipt) {
+const assertSuccessful = (receipt) => {
   assert.ok(receipt.successful, 'Send should be successful');
   assert.ok(receipt.messageId, 'Should have a message ID');
-}
+};
 
-function acceptQuotaLimit(receipt, label) {
+const acceptQuotaLimit = (receipt, label) => {
   if (!isQuotaLimitReceipt(receipt)) return false;
   console.log(`${label} test skipped due to Plunk transactional limit.`);
   return true;
-}
+};
 
-function isQuotaLimitedBatch(receipts) {
+const isQuotaLimitedBatch = (receipts) => {
   const failures = receipts.filter((receipt) => !receipt.successful);
   return failures.length > 0 && failures.every(isQuotaLimitReceipt);
-}
+};
 
-function isQuotaLimitReceipt(receipt) {
+const isQuotaLimitReceipt = (receipt) => {
   return (
     !receipt.successful &&
     receipt.errors?.some((error) => error.statusCode === 402) === true &&
     receipt.errorMessages.some((message) => message.includes('transactional limit'))
   );
-}
+};
diff --git a/tests/e2e/resend-transport.e2e.test.js b/tests/e2e/resend-transport.e2e.test.js
index ccdc728..8961387 100644
--- a/tests/e2e/resend-transport.e2e.test.js
+++ b/tests/e2e/resend-transport.e2e.test.js
@@ -435,13 +435,13 @@ describe('ResendTransport E2E quota helpers', () => {
   });
 });
 
-function acceptDailyQuotaLimit(receipt, label) {
+const acceptDailyQuotaLimit = (receipt, label) => {
   if (!isDailyQuotaLimitReceipt(receipt)) return false;
   console.log(`${label} test skipped due to Resend daily quota.`);
   return true;
-}
+};
 
-function assertBatchReceipts(receipts) {
+const assertBatchReceipts = (receipts) => {
   let dailyQuotaFailures = 0;
   for (const receipt of receipts) {
     if (isDailyQuotaLimitReceipt(receipt)) {
@@ -451,9 +451,9 @@ function assertBatchReceipts(receipts) {
     assert.ok(receipt.successful);
   }
   return dailyQuotaFailures;
-}
+};
 
-function isDailyQuotaLimitReceipt(receipt) {
+const isDailyQuotaLimitReceipt = (receipt) => {
   return (
     !receipt.successful &&
     receipt.errors?.some((error) => error.statusCode === 429) === true &&
@@ -461,4 +461,4 @@ function isDailyQuotaLimitReceipt(receipt) {
       message.toLowerCase().includes('daily email sending quota'),
     )
   );
-}
+};
diff --git a/tests/helpers/jmap/request-url.js b/tests/helpers/jmap/request-url.js
new file mode 100644
index 0000000..d5b10c2
--- /dev/null
+++ b/tests/helpers/jmap/request-url.js
@@ -0,0 +1,9 @@
+// The URL a stubbed fetch was called with, whether it got a string, a URL or a
+// Request.
+
+const requestUrl = (input) => {
+  if (typeof input === 'string') return input;
+  return input instanceof URL ? input.href : input.url;
+};
+
+module.exports = { requestUrl };
diff --git a/tests/helpers/mailgun/test-config.js b/tests/helpers/mailgun/test-config.js
index 5fe89aa..678d316 100644
--- a/tests/helpers/mailgun/test-config.js
+++ b/tests/helpers/mailgun/test-config.js
@@ -24,14 +24,14 @@ const getTestConfig = () => {
   };
 };
 
-function isE2eTestingEnabled() {
+const isE2eTestingEnabled = () => {
   return !!(
     process.env.MAILGUN_KEY &&
     process.env.MAILGUN_FROM &&
     process.env.MAILGUN_TO &&
     process.env.MAILGUN_DOMAIN
   );
-}
+};
 
 const createTestMessage = (options = {}) => {
   const config = getTestConfig();
diff --git a/tests/helpers/otel/mock-otel-providers.js b/tests/helpers/otel/mock-otel-providers.js
index 4c47646..203eb1a 100644
--- a/tests/helpers/otel/mock-otel-providers.js
+++ b/tests/helpers/otel/mock-otel-providers.js
@@ -101,12 +101,9 @@ class MockTracer {
   }
 
   startActiveSpan(name, optionsOrFn, contextOrFn, fn) {
-    const actualFn =
-      typeof optionsOrFn === 'function'
-        ? optionsOrFn
-        : typeof contextOrFn === 'function'
-          ? contextOrFn
-          : fn;
+    let actualFn = fn;
+    if (typeof optionsOrFn === 'function') actualFn = optionsOrFn;
+    else if (typeof contextOrFn === 'function') actualFn = contextOrFn;
     const span = this.startSpan(name, typeof optionsOrFn === 'object' ? optionsOrFn : undefined);
     return actualFn(span);
   }
diff --git a/tests/helpers/plunk/test-config.js b/tests/helpers/plunk/test-config.js
index cd2fc8e..84bcd5c 100644
--- a/tests/helpers/plunk/test-config.js
+++ b/tests/helpers/plunk/test-config.js
@@ -25,9 +25,9 @@ const getTestConfig = () => {
   };
 };
 
-function isE2eTestingEnabled() {
+const isE2eTestingEnabled = () => {
   return !!(process.env.PLUNK_API_KEY && process.env.PLUNK_FROM && process.env.PLUNK_TO);
-}
+};
 
 const createTestMessage = (options = {}) => {
   const config = getTestConfig();
diff --git a/tests/helpers/sendgrid/test-config.js b/tests/helpers/sendgrid/test-config.js
index f64fe24..dfc533b 100644
--- a/tests/helpers/sendgrid/test-config.js
+++ b/tests/helpers/sendgrid/test-config.js
@@ -22,9 +22,9 @@ const getTestConfig = () => {
   };
 };
 
-function isE2eTestingEnabled() {
+const isE2eTestingEnabled = () => {
   return !!(process.env.SENDGRID_API_KEY && process.env.SENDGRID_FROM && process.env.SENDGRID_TO);
-}
+};
 
 const createTestMessage = (options = {}) => {
   const config = getTestConfig();
diff --git a/tests/helpers/smtp/test-config.js b/tests/helpers/smtp/test-config.js
index d0c2d09..53b3c60 100644
--- a/tests/helpers/smtp/test-config.js
+++ b/tests/helpers/smtp/test-config.js
@@ -24,9 +24,9 @@ const getTestConfig = () => {
   };
 };
 
-function isMailpitTestingEnabled() {
+const isMailpitTestingEnabled = () => {
   return !!process.env.MAILPIT_API_URL || !!process.env.MAILPIT_SMTP_HOST;
-}
+};
 
 /**
  * Whether the OAuth 2.0 end-to-end tests are configured to run.
@@ -62,8 +62,7 @@ const getOAuth2TestConfig = () => {
 
   const user = process.env.SMTP_OAUTH2_USER;
   const mechanism = process.env.SMTP_OAUTH2_MECHANISM;
-  const method =
-    mechanism === 'oauthbearer' ? 'oauthbearer' : mechanism === 'xoauth2' ? 'xoauth2' : undefined;
+  const method = mechanism === 'oauthbearer' || mechanism === 'xoauth2' ? mechanism : undefined;
 
   // An empty SMTP_OAUTH2_ACCESS_TOKEN is treated as "not set" (matching
   // isOAuth2TestingEnabled), so the refresh-token flow is used in that case.
diff --git a/tests/unit/jmap-blob-uploader.test.js b/tests/unit/jmap-blob-uploader.test.js
index edd3287..31db467 100644
--- a/tests/unit/jmap-blob-uploader.test.js
+++ b/tests/unit/jmap-blob-uploader.test.js
@@ -5,6 +5,7 @@ const { describe, it } = require('node:test');
 const assert = require('node:assert/strict');
 const { uploadBlob } = require('../../src/jmap/blob-uploader.js');
 const { createJmapConfig } = require('../../src/jmap/config.js');
+const { requestUrl } = require('../helpers/jmap/request-url.js');
 
 describe('uploadBlob', () => {
   const config = createJmapConfig({
@@ -25,8 +26,7 @@ describe('uploadBlob', () => {
       };
 
       globalThis.fetch = (input, init) => {
-        const url =
-          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const url = requestUrl(input);
         capturedRequest.url = url;
         capturedRequest.headers = new Headers(init?.headers);
         capturedRequest.body = init?.body;
diff --git a/tests/unit/jmap-raw-message.integration.test.js b/tests/unit/jmap-raw-message.integration.test.js
index be9bfe0..8c44c3e 100644
--- a/tests/unit/jmap-raw-message.integration.test.js
+++ b/tests/unit/jmap-raw-message.integration.test.js
@@ -577,10 +577,10 @@ for (const stage of ['upload', 'import', 'submission']) {
               responseBody: body,
               jmapErrorType: undefined,
             });
-            assert.equal(
-              error.category,
-              unknown ? 'unknown' : auth ? 'auth' : status === 429 ? 'rate-limit' : 'server-error',
-            );
+            let category = status === 429 ? 'rate-limit' : 'server-error';
+            if (unknown) category = 'unknown';
+            else if (auth) category = 'auth';
+            assert.equal(error.category, category);
             assert.equal(context.uploads.length, 1);
             assert.equal(
               context.calls.filter((c) => c.name === 'Email/import').length,
diff --git a/tests/unit/jmap-retry-attempts.test.js b/tests/unit/jmap-retry-attempts.test.js
index 1b18620..a80fe55 100644
--- a/tests/unit/jmap-retry-attempts.test.js
+++ b/tests/unit/jmap-retry-attempts.test.js
@@ -4,6 +4,7 @@
 const { describe, it } = require('node:test');
 const assert = require('node:assert/strict');
 const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+const { requestUrl } = require('../helpers/jmap/request-url.js');
 
 const baseMessage = {
   sender: { address: 'sender@example.com' },
@@ -28,8 +29,7 @@ describe('JmapTransport retry attempts', () => {
 
     try {
       globalThis.fetch = (input, init) => {
-        const url =
-          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const url = requestUrl(input);
         const body = init?.body == null ? undefined : JSON.parse(init.body);
 
         if (url.includes('.well-known/jmap')) {
diff --git a/tests/unit/jmap-send-error.test.js b/tests/unit/jmap-send-error.test.js
index d68d3ca..1e7a2c8 100644
--- a/tests/unit/jmap-send-error.test.js
+++ b/tests/unit/jmap-send-error.test.js
@@ -4,6 +4,7 @@
 const { describe, it } = require('node:test');
 const assert = require('node:assert/strict');
 const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+const { requestUrl } = require('../helpers/jmap/request-url.js');
 
 const baseMessage = {
   sender: { address: 'sender@example.com' },
@@ -63,8 +64,7 @@ describe('JmapTransport send error', () => {
       let fetchCount = 0;
       globalThis.fetch = (input, init) => {
         fetchCount++;
-        const url =
-          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const url = requestUrl(input);
 
         if (url.includes('.well-known/jmap')) {
           return Promise.resolve(
diff --git a/tests/unit/jmap-send-success.test.js b/tests/unit/jmap-send-success.test.js
index 93bafe7..00f8104 100644
--- a/tests/unit/jmap-send-success.test.js
+++ b/tests/unit/jmap-send-success.test.js
@@ -4,6 +4,7 @@
 const { describe, it } = require('node:test');
 const assert = require('node:assert/strict');
 const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+const { requestUrl } = require('../helpers/jmap/request-url.js');
 
 const baseMessage = {
   sender: { address: 'sender@example.com' },
@@ -27,8 +28,7 @@ describe('JmapTransport send success', () => {
       const fetchInfo = { count: 0 };
       globalThis.fetch = (input, _init) => {
         fetchInfo.count++;
-        const url =
-          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const url = requestUrl(input);
 
         // First call: session fetch
         if (url.includes('.well-known/jmap')) {
diff --git a/tests/unit/jmap-sendmany.test.js b/tests/unit/jmap-sendmany.test.js
index 475660a..016a453 100644
--- a/tests/unit/jmap-sendmany.test.js
+++ b/tests/unit/jmap-sendmany.test.js
@@ -4,6 +4,7 @@
 const { describe, it } = require('node:test');
 const assert = require('node:assert/strict');
 const { JmapTransport } = require('../../src/jmap/jmap-transport.js');
+const { requestUrl } = require('../helpers/jmap/request-url.js');
 
 const baseMessage = {
   sender: { address: 'sender@example.com' },
@@ -26,8 +27,7 @@ describe('sendMany batch - success', () => {
     try {
       const requests = [];
       globalThis.fetch = (input, init) => {
-        const url =
-          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const url = requestUrl(input);
 
         const body = init?.body ? JSON.parse(init.body) : null;
         requests.push({ url, body });
@@ -200,8 +200,7 @@ describe('sendMany batch - partial failure', () => {
 
     try {
       globalThis.fetch = (input, init) => {
-        const url =
-          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const url = requestUrl(input);
 
         const body = init?.body ? JSON.parse(init.body) : null;
 
@@ -366,8 +365,7 @@ describe('sendMany batch - attachment upload timeout', () => {
 
     try {
       globalThis.fetch = (input, init) => {
-        const url =
-          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const url = requestUrl(input);
 
         const body = init?.body && typeof init.body === 'string' ? JSON.parse(init.body) : null;
 
diff --git a/tests/unit/jmap-verify.test.js b/tests/unit/jmap-verify.test.js
index 7a06e6b..82b3ae0 100644
--- a/tests/unit/jmap-verify.test.js
+++ b/tests/unit/jmap-verify.test.js
@@ -77,12 +77,8 @@ const setup = async () => {
       stalled.resolve();
       return;
     }
-    const list =
-      name === 'Mailbox/get'
-        ? state.drafts
-          ? [{ id: 'drafts', role: 'drafts' }]
-          : []
-        : [{ id: state.identity, email: '*@example.com' }];
+    let list = [{ id: state.identity, email: '*@example.com' }];
+    if (name === 'Mailbox/get') list = state.drafts ? [{ id: 'drafts', role: 'drafts' }] : [];
     const response = state.methodError
       ? ['error', { type: 'forbidden', description: 'Not allowed.' }, id]
       : [
diff --git a/tests/unit/lettermint-transport.test.js b/tests/unit/lettermint-transport.test.js
index 41d869c..9e6f280 100644
--- a/tests/unit/lettermint-transport.test.js
+++ b/tests/unit/lettermint-transport.test.js
@@ -36,7 +36,7 @@ it('rejects a singleton batch canceled during attachment acquisition', async ()
   );
 });
 
-function createMessage(overrides = {}) {
+const createMessage = (overrides = {}) => {
   return {
     sender: { address: 'sender@example.com' },
     recipients: [{ address: 'recipient@example.com' }],
@@ -51,7 +51,7 @@ function createMessage(overrides = {}) {
     headers: new Headers(),
     ...overrides,
   };
-}
+};
 
 let fetchMockChain = Promise.resolve();
 
diff --git a/tests/unit/logger-transport.test.js b/tests/unit/logger-transport.test.js
index cb61c0b..dd24a4b 100644
--- a/tests/unit/logger-transport.test.js
+++ b/tests/unit/logger-transport.test.js
@@ -567,7 +567,7 @@ describe('LoggerTransport', () => {
 // A pino-like logger that records each call, and the matching LogTape's
 // recorder offered: assertLogged() and filter() over level, message and
 // properties (a partial object, or a predicate).
-function createRecorder() {
+const createRecorder = () => {
   const records = [];
   const logger = {};
   for (const level of ['trace', 'debug', 'info', 'warn', 'error', 'fatal']) {
@@ -601,11 +601,11 @@ function createRecorder() {
       );
     },
   };
-}
+};
 
-async function withRecorder(run) {
+const withRecorder = async (run) => {
   await run(createRecorder());
-}
+};
 
 class RecordingTransport {
   id = 'base';
diff --git a/tests/unit/mailgun-transport.test.js b/tests/unit/mailgun-transport.test.js
index 1a9e2f0..9da136f 100644
--- a/tests/unit/mailgun-transport.test.js
+++ b/tests/unit/mailgun-transport.test.js
@@ -872,10 +872,6 @@ describe('MailgunTransport - Concurrent Error Handling', () => {
       // Should have processed all messages
       assert.equal(successful.length + failed.length, 4);
 
-      // If the mocking works as expected, we should have some failures
-      // But the exact distribution might vary based on implementation
-      console.log(`Successful: ${successful.length}, Failed: ${failed.length}`);
-
       // At minimum, we should have processed all messages
       assert.ok(receipts.length === 4);
     } finally {
diff --git a/tests/unit/mime-compose.test.js b/tests/unit/mime-compose.test.js
index 2dd23b5..277cf32 100644
--- a/tests/unit/mime-compose.test.js
+++ b/tests/unit/mime-compose.test.js
@@ -75,21 +75,21 @@ const collect = async (raw, signal) =>
 for (const kind of ['bytes', 'promise', 'blob', 'factory']) {
   test(`independent parser decodes Unicode, alternatives and ${kind} attachments`, async () => {
     const bytes = Uint8Array.from({ length: 65539 }, (_, i) => i % 251);
-    const source =
-      kind === 'bytes'
-        ? bytes
-        : kind === 'promise'
-          ? Promise.resolve(bytes)
-          : kind === 'blob'
-            ? new Blob([bytes])
-            : async function* () {
-                const reused = new Uint8Array(13);
-                for (let offset = 0; offset < bytes.length; offset += reused.length) {
-                  const slice = bytes.subarray(offset, offset + reused.length);
-                  reused.set(slice);
-                  yield reused.subarray(0, slice.length);
-                }
-              };
+    const sources = {
+      bytes: () => bytes,
+      promise: () => Promise.resolve(bytes),
+      blob: () => new Blob([bytes]),
+      factory: () =>
+        async function* () {
+          const reused = new Uint8Array(13);
+          for (let offset = 0; offset < bytes.length; offset += reused.length) {
+            const slice = bytes.subarray(offset, offset + reused.length);
+            reused.set(slice);
+            yield reused.subarray(0, slice.length);
+          }
+        },
+    };
+    const source = sources[kind]();
     const raw = await composeMessage({
       ...message(),
       content: { text: '한글\r\nNext \nend\r', html: '<b>한글</b>' },
diff --git a/tests/unit/retry-transport.test.js b/tests/unit/retry-transport.test.js
index d5ea6ef..3bb5060 100644
--- a/tests/unit/retry-transport.test.js
+++ b/tests/unit/retry-transport.test.js
@@ -1089,22 +1089,22 @@ describe('RetryTransport', () => {
   });
 });
 
-function message(subject = 'Hello') {
+const message = (subject = 'Hello') => {
   return createMessage({
     from: 'sender@example.com',
     to: 'recipient@example.com',
     subject,
     content: { text: 'Hello' },
   });
-}
+};
 
-async function collect(values) {
+const collect = async (values) => {
   const result = [];
   for await (const value of values) result.push(value);
   return result;
-}
+};
 
-function createDeferred() {
+const createDeferred = () => {
   let resolve;
   let reject;
   // oxlint-disable-next-line promise/param-names -- upstream
@@ -1115,9 +1115,9 @@ function createDeferred() {
   assert.ok(resolve != null);
   assert.ok(reject != null);
   return { promise, resolve, reject };
-}
+};
 
-async function waitFor(predicate) {
+const waitFor = async (predicate) => {
   const deadline = Date.now() + 1_000;
   while (!predicate()) {
     if (Date.now() >= deadline) {
@@ -1125,9 +1125,9 @@ async function waitFor(predicate) {
     }
     await new Promise((resolve) => setTimeout(resolve, 0));
   }
-}
+};
 
-async function settlesWithin(promise, milliseconds = 10) {
+const settlesWithin = async (promise, milliseconds = 10) => {
   let timeout;
   try {
     return await Promise.race([
@@ -1142,18 +1142,18 @@ async function settlesWithin(promise, milliseconds = 10) {
   } finally {
     if (timeout != null) clearTimeout(timeout);
   }
-}
+};
 
-function rejectAfter(milliseconds) {
+const rejectAfter = (milliseconds) => {
   return new Promise((_resolve, reject) => {
     setTimeout(() => reject(new Error('Timed out waiting for rejection.')), milliseconds);
   });
-}
+};
 
 // oxlint-disable-next-line no-shadow -- upstream
-function createAbortError(message = 'The operation was aborted.') {
+const createAbortError = (message = 'The operation was aborted.') => {
   return new DOMException(message, 'AbortError');
-}
+};
 
 class SequenceTransport {
   id = 'base';
@@ -1185,7 +1185,7 @@ class SequenceTransport {
   }
 }
 
-function isReceiptError(value) {
+const isReceiptError = (value) => {
   return (
     typeof value === 'object' &&
     value != null &&
@@ -1193,7 +1193,7 @@ function isReceiptError(value) {
     'retryable' in value &&
     'message' in value
   );
-}
+};
 
 class TrackingTransport {
   id = 'base';
diff --git a/tests/unit/smtp-large-attachment.integration.test.js b/tests/unit/smtp-large-attachment.integration.test.js
index ce28c40..7858b17 100644
--- a/tests/unit/smtp-large-attachment.integration.test.js
+++ b/tests/unit/smtp-large-attachment.integration.test.js
@@ -8,6 +8,25 @@ const { Buffer } = require('node:buffer');
 const { createHash, verify } = require('node:crypto');
 const { createMessage } = require('../../src/core/message.js');
 const { SmtpTransport } = require('../../src/smtp/smtp-transport.js');
+
+// Changed after the port: each name of h= takes the next instance of its field
+// from the bottom up, and a name with none left adds nothing (RFC 6376
+// §5.4.2).
+const selectSignedHeaders = (headers, names) => {
+  const used = new Set();
+  const selected = [];
+  for (const name of names) {
+    const prefix = `${name.toLowerCase()}:`;
+    for (let i = headers.length - 1; i >= 0; i--) {
+      if (!used.has(i) && headers[i].toLowerCase().startsWith(prefix)) {
+        used.add(i);
+        selected.push(headers[i]);
+        break;
+      }
+    }
+  }
+  return selected;
+};
 const {
   TEST_DKIM_PRIVATE_KEY,
   TEST_DKIM_PUBLIC_KEY,
@@ -156,20 +175,8 @@ for (const megabytes of [8, 64]) {
               }),
           );
           assert.equal(tags.get('bh'), bodyHash.digest('base64'));
-          // Changed after the port: each name takes the next instance from the
-          // bottom up, and a name with none left adds nothing (RFC 6376 §5.4.2),
-          // as the default h= now lists absent and over-signed fields.
-          const used = new Set();
-          const selected = [];
-          for (const name of tags.get('h').split(':')) {
-            for (let i = headers.length - 1; i >= 0; i--) {
-              if (!used.has(i) && headers[i].toLowerCase().startsWith(`${name.toLowerCase()}:`)) {
-                used.add(i);
-                selected.push(headers[i]);
-                break;
-              }
-            }
-          }
+          // The default h= now lists absent and over-signed fields.
+          const selected = selectSignedHeaders(headers, tags.get('h').split(':'));
           selected.push(signature.replace(/b=[^;]*$/, 'b='));
           assert.ok(
             verify(
diff --git a/tests/unit/smtp-oauth2.test.js b/tests/unit/smtp-oauth2.test.js
index 6cbd054..78a595e 100644
--- a/tests/unit/smtp-oauth2.test.js
+++ b/tests/unit/smtp-oauth2.test.js
@@ -170,7 +170,7 @@ describe('OAuth2TokenManager', () => {
 
   test('calls fetchFn without binding it to the manager', async () => {
     const receivers = [];
-    function recordingFetch() {
+    const recordingFetch = function () {
       receivers.push(this);
       return Promise.resolve(
         new Response(JSON.stringify({ access_token: 't', expires_in: 3600 }), {
@@ -178,7 +178,7 @@ describe('OAuth2TokenManager', () => {
           headers: { 'content-type': 'application/json' },
         }),
       );
-    }
+    };
     const auth = {
       user: 'u@e.com',
       clientId: 'client-id',
diff --git a/tests/unit/smtp-transport.pool.integration.test.js b/tests/unit/smtp-transport.pool.integration.test.js
index 4061d61..d3e3347 100644
--- a/tests/unit/smtp-transport.pool.integration.test.js
+++ b/tests/unit/smtp-transport.pool.integration.test.js
@@ -406,10 +406,8 @@ describe('SmtpTransport connection limit', () => {
 
   test('shutdown waits for a paused batch to be returned', async () => {
     const { server, transport } = await setupTest({ poolSize: 1 });
-    const batch = transport.sendMany([createTestMessage(), createTestMessage()])[
-      // oxlint-disable-next-line no-unexpected-multiline -- upstream
-      Symbol.asyncIterator
-    ]();
+    const receipts = transport.sendMany([createTestMessage(), createTestMessage()]);
+    const batch = receipts[Symbol.asyncIterator]();
     try {
       assert.ok((await batch.next()).value?.successful);
       let closed = false;
diff --git a/tests/unit/smtp-transport.test.js b/tests/unit/smtp-transport.test.js
index bb3ec1b..f22a386 100644
--- a/tests/unit/smtp-transport.test.js
+++ b/tests/unit/smtp-transport.test.js
@@ -502,12 +502,9 @@ describe('SmtpTransport', () => {
       try {
         await transport.closeAllConnections();
         await transport[Symbol.asyncDispose]();
-      } catch (error) {
-        // Cleanup should not throw additional errors
-        console.warn(
-          'Cleanup error (might be expected):',
-          error instanceof Error ? error.message : String(error),
-        );
+      } catch {
+        // Cleanup may fail after the failure above, which this test does not
+        // check (changed after the port: it was logged with console.warn).
       }
 
       // Test should complete without hanging
diff --git a/tests/unit/smtp-verify.integration.test.js b/tests/unit/smtp-verify.integration.test.js
index 7cdaafc..ff04e9b 100644
--- a/tests/unit/smtp-verify.integration.test.js
+++ b/tests/unit/smtp-verify.integration.test.js
@@ -31,6 +31,11 @@ const message = () =>
     content: { text: 'Test' },
   });
 
+const authKind = (auth) => {
+  if (auth == null) return 'none';
+  return 'pass' in auth ? 'password' : 'oauth';
+};
+
 for (const auth of [
   undefined,
   { user: 'u', pass: 'p' },
@@ -39,7 +44,7 @@ for (const auth of [
     accessToken: 'token',
   },
 ]) {
-  test(`verify performs fresh setup without delivery, auth=${auth == null ? 'none' : 'pass' in auth ? 'password' : 'oauth'}`, async () => {
+  test(`verify performs fresh setup without delivery, auth=${authKind(auth)}`, async () => {
     const server = new MockSmtpServer();
     const port = await server.start();
     const transport = new SmtpTransport({

From b97909bdc4589d3acb9009ba4571872e0e40c1a8 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 20:58:42 +0300
Subject: [PATCH 140/158] fix(ses,resend,jmap): stream sendMany a batch at a
 time

Each read its whole input into an array before the first message went
out, so a long or endless iterable was held in memory, or never sent.
chunks() of internal/batch.js reads an iterable, synchronous or not, an
array at a time: SES reads batchSize messages, Resend 100 (the batch API
is now chosen per chunk, not for the whole input), and JMAP batches of
maxObjectsInSet after one discovery, made only once there is a first
message; a failed discovery still fails every message, read as it comes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                   |  5 ++
 CLAUDE.md                      |  9 +++-
 docs/transports/jmap.md        | 10 ++--
 docs/transports/resend.md      | 15 +++---
 docs/transports/ses.md         |  3 ++
 src/internal/batch.js          | 25 +++++++++
 src/jmap/jmap-transport.js     | 96 ++++++++++++++++++----------------
 src/resend/resend-transport.js | 64 ++++++-----------------
 src/ses/ses-transport.js       | 28 ++--------
 tests/unit/jmap.test.js        | 40 ++++++++++++++
 tests/unit/resend.test.js      | 23 ++++++++
 tests/unit/ses.test.js         | 23 ++++++++
 12 files changed, 212 insertions(+), 129 deletions(-)
 create mode 100644 src/internal/batch.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bef4290..f3d3ea8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -320,6 +320,11 @@ fixed ones below.
   error and `timeout after 5000ms` a `server-error`. It now gives the category of
   `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
   `aborted` for an `AbortError`, which upstream counted as `network`.
+- **`./ses`, `./resend` and `./jmap` stream `sendMany`** (an upstream bug): each read its whole
+  input into an array before the first message went out, so a long or endless iterable was held
+  in memory, or never sent. SES now reads `batchSize` messages at a time, Resend 100 (the batch
+  API is chosen per chunk, where it used to be all or nothing for the whole input) and JMAP a
+  batch of `maxObjectsInSet`, after one discovery.
 - **`./otel` streams `sendMany`** (an upstream bug): it read the whole input into an array before
   the first message went out, and kept every receipt to the end, so a long or endless batch
   held it all in memory. The messages now pass on as the wrapped transport reads them; the batch
diff --git a/CLAUDE.md b/CLAUDE.md
index cf7f0ad..e9e8511 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -372,6 +372,12 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 73. plunk (known bug 12): an attachment that could not be read was left out with a
     `console.warn`, and the message went without it, reported as sent. It fails the send, as
     on the other providers, before any request.
+74. ses, resend, jmap: `sendMany` read its whole input into an array before the first message
+    went out, so a long or endless iterable was held in memory, or never sent. Each reads a
+    batch at a time (`chunks` of `internal/batch.js`): SES `batchSize` messages, Resend 100,
+    each chunk choosing between the batch API and single requests, and JMAP `maxObjectsInSet`
+    after one discovery, made only when there is a first message.
+
 ## Repository layout
 
 ```
@@ -382,7 +388,8 @@ src/
   <subpath>/        one directory per subpath: index.js + index.d.ts + its modules
   internal/         private modules shared by subpaths, not in the exports map (redact.js,
                     redact-addresses.js, unsent.js, delivery-unknown.js, http.js,
-                    config.js, loopback.js, body.js)
+                    config.js, loopback.js, body.js, sleep.js, log.js, base64.js,
+                    headers.js, provider.js, batch.js)
 tests/
   unit/*.test.js    node:test suites, one per area (<subpath>-<module>.test.js for a subpath)
   helpers/<sub>/    shared test code of a subpath (fake servers, fixtures builders)
diff --git a/docs/transports/jmap.md b/docs/transports/jmap.md
index 59bbe26..ba458dd 100644
--- a/docs/transports/jmap.md
+++ b/docs/transports/jmap.md
@@ -189,10 +189,12 @@ for await (const receipt of transport.sendMany(messages)) {
 }
 ```
 
-The `JmapTransport.sendMany()` method batches all emails into a single
-JMAP request, significantly reducing HTTP round-trips. Each message
-gets its own receipt, and partial failures are handled gracefully—if
-some emails fail, others in the batch can still succeed.
+The `JmapTransport.sendMany()` method batches emails into JMAP requests of as
+many as the server's `maxObjectsInSet` allows, significantly reducing HTTP
+round-trips. It discovers the account, the drafts mailbox and the identities
+once, reads a batch of messages at a time as it sends them, and gives each
+message its own receipt: if some emails fail, others in the batch can still
+succeed.
 
 ## Error handling
 
diff --git a/docs/transports/resend.md b/docs/transports/resend.md
index e906f09..eca582f 100644
--- a/docs/transports/resend.md
+++ b/docs/transports/resend.md
@@ -102,14 +102,13 @@ for await (const receipt of transport.sendMany(messages)) {
 }
 ```
 
-The transport automatically determines the optimal sending strategy:
-
- -  **≤100 messages without attachments/tags**: Uses Resend's batch API for
-    fastest delivery
- -  **>100 messages**: Automatically chunks into multiple batch requests
- -  **Messages with attachments or tags**: Falls back to individual requests
- -  **Mixed scenarios**: Intelligently separates batch-compatible from
-    individual messages
+The transport reads the messages 100 at a time, the most a batch request
+takes, so an endless or very long iterable costs one chunk of memory, and
+chooses for each chunk:
+
+ -  **No attachments, tags or calendar in the chunk**: one request of
+    Resend's batch API for the whole chunk
+ -  **Any of them in the chunk**: a request per message of that chunk
 
 This optimization happens transparently, ensuring maximum performance while
 maintaining full feature compatibility.
diff --git a/docs/transports/ses.md b/docs/transports/ses.md
index 2588fb5..bf0da49 100644
--- a/docs/transports/ses.md
+++ b/docs/transports/ses.md
@@ -284,6 +284,9 @@ The `SesTransport.sendMany()` method processes messages concurrently using
 individual `SendEmail` API calls rather than SES's `SendBulkEmail` API.
 This approach provides maximum flexibility for different message content
 while still achieving excellent throughput through concurrent processing.
+It reads `batchSize` messages (50 by default) at a time and sends them
+together before it reads more, so an endless or very long iterable costs one
+batch of memory.
 
 ## Configuration sets and tracking
 
diff --git a/src/internal/batch.js b/src/internal/batch.js
new file mode 100644
index 0000000..c44d3bd
--- /dev/null
+++ b/src/internal/batch.js
@@ -0,0 +1,25 @@
+// Not ported from upyo: a batch of messages read as it is needed rather than
+// all at once, so that a sendMany() holds one batch in memory, not its input.
+
+/**
+ * Reads an iterable, synchronous or not, in arrays of at most `size` items,
+ * one array at a time.
+ *
+ * @param iterable The items.
+ * @param size The most items an array holds.
+ * @returns The arrays, none of them empty.
+ * @internal
+ */
+const chunks = async function* (iterable, size) {
+  let chunk = [];
+  for await (const item of iterable) {
+    chunk.push(item);
+    if (chunk.length === size) {
+      yield chunk;
+      chunk = [];
+    }
+  }
+  if (chunk.length > 0) yield chunk;
+};
+
+module.exports = { chunks };
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index f3b7098..4ce0a68 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -16,6 +16,7 @@ const { isUnsentRequestError } = require('../internal/unsent.js');
 const { convertMessage } = require('./message-converter.js');
 const { findMailAccount } = require('./session.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
+const { chunks } = require('../internal/batch.js');
 
 /**
  * JMAP capabilities required for email sending.
@@ -329,76 +330,70 @@ class JmapTransport {
    */
   async *sendMany(messages, options) {
     const signal = options?.signal;
-
-    // Collect all messages into an array first
-    const messageArray = [];
-    for await (const message of messages) {
-      messageArray.push(message);
+    // The input is read as its batches are sent, not all at once.  What every
+    // batch shares is discovered once, when there is a first message; if it
+    // fails, every message fails with it.
+    const input = readItems(messages);
+    const first = await input.next();
+    if (first.done) return;
+    const discovery = await this.discoverForBatch(signal);
+    if (discovery.failure !== undefined) {
+      yield discovery.failure();
+      while (!(await input.next()).done) yield discovery.failure();
+      return;
     }
 
-    // If no messages, return early
-    if (messageArray.length === 0) {
-      return;
+    // RFC 8620 §2: a server may limit the objects one /set method creates;
+    // a batch over it would be refused as a whole.
+    const limit = getMaxObjectsInSet(discovery.discovered.session);
+    for await (const batch of chunks(prepend(first.value, input), limit)) {
+      yield* this.sendBatch(discovery.discovered, batch, signal);
     }
+  }
 
-    // What every batch shares is discovered once; if it fails, every message
-    // fails with it.
+  /**
+   * Discovers what every batch of a sendMany() shares: the session, the
+   * account, its drafts mailbox and its identities.
+   *
+   * @param signal Cancellation signal.
+   * @returns The `discovered` values, or the `failure` that makes the receipt
+   * of each message when discovery fails.
+   * @throws The caller's abort reason if cancelled.
+   */
+  async discoverForBatch(signal) {
     let processingStage = 'initialization';
-    let discovered;
     try {
       signal?.throwIfAborted();
-
-      // Get or refresh session (once)
       processingStage = 'session fetch';
       const session = await this.getSession(signal);
       signal?.throwIfAborted();
 
-      // Get account ID (once)
       processingStage = 'account discovery';
       const accountId = this.config.accountId ?? findMailAccount(session);
       if (!accountId) {
-        for (let i = 0; i < messageArray.length; i++) {
-          yield createJmapFailure('No mail-capable account found in JMAP session', undefined, {
-            category: 'configuration',
-            code: 'jmap.no_mail_account',
-            retryable: false,
-          });
-        }
-        return;
+        return {
+          failure: () =>
+            createJmapFailure('No mail-capable account found in JMAP session', undefined, {
+              category: 'configuration',
+              code: 'jmap.no_mail_account',
+              retryable: false,
+            }),
+        };
       }
 
-      // Get drafts mailbox ID (once)
       processingStage = 'mailbox discovery';
       const draftsMailboxId = await this.getDraftsMailboxId(session, accountId, signal);
       signal?.throwIfAborted();
 
-      // Get identities (once) and build a map
       processingStage = 'identity resolution';
       const identityMap = await this.getIdentityMap(session, accountId, signal);
       signal?.throwIfAborted();
 
-      discovered = { session, accountId, draftsMailboxId, identityMap };
+      return { discovered: { session, accountId, draftsMailboxId, identityMap } };
     } catch (error) {
-      for (const failure of this.failBatch(
-        error,
-        processingStage,
-        messageArray.length,
-        0,
-        signal,
-      )) {
-        yield failure;
-      }
-      return;
-    }
-
-    // RFC 8620 §2: a server may limit the objects one /set method creates;
-    // a batch over it would be refused as a whole.
-    const limit = getMaxObjectsInSet(discovered.session);
-    for (let start = 0; start < messageArray.length; start += limit) {
-      const batch = messageArray.slice(start, start + limit);
-      for await (const receipt of this.sendBatch(discovered, batch, signal)) {
-        yield receipt;
-      }
+      // A caller's abort rejects at the first of these, before any receipt.
+      const stage = processingStage;
+      return { failure: () => this.failBatch(error, stage, 1, 0, signal).next().value };
     }
   }
 
@@ -830,6 +825,17 @@ class JmapTransport {
   }
 }
 
+// The items of an iterable, synchronous or not, through one async iterator
+// that can be read from by hand and then iterated for the rest.
+const readItems = async function* (iterable) {
+  for await (const item of iterable) yield item;
+};
+
+const prepend = async function* (first, rest) {
+  yield first;
+  yield* rest;
+};
+
 const REQUIRED_CAPABILITIES = [
   JMAP_CAPABILITIES.core,
   JMAP_CAPABILITIES.mail,
diff --git a/src/resend/resend-transport.js b/src/resend/resend-transport.js
index 921f3b2..07fcc13 100644
--- a/src/resend/resend-transport.js
+++ b/src/resend/resend-transport.js
@@ -11,6 +11,7 @@ const {
 } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { chunks } = require('../internal/batch.js');
 
 /**
  * Resend transport implementation for sending emails via Resend API.
@@ -37,6 +38,9 @@ const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
  * }
  * ```
  */
+// The most messages a request of the batch API takes.
+const MAX_BATCH_SIZE = 100;
+
 class ResendTransport {
   id = 'resend';
 
@@ -148,11 +152,10 @@ class ResendTransport {
   /**
    * Sends multiple email messages efficiently via Resend API.
    *
-   * This method intelligently chooses between single requests and batch API
-   * based on message count and features used. For optimal performance:
-   * - Uses batch API for ≤100 messages without attachments or tags
-   * - Falls back to individual requests for messages with unsupported features
-   * - Chunks large batches (>100) into multiple batch requests
+   * The messages are read 100 at a time, the most a batch request takes, so
+   * that memory holds one chunk rather than the whole input.  A chunk whose
+   * messages carry no attachments, tags or calendar goes in one batch request;
+   * another is sent one message at a time.
    *
    * @example
    * ```typescript
@@ -202,31 +205,19 @@ class ResendTransport {
   async *sendMany(messages, options) {
     options?.signal?.throwIfAborted();
 
-    const isAsyncIterable = Symbol.asyncIterator in messages;
-
-    // Convert to array for batch processing optimization
-    const messageArray = [];
-
-    if (isAsyncIterable) {
-      for await (const message of messages) {
-        options?.signal?.throwIfAborted();
-        messageArray.push(message);
-      }
-    } else {
-      for (const message of messages) {
-        options?.signal?.throwIfAborted();
-        messageArray.push(message);
-      }
+    // Read as many messages as a batch request takes, and no more, before
+    // sending them; each chunk goes through the batch API when all of its
+    // messages can.
+    for await (const chunk of chunks(messages, MAX_BATCH_SIZE)) {
+      options?.signal?.throwIfAborted();
+      yield* this.sendManyOptimized(chunk, options);
     }
-
-    // Optimize sending strategy based on message characteristics
-    yield* this.sendManyOptimized(messageArray, options);
   }
 
   /**
    * Optimized batch sending that chooses the best strategy based on message features.
    *
-   * @param messages Array of messages to send
+   * @param messages At most 100 messages to send
    * @param options Transport options
    * @returns Async iterable of receipts
    */
@@ -238,16 +229,8 @@ class ResendTransport {
     // Check if messages are suitable for batch API
     const canUseBatch = this.canUseBatchApi(messages);
 
-    if (canUseBatch && messages.length <= 100) {
-      // Use batch API for optimal performance
+    if (canUseBatch) {
       yield* this.sendBatch(messages, options);
-    } else if (canUseBatch && messages.length > 100) {
-      // Chunk large batches into multiple batch requests
-      const chunks = this.chunkArray(messages, 100);
-      for (const chunk of chunks) {
-        options?.signal?.throwIfAborted();
-        yield* this.sendBatch(chunk, options);
-      }
     } else {
       // Fall back to individual requests for messages with unsupported features
       for (const message of messages) {
@@ -328,21 +311,6 @@ class ResendTransport {
     }
     return true;
   }
-
-  /**
-   * Splits an array into chunks of specified size.
-   *
-   * @param array Array to chunk
-   * @param size Chunk size
-   * @returns Array of chunks
-   */
-  chunkArray(array, size) {
-    const chunks = [];
-    for (let i = 0; i < array.length; i += size) {
-      chunks.push(array.slice(i, i + size));
-    }
-    return chunks;
-  }
 }
 
 const createResendFailure = (message, error) => {
diff --git a/src/ses/ses-transport.js b/src/ses/ses-transport.js
index e856e6f..3110b02 100644
--- a/src/ses/ses-transport.js
+++ b/src/ses/ses-transport.js
@@ -8,6 +8,7 @@ const { SesApiError, SesHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { chunks } = require('../internal/batch.js');
 
 /**
  * Amazon SES email transport implementation.
@@ -171,30 +172,11 @@ class SesTransport {
   async *sendMany(messages, options) {
     options?.signal?.throwIfAborted();
 
-    const isAsyncIterable = Symbol.asyncIterator in messages;
-    const messageArray = [];
-
-    if (isAsyncIterable) {
-      for await (const message of messages) {
-        messageArray.push(message);
-      }
-    } else {
-      for (const message of messages) {
-        messageArray.push(message);
-      }
-    }
-
-    const batchSize = this.config.batchSize;
-
-    for (let i = 0; i < messageArray.length; i += batchSize) {
+    // A batch is read when the one before it is sent, not the whole input
+    // first.
+    for await (const batch of chunks(messages, this.config.batchSize)) {
       options?.signal?.throwIfAborted();
-
-      const batch = messageArray.slice(i, i + batchSize);
-
-      const receipts = await this.sendConcurrent(batch, options);
-      for (const receipt of receipts) {
-        yield receipt;
-      }
+      yield* await this.sendConcurrent(batch, options);
     }
   }
 
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index 997d980..967409b 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -357,3 +357,43 @@ test('JMAP: an account ID cannot climb the path of a blob upload', async (t) =>
   );
   assert.deepStrictEqual(paths, ['/upload/a%2F..%2F..%2Fx/']);
 });
+
+test('JMAP: sendMany reads a batch at a time, after one discovery', async (t) => {
+  const createdOf = (args) => {
+    const created = {};
+    for (const key in args.create) created[key] = { id: key, blobId: 'b', threadId: 't' };
+    return { created };
+  };
+  const calls = serve(t, {
+    session: session({
+      capabilities: { [CORE]: { maxObjectsInSet: 2 }, [MAIL]: {}, [SUBMISSION]: {} },
+    }),
+    'Email/set': createdOf,
+    'EmailSubmission/set': createdOf,
+  });
+  let read = 0;
+  const messages = (async function* () {
+    for (let index = 0; index < 1000; index++) {
+      read++;
+      yield message();
+    }
+  })();
+  const receipts = [];
+  for await (const receipt of transport().sendMany(messages)) {
+    receipts.push(receipt);
+    if (receipts.length === 3) break;
+  }
+  assert.deepStrictEqual(
+    receipts.map((receipt) => receipt.successful),
+    [true, true, true],
+  );
+  // Two batches of two: the third receipt is the first of the second batch.
+  assert.strictEqual(read, 4);
+  assert.strictEqual(calls.filter((call) => call === 'Mailbox/get').length, 1);
+});
+
+test('JMAP: sendMany of nothing discovers nothing', async (t) => {
+  const calls = serve(t);
+  for await (const receipt of transport().sendMany([])) assert.fail(receipt);
+  assert.deepStrictEqual(calls, []);
+});
diff --git a/tests/unit/resend.test.js b/tests/unit/resend.test.js
index 8964cbe..36142dd 100644
--- a/tests/unit/resend.test.js
+++ b/tests/unit/resend.test.js
@@ -125,3 +125,26 @@ test('Resend: an idempotency key is random, not derived from the clock and Math.
   assert.notStrictEqual(first, generateIdempotencyKey());
   assert.match(first, /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
 });
+
+test('Resend: sendMany reads a batch request at a time, not its whole input first', async (t) => {
+  t.mock.method(globalThis, 'fetch', async (url, init) => {
+    const body = JSON.parse(init.body);
+    const data = [];
+    for (let index = 0; index < body.length; index++) data.push({ id: `r${index}` });
+    return json({ data });
+  });
+  let read = 0;
+  const messages = (function* () {
+    for (let index = 0; index < 1000; index++) {
+      read++;
+      yield message(index);
+    }
+  })();
+  const transport = new ResendTransport({ apiKey: 're_key', retries: 0 });
+  for await (const receipt of transport.sendMany(messages)) {
+    assert.strictEqual(receipt.successful, true);
+    break;
+  }
+  // The most a batch request takes.
+  assert.strictEqual(read, 100);
+});
diff --git a/tests/unit/ses.test.js b/tests/unit/ses.test.js
index 1f47d0e..dd39d06 100644
--- a/tests/unit/ses.test.js
+++ b/tests/unit/ses.test.js
@@ -214,3 +214,26 @@ test('SES: a rate limit (429) is retried, a refusal (400) is not', async (t) =>
   assert.strictEqual(requests, 2);
   assert.strictEqual(receipt.errors[0].statusCode, 400);
 });
+
+// A generator of many messages that counts how many were read.
+const counted = (count, make) => {
+  const state = { read: 0 };
+  state.messages = (function* () {
+    for (let index = 0; index < count; index++) {
+      state.read++;
+      yield make(index);
+    }
+  })();
+  return state;
+};
+
+test('SES: sendMany reads a batch at a time, not its whole input first', async (t) => {
+  await withFetch(t, async () => new Response('{"MessageId":"m1"}', { status: 200 }));
+  const transport = new SesTransport({ authentication, retries: 0, batchSize: 2 });
+  const input = counted(1000, () => message());
+  for await (const receipt of transport.sendMany(input.messages)) {
+    assert.strictEqual(receipt.successful, true);
+    break;
+  }
+  assert.strictEqual(input.read, 2);
+});

From 994c385b31ddd3f2f26c155314cd95bb26b2b71a Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:02:57 +0300
Subject: [PATCH 141/158] feat(sendgrid,mailgun,plunk,maileroo): concurrency
 for sendMany

The providers that send one message per request sent a batch strictly one
after the other. With `concurrency` (1 by default, the behavior so far)
they send that many at once through sendConcurrently of
internal/batch.js, which reads a message only when a send can start,
gives the receipts in the order of the messages, observes a later
failure until its turn, and closes the input when the caller stops. The
option must be a positive integer (checkConcurrency).

The budgets of ./sendgrid, ./mailgun and ./plunk go from 5 to 5.5 KB:
the shared module adds about 0.2 KB, which took SendGrid to 5.1 and the
other two to 4.9.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                       |   4 ++
 docs/transports/maileroo.md        |   6 +-
 docs/transports/mailgun.md         |  20 ++++--
 docs/transports/plunk.md           |  12 +++-
 docs/transports/sendgrid.md        |  19 ++++--
 scripts/size-budgets.json          |   6 +-
 src/internal/batch.js              |  67 ++++++++++++++++++-
 src/internal/config.js             |  15 ++++-
 src/jmap/jmap-transport.js         |   8 +--
 src/maileroo/config.js             |   4 +-
 src/maileroo/index.d.ts            |   8 +++
 src/maileroo/maileroo-transport.js |  12 ++--
 src/mailgun/config.js              |   4 +-
 src/mailgun/index.d.ts             |   8 +++
 src/mailgun/mailgun-transport.js   |  21 ++----
 src/plunk/config.js                |   4 +-
 src/plunk/index.d.ts               |   8 +++
 src/plunk/plunk-transport.js       |  21 ++----
 src/sendgrid/config.js             |   4 +-
 src/sendgrid/index.d.ts            |   8 +++
 src/sendgrid/sendgrid-transport.js |  21 ++----
 tests/types/maileroo.test-d.ts     |  10 ++-
 tests/types/mailgun.test-d.ts      |  15 ++++-
 tests/types/plunk.test-d.ts        |   5 +-
 tests/types/sendgrid.test-d.ts     |  10 ++-
 tests/unit/internal.test.js        | 101 +++++++++++++++++++++++++++++
 tests/unit/sendgrid.test.js        |  27 ++++++++
 27 files changed, 366 insertions(+), 82 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f3d3ea8..67be346 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,10 @@ fixed ones below.
   `Retry-After`), `./otel` (spans and metrics, with the OpenTelemetry providers passed in, the
   attributes as `mailer.*`) and `./logger` (the lifecycle logged through any pino-like logger
   passed in, in place of upstream's LogTape transport); and `./mock` for tests.
+- **`concurrency` for `sendMany` of `./sendgrid`, `./mailgun`, `./plunk` and `./maileroo`:** the
+  providers that send one message per request send that many at once (1 by default, as
+  before), reading a message only when a send can start and giving the receipts in the order of
+  the messages.
 - **`onRetry` in the options of a send:** the HTTP providers and `./retry` call it before each
   retry with the attempt, the wait and the error, and the decorators pass it on, so one callback
   hears every level (not yet from `./jmap`).
diff --git a/docs/transports/maileroo.md b/docs/transports/maileroo.md
index 7b18b23..8401d1f 100644
--- a/docs/transports/maileroo.md
+++ b/docs/transports/maileroo.md
@@ -93,8 +93,10 @@ and `tag2`, alongside any default tags configured on the transport.
 
 ## Sending multiple emails
 
-The `sendMany()` method sends messages sequentially through the single-message
-Maileroo endpoint:
+The `sendMany()` method sends messages through the single-message Maileroo
+endpoint, one after the other unless `concurrency` (1 by default) lets it send
+that many at once; it reads a message only when a send can start and gives the
+receipts in the order of the messages:
 
 ```js
 const { createMessage } = require('@alexify/mailer');
diff --git a/docs/transports/mailgun.md b/docs/transports/mailgun.md
index 3d0b0dc..02ac7c7 100644
--- a/docs/transports/mailgun.md
+++ b/docs/transports/mailgun.md
@@ -195,10 +195,22 @@ for await (const receipt of transport.sendMany(messages)) {
 }
 ```
 
-The `MailgunTransport.sendMany()` method processes emails sequentially with
-built-in retry logic.  Failed emails don't prevent subsequent emails from being
-sent, and detailed error information helps you identify and resolve delivery
-issues.
+The `MailgunTransport.sendMany()` method processes emails one after the other
+with built-in retry logic.  Failed emails don't prevent subsequent emails from
+being sent, and detailed error information helps you identify and resolve
+delivery issues.
+
+With `concurrency` set (1 by default), it sends that many messages at once: it
+reads a message only when a send can start, so a long iterable costs that many
+messages of memory, and gives the receipts in the order of the messages.
+
+```js
+const transport = new MailgunTransport({
+  apiKey: process.env.MAILGUN_KEY,
+  domain: 'mg.example.com',
+  concurrency: 4,
+});
+```
 
 ## Advanced configuration and reliability
 
diff --git a/docs/transports/plunk.md b/docs/transports/plunk.md
index a99671c..7a7d75c 100644
--- a/docs/transports/plunk.md
+++ b/docs/transports/plunk.md
@@ -145,9 +145,15 @@ for await (const receipt of transport.sendMany(messages)) {
 ```
 
 Tags help you categorize emails and track performance through Plunk's
-analytics dashboard. The `sendMany()` method processes emails efficiently
-with built-in retry logic, ensuring reliable delivery even when some
-individual messages encounter temporary issues.
+analytics dashboard. The `sendMany()` method processes emails one after the
+other with built-in retry logic, ensuring reliable delivery even when some
+individual messages encounter temporary issues.  With `concurrency` set
+(1 by default), it sends that many at once: it reads a message only when a send
+can start and gives the receipts in the order of the messages.
+
+```js
+const transport = new PlunkTransport({ apiKey: process.env.PLUNK_API_KEY, concurrency: 4 });
+```
 
 ## Advanced features and reliability
 
diff --git a/docs/transports/sendgrid.md b/docs/transports/sendgrid.md
index 408b7bd..cff53e0 100644
--- a/docs/transports/sendgrid.md
+++ b/docs/transports/sendgrid.md
@@ -160,10 +160,21 @@ for await (const receipt of transport.sendMany(messages)) {
 }
 ```
 
-The `SendGridTransport.sendMany()` method processes emails sequentially with
-built-in retry logic. Failed emails don't prevent subsequent emails from being
-sent, and detailed error information helps you identify and resolve delivery
-issues quickly.
+The `SendGridTransport.sendMany()` method processes emails one after the other
+with built-in retry logic. Failed emails don't prevent subsequent emails from
+being sent, and detailed error information helps you identify and resolve
+delivery issues quickly.
+
+With `concurrency` set (1 by default), it sends that many messages at once: it
+reads a message only when a send can start, so a long iterable costs that many
+messages of memory, and gives the receipts in the order of the messages.
+
+```js
+const transport = new SendGridTransport({
+  apiKey: process.env.SENDGRID_API_KEY,
+  concurrency: 4,
+});
+```
 
 ## Advanced configuration and reliability
 
diff --git a/scripts/size-budgets.json b/scripts/size-budgets.json
index 8ee6a33..1e3e49f 100644
--- a/scripts/size-budgets.json
+++ b/scripts/size-budgets.json
@@ -5,12 +5,12 @@
   "./jmap": 11.5,
   "./ses": 6,
   "./resend": 5.5,
-  "./sendgrid": 5,
-  "./mailgun": 5,
+  "./sendgrid": 5.5,
+  "./mailgun": 5.5,
   "./mailtrap": 6,
   "./maileroo": 5.5,
   "./lettermint": 5.5,
-  "./plunk": 5,
+  "./plunk": 5.5,
   "./pool": 3,
   "./retry": 3,
   "./mock": 2,
diff --git a/src/internal/batch.js b/src/internal/batch.js
index c44d3bd..b154527 100644
--- a/src/internal/batch.js
+++ b/src/internal/batch.js
@@ -1,5 +1,19 @@
-// Not ported from upyo: a batch of messages read as it is needed rather than
-// all at once, so that a sendMany() holds one batch in memory, not its input.
+// Not ported from upyo: the messages of a sendMany() read as they are needed
+// rather than all at once, so that it holds a batch in memory, not its input.
+
+const noop = () => {};
+
+/**
+ * The items of an iterable, synchronous or not, through one async iterator
+ * that can be read by hand and then iterated for the rest.
+ *
+ * @param iterable The items.
+ * @returns An async generator of them.
+ * @internal
+ */
+const readItems = async function* (iterable) {
+  for await (const item of iterable) yield item;
+};
 
 /**
  * Reads an iterable, synchronous or not, in arrays of at most `size` items,
@@ -22,4 +36,51 @@ const chunks = async function* (iterable, size) {
   if (chunk.length > 0) yield chunk;
 };
 
-module.exports = { chunks };
+/**
+ * Sends the messages of an iterable with up to `limit` sends at a time,
+ * reading a message only when a send can start, and gives the receipts in the
+ * order of the messages.  With a limit of 1 a message is read and sent only
+ * after the receipt of the one before was taken.
+ *
+ * @param messages The messages, synchronous or not.
+ * @param limit The most sends at once.
+ * @param send Sends one message and gives its receipt.
+ * @param signal Checked before each send.
+ * @returns The receipts, in order.
+ * @internal
+ */
+const sendConcurrently = async function* (messages, limit, send, signal) {
+  const iterator = readItems(messages);
+  const pending = [];
+  let head = 0;
+  let done = false;
+  try {
+    while (true) {
+      while (!done && pending.length - head < limit) {
+        const item = await iterator.next();
+        if (item.done) {
+          done = true;
+        } else {
+          signal?.throwIfAborted();
+          const sending = send(item.value);
+          // A later send can fail while an earlier one is awaited: observed
+          // here, its failure still reaches the caller when its turn comes.
+          sending.catch(noop);
+          pending.push(sending);
+        }
+      }
+      if (head === pending.length) return;
+      const receipt = await pending[head];
+      pending[head++] = undefined;
+      if (head === pending.length) {
+        pending.length = 0;
+        head = 0;
+      }
+      yield receipt;
+    }
+  } finally {
+    await iterator.return();
+  }
+};
+
+module.exports = { chunks, readItems, sendConcurrently };
diff --git a/src/internal/config.js b/src/internal/config.js
index 74ce06b..599c5b7 100644
--- a/src/internal/config.js
+++ b/src/internal/config.js
@@ -47,4 +47,17 @@ const checkSecureUrl = (value, name) => {
   );
 };
 
-module.exports = { checkRequestOptions, checkSecureUrl };
+/**
+ * Checks how many messages a sendMany() of a provider sends at once.
+ *
+ * @param concurrency The most sends at once.
+ * @throws {RangeError} If it is not a positive integer.
+ * @internal
+ */
+const checkConcurrency = (concurrency) => {
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw new RangeError('`concurrency` must be a positive integer: ' + String(concurrency));
+  }
+};
+
+module.exports = { checkConcurrency, checkRequestOptions, checkSecureUrl };
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index 4ce0a68..fcaeadd 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -16,7 +16,7 @@ const { isUnsentRequestError } = require('../internal/unsent.js');
 const { convertMessage } = require('./message-converter.js');
 const { findMailAccount } = require('./session.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
-const { chunks } = require('../internal/batch.js');
+const { chunks, readItems } = require('../internal/batch.js');
 
 /**
  * JMAP capabilities required for email sending.
@@ -825,12 +825,6 @@ class JmapTransport {
   }
 }
 
-// The items of an iterable, synchronous or not, through one async iterator
-// that can be read from by hand and then iterated for the rest.
-const readItems = async function* (iterable) {
-  for await (const item of iterable) yield item;
-};
-
 const prepend = async function* (first, rest) {
   yield first;
   yield* rest;
diff --git a/src/maileroo/config.js b/src/maileroo/config.js
index e9372ea..7e00c86 100644
--- a/src/maileroo/config.js
+++ b/src/maileroo/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/maileroo/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
+const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved Maileroo configuration by applying default values.
@@ -18,11 +18,13 @@ const createMailerooConfig = (config) => {
     generateId: config.generateId,
     logger: config.logger,
     retries: config.retries ?? 3,
+    concurrency: config.concurrency ?? 1,
     headers: config.headers == null ? {} : { ...config.headers },
     tracking: config.tracking,
     tags: config.tags == null ? undefined : { ...config.tags },
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkConcurrency(resolved.concurrency);
   checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
diff --git a/src/maileroo/index.d.ts b/src/maileroo/index.d.ts
index 356ac44..a8219c7 100644
--- a/src/maileroo/index.d.ts
+++ b/src/maileroo/index.d.ts
@@ -48,6 +48,14 @@ export interface MailerooConfig extends TransportDependencies {
    * @default 3
    */
   readonly retries?: number;
+  /**
+   * How many messages `sendMany()` sends at once.  It reads a message only
+   * when a send can start and gives the receipts in the order of the
+   * messages; 1 sends one after the other.
+   *
+   * @default 1
+   */
+  readonly concurrency?: number;
   /**
    * Additional HTTP headers to include with requests.
    */
diff --git a/src/maileroo/maileroo-transport.js b/src/maileroo/maileroo-transport.js
index 37bd21b..fef35ca 100644
--- a/src/maileroo/maileroo-transport.js
+++ b/src/maileroo/maileroo-transport.js
@@ -7,6 +7,7 @@ const { MailerooApiError, MailerooHttpClient, MailerooTimeoutError } = require('
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { sendConcurrently } = require('../internal/batch.js');
 
 /**
  * Maileroo transport implementation for sending emails via Maileroo API.
@@ -103,11 +104,12 @@ class MailerooTransport {
    */
   async *sendMany(messages, options) {
     options?.signal?.throwIfAborted();
-
-    for await (const message of messages) {
-      options?.signal?.throwIfAborted();
-      yield await this.send(message, options);
-    }
+    yield* sendConcurrently(
+      messages,
+      this.config.concurrency,
+      (message) => this.send(message, options),
+      options?.signal,
+    );
   }
 }
 
diff --git a/src/mailgun/config.js b/src/mailgun/config.js
index 1ca902b..5f34f6b 100644
--- a/src/mailgun/config.js
+++ b/src/mailgun/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/mailgun/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
+const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved Mailgun configuration by applying default values to optional fields.
@@ -28,6 +28,7 @@ const createMailgunConfig = (config) => {
     generateId: config.generateId,
     logger: config.logger,
     retries: config.retries ?? 3,
+    concurrency: config.concurrency ?? 1,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
     tracking: config.tracking ?? true,
@@ -35,6 +36,7 @@ const createMailgunConfig = (config) => {
     openTracking: config.openTracking ?? true,
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkConcurrency(resolved.concurrency);
   checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
diff --git a/src/mailgun/index.d.ts b/src/mailgun/index.d.ts
index c235054..b3a790a 100644
--- a/src/mailgun/index.d.ts
+++ b/src/mailgun/index.d.ts
@@ -67,6 +67,14 @@ export interface MailgunConfig extends TransportDependencies {
    * @default 3
    */
   readonly retries?: number;
+  /**
+   * How many messages `sendMany()` sends at once.  It reads a message only
+   * when a send can start and gives the receipts in the order of the
+   * messages; 1 sends one after the other.
+   *
+   * @default 1
+   */
+  readonly concurrency?: number;
   /**
    * Whether to validate SSL certificates.
    *
diff --git a/src/mailgun/mailgun-transport.js b/src/mailgun/mailgun-transport.js
index cfa833e..1cf4e6d 100644
--- a/src/mailgun/mailgun-transport.js
+++ b/src/mailgun/mailgun-transport.js
@@ -7,6 +7,7 @@ const { MailgunApiError, MailgunHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { sendConcurrently } = require('../internal/batch.js');
 
 /**
  * Mailgun transport implementation for sending emails via Mailgun API.
@@ -186,20 +187,12 @@ class MailgunTransport {
    */
   async *sendMany(messages, options) {
     options?.signal?.throwIfAborted();
-
-    const isAsyncIterable = Symbol.asyncIterator in messages;
-
-    if (isAsyncIterable) {
-      for await (const message of messages) {
-        options?.signal?.throwIfAborted();
-        yield await this.send(message, options);
-      }
-    } else {
-      for (const message of messages) {
-        options?.signal?.throwIfAborted();
-        yield await this.send(message, options);
-      }
-    }
+    yield* sendConcurrently(
+      messages,
+      this.config.concurrency,
+      (message) => this.send(message, options),
+      options?.signal,
+    );
   }
 }
 
diff --git a/src/plunk/config.js b/src/plunk/config.js
index 293c74a..3318937 100644
--- a/src/plunk/config.js
+++ b/src/plunk/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/plunk/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
+const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved Plunk configuration by applying default values to optional fields.
@@ -23,10 +23,12 @@ const createPlunkConfig = (config) => {
     generateId: config.generateId,
     logger: config.logger,
     retries: config.retries ?? 3,
+    concurrency: config.concurrency ?? 1,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkConcurrency(resolved.concurrency);
   checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
diff --git a/src/plunk/index.d.ts b/src/plunk/index.d.ts
index e56015f..05955b8 100644
--- a/src/plunk/index.d.ts
+++ b/src/plunk/index.d.ts
@@ -57,6 +57,14 @@ export interface PlunkConfig extends TransportDependencies {
    * @default 3
    */
   readonly retries?: number;
+  /**
+   * How many messages `sendMany()` sends at once.  It reads a message only
+   * when a send can start and gives the receipts in the order of the
+   * messages; 1 sends one after the other.
+   *
+   * @default 1
+   */
+  readonly concurrency?: number;
   /**
    * Whether to validate SSL certificates.
    *
diff --git a/src/plunk/plunk-transport.js b/src/plunk/plunk-transport.js
index 40a9b86..07e16ae 100644
--- a/src/plunk/plunk-transport.js
+++ b/src/plunk/plunk-transport.js
@@ -8,6 +8,7 @@ const { PlunkApiError, PlunkHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { sendConcurrently } = require('../internal/batch.js');
 
 /**
  * Plunk transport implementation for sending emails via Plunk API.
@@ -192,20 +193,12 @@ class PlunkTransport {
    */
   async *sendMany(messages, options) {
     options?.signal?.throwIfAborted();
-
-    const isAsyncIterable = Symbol.asyncIterator in messages;
-
-    if (isAsyncIterable) {
-      for await (const message of messages) {
-        options?.signal?.throwIfAborted();
-        yield await this.send(message, options);
-      }
-    } else {
-      for (const message of messages) {
-        options?.signal?.throwIfAborted();
-        yield await this.send(message, options);
-      }
-    }
+    yield* sendConcurrently(
+      messages,
+      this.config.concurrency,
+      (message) => this.send(message, options),
+      options?.signal,
+    );
   }
 
   /**
diff --git a/src/sendgrid/config.js b/src/sendgrid/config.js
index 154d332..8032b73 100644
--- a/src/sendgrid/config.js
+++ b/src/sendgrid/config.js
@@ -1,7 +1,7 @@
 // Ported from upyo v0.7.0 (packages/sendgrid/src/config.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
-const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
+const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
 
 /**
  * Creates a resolved SendGrid configuration by applying default values to optional fields.
@@ -23,6 +23,7 @@ const createSendGridConfig = (config) => {
     generateId: config.generateId,
     logger: config.logger,
     retries: config.retries ?? 3,
+    concurrency: config.concurrency ?? 1,
     validateSsl: config.validateSsl ?? true,
     headers: config.headers ?? {},
     clickTracking: config.clickTracking ?? true,
@@ -31,6 +32,7 @@ const createSendGridConfig = (config) => {
     googleAnalytics: config.googleAnalytics ?? false,
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
+  checkConcurrency(resolved.concurrency);
   checkSecureUrl(resolved.baseUrl, 'baseUrl');
   return resolved;
 };
diff --git a/src/sendgrid/index.d.ts b/src/sendgrid/index.d.ts
index cd790af..e17e64f 100644
--- a/src/sendgrid/index.d.ts
+++ b/src/sendgrid/index.d.ts
@@ -52,6 +52,14 @@ export interface SendGridConfig extends TransportDependencies {
    * @default 3
    */
   readonly retries?: number;
+  /**
+   * How many messages `sendMany()` sends at once.  It reads a message only
+   * when a send can start and gives the receipts in the order of the
+   * messages; 1 sends one after the other.
+   *
+   * @default 1
+   */
+  readonly concurrency?: number;
   /**
    * Whether to validate SSL certificates.
    *
diff --git a/src/sendgrid/sendgrid-transport.js b/src/sendgrid/sendgrid-transport.js
index 16414ba..6498801 100644
--- a/src/sendgrid/sendgrid-transport.js
+++ b/src/sendgrid/sendgrid-transport.js
@@ -8,6 +8,7 @@ const { SendGridApiError, SendGridHttpClient } = require('./http-client.js');
 const { convertMessage } = require('./message-converter.js');
 const { INSPECT, inspectRedacted, redactSecrets } = require('../internal/redact.js');
 const { isDeliveryUnknown } = require('../internal/delivery-unknown.js');
+const { sendConcurrently } = require('../internal/batch.js');
 
 /**
  * SendGrid transport implementation for sending emails via SendGrid API.
@@ -191,20 +192,12 @@ class SendGridTransport {
    */
   async *sendMany(messages, options) {
     options?.signal?.throwIfAborted();
-
-    const isAsyncIterable = Symbol.asyncIterator in messages;
-
-    if (isAsyncIterable) {
-      for await (const message of messages) {
-        options?.signal?.throwIfAborted();
-        yield await this.send(message, options);
-      }
-    } else {
-      for (const message of messages) {
-        options?.signal?.throwIfAborted();
-        yield await this.send(message, options);
-      }
-    }
+    yield* sendConcurrently(
+      messages,
+      this.config.concurrency,
+      (message) => this.send(message, options),
+      options?.signal,
+    );
   }
 
   /**
diff --git a/tests/types/maileroo.test-d.ts b/tests/types/maileroo.test-d.ts
index 1e7bdb9..d50affe 100644
--- a/tests/types/maileroo.test-d.ts
+++ b/tests/types/maileroo.test-d.ts
@@ -1,4 +1,4 @@
-import { expectAssignable, expectError, expectType } from 'tsd';
+import { expectNotAssignable, expectAssignable, expectError, expectType } from 'tsd';
 import { createMessage, type Receipt, type Transport } from '../../index.js';
 import {
   MailerooApiError,
@@ -23,6 +23,14 @@ expectType<Promise<Receipt<'maileroo'>>>(transport.send(message));
 expectType<AsyncIterable<Receipt<'maileroo'>>>(transport.sendMany([message]));
 
 expectAssignable<MailerooConfig>({ apiKey: 'key', tracking: false, retries: 1 });
+// sendMany() sends as many messages at once.
+expectAssignable<MailerooConfig>({ apiKey: 'key', tracking: false, retries: 1, concurrency: 4 });
+expectNotAssignable<MailerooConfig>({
+  apiKey: 'key',
+  tracking: false,
+  retries: 1,
+  concurrency: '4',
+});
 expectAssignable<Error>(new MailerooApiError('Unauthorized', 401));
 expectAssignable<Error>(new MailerooTimeoutError(1000));
 expectError(new MailerooTransport({ timeout: 5000 }));
diff --git a/tests/types/mailgun.test-d.ts b/tests/types/mailgun.test-d.ts
index 29cb906..07ca152 100644
--- a/tests/types/mailgun.test-d.ts
+++ b/tests/types/mailgun.test-d.ts
@@ -1,4 +1,4 @@
-import { expectAssignable, expectError, expectType } from 'tsd';
+import { expectNotAssignable, expectAssignable, expectError, expectType } from 'tsd';
 import { createMessage, type Receipt, type Transport } from '../../index.js';
 import { MailgunApiError, MailgunTransport, type MailgunConfig } from '../../src/mailgun/index.js';
 
@@ -15,6 +15,19 @@ expectType<Promise<Receipt<'mailgun'>>>(transport.send(message));
 expectType<AsyncIterable<Receipt<'mailgun'>>>(transport.sendMany([message]));
 
 expectAssignable<MailgunConfig>({ apiKey: 'key', domain: 'mg.example.com', tracking: true });
+// sendMany() sends as many messages at once.
+expectAssignable<MailgunConfig>({
+  apiKey: 'key',
+  domain: 'mg.example.com',
+  tracking: true,
+  concurrency: 4,
+});
+expectNotAssignable<MailgunConfig>({
+  apiKey: 'key',
+  domain: 'mg.example.com',
+  tracking: true,
+  concurrency: '4',
+});
 expectAssignable<Error>(new MailgunApiError('Forbidden', 403));
 expectError(new MailgunTransport({ apiKey: 'key' }));
 expectError(new MailgunTransport({ apiKey: 'key', domain: 'mg.example.com', region: 'ap' }));
diff --git a/tests/types/plunk.test-d.ts b/tests/types/plunk.test-d.ts
index 0e43762..cf01ada 100644
--- a/tests/types/plunk.test-d.ts
+++ b/tests/types/plunk.test-d.ts
@@ -1,4 +1,4 @@
-import { expectAssignable, expectError, expectType } from 'tsd';
+import { expectNotAssignable, expectAssignable, expectError, expectType } from 'tsd';
 import { createMessage, type Receipt, type Transport } from '../../index.js';
 import {
   PlunkTransport,
@@ -21,6 +21,9 @@ expectType<Promise<Receipt<'plunk'>>>(transport.send(message));
 expectType<AsyncIterable<Receipt<'plunk'>>>(transport.sendMany([message]));
 
 expectAssignable<PlunkConfig>({ apiKey: 'sk_key', retries: 1, timeout: 5000 });
+// sendMany() sends as many messages at once.
+expectAssignable<PlunkConfig>({ apiKey: 'sk_key', retries: 1, timeout: 5000, concurrency: 4 });
+expectNotAssignable<PlunkConfig>({ apiKey: 'sk_key', retries: 1, timeout: 5000, concurrency: '4' });
 declare const response: PlunkResponse;
 expectType<boolean>(response.success);
 expectError(new PlunkTransport({ baseUrl: 'https://plunk.example.com' }));
diff --git a/tests/types/sendgrid.test-d.ts b/tests/types/sendgrid.test-d.ts
index afcfd78..2564950 100644
--- a/tests/types/sendgrid.test-d.ts
+++ b/tests/types/sendgrid.test-d.ts
@@ -1,4 +1,4 @@
-import { expectAssignable, expectError, expectType } from 'tsd';
+import { expectNotAssignable, expectAssignable, expectError, expectType } from 'tsd';
 import { createMessage, type Receipt, type Transport } from '../../index.js';
 import {
   SendGridApiError,
@@ -19,5 +19,13 @@ expectType<Promise<Receipt<'sendgrid'>>>(transport.send(message));
 expectType<AsyncIterable<Receipt<'sendgrid'>>>(transport.sendMany([message]));
 
 expectAssignable<SendGridConfig>({ apiKey: 'SG.key', timeout: 5000, retries: 2 });
+// sendMany() sends as many messages at once.
+expectAssignable<SendGridConfig>({ apiKey: 'SG.key', timeout: 5000, retries: 2, concurrency: 4 });
+expectNotAssignable<SendGridConfig>({
+  apiKey: 'SG.key',
+  timeout: 5000,
+  retries: 2,
+  concurrency: '4',
+});
 expectAssignable<Error>(new SendGridApiError('Bad request', 400));
 expectError(new SendGridTransport({ retries: 1 }));
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index fe0baf3..b6c6cde 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -422,3 +422,104 @@ test('Internal: a log binds its component, builds records lazily, and never thro
   createLog(undefined, {}).write('warn', () => assert.fail('no logger'), 'x');
   assert.strictEqual(createLog(undefined, {}).isEnabled('warn'), false);
 });
+
+test('Internal: sendConcurrently keeps the order and at most `limit` sends at once', async () => {
+  const { sendConcurrently } = require('../../src/internal/batch.js');
+  let read = 0;
+  let inFlight = 0;
+  let most = 0;
+  const messages = (function* () {
+    for (let index = 0; index < 6; index++) {
+      read++;
+      yield index;
+    }
+  })();
+  // Later messages finish sooner, so the receipts come back out of order.
+  const send = async (index) => {
+    inFlight++;
+    most = Math.max(most, inFlight);
+    await new Promise((resolve) => setTimeout(resolve, (6 - index) * 2));
+    inFlight--;
+    return index;
+  };
+  const receipts = [];
+  for await (const receipt of sendConcurrently(messages, 3, send)) {
+    receipts.push(receipt);
+    if (receipts.length === 1) assert.ok(read <= 3, `read ${read} before the first receipt`);
+  }
+  assert.deepStrictEqual(receipts, [0, 1, 2, 3, 4, 5]);
+  assert.strictEqual(most, 3);
+});
+
+test('Internal: sendConcurrently with a limit of 1 reads after each receipt', async () => {
+  const { sendConcurrently } = require('../../src/internal/batch.js');
+  const events = [];
+  const messages = (async function* () {
+    for (let index = 0; index < 3; index++) {
+      events.push(`read ${index}`);
+      yield index;
+    }
+  })();
+  for await (const receipt of sendConcurrently(messages, 1, async (index) => index)) {
+    events.push(`receipt ${receipt}`);
+  }
+  assert.deepStrictEqual(events, [
+    'read 0',
+    'receipt 0',
+    'read 1',
+    'receipt 1',
+    'read 2',
+    'receipt 2',
+  ]);
+});
+
+test('Internal: sendConcurrently closes its input early and surfaces failures in turn', async (t) => {
+  const { sendConcurrently } = require('../../src/internal/batch.js');
+  let closed = false;
+  const messages = (function* () {
+    try {
+      for (let index = 0; ; index++) yield index;
+    } finally {
+      closed = true;
+    }
+  })();
+  for await (const receipt of sendConcurrently(messages, 2, async (index) => index)) {
+    assert.strictEqual(receipt, 0);
+    break;
+  }
+  assert.ok(closed);
+
+  // A later send that fails while an earlier one is awaited is no unhandled
+  // rejection; its error comes when its turn does.
+  const unhandled = [];
+  const onUnhandled = (reason) => unhandled.push(reason);
+  process.on('unhandledRejection', onUnhandled);
+  t.after(() => process.off('unhandledRejection', onUnhandled));
+  const send = async (index) => {
+    if (index === 1) throw new Error('second failed');
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    return index;
+  };
+  const receipts = [];
+  await assert.rejects(async () => {
+    for await (const receipt of sendConcurrently([0, 1, 2], 3, send)) receipts.push(receipt);
+  }, /second failed/);
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.deepStrictEqual(receipts, [0]);
+  assert.deepStrictEqual(unhandled, []);
+
+  const aborted = AbortSignal.abort(new Error('stop'));
+  await assert.rejects(async () => {
+    for await (const receipt of sendConcurrently([0], 1, async (index) => index, aborted)) {
+      assert.fail(receipt);
+    }
+  }, /stop/);
+});
+
+test('Internal: concurrency must be a positive integer', () => {
+  const { checkConcurrency } = require('../../src/internal/config.js');
+  for (const concurrency of [1, 8]) checkConcurrency(concurrency);
+  for (const concurrency of [0, -1, 1.5, Infinity, '2', undefined]) {
+    assert.throws(() => checkConcurrency(concurrency), RangeError, String(concurrency));
+  }
+});
diff --git a/tests/unit/sendgrid.test.js b/tests/unit/sendgrid.test.js
index 6fab20e..2fdd961 100644
--- a/tests/unit/sendgrid.test.js
+++ b/tests/unit/sendgrid.test.js
@@ -97,3 +97,30 @@ test('SendGrid: error bodies, retries, timeouts and aborts', async (t) => {
     { name: 'AbortError' },
   );
 });
+
+test('SendGrid: sendMany sends `concurrency` messages at once and keeps their order', async (t) => {
+  let inFlight = 0;
+  let most = 0;
+  let index = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    const id = `m${index++}`;
+    inFlight++;
+    most = Math.max(most, inFlight);
+    // Each answer comes sooner than the one before it.
+    await new Promise((resolve) => setTimeout(resolve, 20 - index * 4));
+    inFlight--;
+    return new Response(null, { status: 202, headers: { 'x-message-id': id } });
+  });
+  const transport = new SendGridTransport({ apiKey: 'SG.key', retries: 0, concurrency: 3 });
+  const messages = [];
+  for (let i = 0; i < 4; i++) {
+    messages.push(
+      createMessage({ from: 'a@example.com', to: 'b@example.com', subject: `${i}`, content: {} }),
+    );
+  }
+  const ids = [];
+  for await (const receipt of transport.sendMany(messages)) ids.push(receipt.messageId);
+  assert.deepStrictEqual(ids, ['m0', 'm1', 'm2', 'm3']);
+  assert.strictEqual(most, 3);
+  assert.throws(() => new SendGridTransport({ apiKey: 'SG.key', concurrency: 0 }), RangeError);
+});

From 8ce8b15fc8aaafd88d2141f789f8eac72cff144e Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:06:33 +0300
Subject: [PATCH 142/158] fix(retry): hold back at most maxConcurrent receipts
 in sendMany

Only the sends in flight counted against maxConcurrent, so while a slow
first message was out, each later one that finished freed its slot for
the next, and the whole input could be sent with its receipts held for
the first; every turn also raced all the sends in flight, adding a
reaction to each. A freed slot is still refilled, as the ported tests
ask, but no more than maxConcurrent finished receipts wait for an
earlier one, and a send that settles wakes the loop (SendManyRun, a
class with short methods in place of a 126-line generator).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                 |   5 +
 CLAUDE.md                    |   5 +
 docs/transports/retry.md     |   6 +
 src/retry/retry-transport.js | 292 ++++++++++++++++++++---------------
 tests/unit/retry.test.js     |  28 ++++
 5 files changed, 213 insertions(+), 123 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 67be346..779fd21 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -329,6 +329,11 @@ fixed ones below.
   in memory, or never sent. SES now reads `batchSize` messages at a time, Resend 100 (the batch
   API is chosen per chunk, where it used to be all or nothing for the whole input) and JMAP a
   batch of `maxObjectsInSet`, after one discovery.
+- **`./retry` holds back at most `maxConcurrent` receipts in `sendMany`** (an upstream bug):
+  while a slow first message was out, each later one that finished made room for the next, so
+  the whole input could be sent and its receipts held for the first. A freed slot is still
+  refilled, but no more than `maxConcurrent` finished receipts wait for an earlier one, and a
+  settled send wakes the loop instead of a `Promise.race` over all the sends in flight.
 - **`./otel` streams `sendMany`** (an upstream bug): it read the whole input into an array before
   the first message went out, and kept every receipt to the end, so a long or endless batch
   held it all in memory. The messages now pass on as the wrapped transport reads them; the batch
diff --git a/CLAUDE.md b/CLAUDE.md
index e9e8511..146d8d4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -377,6 +377,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     batch at a time (`chunks` of `internal/batch.js`): SES `batchSize` messages, Resend 100,
     each chunk choosing between the batch API and single requests, and JMAP `maxObjectsInSet`
     after one discovery, made only when there is a first message.
+75. retry: `sendMany` counted only the sends in flight against `maxConcurrent`, so while a
+    slow first message was out, every later one that finished freed its slot for the next,
+    and the whole input could be sent with its receipts held for the first; it also raced all
+    the sends in flight on every turn. No more than `maxConcurrent` finished receipts wait for
+    an earlier one (`SendManyRun`), and a send that settles wakes the loop instead of a race.
 
 ## Repository layout
 
diff --git a/docs/transports/retry.md b/docs/transports/retry.md
index c1626a7..640b7e4 100644
--- a/docs/transports/retry.md
+++ b/docs/transports/retry.md
@@ -193,6 +193,12 @@ for await (const receipt of transport.sendMany(messages)) {
 }
 ```
 
+Receipts come in the order of the messages.  A slot that a later message frees
+is refilled while an earlier one is still out, but no more than
+`maxConcurrent` finished receipts wait for an earlier one: past that, no new
+message starts until the slow one ends, so a stuck first message cannot let the
+whole input go out behind it.
+
 Receipts are yielded in the same order as input messages, even when later
 messages finish first.
 
diff --git a/src/retry/retry-transport.js b/src/retry/retry-transport.js
index 4d6adc1..be112d5 100644
--- a/src/retry/retry-transport.js
+++ b/src/retry/retry-transport.js
@@ -142,139 +142,31 @@ class RetryTransport {
    * @throws {DOMException} If the operation is aborted.
    */
   async *sendMany(messages, options) {
-    const iterator = toAsyncIterator(messages);
-    const inFlight = new Map();
-    const completed = new Map();
-    let inputDone = false;
-    let nextLaunchIndex = 0;
-    let nextYieldIndex = 0;
-    let launchPromise;
-    let launchError;
-    let hasLaunchError = false;
-    let hasQueuedFailure = false;
-    let pullingInput = false;
-    let closed = false;
     const controller = new AbortController();
     const combinedSignal = combineSignals(controller.signal, options?.signal);
-    const sendOptions = {
-      ...options,
-      signal: combinedSignal.signal,
-    };
-
-    const launchNext = async () => {
-      if (inputDone) return;
-      combinedSignal.signal.throwIfAborted();
-
-      pullingInput = true;
-      let inputPull;
-      try {
-        inputPull = Promise.resolve(iterator.next());
-      } catch (error) {
-        inputPull = Promise.reject(error);
-      }
-      inputPull = inputPull.finally(() => {
-        pullingInput = false;
-      });
-      const next = await raceWithAbort(inputPull, combinedSignal.signal);
-      if (closed) return;
-      if (next.done) {
-        inputDone = true;
-        return;
-      }
-
-      const index = nextLaunchIndex++;
-      if (index > 0) await this.waitBetweenSendMany(combinedSignal.signal);
-      if (closed) return;
-      const promise = this.send(next.value, sendOptions).then(
-        (receipt) => ({
-          index,
-          successful: true,
-          receipt,
-        }),
-        (error) => ({
-          index,
-          successful: false,
-          error,
-        }),
-      );
-      inFlight.set(index, promise);
-    };
-
-    const startLaunch = () => {
-      if (
-        launchPromise != null ||
-        inputDone ||
-        hasLaunchError ||
-        hasQueuedFailure ||
-        inFlight.size >= this.config.sendMany.maxConcurrent
-      ) {
-        return;
-      }
-
-      launchPromise = launchNext()
-        .catch((error) => {
-          launchError = error;
-          hasLaunchError = true;
-        })
-        .finally(() => {
-          launchPromise = undefined;
-        });
-    };
-
+    const signal = combinedSignal.signal;
+    const run = new SendManyRun(this, toAsyncIterator(messages), { ...options, signal });
     try {
-      startLaunch();
-
-      while (
-        inFlight.size > 0 ||
-        completed.has(nextYieldIndex) ||
-        // oxlint-disable-next-line no-unmodified-loop-condition -- upstream
-        launchPromise != null ||
-        // oxlint-disable-next-line no-unmodified-loop-condition -- upstream
-        !inputDone
-      ) {
-        combinedSignal.signal.throwIfAborted();
-
-        while (completed.has(nextYieldIndex)) {
-          const result = completed.get(nextYieldIndex);
-          completed.delete(nextYieldIndex);
-          if (result == null) break;
+      run.launch();
+      while (run.isActive()) {
+        signal.throwIfAborted();
+        for (let result = run.takeNext(); result !== undefined; result = run.takeNext()) {
           if (!result.successful) throw result.error;
           yield result.receipt;
-          nextYieldIndex++;
-          startLaunch();
+          run.launch();
         }
-
-        if (hasLaunchError && inFlight.size <= 0) throw launchError;
-
-        startLaunch();
-        if (inFlight.size <= 0 && launchPromise == null) break;
-
-        const launch = launchPromise?.then(() => ({
-          launched: true,
-        }));
-        const result = await raceWithAbort(
-          Promise.race([...inFlight.values(), ...(launch == null ? [] : [launch])]),
-          combinedSignal.signal,
-        );
-        if ('launched' in result) continue;
-        inFlight.delete(result.index);
-        completed.set(result.index, result);
-        if (!result.successful) hasQueuedFailure = true;
-        startLaunch();
+        if (run.hasLaunchError && run.inFlight <= 0) throw run.launchError;
+        run.launch();
+        if (run.inFlight <= 0 && run.launching === undefined) break;
+        await raceWithAbort(run.progress(), signal);
+        run.launch();
       }
-      if (hasLaunchError) throw launchError;
+      if (run.hasLaunchError) throw run.launchError;
     } finally {
-      closed = true;
+      run.closed = true;
       controller.abort(new DOMException('The operation was aborted.', 'AbortError'));
-      launchPromise?.catch(() => {});
       try {
-        const closeIterator = () => (inputDone ? undefined : iterator.return?.());
-        const closePromise = closeIterator();
-        if (pullingInput) {
-          closePromise?.catch(() => {});
-        } else {
-          await closePromise;
-        }
+        await run.close();
       } finally {
         combinedSignal.cleanup();
       }
@@ -480,6 +372,160 @@ const getRetryAfterMilliseconds = (failure) => {
   return undefined;
 };
 
+/**
+ * The state of one sendMany() of the retry decorator.  Messages are read and
+ * sent up to `maxConcurrent` at a time, and a slot freed by a later message
+ * is refilled while an earlier one is still out; a send that finishes waits
+ * among the completed ones until the receipts before it are given, and no
+ * more than `maxConcurrent` wait, so that a slow first message cannot let the
+ * whole input be sent and its receipts held.  Each send that settles, and each
+ * launch that ends, wakes the loop through progress(), with no race over the
+ * sends in flight.
+ */
+class SendManyRun {
+  inFlight = 0;
+  launching = undefined;
+  launchError = undefined;
+  hasLaunchError = false;
+  closed = false;
+  #transport;
+  #iterator;
+  #sendOptions;
+  #completed = new Map();
+  #nextLaunchIndex = 0;
+  #nextYieldIndex = 0;
+  #inputDone = false;
+  #pullingInput = false;
+  #hasQueuedFailure = false;
+  #wake = undefined;
+  #woken = false;
+
+  /**
+   * @param transport The retry decorator.
+   * @param iterator The async iterator of the messages.
+   * @param sendOptions The options of each send, with the signal of the batch.
+   */
+  constructor(transport, iterator, sendOptions) {
+    this.#transport = transport;
+    this.#iterator = iterator;
+    this.#sendOptions = sendOptions;
+  }
+
+  /** Starts reading and sending the next message, when a slot is free. */
+  launch() {
+    const maxConcurrent = this.#transport.config.sendMany.maxConcurrent;
+    if (
+      this.launching !== undefined ||
+      this.#inputDone ||
+      this.hasLaunchError ||
+      this.#hasQueuedFailure ||
+      this.inFlight >= maxConcurrent ||
+      this.#completed.size >= maxConcurrent
+    ) {
+      return;
+    }
+    this.launching = this.#launchNext()
+      .catch((error) => {
+        this.launchError = error;
+        this.hasLaunchError = true;
+      })
+      .finally(() => {
+        this.launching = undefined;
+        this.#notify();
+      });
+  }
+
+  /** The result of the next message in order, once it is there. */
+  takeNext() {
+    const result = this.#completed.get(this.#nextYieldIndex);
+    if (result === undefined) return undefined;
+    this.#completed.delete(this.#nextYieldIndex);
+    if (result.successful) this.#nextYieldIndex++;
+    return result;
+  }
+
+  isActive() {
+    return (
+      this.inFlight > 0 ||
+      this.#completed.has(this.#nextYieldIndex) ||
+      this.launching !== undefined ||
+      !this.#inputDone
+    );
+  }
+
+  /** Settles at the next send that settles or launch that ends, at once if one did since. */
+  progress() {
+    if (this.#woken) {
+      this.#woken = false;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => (this.#wake = resolve));
+  }
+
+  /** Closes the input unless it ended, without waiting for a read in progress. */
+  close() {
+    this.launching?.catch(() => {});
+    if (this.#inputDone) return undefined;
+    const closing = this.#iterator.return?.();
+    if (this.#pullingInput) {
+      closing?.catch(() => {});
+      return undefined;
+    }
+    return closing;
+  }
+
+  #notify() {
+    if (this.#wake === undefined) {
+      this.#woken = true;
+      return;
+    }
+    const resolve = this.#wake;
+    this.#wake = undefined;
+    resolve();
+  }
+
+  #record(result) {
+    this.inFlight--;
+    this.#completed.set(result.index, result);
+    if (!result.successful) this.#hasQueuedFailure = true;
+    this.#notify();
+  }
+
+  async #pull() {
+    this.#pullingInput = true;
+    let inputPull;
+    try {
+      inputPull = Promise.resolve(this.#iterator.next());
+    } catch (error) {
+      inputPull = Promise.reject(error);
+    }
+    const pulled = inputPull.finally(() => {
+      this.#pullingInput = false;
+    });
+    return await raceWithAbort(pulled, this.#sendOptions.signal);
+  }
+
+  async #launchNext() {
+    if (this.#inputDone) return;
+    const signal = this.#sendOptions.signal;
+    signal.throwIfAborted();
+    const next = await this.#pull();
+    if (this.closed) return;
+    if (next.done) {
+      this.#inputDone = true;
+      return;
+    }
+    const index = this.#nextLaunchIndex++;
+    if (index > 0) await this.#transport.waitBetweenSendMany(signal);
+    if (this.closed) return;
+    this.inFlight++;
+    this.#transport.send(next.value, this.#sendOptions).then(
+      (receipt) => this.#record({ index, successful: true, receipt }),
+      (error) => this.#record({ index, successful: false, error }),
+    );
+  }
+}
+
 const toAsyncIterator = (values) => {
   const asyncIterator = values[Symbol.asyncIterator];
   if (typeof asyncIterator === 'function') return asyncIterator.call(values);
diff --git a/tests/unit/retry.test.js b/tests/unit/retry.test.js
index 62566a5..11a8218 100644
--- a/tests/unit/retry.test.js
+++ b/tests/unit/retry.test.js
@@ -238,3 +238,31 @@ test('Retry: the logger hears each retry it schedules', async () => {
     [{ transport: 'retry', attempt: 1, delayMilliseconds: 5 }, 'Retrying send'],
   ]);
 });
+
+test('Retry: a slow first message holds at most maxConcurrent receipts back', async () => {
+  let started = 0;
+  let releaseFirst;
+  const first = new Promise((resolve) => (releaseFirst = resolve));
+  const base = {
+    id: 'base',
+    send: async () => {
+      const index = started++;
+      if (index === 0) await first;
+      return { successful: true, messageId: `m${index}`, provider: 'base' };
+    },
+    async *sendMany() {},
+  };
+  const transport = createRetryTransport(base, { maxAttempts: 1, sendMany: { maxConcurrent: 2 } });
+  const messages = (function* () {
+    for (let index = 0; index < 100; index++) yield message();
+  })();
+  const receipts = transport.sendMany(messages)[Symbol.asyncIterator]();
+  const pending = receipts.next();
+  for (let turn = 0; turn < 20; turn++) await new Promise((resolve) => setImmediate(resolve));
+  // The first, the one that took its freed slot, and one more: the two
+  // finished ones wait for the first, and nothing else starts.
+  assert.strictEqual(started, 3);
+  releaseFirst();
+  assert.strictEqual((await pending).value.messageId, 'm0');
+  await receipts.return();
+});

From 4d712b75b05969581eca151bb3e505aea8a35c7c Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:08:04 +0300
Subject: [PATCH 143/158] fix(pool): keep the round-robin rotation across
 batches

sendMany reset the strategy, so round-robin sent every batch of one
message through the first transport, and two batches at once reset each
other's rotation. The strategy now goes on from where the sends before
left it; reset() stays on the strategies for the caller's own code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  3 +++
 CLAUDE.md                  |  3 +++
 docs/transports/pool.md    |  8 ++++++--
 src/pool/pool-transport.js |  6 +++---
 tests/unit/pool.test.js    | 17 +++++++++++++++++
 5 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 779fd21..7e2ed2e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -334,6 +334,9 @@ fixed ones below.
   the whole input could be sent and its receipts held for the first. A freed slot is still
   refilled, but no more than `maxConcurrent` finished receipts wait for an earlier one, and a
   settled send wakes the loop instead of a `Promise.race` over all the sends in flight.
+- **`./pool` keeps the round-robin rotation across batches** (an upstream bug): `sendMany` reset
+  the strategy, so a batch of one message always went through the first transport, and two
+  batches at once reset each other's rotation.
 - **`./otel` streams `sendMany`** (an upstream bug): it read the whole input into an array before
   the first message went out, and kept every receipt to the end, so a long or endless batch
   held it all in memory. The messages now pass on as the wrapped transport reads them; the batch
diff --git a/CLAUDE.md b/CLAUDE.md
index 146d8d4..4cba37e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -382,6 +382,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     and the whole input could be sent with its receipts held for the first; it also raced all
     the sends in flight on every turn. No more than `maxConcurrent` finished receipts wait for
     an earlier one (`SendManyRun`), and a send that settles wakes the loop instead of a race.
+76. pool: `sendMany` reset the strategy, so round-robin sent every batch of one message
+    through the first transport, and concurrent batches reset each other's rotation. The
+    strategy goes on from where the sends before left it.
 
 ## Repository layout
 
diff --git a/docs/transports/pool.md b/docs/transports/pool.md
index 285850f..f7f8580 100644
--- a/docs/transports/pool.md
+++ b/docs/transports/pool.md
@@ -105,7 +105,9 @@ const pool = new PoolTransport({
 ```
 
 Round-robin is perfect when you want equal load distribution and have providers
-with similar capabilities and costs.
+with similar capabilities and costs.  The rotation goes on across `send()` and
+`sendMany()` calls: a batch starts with the transport after the last one used,
+so many small batches still spread over every transport.
 
 ### Weighted distribution
 
@@ -272,7 +274,9 @@ such a selector skips its transport, as before, but is no longer silent.
 
 For advanced use cases, you can implement custom routing strategies by
 creating a class that implements the `Strategy` interface. This allows
-you to build sophisticated routing logic based on any criteria:
+you to build sophisticated routing logic based on any criteria.  The pool
+calls `select()` for each attempt and never `reset()`, which is there for your
+own code to call:
 
 ```js
 class TimeBasedStrategy {
diff --git a/src/pool/pool-transport.js b/src/pool/pool-transport.js
index 5b1f33f..b67b21a 100644
--- a/src/pool/pool-transport.js
+++ b/src/pool/pool-transport.js
@@ -188,9 +188,9 @@ class PoolTransport {
    * @returns An async iterable of receipts, one for each message.
    */
   async *sendMany(messages, options) {
-    // Reset strategy state for batch operations
-    this.strategy.reset();
-
+    // The strategy goes on from where the sends before left it: reset here,
+    // round-robin sent every batch of one message through the first
+    // transport, and concurrent batches reset each other.
     for await (const message of messages) {
       options?.signal?.throwIfAborted();
 
diff --git a/tests/unit/pool.test.js b/tests/unit/pool.test.js
index ed9fe18..0bc85d8 100644
--- a/tests/unit/pool.test.js
+++ b/tests/unit/pool.test.js
@@ -232,3 +232,20 @@ test('Pool: the logger hears a selector that throws and a failover', async () =>
   assert.deepStrictEqual(warns[0][1], { transport: 'pool', index: 0, error: 'Selector bug' });
   assert.ok(records.some(([level, , text]) => level === 'debug' && text === 'Pool failing over'));
 });
+
+test('Pool: round-robin goes on across sends and batches', async () => {
+  const first = new MockTransport();
+  const second = new MockTransport();
+  const pool = new PoolTransport({
+    strategy: 'round-robin',
+    transports: [{ transport: first }, { transport: second }],
+  });
+  await pool.send(message());
+  for (let batch = 0; batch < 3; batch++) {
+    for await (const receipt of pool.sendMany([message()])) assert.ok(receipt.successful);
+  }
+  // Upstream reset the rotation for each batch, so a batch of one message
+  // always went through the first transport.
+  assert.strictEqual(first.getSentMessagesCount(), 2);
+  assert.strictEqual(second.getSentMessagesCount(), 2);
+});

From 27b2a747ad0ffabd60221c608a0cea8990bd6c89 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:08:23 +0300
Subject: [PATCH 144/158] docs(logger): say how many messages sendMany holds
 for their receipts

The queue of messages waiting for a receipt grows only with the read-ahead
of the wrapped transport, which streaming sendMany, concurrency and the
bound of ./retry now keep to a batch at most; no limit of its own is
needed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/transports/logger.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/transports/logger.md b/docs/transports/logger.md
index 128f312..b01eb58 100644
--- a/docs/transports/logger.md
+++ b/docs/transports/logger.md
@@ -92,6 +92,13 @@ to disposable wrapped transports. Completion logs are emitted as callers consume
 receipts. If a caller stops reading a batch early, the wrapped iterator is closed
 without being drained so the logging layer does not start additional delivery work.
 
+In `sendMany()`, the decorator keeps each message it has passed on until its
+receipt comes back, to log the two together.  It holds as many as the wrapped
+transport reads ahead of its receipts and no more: one for the providers that
+send one message at a time, `concurrency` for those that take it, a batch for
+SES, Resend, Mailtrap, Lettermint and JMAP, and at most twice `maxConcurrent`
+for a `./retry` inside it.
+
 A logger that throws changes nothing of the delivery: the message is still sent,
 its receipt still comes back, and the failure is emitted as a process warning
 with the code `MAILER_LOGGER_FAILED` (`process.on('warning', …)`), since losing

From 4f3dceac8cc98cdc75198bf04ace6df991e42d86 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:09:51 +0300
Subject: [PATCH 145/158] test: check the attribution header of every shipped
 file

tests/unit/attribution.test.js reads src/ and the root index.d.ts: each
file starts with the upyo header (the upstream file, or the package
directory for a d.ts) and carries its notice, or starts with "Not ported
from upyo:". src/index.js, src/version.js, src/core/text.js and the root
index.d.ts get headers of that form, and LICENSE must keep the notice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                      |  5 +++
 index.d.ts                     |  5 ++-
 src/core/text.js               |  4 +-
 src/index.js                   |  6 ++-
 src/version.js                 |  9 ++--
 tests/unit/attribution.test.js | 82 ++++++++++++++++++++++++++++++++++
 6 files changed, 101 insertions(+), 10 deletions(-)
 create mode 100644 tests/unit/attribution.test.js

diff --git a/CLAUDE.md b/CLAUDE.md
index 4cba37e..1fd6e52 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -105,6 +105,11 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
   // Ported from upyo v0.7.0 (packages/smtp/src/smtp-connection.ts)
   // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
   ```
+  A d.ts names the directory of its package (`// Types ported from upyo v0.7.0
+  (packages/smtp/src)`), as its types come from several files, and lines that say how a file
+  was adapted may come between the two. A file that is not a port starts with
+  `// Not ported from upyo:` and what it is. `tests/unit/attribution.test.js` checks one or the
+  other in every file the package ships.
 - **The port keeps upstream's behavior.** What changes is the platform: CommonJS and the code
   style below, `node:crypto` instead of `@noble/hashes`, the OpenTelemetry providers and the
   logger passed in, fallbacks for runtimes older than Node 22 dropped, and the `@since` tags of
diff --git a/index.d.ts b/index.d.ts
index abaaba5..b23e4c0 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -1,6 +1,7 @@
+// Types ported from upyo v0.7.0 (packages/core/src)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 // The types of the root entry of @alexify/mailer, written by hand: the message
-// model and the transport contract (src/core/), ported from @upyo/core 0.7.0
-// (https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee).
+// model and the transport contract (src/core/).
 
 /**
  * A type alias for email address strings that must contain an @ symbol.
diff --git a/src/core/text.js b/src/core/text.js
index 425ad55..1fbe8ef 100644
--- a/src/core/text.js
+++ b/src/core/text.js
@@ -1,5 +1,5 @@
-// The character classes RFC 5322 builds atoms and address literals from, as
-// tables indexed by char code, and a scan of them in one pass.
+// Not ported from upyo: the character classes RFC 5322 builds atoms and address
+// literals from, as tables indexed by char code, and a scan of them in one pass.
 
 const DOT = 0x2e;
 
diff --git a/src/index.js b/src/index.js
index 5248e7e..fa7df51 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,5 +1,7 @@
-// The root entry: the message model and the transport contract ported from
-// @upyo/core 0.7.0 (src/core/), in upstream's order.
+// Ported from upyo v0.7.0 (packages/core/src/index.ts)
+// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
+// The root entry: the message model and the transport contract (src/core/), in
+// upstream's order.
 const { formatAddress, parseAddress, isEmailAddress } = require('./core/address.js');
 const { combineSignals } = require('./core/abort-signal.js');
 const {
diff --git a/src/version.js b/src/version.js
index d7c9319..01e944c 100644
--- a/src/version.js
+++ b/src/version.js
@@ -1,5 +1,6 @@
-// The package's own name and version, for the instrumentation scope of the
-// OpenTelemetry tracer and meter: a relative require of package.json would
-// bundle the whole manifest into ./otel. tests/unit/version.test.js keeps it
-// equal to package.json, and the release process bumps both.
+// Not ported from upyo: the package's own name and version, for the
+// instrumentation scope of the OpenTelemetry tracer and meter: a relative
+// require of package.json would bundle the whole manifest into ./otel.
+// tests/unit/version.test.js keeps it equal to package.json, and the release
+// process bumps both.
 module.exports = { name: '@alexify/mailer', version: '0.0.1' };
diff --git a/tests/unit/attribution.test.js b/tests/unit/attribution.test.js
new file mode 100644
index 0000000..a73e109
--- /dev/null
+++ b/tests/unit/attribution.test.js
@@ -0,0 +1,82 @@
+// Every file the package ships says where it comes from: the attribution header
+// of upyo, whose code most of the transport is a port of (MIT, the notice is in
+// LICENSE), or that it is not ported (CLAUDE.md, "Code ported from upyo").
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '../..');
+const NOTICE = '// https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee';
+const PORTED = /^\/\/ Ported from upyo v0\.7\.0 \(packages\/[a-z-]+\/src\/[\w./-]+\.ts[),]/;
+const PORTED_TYPES = /^\/\/ Types ported from upyo v0\.7\.0 \(packages\/[a-z-]+\/src[/)]/;
+const NOT_PORTED = '// Not ported from upyo: ';
+
+const shippedFiles = () => {
+  const files = ['index.d.ts'];
+  const walk = (directory) => {
+    for (const entry of fs.readdirSync(path.join(ROOT, directory), { withFileTypes: true })) {
+      const relative = path.posix.join(directory, entry.name);
+      if (entry.isDirectory()) walk(relative);
+      else if (relative.endsWith('.js') || relative.endsWith('.d.ts')) files.push(relative);
+    }
+  };
+  walk('src');
+  return files;
+};
+
+// The comment lines a file starts with.
+const headerOf = (text) => {
+  const lines = [];
+  for (const line of text.split('\n')) {
+    if (!line.startsWith('//')) break;
+    lines.push(line);
+  }
+  return lines;
+};
+
+const problemOf = (file, text) => {
+  const header = headerOf(text);
+  if (header.length === 0) return `${file} has no header`;
+  if (header[0].startsWith(NOT_PORTED)) return undefined;
+  const pattern = file.endsWith('.d.ts') ? PORTED_TYPES : PORTED;
+  if (!pattern.test(header[0])) {
+    return `${file} starts with neither the upyo header nor "${NOT_PORTED.trim()}"`;
+  }
+  if (!header.includes(NOTICE)) return `${file} has the upyo header without its notice`;
+  return undefined;
+};
+
+test('Attribution: every shipped file has the upyo header or says it is not ported', () => {
+  // The root index.js is a one-line shim over src/index.js.
+  const problems = [];
+  for (const file of shippedFiles()) {
+    const problem = problemOf(file, fs.readFileSync(path.join(ROOT, file), 'utf8'));
+    if (problem !== undefined) problems.push(problem);
+  }
+  assert.deepStrictEqual(problems, []);
+});
+
+test('Attribution: the check refuses a file without a header or without the notice', () => {
+  const notice = `${NOTICE}\n`;
+  const ported = '// Ported from upyo v0.7.0 (packages/smtp/src/smtp-connection.ts)\n';
+  assert.strictEqual(problemOf('src/a.js', `${ported}${notice}code`), undefined);
+  assert.strictEqual(problemOf('src/a.js', `${NOT_PORTED}a helper.\ncode`), undefined);
+  assert.strictEqual(
+    problemOf('src/a.d.ts', `// Types ported from upyo v0.7.0 (packages/smtp/src)\n${notice}`),
+    undefined,
+  );
+  assert.strictEqual(problemOf('src/a.js', 'const a = 1;'), 'src/a.js has no header');
+  assert.strictEqual(
+    problemOf('src/a.js', `${ported}code`),
+    'src/a.js has the upyo header without its notice',
+  );
+  assert.match(problemOf('src/a.js', '// Some code.\ncode'), /starts with neither/);
+  assert.match(problemOf('src/a.d.ts', `${ported}${notice}`), /starts with neither/);
+});
+
+test('Attribution: LICENSE carries the notice of upyo', () => {
+  const license = fs.readFileSync(path.join(ROOT, 'LICENSE'), 'utf8');
+  assert.match(license, /derived from Upyo \(https:\/\/github\.com\/dahlia\/upyo\)/);
+  assert.match(license, /Copyright 2025 Hong Minhee/);
+});

From c97bf4f0765978ae41f33dfa5de5db2e417036ac Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:40:15 +0300
Subject: [PATCH 146/158] fix(jmap): report the retries of discovery through
 onRetry

The requests JMAP retries are those of discovery, Mailbox/get and
Identity/get; the submission, the session and the uploads are not
retried. executeRequest takes the onRetry of the send, and send(),
sendMany() and sendRaw() pass it through getDraftsMailboxId,
getIdentityId and getIdentityMap, so ./otel, ./logger and the caller hear
those retries as they hear the HTTP providers'.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  6 ++--
 docs/guide/known-issues.md |  1 -
 src/jmap/http-client.js    |  4 ++-
 src/jmap/jmap-transport.js | 61 +++++++++++++++++++++++++++++++-------
 tests/unit/jmap.test.js    | 32 ++++++++++++++++++++
 5 files changed, 88 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e2ed2e..ea56b61 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,9 +36,9 @@ fixed ones below.
   providers that send one message per request send that many at once (1 by default, as
   before), reading a message only when a send can start and giving the receipts in the order of
   the messages.
-- **`onRetry` in the options of a send:** the HTTP providers and `./retry` call it before each
-  retry with the attempt, the wait and the error, and the decorators pass it on, so one callback
-  hears every level (not yet from `./jmap`).
+- **`onRetry` in the options of a send:** the HTTP providers, `./jmap` (whose discovery requests
+  are the ones it retries) and `./retry` call it before each retry with the attempt, the wait and
+  the error, and the decorators pass it on, so one callback hears every level.
 - **`generateId` for the identifiers the library makes:** an `IdGenerator` (`(kind) => string`,
   with `IdKind` one of `message-id`, `content-id`, `idempotency-key` and `receipt-id`) can
   replace `crypto.randomUUID()`, such as a cuid2, a ULID or a nanoid. `generateMessageId` and
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 75cae07..62bb9f8 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -21,7 +21,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 - Mailgun sends an inline attachment under its file name rather than its `contentId`, so a
   `cid:` in the HTML does not match it.
 - SES: custom and threading headers are not sent.
-- JMAP does not report its retries through `onRetry`.
 - JMAP on Node 24: an authentication rejection (401) of a streamed request body (raw upload,
   import, raw submission) becomes a retryable network error, as Node's `fetch` reports it so.
 
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index f05c5aa..5eecb52 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -59,9 +59,10 @@ class JmapHttpClient {
    * @param apiUrl The JMAP API URL.
    * @param request The JMAP request payload.
    * @param signal Optional abort signal.
+   * @param onRetry Optional callback of each retry.
    * @returns The JMAP response.
    */
-  executeRequest(apiUrl, request, signal) {
+  executeRequest(apiUrl, request, signal, onRetry) {
     signal?.throwIfAborted();
     // Serialized once rather than on every attempt.
     const json = JSON.stringify(request);
@@ -69,6 +70,7 @@ class JmapHttpClient {
     return requestWithRetry({
       log: this.log,
       signal,
+      onRetry,
       retries: this.replayableRequests ? this.config.retries : 0,
       timeoutMs: this.config.timeout,
       // A JMAP request is retried after a 2xx it could not read, as upstream
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index fcaeadd..8309c11 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -187,7 +187,14 @@ class JmapTransport {
       }
 
       // Get drafts mailbox ID
-      const draftsMailboxId = await this.getDraftsMailboxId(session, accountId, signal);
+      const onRetry = options?.onRetry;
+      const draftsMailboxId = await this.getDraftsMailboxId(
+        session,
+        accountId,
+        signal,
+        false,
+        onRetry,
+      );
       signal?.throwIfAborted();
 
       // Get identity ID
@@ -196,6 +203,8 @@ class JmapTransport {
         accountId,
         message.sender.address,
         signal,
+        false,
+        onRetry,
       );
       signal?.throwIfAborted();
 
@@ -286,12 +295,20 @@ class JmapTransport {
       }
       const drafts = await rawOperation(
         this.config.timeout,
-        (owned) => this.getDraftsMailboxId(session, accountId, owned, true),
+        (owned) => this.getDraftsMailboxId(session, accountId, owned, true, options?.onRetry),
         signal,
       );
       const identity = await rawOperation(
         this.config.timeout,
-        (owned) => this.getIdentityId(session, accountId, plan.envelope.from ?? '', owned, true),
+        (owned) =>
+          this.getIdentityId(
+            session,
+            accountId,
+            plan.envelope.from ?? '',
+            owned,
+            true,
+            options?.onRetry,
+          ),
         signal,
       );
       return await deliverRawMessage(
@@ -336,7 +353,7 @@ class JmapTransport {
     const input = readItems(messages);
     const first = await input.next();
     if (first.done) return;
-    const discovery = await this.discoverForBatch(signal);
+    const discovery = await this.discoverForBatch(signal, options?.onRetry);
     if (discovery.failure !== undefined) {
       yield discovery.failure();
       while (!(await input.next()).done) yield discovery.failure();
@@ -356,11 +373,12 @@ class JmapTransport {
    * account, its drafts mailbox and its identities.
    *
    * @param signal Cancellation signal.
+   * @param onRetry Optional callback of each retry.
    * @returns The `discovered` values, or the `failure` that makes the receipt
    * of each message when discovery fails.
    * @throws The caller's abort reason if cancelled.
    */
-  async discoverForBatch(signal) {
+  async discoverForBatch(signal, onRetry) {
     let processingStage = 'initialization';
     try {
       signal?.throwIfAborted();
@@ -382,11 +400,17 @@ class JmapTransport {
       }
 
       processingStage = 'mailbox discovery';
-      const draftsMailboxId = await this.getDraftsMailboxId(session, accountId, signal);
+      const draftsMailboxId = await this.getDraftsMailboxId(
+        session,
+        accountId,
+        signal,
+        false,
+        onRetry,
+      );
       signal?.throwIfAborted();
 
       processingStage = 'identity resolution';
-      const identityMap = await this.getIdentityMap(session, accountId, signal);
+      const identityMap = await this.getIdentityMap(session, accountId, signal, false, onRetry);
       signal?.throwIfAborted();
 
       return { discovered: { session, accountId, draftsMailboxId, identityMap } };
@@ -599,9 +623,11 @@ class JmapTransport {
    * @param session The JMAP session.
    * @param accountId The account ID.
    * @param signal Optional abort signal.
+   * @param strict Whether the discovery is the checked one of sendRaw().
+   * @param onRetry Optional callback of each retry.
    * @returns The drafts mailbox ID.
    */
-  async getDraftsMailboxId(session, accountId, signal, strict = false) {
+  async getDraftsMailboxId(session, accountId, signal, strict = false, onRetry = undefined) {
     const response = await this.httpClient.executeRequest(
       session.apiUrl,
       {
@@ -618,6 +644,7 @@ class JmapTransport {
         ],
       },
       signal,
+      onRetry,
     );
 
     const mailboxResponse = strict
@@ -649,15 +676,24 @@ class JmapTransport {
    * @param accountId The account ID.
    * @param senderEmail The sender's email address.
    * @param signal Optional abort signal.
+   * @param strict Whether the discovery is the checked one of sendRaw().
+   * @param onRetry Optional callback of each retry.
    * @returns The identity ID.
    */
-  async getIdentityId(session, accountId, senderEmail, signal, strict = false) {
+  async getIdentityId(
+    session,
+    accountId,
+    senderEmail,
+    signal,
+    strict = false,
+    onRetry = undefined,
+  ) {
     // If identity ID is configured, use it
     if (this.config.identityId) {
       return this.config.identityId;
     }
 
-    const identityMap = await this.getIdentityMap(session, accountId, signal, strict);
+    const identityMap = await this.getIdentityMap(session, accountId, signal, strict, onRetry);
     const matching = identityMap.get(senderEmail.toLowerCase());
     if (matching) {
       return matching;
@@ -672,9 +708,11 @@ class JmapTransport {
    * @param session The JMAP session.
    * @param accountId The account ID.
    * @param signal Optional abort signal.
+   * @param strict Whether the discovery is the checked one of sendRaw().
+   * @param onRetry Optional callback of each retry.
    * @returns Map of lowercase email to identity ID.
    */
-  async getIdentityMap(session, accountId, signal, strict = false) {
+  async getIdentityMap(session, accountId, signal, strict = false, onRetry = undefined) {
     // If identity ID is configured, return a map with just that
     if (this.config.identityId) {
       return new Map([['*', this.config.identityId]]);
@@ -695,6 +733,7 @@ class JmapTransport {
         ],
       },
       signal,
+      onRetry,
     );
 
     const identityResponse = strict
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index 967409b..2451801 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -397,3 +397,35 @@ test('JMAP: sendMany of nothing discovers nothing', async (t) => {
   for await (const receipt of transport().sendMany([])) assert.fail(receipt);
   assert.deepStrictEqual(calls, []);
 });
+
+test('JMAP: a retried discovery request is told through onRetry', async (t) => {
+  // The shortest jittered wait: half of the first delay.
+  t.mock.method(Math, 'random', () => 0);
+  let mailboxCalls = 0;
+  const handlers = {
+    session: session(),
+    'Mailbox/get': () => {
+      mailboxCalls++;
+      return defaults['Mailbox/get']();
+    },
+  };
+  serve(t, handlers);
+  const served = globalThis.fetch;
+  let failed = false;
+  t.mock.method(globalThis, 'fetch', async (input, init) => {
+    if (!failed && String(input).endsWith('/api') && init.body.includes('Mailbox/get')) {
+      failed = true;
+      return new Response('busy', { status: 503 });
+    }
+    return served(input, init);
+  });
+  const events = [];
+  const receipt = await transport({ retries: 1 }).send(message(), {
+    onRetry: (event) => events.push(event),
+  });
+  assert.strictEqual(receipt.successful, true);
+  assert.strictEqual(mailboxCalls, 1);
+  assert.strictEqual(events.length, 1);
+  assert.strictEqual(events[0].attempt, 1);
+  assert.strictEqual(events[0].error.statusCode, 503);
+});

From 171a28854c1101e87ab0d9079b46e4827a27d746 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:42:44 +0300
Subject: [PATCH 147/158] fix(mime): put inline parts in multipart/related

Inline parts (known upstream bug 1) went into the multipart/mixed of the
files, so some clients showed an image the HTML refers to by cid: as an
attachment. They go with the body in a multipart/related whose type
names the root part (RFC 2387); with files too, the related part comes
first in a multipart/mixed, as ./jmap already built it. A message without
attachments keeps its structure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  4 +++
 CLAUDE.md                  |  7 +++-
 docs/guide/known-issues.md |  2 --
 src/mime/message.js        | 68 +++++++++++++++++++++++++++++++++-----
 tests/unit/mime.test.js    | 49 +++++++++++++++++++++++++++
 5 files changed, 119 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ea56b61..e4ee8f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -324,6 +324,10 @@ fixed ones below.
   error and `timeout after 5000ms` a `server-error`. It now gives the category of
   `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
   `aborted` for an `AbortError`, which upstream counted as `network`.
+- **Inline images go in `multipart/related`** (an upstream bug): `./mime`, and so `./smtp`,
+  put inline parts in the `multipart/mixed` of the files, so some clients showed an image the
+  HTML refers to by `cid:` as an attachment. They now go with the body in a `multipart/related`
+  (RFC 2387), first in a `multipart/mixed` when there are files too.
 - **`./ses`, `./resend` and `./jmap` stream `sendMany`** (an upstream bug): each read its whole
   input into an array before the first message went out, so a long or endless iterable was held
   in memory, or never sent. SES now reads `batchSize` messages at a time, Resend 100 (the batch
diff --git a/CLAUDE.md b/CLAUDE.md
index 1fd6e52..f4db912 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -129,7 +129,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 
 **Known upstream bugs, each to fix in its own `fix:` commit after the port:**
 
-1. mime: inline images (`contentId`) go into `multipart/mixed`, not `multipart/related`.
+1. (fixed, see 77) mime: inline images (`contentId`) went into `multipart/mixed`, not
+   `multipart/related`.
 2. mailgun: an inline attachment is sent under its `filename`, not its `contentId`
    (`message-converter.js`), so a `cid:` in the HTML does not match it.
 3. `validateSsl` is accepted and never read (ses, resend, sendgrid, mailgun, mailtrap, plunk).
@@ -390,6 +391,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 76. pool: `sendMany` reset the strategy, so round-robin sent every batch of one message
     through the first transport, and concurrent batches reset each other's rotation. The
     strategy goes on from where the sends before left it.
+77. mime (known bug 1): inline parts went into the `multipart/mixed` of the files, so a client
+    could show an image the HTML refers to by `cid:` as an attachment. They go with the body in
+    a `multipart/related` whose `type` names the root part (RFC 2387), which sits first in a
+    `multipart/mixed` when there are files too, as `./jmap` already built it.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 62bb9f8..2cde8d8 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -6,8 +6,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 
 ## Messages and MIME
 
-- Inline images (`contentId`) go into `multipart/mixed` rather than `multipart/related`, so some
-  clients show them as attachments.
 - The first encoded word of a header shares its line with the field name
   (`Subject: =?UTF-8?B?…?=`), past the 76 characters that RFC 2047 allows such a line.
 
diff --git a/src/mime/message.js b/src/mime/message.js
index 8acf1a8..f9e70fc 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -134,16 +134,28 @@ const buildMimeParts = (message, generateId) => {
   const alternatives = buildAlternatives(message);
   pushHeaderFields(lines, message, generateId);
   lines.push('MIME-Version: 1.0');
-  if (message.attachments.length > 0 || alternatives.length > 1) {
-    const boundary = generateBoundary();
-    lines.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
-    lines.push('');
-    lines.push('This is a multi-part message in MIME format.');
+  // RFC 2387: an inline part goes with the body it is shown in, in a
+  // multipart/related; the files go beside them in a multipart/mixed.
+  const inline = [];
+  const attached = [];
+  for (const attachment of message.attachments) {
+    if (attachment.inline) inline.push(attachment);
+    else attached.push(attachment);
+  }
+  if (attached.length > 0) {
+    const boundary = pushMultipartHeader(lines, 'multipart/mixed');
+    lines.push(`--${boundary}`);
+    if (inline.length > 0) pushRelated(lines, alternatives, inline);
+    else pushBody(lines, alternatives);
+    for (const attachment of attached) pushAttachment(lines, attachment, boundary);
     lines.push('');
+    lines.push(`--${boundary}--`);
+  } else if (inline.length > 0) {
+    pushRelated(lines, alternatives, inline, true);
+  } else if (alternatives.length > 1) {
+    const boundary = pushMultipartHeader(lines, 'multipart/mixed');
     lines.push(`--${boundary}`);
-    if (alternatives.length > 1) pushAlternatives(lines, alternatives);
-    else pushSinglePart(lines, alternatives[0]);
-    for (const attachment of message.attachments) pushAttachment(lines, attachment, boundary);
+    pushAlternatives(lines, alternatives);
     lines.push('');
     lines.push(`--${boundary}--`);
   } else {
@@ -152,6 +164,46 @@ const buildMimeParts = (message, generateId) => {
   return joinLines(lines);
 };
 
+// The Content-Type of a top-level multipart and its preamble.
+const pushMultipartHeader = (lines, type, parameters = '') => {
+  const boundary = generateBoundary();
+  lines.push(`Content-Type: ${type}; boundary="${boundary}"${parameters}`);
+  lines.push('');
+  lines.push('This is a multi-part message in MIME format.');
+  lines.push('');
+  return boundary;
+};
+
+const pushBody = (lines, alternatives) => {
+  if (alternatives.length > 1) pushAlternatives(lines, alternatives);
+  else pushSinglePart(lines, alternatives[0]);
+};
+
+// A multipart/related of the body and its inline parts; `type` names the root
+// part, the body (RFC 2387 §3.1).
+const pushRelated = (lines, alternatives, inline, top = false) => {
+  const root = alternatives.length > 1 ? 'multipart/alternative' : mediaType(alternatives[0]);
+  const parameters = `; type="${root}"`;
+  let boundary;
+  if (top) {
+    boundary = pushMultipartHeader(lines, 'multipart/related', parameters);
+  } else {
+    boundary = generateBoundary();
+    lines.push(`Content-Type: multipart/related; boundary="${boundary}"${parameters}`);
+    lines.push('');
+  }
+  lines.push(`--${boundary}`);
+  pushBody(lines, alternatives);
+  for (const attachment of inline) pushAttachment(lines, attachment, boundary);
+  lines.push('');
+  lines.push(`--${boundary}--`);
+};
+
+const mediaType = (alternative) => {
+  const end = alternative.contentType.indexOf(';');
+  return end === -1 ? alternative.contentType : alternative.contentType.slice(0, end);
+};
+
 const pushHeaderFields = (lines, message, generateId) => {
   lines.push(foldHeader('From', encodeAddress(message.sender)));
   lines.push(foldHeader('To', encodeAddressList(message.recipients)));
diff --git a/tests/unit/mime.test.js b/tests/unit/mime.test.js
index 32d310d..ec2ea13 100644
--- a/tests/unit/mime.test.js
+++ b/tests/unit/mime.test.js
@@ -216,3 +216,52 @@ test('MIME: generateId makes the left half of a generated Message-ID', async ()
   });
   assert.match(headerBlock(text), /\r\nMessage-ID: <01JMIME\.message-id@example\.com>/);
 });
+
+test('MIME: an inline image goes in multipart/related with its HTML, a file beside them', async () => {
+  const image = {
+    inline: true,
+    filename: 'logo.png',
+    content: new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+    contentType: 'image/png',
+    contentId: 'logo@example.com',
+  };
+  const file = {
+    inline: false,
+    filename: 'report.pdf',
+    content: new Uint8Array([0x25, 0x50]),
+    contentType: 'application/pdf',
+    contentId: '',
+  };
+  const html = { text: 'Hi', html: '<p>Hi <img src="cid:logo@example.com"></p>' };
+
+  const onlyInline = await wire(
+    createMessage({ ...base, subject: 'a', content: html, attachments: [image] }),
+  );
+  assert.match(
+    headerBlock(onlyInline),
+    /^Content-Type: multipart\/related; boundary="[^"]+"; type="multipart\/alternative"$/m,
+  );
+  const parsedInline = await PostalMime.parse(onlyInline);
+  assert.strictEqual(parsedInline.html.trim(), html.html);
+  assert.deepStrictEqual(
+    parsedInline.attachments.map((part) => [part.contentId, part.related]),
+    [['<logo@example.com>', true]],
+  );
+
+  const both = await wire(
+    createMessage({ ...base, subject: 'a', content: html, attachments: [image, file] }),
+  );
+  assert.match(headerBlock(both), /^Content-Type: multipart\/mixed; boundary=/m);
+  // The related part, with the image in it, comes first; the file after it.
+  const related = both.indexOf('Content-Type: multipart/related;');
+  assert.ok(related > 0 && related < both.indexOf('name="logo.png"'));
+  assert.ok(both.indexOf('name="logo.png"') < both.indexOf('name="report.pdf"'));
+  const parsedBoth = await PostalMime.parse(both);
+  assert.deepStrictEqual(
+    parsedBoth.attachments.map((part) => [part.filename, part.related === true]),
+    [
+      ['logo.png', true],
+      ['report.pdf', false],
+    ],
+  );
+});

From 12cc7fad0d102e56ccc3bbbc9efeebcc827a3149 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:46:21 +0300
Subject: [PATCH 148/158] fix(mime): keep header lines with encoded words to 76
 characters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first encoded word of a header (known upstream bug 13) shared its
line with the field name, up to 84 characters, and other lines folded at
78, past the 76 that RFC 2047 §2 allows a line with an encoded word. A
field with encoded words folds at 76; its first word is split at a whole
UTF-8 character so that the first line keeps text and fits, the parts
decoding as one text (§6.2); a field name too long for any text after it
leaves the first line to itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  3 +++
 CLAUDE.md                  | 11 +++++++---
 docs/guide/known-issues.md |  5 -----
 src/mime/message.js        | 42 ++++++++++++++++++++++++++++++++++++--
 tests/unit/mime.test.js    | 30 ++++++++++++++++++++++++---
 5 files changed, 78 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e4ee8f8..2b89857 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -324,6 +324,9 @@ fixed ones below.
   error and `timeout after 5000ms` a `server-error`. It now gives the category of
   `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
   `aborted` for an `AbortError`, which upstream counted as `network`.
+- **Header lines with encoded words keep to 76 characters** (an upstream bug): the first encoded
+  word shared its line with the field name (`Subject: =?UTF-8?B?…?=`, up to 84 characters), past
+  what RFC 2047 allows. Such a field now folds at 76, and its first word is split to fit.
 - **Inline images go in `multipart/related`** (an upstream bug): `./mime`, and so `./smtp`,
   put inline parts in the `multipart/mixed` of the files, so some clients showed an image the
   HTML refers to by `cid:` as an attachment. They now go with the body in a `multipart/related`
diff --git a/CLAUDE.md b/CLAUDE.md
index f4db912..3da4f9f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -151,9 +151,9 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 11. (fixed, see 71) resend: the `Idempotency-Key` came from `Math.random`.
 12. (fixed, see 72 and 73) `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of
     an injected logger.
-13. mime: the first encoded word of a header shares its line with the field name
-    (`Subject: =?UTF-8?B?…?=`, 84 characters), past the 76 that RFC 2047 allows a line with
-    encoded words.
+13. (fixed, see 78) mime: the first encoded word of a header shared its line with the field
+    name (`Subject: =?UTF-8?B?…?=`, 84 characters), past the 76 that RFC 2047 allows a line
+    with encoded words.
 14. jmap: on Node 24, `fetch` answers a 401 to a streamed request body (raw upload, import,
     submission) with `TypeError: fetch failed` ("expected non-null body source") instead of the
     response, so an authentication rejection becomes a retryable network error. Node 22 returns
@@ -395,6 +395,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     could show an image the HTML refers to by `cid:` as an attachment. They go with the body in
     a `multipart/related` whose `type` names the root part (RFC 2387), which sits first in a
     `multipart/mixed` when there are files too, as `./jmap` already built it.
+78. mime (known bug 13): a line with an encoded word could reach 84 characters, as the first
+    word shared its line with the field name and other lines folded at 78, past the 76 of
+    RFC 2047 §2. A field with encoded words folds at 76, the first word is split at a whole
+    character to fit after the field name (`fitFirstEncodedWord`), and a name too long for
+    any text after it leaves the first line to itself.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 2cde8d8..1159b19 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -4,11 +4,6 @@ The transport layer is ported from [upyo](https://github.com/dahlia/upyo) 0.7.0
 behavior, bugs included, until each bug is fixed on its own with a test. This page lists the ones
 still open; the fixed ones are in the [changelog](https://github.com/Alexis-Technologies/mailer/blob/main/CHANGELOG.md).
 
-## Messages and MIME
-
-- The first encoded word of a header shares its line with the field name
-  (`Subject: =?UTF-8?B?…?=`), past the 76 characters that RFC 2047 allows such a line.
-
 ## SMTP
 
 - `cram-md5` is in the `SmtpAuth` type but not implemented.
diff --git a/src/mime/message.js b/src/mime/message.js
index f9e70fc..0cbc436 100644
--- a/src/mime/message.js
+++ b/src/mime/message.js
@@ -653,10 +653,18 @@ const foldHeader = (name, value) => {
       'Header field name must contain printable ASCII characters other than colon.',
     );
   }
-  const recommendedLineLength = 78;
+  // RFC 2047 §2 holds a line with an encoded word to 76 characters.
+  const hasEncodedWords = value.includes('=?');
+  const recommendedLineLength = hasEncodedWords ? MAX_ENCODED_LINE_LENGTH : 78;
   const lines = [];
   let prefix = `${name}: `;
-  let remaining = value;
+  let remaining = hasEncodedWords ? fitFirstEncodedWord(prefix, value) : value;
+  if (remaining === undefined) {
+    // A field name too long to leave room for any encoded text after it.
+    lines.push(`${name}:`);
+    prefix = ' ';
+    remaining = value;
+  }
 
   while (prefix.length + remaining.length > recommendedLineLength) {
     const availableLength = recommendedLineLength - prefix.length;
@@ -703,6 +711,36 @@ const foldHeader = (name, value) => {
   return folded;
 };
 
+const MAX_ENCODED_LINE_LENGTH = 76;
+const ENCODED_WORD = /^=\?UTF-8\?B\?([A-Za-z0-9+/=]*)\?=$/;
+
+/**
+ * Splits the encoded word a value starts with when it would not fit on the
+ * first line after the field name, so that the first line keeps text and
+ * stays within 76 characters; the rest of the word folds to the next line.
+ * Adjacent encoded words decode as one text (RFC 2047 §6.2).
+ *
+ * @param prefix The field name with its colon and space.
+ * @param value The encoded value.
+ * @returns The value, with its first word split if it had to be, or
+ * `undefined` when not even one character fits after the field name.
+ */
+const fitFirstEncodedWord = (prefix, value) => {
+  const space = value.indexOf(' ');
+  const end = space === -1 ? value.length : space;
+  const match = ENCODED_WORD.exec(value.slice(0, end));
+  if (match === null || prefix.length + end <= MAX_ENCODED_LINE_LENGTH) return value;
+  const bytes = Buffer.from(match[1], 'base64');
+  // 12 characters of `=?UTF-8?B?` and `?=`, then 4 of base64 per 3 bytes.
+  let cut = Math.floor((MAX_ENCODED_LINE_LENGTH - prefix.length - 12) / 4) * 3;
+  // A UTF-8 character is not split: a continuation byte moves the cut back.
+  while (cut > 0 && (bytes[cut] & 0xc0) === 0x80) cut--;
+  if (cut <= 0) return undefined;
+  const first = `=?UTF-8?B?${base64(bytes.subarray(0, cut))}?=`;
+  const rest = `=?UTF-8?B?${base64(bytes.subarray(cut))}?=`;
+  return `${first} ${rest}${value.slice(end)}`;
+};
+
 // The digits of an escaped byte, as character codes.
 const HEX_DIGITS = Buffer.from('0123456789ABCDEF', 'latin1');
 
diff --git a/tests/unit/mime.test.js b/tests/unit/mime.test.js
index ec2ea13..f3667c2 100644
--- a/tests/unit/mime.test.js
+++ b/tests/unit/mime.test.js
@@ -38,9 +38,14 @@ test('MIME: non-ASCII names, subjects and filenames round-trip through encoded w
     ],
   });
   const text = await wire(message);
-  // RFC 5322's hard limit; upstream puts the first encoded word next to the field
-  // name, past the 76 characters of RFC 2047 (CLAUDE.md, known upstream bugs).
-  for (const line of headerBlock(text).split('\r\n')) assert.ok(line.length <= 998, line);
+  // RFC 2047 §2: a line with an encoded word holds 76 characters at most; the
+  // first word, next to the field name, is split to fit.
+  const header = headerBlock(text);
+  assert.match(header, /^Subject: =\?UTF-8\?B\?/m);
+  assert.match(header, /^From: =\?UTF-8\?B\?/m);
+  for (const line of header.split('\r\n')) {
+    if (line.includes('=?')) assert.ok(line.length <= 76, `${line.length}: ${line}`);
+  }
   const parsed = await PostalMime.parse(text);
   assert.strictEqual(parsed.subject, subject);
   assert.deepStrictEqual(parsed.from, { address: 'alex@example.com', name: 'Алекс Долід' });
@@ -265,3 +270,22 @@ test('MIME: an inline image goes in multipart/related with its HTML, a file besi
     ],
   );
 });
+
+test('MIME: a field name too long for encoded text after it puts the text on the next line', async () => {
+  const name = `X-${'Long-'.repeat(12)}Name`;
+  // A Headers object takes Latin-1 text only.
+  const value = 'Café crème brûlée, déjà vu';
+  const text = await wire(createMessage({ ...base, subject: 'a', headers: { [name]: value } }));
+  const lines = headerBlock(text).split('\r\n');
+  const at = lines.findIndex((line) => line.toLowerCase().startsWith(`${name.toLowerCase()}:`));
+  assert.strictEqual(lines[at].toLowerCase(), `${name.toLowerCase()}:`);
+  for (let i = at + 1; lines[i]?.startsWith(' '); i++) assert.ok(lines[i].length <= 76, lines[i]);
+  const parsed = await PostalMime.parse(text);
+  const header = parsed.headers.find((field) => field.key === name.toLowerCase());
+  // Adjacent encoded words decode as one text (RFC 2047 §6.2), split only at
+  // whole characters.
+  const decoded = header.value
+    .replace(/\?=\s+=\?/g, '?==?')
+    .replace(/=\?UTF-8\?B\?([^?]*)\?=/g, (_, encoded) => Buffer.from(encoded, 'base64').toString());
+  assert.strictEqual(decoded, value);
+});

From ec998af3a19399cb7bb47d83ecca2ef92d9e63f7 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:47:51 +0300
Subject: [PATCH 149/158] fix(mailgun): send an inline part under its
 Content-ID

Mailgun makes the file name of an inline part its Content-ID, and the
converter sent the file name (known upstream bug 2), so the cid: of the
HTML matched nothing. The part goes under its contentId.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                     |  3 +++
 CLAUDE.md                        |  6 ++++--
 docs/guide/known-issues.md       |  2 --
 src/mailgun/message-converter.js |  5 +++--
 tests/unit/mailgun.test.js       | 22 ++++++++++++++++++++++
 5 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2b89857..fe67d2d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -324,6 +324,9 @@ fixed ones below.
   error and `timeout after 5000ms` a `server-error`. It now gives the category of
   `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
   `aborted` for an `AbortError`, which upstream counted as `network`.
+- **`./mailgun` sends an inline part under its Content-ID** (an upstream bug): Mailgun makes the
+  file name of an inline part its Content-ID, and the file name was sent, so a `cid:` in the
+  HTML matched nothing.
 - **Header lines with encoded words keep to 76 characters** (an upstream bug): the first encoded
   word shared its line with the field name (`Subject: =?UTF-8?B?…?=`, up to 84 characters), past
   what RFC 2047 allows. Such a field now folds at 76, and its first word is split to fit.
diff --git a/CLAUDE.md b/CLAUDE.md
index 3da4f9f..768f8ed 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -131,8 +131,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 
 1. (fixed, see 77) mime: inline images (`contentId`) went into `multipart/mixed`, not
    `multipart/related`.
-2. mailgun: an inline attachment is sent under its `filename`, not its `contentId`
-   (`message-converter.js`), so a `cid:` in the HTML does not match it.
+2. (fixed, see 79) mailgun: an inline attachment was sent under its `filename`, not its
+   `contentId` (`message-converter.js`), so a `cid:` in the HTML did not match it.
 3. `validateSsl` is accepted and never read (ses, resend, sendgrid, mailgun, mailtrap, plunk).
 4. (fixed, see 38) SMTP AUTH PLAIN and LOGIN encoded with `btoa`, which fails on non-Latin-1
    credentials; so did Basic auth in jmap and mailgun.
@@ -400,6 +400,8 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     RFC 2047 §2. A field with encoded words folds at 76, the first word is split at a whole
     character to fit after the field name (`fitFirstEncodedWord`), and a name too long for
     any text after it leaves the first line to itself.
+79. mailgun (known bug 2): an inline part was sent under its file name, which Mailgun makes its
+    Content-ID, so the `cid:` of the HTML matched nothing. It goes under its `contentId`.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 1159b19..d09a206 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -11,8 +11,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 ## HTTP providers and JMAP
 
 - `validateSsl` is accepted and never read (SES, Resend, SendGrid, Mailgun, Mailtrap, Plunk).
-- Mailgun sends an inline attachment under its file name rather than its `contentId`, so a
-  `cid:` in the HTML does not match it.
 - SES: custom and threading headers are not sent.
 - JMAP on Node 24: an authentication rejection (401) of a streamed request body (raw upload,
   import, raw submission) becomes a retryable network error, as Node's `fetch` reports it so.
diff --git a/src/mailgun/message-converter.js b/src/mailgun/message-converter.js
index 9820b7a..425adb1 100644
--- a/src/mailgun/message-converter.js
+++ b/src/mailgun/message-converter.js
@@ -121,8 +121,9 @@ const appendAttachment = async (formData, attachment, signal) => {
   });
 
   if (attachment.contentId) {
-    // Inline attachment
-    formData.append('inline', blob, attachment.filename);
+    // Mailgun gives an inline part the file name it is sent under as its
+    // Content-ID, so it goes under the ID the HTML refers to by cid:.
+    formData.append('inline', blob, attachment.contentId);
   } else {
     // Regular attachment
     formData.append('attachment', blob, attachment.filename);
diff --git a/tests/unit/mailgun.test.js b/tests/unit/mailgun.test.js
index 3413b5c..d5465ea 100644
--- a/tests/unit/mailgun.test.js
+++ b/tests/unit/mailgun.test.js
@@ -75,3 +75,25 @@ test('Mailgun: a display name with "<", "," or "@" stays a single mailbox', asyn
   });
   assert.deepStrictEqual(parsed.to, [{ address: 'bob@example.com', name }]);
 });
+
+test('Mailgun: an inline part goes under its Content-ID, which cid: refers to', async () => {
+  const withLogo = createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Logo',
+    content: { html: '<img src="cid:logo@example.com">' },
+    attachments: [
+      {
+        inline: true,
+        filename: 'logo.png',
+        content: new Uint8Array([1, 2, 3]),
+        contentType: 'image/png',
+        contentId: 'logo@example.com',
+      },
+    ],
+  });
+  const form = await convertMessage(withLogo, { domain: 'mg.example.com' });
+  const inline = form.getAll('inline');
+  assert.strictEqual(inline.length, 1);
+  assert.strictEqual(inline[0].name, 'logo@example.com');
+});

From edc36831c00312b03d3711a76d8f8eca6025f20c Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:50:35 +0300
Subject: [PATCH 150/158] fix(jmap): respect the maxSizeRequest of the server
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The maxSizeRequest of the Session (RFC 8620 §2) was not followed, so a
batch over it, or one message with a long body, was refused whole. A
batch goes in as many requests as the limit takes, grouped in order by
sizes measured once per message (groupBySize), each request failing on
its own; a message whose request alone is over the limit fails with
jmap.request_too_large and is not sent, in a batch or alone.

The budget of ./jmap goes from 11.5 to 12.5 KB: it was at its limit, and
onRetry and this fix add 0.4 KB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |   3 +
 CLAUDE.md                  |   6 +-
 docs/transports/jmap.md    |   4 +-
 scripts/size-budgets.json  |   2 +-
 src/jmap/jmap-transport.js | 177 ++++++++++++++++++++++++-------------
 tests/unit/jmap.test.js    |  64 ++++++++++++++
 6 files changed, 191 insertions(+), 65 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fe67d2d..310c1ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -221,6 +221,9 @@ fixed ones below.
 - **`./jmap` respects the `maxObjectsInSet` of the server in `sendMany`** (an upstream bug): it
   sent every message in one request, which a server with a lower limit refuses whole. It sends
   batches of at most that many messages, and a batch that fails fails only its own messages.
+- **`./jmap` respects the `maxSizeRequest` of the server** (an upstream bug): a batch goes in as
+  many requests as the limit takes, and a message whose request alone is over it fails with
+  `jmap.request_too_large` before anything is sent, where the server refused it whole.
 - **A configured name can no longer redirect a request** (an upstream bug): the SES `region` went
   into the host name as given, so `foo@evil.example/` sent the signed request, with its session
   token, to `evil.example`; the Mailgun `domain`, the Mailtrap `inboxId` and the JMAP account ID
diff --git a/CLAUDE.md b/CLAUDE.md
index 768f8ed..b282df9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -266,7 +266,7 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
 42. jmap: `sendMany` put every message into one Email/set and EmailSubmission/set, whatever
     the `maxObjectsInSet` of the Session, so a server with a limit refused the whole batch,
     and any failure failed every message. It sends batches of at most that many (`sendBatch`),
-    each failing on its own; discovery still runs once. `maxSizeRequest` is not yet followed.
+    each failing on its own; discovery still runs once. `maxSizeRequest` is 80.
 43. ses, mailgun, mailtrap, jmap: the SES `region` went into the host name unchecked
     (`foo@evil.example/` sent the signed request to `evil.example`), and the Mailgun `domain`,
     the Mailtrap `inboxId` and the JMAP `accountId` of a blob upload into the path unencoded.
@@ -402,6 +402,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     any text after it leaves the first line to itself.
 79. mailgun (known bug 2): an inline part was sent under its file name, which Mailgun makes its
     Content-ID, so the `cid:` of the HTML matched nothing. It goes under its `contentId`.
+80. jmap: the `maxSizeRequest` of the Session (RFC 8620 §2) was not followed, so a batch, or a
+    message with a long body, over it was refused whole. A batch goes in as many requests as
+    the limit takes (`groupBySize`, measured once per message), each failing on its own, and a
+    message whose request alone is over it fails with `jmap.request_too_large`, unsent.
 
 ## Repository layout
 
diff --git a/docs/transports/jmap.md b/docs/transports/jmap.md
index ba458dd..4317c02 100644
--- a/docs/transports/jmap.md
+++ b/docs/transports/jmap.md
@@ -191,7 +191,9 @@ for await (const receipt of transport.sendMany(messages)) {
 
 The `JmapTransport.sendMany()` method batches emails into JMAP requests of as
 many as the server's `maxObjectsInSet` allows, significantly reducing HTTP
-round-trips. It discovers the account, the drafts mailbox and the identities
+round-trips, and splits a batch further so that no request is over the
+server's `maxSizeRequest` (a message too large alone fails with
+`jmap.request_too_large`, unsent). It discovers the account, the drafts mailbox and the identities
 once, reads a batch of messages at a time as it sends them, and gives each
 message its own receipt: if some emails fail, others in the batch can still
 succeed.
diff --git a/scripts/size-budgets.json b/scripts/size-budgets.json
index 1e3e49f..3d31507 100644
--- a/scripts/size-budgets.json
+++ b/scripts/size-budgets.json
@@ -2,7 +2,7 @@
   ".": 8.5,
   "./mime": 7,
   "./smtp": 20,
-  "./jmap": 11.5,
+  "./jmap": 12.5,
   "./ses": 6,
   "./resend": 5.5,
   "./sendgrid": 5.5,
diff --git a/src/jmap/jmap-transport.js b/src/jmap/jmap-transport.js
index 8309c11..68efcfe 100644
--- a/src/jmap/jmap-transport.js
+++ b/src/jmap/jmap-transport.js
@@ -1,6 +1,7 @@
 // Ported from upyo v0.7.0 (packages/jmap/src/jmap-transport.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { Buffer } = require('node:buffer');
 const { combineSignals } = require('../core/abort-signal.js');
 const { createRawMessagePlan, RawMessageValidationError } = require('../core/raw-message.js');
 const { deliverRawMessage, rawDiscoveryResult } = require('./raw-delivery.js');
@@ -220,11 +221,18 @@ class JmapTransport {
       // Convert message and send
       const emailCreate = convertMessage(message, draftsMailboxId, uploadedBlobs);
 
-      // Execute Email/set + EmailSubmission/set batch request
+      // Execute Email/set + EmailSubmission/set batch request, unless it is
+      // larger than the server takes (RFC 8620 §2).
+      const request = submissionRequest(accountId, emailCreate, identityId);
+      const maxSizeRequest = getMaxSizeRequest(session);
+      if (maxSizeRequest !== Infinity) {
+        const size = Buffer.byteLength(JSON.stringify(request));
+        if (size > maxSizeRequest) return requestTooLarge(size, maxSizeRequest);
+      }
       const response = await executeSubmission(
         this.submissionClient,
         session.apiUrl,
-        submissionRequest(accountId, emailCreate, identityId),
+        request,
         signal,
       );
 
@@ -429,84 +437,60 @@ class JmapTransport {
     const { session, accountId, draftsMailboxId, identityMap } = discovered;
     let processingStage = 'attachment upload';
     let attachmentsUploadedCount = 0;
+    const emailCreates = [];
+    const submissionCreates = [];
     try {
       // Upload all attachments for all messages
-      const allUploadedBlobs = new Map();
+      const allUploadedBlobs = [];
       for (let i = 0; i < batch.length; i++) {
-        const uploadedBlobs = await this.uploadAttachments(
-          session,
-          accountId,
-          batch[i].attachments,
-          signal,
+        allUploadedBlobs.push(
+          await this.uploadAttachments(session, accountId, batch[i].attachments, signal),
         );
-        allUploadedBlobs.set(i, uploadedBlobs);
         attachmentsUploadedCount = i + 1;
         signal?.throwIfAborted();
       }
 
       // Build batch Email/set and EmailSubmission/set create objects
       processingStage = 'message conversion';
-      const emailCreates = {};
-      const submissionCreates = {};
-
       for (let i = 0; i < batch.length; i++) {
         const message = batch[i];
-        const emailCreate = convertMessage(message, draftsMailboxId, allUploadedBlobs.get(i));
-
+        emailCreates.push(convertMessage(message, draftsMailboxId, allUploadedBlobs[i]));
         // Find identity for this sender
         const senderEmail = message.sender.address.toLowerCase();
         const identityId = identityMap.get(senderEmail) ?? identityMap.values().next().value;
-
-        emailCreates[`draft${i}`] = emailCreate;
-        submissionCreates[`sub${i}`] = {
-          identityId,
-          emailId: `#draft${i}`,
-        };
+        submissionCreates.push({ identityId, emailId: `#draft${i}` });
       }
+    } catch (error) {
+      yield* this.failBatch(error, processingStage, batch.length, attachmentsUploadedCount, signal);
+      return;
+    }
 
-      // Execute batch request
-      processingStage = 'batch request execution';
-      const response = await executeSubmission(
-        this.submissionClient,
-        session.apiUrl,
-        {
-          using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.mail, JMAP_CAPABILITIES.submission],
-          methodCalls: [
-            [
-              'Email/set',
-              {
-                accountId,
-                create: emailCreates,
-              },
-              'c0',
-            ],
-            [
-              'EmailSubmission/set',
-              {
-                accountId,
-                create: submissionCreates,
-              },
-              'c1',
-            ],
-          ],
-        },
-        signal,
-      );
-
-      // The results of the sets are found once for the whole batch.
-      const results = setResultsOf(response);
-      for (let i = 0; i < batch.length; i++) {
-        yield this.parseBatchResponseForIndex(results, i);
+    // RFC 8620 §2: a request over the maxSizeRequest of the server is
+    // refused as a whole, so the batch goes in as many requests as it takes,
+    // each failing on its own.
+    const groups = groupBySize(
+      accountId,
+      emailCreates,
+      submissionCreates,
+      getMaxSizeRequest(session),
+    );
+    for (const group of groups) {
+      if (group.size !== undefined) {
+        yield requestTooLarge(group.size, getMaxSizeRequest(session));
+        continue;
       }
-    } catch (error) {
-      for (const failure of this.failBatch(
-        error,
-        processingStage,
-        batch.length,
-        attachmentsUploadedCount,
-        signal,
-      )) {
-        yield failure;
+      try {
+        const response = await executeSubmission(
+          this.submissionClient,
+          session.apiUrl,
+          batchRequest(accountId, group.indices, emailCreates, submissionCreates),
+          signal,
+        );
+        // The results of the sets are found once for the whole request.
+        const results = setResultsOf(response);
+        for (const i of group.indices) yield this.parseBatchResponseForIndex(results, i);
+      } catch (error) {
+        yield* this.failBatch(error, 'batch request execution', group.indices.length, 0, signal);
       }
     }
   }
@@ -1064,6 +1048,75 @@ const verificationOperation = async (timeout, operation, signal) => {
   }
 };
 
+const getMaxSizeRequest = (session) => {
+  const limit = session.capabilities?.[JMAP_CAPABILITIES.core]?.maxSizeRequest;
+  return Number.isInteger(limit) && limit > 0 ? limit : Infinity;
+};
+
+// The request that creates and submits the messages of a batch at `indices`,
+// each under the creation ids of its index in the batch.
+const batchRequest = (accountId, indices, emailCreates, submissionCreates) => {
+  const create = {};
+  const submit = {};
+  for (const i of indices) {
+    create[`draft${i}`] = emailCreates[i];
+    submit[`sub${i}`] = submissionCreates[i];
+  }
+  return {
+    using: REQUIRED_CAPABILITIES,
+    methodCalls: [
+      ['Email/set', { accountId, create }, 'c0'],
+      ['EmailSubmission/set', { accountId, create: submit }, 'c1'],
+    ],
+  };
+};
+
+/**
+ * Groups the messages of a batch, in order, into requests no larger than the
+ * limit.  The size of a request is that of the request without messages and
+ * of the entries of each, measured once.
+ *
+ * @returns Groups of `indices`, or a group with the `size` of the request of
+ * one message alone that is over the limit.
+ */
+const groupBySize = (accountId, emailCreates, submissionCreates, limit) => {
+  const all = [];
+  for (let i = 0; i < emailCreates.length; i++) all.push(i);
+  if (limit === Infinity) return [{ indices: all }];
+  const empty = Buffer.byteLength(JSON.stringify(batchRequest(accountId, [], [], [])));
+  const groups = [];
+  let indices = [];
+  let size = empty;
+  for (const i of all) {
+    const entries =
+      Buffer.byteLength(`"draft${i}":${JSON.stringify(emailCreates[i])}`) +
+      Buffer.byteLength(`"sub${i}":${JSON.stringify(submissionCreates[i])}`);
+    // A comma before each entry of the two creates but the first.
+    const added = entries + (indices.length > 0 ? 2 : 0);
+    if (indices.length > 0 && size + added > limit) {
+      groups.push({ indices });
+      indices = [];
+      size = empty;
+    }
+    if (empty + entries > limit) {
+      groups.push({ size: empty + entries });
+      continue;
+    }
+    size += indices.length > 0 ? entries + 2 : entries;
+    indices.push(i);
+  }
+  if (indices.length > 0) groups.push({ indices });
+  return groups;
+};
+
+// A message whose request alone is larger than the server takes.
+const requestTooLarge = (size, limit) =>
+  createJmapFailure(
+    `The JMAP request of ${size} bytes is larger than the server's maxSizeRequest of ${limit}.`,
+    undefined,
+    { category: 'rejected', code: 'jmap.request_too_large', retryable: false },
+  );
+
 const getMaxObjectsInSet = (session) => {
   const limit = session.capabilities?.[JMAP_CAPABILITIES.core]?.maxObjectsInSet;
   return Number.isInteger(limit) && limit > 0 ? limit : Infinity;
diff --git a/tests/unit/jmap.test.js b/tests/unit/jmap.test.js
index 2451801..2bcd8be 100644
--- a/tests/unit/jmap.test.js
+++ b/tests/unit/jmap.test.js
@@ -429,3 +429,67 @@ test('JMAP: a retried discovery request is told through onRetry', async (t) => {
   assert.strictEqual(events[0].attempt, 1);
   assert.strictEqual(events[0].error.statusCode, 503);
 });
+
+test('JMAP: a batch goes in requests within maxSizeRequest, a message too large alone fails', async (t) => {
+  const createdOf = (args) => {
+    const created = {};
+    for (const key in args.create) created[key] = { id: key, blobId: 'b', threadId: 't' };
+    return { created };
+  };
+  const run = async (maxSizeRequest, messages) => {
+    t.mock.restoreAll();
+    const core = maxSizeRequest === undefined ? {} : { maxSizeRequest };
+    serve(t, {
+      session: session({ capabilities: { [CORE]: core, [MAIL]: {}, [SUBMISSION]: {} } }),
+      'Email/set': createdOf,
+      'EmailSubmission/set': createdOf,
+    });
+    const served = globalThis.fetch;
+    const sizes = [];
+    t.mock.method(globalThis, 'fetch', async (input, init) => {
+      if (init?.body != null && String(init.body).includes('Email/set')) {
+        sizes.push(Buffer.byteLength(String(init.body)));
+      }
+      return served(input, init);
+    });
+    const receipts = [];
+    for await (const receipt of transport().sendMany(messages)) receipts.push(receipt);
+    return { receipts, sizes };
+  };
+  const five = [message(), message(), message(), message(), message()];
+  const whole = await run(undefined, five);
+  assert.strictEqual(whole.sizes.length, 1);
+
+  const limit = Math.ceil(whole.sizes[0] / 2);
+  const split = await run(limit, five);
+  assert.ok(split.sizes.length >= 2, String(split.sizes));
+  for (const size of split.sizes) assert.ok(size <= limit, `${size} > ${limit}`);
+  assert.deepStrictEqual(
+    split.receipts.map((receipt) => receipt.successful),
+    [true, true, true, true, true],
+  );
+
+  const large = createMessage({
+    from: 'alex@example.com',
+    to: 'bob@example.com',
+    subject: 'Large',
+    content: { text: 'x'.repeat(limit) },
+  });
+  const mixed = await run(limit, [message(), large, message()]);
+  assert.deepStrictEqual(
+    mixed.receipts.map((receipt) => receipt.successful || receipt.errors[0].code),
+    [true, 'jmap.request_too_large', true],
+  );
+  for (const size of mixed.sizes) assert.ok(size <= limit);
+
+  // A single send is refused before its request too.
+  t.mock.restoreAll();
+  const calls = serve(t, {
+    session: session({
+      capabilities: { [CORE]: { maxSizeRequest: limit }, [MAIL]: {}, [SUBMISSION]: {} },
+    }),
+  });
+  const receipt = await transport().send(large);
+  assert.strictEqual(receipt.errors[0].code, 'jmap.request_too_large');
+  assert.ok(!calls.includes('Email/set'));
+});

From 611e93fd908488f3d7e6c994750fdef4b8d872f1 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:53:28 +0300
Subject: [PATCH 151/158] fix(jmap): send requests and small raw messages from
 a buffer on Node 24

Node 24's fetch answers an early 401 to a streamed request body with
"fetch failed" (known upstream bug 14), so an authentication rejection
of the import, the submission or a raw upload became a retryable network
error. Requests go as a buffer: upstream streamed them against a replay
seen in Deno, and Node's fetch does not replay a POST whose connection
drops (checked against Node 24.14.1, undici 7.24.4). A raw message of a
known size up to 4 MiB is read into one buffer after validation; one of
unknown size still has to stream, and its test stays todo on Node 24.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  4 +
 CLAUDE.md                                     | 18 +++--
 docs/guide/known-issues.md                    |  6 +-
 src/jmap/http-client.js                       | 16 ++--
 src/jmap/raw-upload.js                        | 36 ++++++++-
 .../unit/jmap-raw-message.integration.test.js | 81 +++++++++----------
 6 files changed, 98 insertions(+), 63 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 310c1ad..9572883 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -221,6 +221,10 @@ fixed ones below.
 - **`./jmap` respects the `maxObjectsInSet` of the server in `sendMany`** (an upstream bug): it
   sent every message in one request, which a server with a lower limit refuses whole. It sends
   batches of at most that many messages, and a batch that fails fails only its own messages.
+- **`./jmap` on Node 24 tells an authentication rejection from a network failure** (an upstream
+  bug): the import, the submission and every raw upload went as a stream, which Node 24's
+  `fetch` answers with `fetch failed` instead of an early 401. Requests go as a buffer, and a raw
+  message of a known size up to 4 MiB is uploaded from one; one of unknown size still streams.
 - **`./jmap` respects the `maxSizeRequest` of the server** (an upstream bug): a batch goes in as
   many requests as the limit takes, and a message whose request alone is over it fails with
   `jmap.request_too_large` before anything is sent, where the server refused it whole.
diff --git a/CLAUDE.md b/CLAUDE.md
index b282df9..7b09261 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -154,10 +154,11 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 13. (fixed, see 78) mime: the first encoded word of a header shared its line with the field
     name (`Subject: =?UTF-8?B?…?=`, 84 characters), past the 76 that RFC 2047 allows a line
     with encoded words.
-14. jmap: on Node 24, `fetch` answers a 401 to a streamed request body (raw upload, import,
-    submission) with `TypeError: fetch failed` ("expected non-null body source") instead of the
-    response, so an authentication rejection becomes a retryable network error. Node 22 returns
-    the 401. The tests of it are `todo` on Node 24 until the fix.
+14. (mostly fixed, see 81) jmap: on Node 24, `fetch` answers a 401 to a streamed request body
+    with `TypeError: fetch failed` ("expected non-null body source") instead of the response,
+    so an authentication rejection becomes a retryable network error; Node 22 returns the 401.
+    Still open for a raw message of unknown size, which has to stream; its test is `todo` on
+    Node 24.
 
 **Upstream bugs found and fixed after the port** (each in its own `fix:` commit, with a test that
 fails without it; ported tests that pinned the old behavior say "Changed after the port"):
@@ -406,6 +407,11 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     message with a long body, over it was refused whole. A batch goes in as many requests as
     the limit takes (`groupBySize`, measured once per message), each failing on its own, and a
     message whose request alone is over it fails with `jmap.request_too_large`, unsent.
+81. jmap (known bug 14, Node 24): the import, the submission and every raw upload went as a
+    stream, which Node 24's fetch answers with a network failure instead of an early 401.
+    Requests go as a buffer (upstream streamed them against a replay seen in Deno; Node's fetch
+    does not replay a POST), and a raw message of a known size up to 4 MiB is read into one
+    buffer after validation (`bufferRawUpload`). A raw message of unknown size still streams.
 
 ## Repository layout
 
@@ -624,8 +630,8 @@ change. **This file wins** if they ever disagree.
   `MAILPIT_SMTP_HOST`/`MAILPIT_API_URL`) and `tests/e2e/` (`pnpm test:e2e`, each suite skipped
   until its provider's variables are set; Stalwart for JMAP in `tests/e2e/jmap/`).
 - **Platform-dependent tests:** the mock SMTP server tolerates a client's connection reset (macOS
-  and Windows send an RST where Linux sends a FIN); the seven JMAP tests of a 401 to a streamed
-  body are `todo` on Node 24 (known upstream bug 14). `tests/unit/export-parity.test.js` also
+  and Windows send an RST where Linux sends a FIN); the JMAP test of a 401 to a raw message of
+  unknown size, which streams, is `todo` on Node 24 (known upstream bug 14). `tests/unit/export-parity.test.js` also
   checks that every d.ts using `AsyncDisposable` references `esnext.disposable` itself.
 
 ## Documentation site
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index d09a206..e8fec2a 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -12,8 +12,10 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 
 - `validateSsl` is accepted and never read (SES, Resend, SendGrid, Mailgun, Mailtrap, Plunk).
 - SES: custom and threading headers are not sent.
-- JMAP on Node 24: an authentication rejection (401) of a streamed request body (raw upload,
-  import, raw submission) becomes a retryable network error, as Node's `fetch` reports it so.
+- JMAP on Node 24: an authentication rejection (401) during the upload of a raw message whose
+  size is not known ahead becomes a retryable network error, as Node's `fetch` reports an early
+  answer to a streamed body so. Requests, and raw messages of a known size up to 4 MiB, go from a
+  buffer and are not affected.
 
 ## Decorators
 
diff --git a/src/jmap/http-client.js b/src/jmap/http-client.js
index 5eecb52..70dc217 100644
--- a/src/jmap/http-client.js
+++ b/src/jmap/http-client.js
@@ -82,17 +82,11 @@ class JmapHttpClient {
           {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            // A stream prevents runtime-level replay of a POST after a lost
-            // response (observed with Deno even when application retries are 0).
-            body: this.replayableRequests
-              ? json
-              : new ReadableStream({
-                  start(controller) {
-                    controller.enqueue(Buffer.from(json));
-                    controller.close();
-                  },
-                }),
-            ...(this.replayableRequests ? {} : { duplex: 'half', redirect: 'error' }),
+            // Upstream streamed a request that must not be replayed, against a
+            // replay seen in Deno; Node's fetch does not replay a POST, and on
+            // Node 24 it reports a 401 to a streamed body as a network failure.
+            body: json,
+            ...(this.replayableRequests ? {} : { redirect: 'error' }),
           },
           attemptSignal,
         ),
diff --git a/src/jmap/raw-upload.js b/src/jmap/raw-upload.js
index bf9f3ca..9fc85e1 100644
--- a/src/jmap/raw-upload.js
+++ b/src/jmap/raw-upload.js
@@ -73,7 +73,10 @@ const uploadRawMessage = async (config, uploadUrl, accountId, plan, signal) => {
           ? await analyzeRawMessage(plan, outerSignal, progress)
           : { encoding: plan.encoding, size: plan.size };
       outerSignal.throwIfAborted();
-      const source = createRawUploadBody(plan, analysis, outerSignal, progress);
+      const source =
+        analysis.size !== undefined && analysis.size <= MAX_BUFFERED_UPLOAD_BYTES
+          ? await bufferRawUpload(plan, analysis, outerSignal, progress)
+          : createRawUploadBody(plan, analysis, outerSignal, progress);
       try {
         const response = await (config.fetch ?? globalThis.fetch)(
           uploadUrl.replace('{accountId}', encodeURIComponent(accountId)),
@@ -103,6 +106,37 @@ const uploadRawMessage = async (config, uploadUrl, accountId, plan, signal) => {
   );
 };
 
+// A raw message up to this size is uploaded from one buffer rather than a
+// stream: Node 24's fetch reports an early answer to a streamed body, such as
+// a 401, as a network failure, which a buffer avoids, at a bounded cost.
+const MAX_BUFFERED_UPLOAD_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Reads the validated bytes of a plan into one buffer, as an upload source of
+ * the shape of {@link createRawUploadBody}.
+ *
+ * @returns The `body`, its `state` (the source ended, its size) and a
+ * `dispose()` with nothing to do.
+ * @throws {Error} If the source fails or breaks the wire rules.
+ */
+const bufferRawUpload = async (plan, analysis, outerSignal, progress) => {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of iterateRawMessage(plan, {
+    signal: outerSignal,
+    encoding: analysis.encoding,
+    expectedSize: analysis.size,
+    onProgress: progress,
+  })) {
+    // A chunk stays valid only until the next read.
+    chunks.push(Buffer.from(chunk));
+    size += chunk.length;
+  }
+  progress();
+  const state = { eof: true, size, sourceError: undefined, hasSourceError: false };
+  return { body: Buffer.concat(chunks, size), state, dispose: () => {} };
+};
+
 /**
  * Gives the validated bytes of a plan as a request body that fetch pulls one
  * chunk at a time, under a signal of its own, so that reading the source stops
diff --git a/tests/unit/jmap-raw-message.integration.test.js b/tests/unit/jmap-raw-message.integration.test.js
index 8c44c3e..a5a67a9 100644
--- a/tests/unit/jmap-raw-message.integration.test.js
+++ b/tests/unit/jmap-raw-message.integration.test.js
@@ -544,9 +544,9 @@ for (const method of ['Mailbox/get', 'Identity/get']) {
 }
 
 // The fetch of Node 24 (undici) answers a 401 to a streamed request body with
-// "expected non-null body source" instead of the response, so the transport
-// reports a retryable network error (CLAUDE.md, known upstream bug 14). The
-// fix commit lifts the todo.
+// "expected non-null body source" instead of the response (CLAUDE.md, known
+// upstream bug 14). Requests and raw messages up to 4 MiB go from a buffer, so
+// only a raw message of unknown size, streamed, still meets it.
 const streamed401 =
   Number(process.versions.node.split('.')[0]) >= 24
     ? 'Node 24 fetch turns a 401 to a streamed body into a network error'
@@ -555,46 +555,41 @@ const streamed401 =
 for (const stage of ['upload', 'import', 'submission']) {
   for (const status of [401, 403, 429, 502]) {
     for (const body of ['', 'plain response']) {
-      const todo = status === 401 ? streamed401 : undefined;
-      test(
-        `JMAP raw ${stage} HTTP ${status} retains ${body ? 'text' : 'empty'} error metadata`,
-        { todo },
-        async () => {
-          const context = await setup({ httpError: { stage, status, body } });
-          try {
-            const receipt = await context.transport.sendRaw(raw);
-            assert.ok(!receipt.successful);
-            const auth = status === 401 || status === 403;
-            const unknown = stage === 'submission' && !auth;
-            assert.equal(receipt.retryable, stage !== 'submission' && !auth);
-            assert.equal(receipt.attempts, 1);
-            const error = receipt.errors?.[0];
-            assert.ok(error);
-            assert.equal(error.code, `jmap.raw_${stage}_${unknown ? 'unknown' : 'failed'}`);
-            assert.equal(error.statusCode, status);
-            assert.equal(error.retryAfterMilliseconds, 7000);
-            assert.deepEqual(error.providerDetails, {
-              responseBody: body,
-              jmapErrorType: undefined,
-            });
-            let category = status === 429 ? 'rate-limit' : 'server-error';
-            if (unknown) category = 'unknown';
-            else if (auth) category = 'auth';
-            assert.equal(error.category, category);
-            assert.equal(context.uploads.length, 1);
-            assert.equal(
-              context.calls.filter((c) => c.name === 'Email/import').length,
-              stage === 'upload' ? 0 : 1,
-            );
-            assert.equal(
-              context.calls.filter((c) => c.name === 'EmailSubmission/set').length,
-              stage === 'submission' ? 1 : 0,
-            );
-          } finally {
-            await context.close();
-          }
-        },
-      );
+      test(`JMAP raw ${stage} HTTP ${status} retains ${body ? 'text' : 'empty'} error metadata`, async () => {
+        const context = await setup({ httpError: { stage, status, body } });
+        try {
+          const receipt = await context.transport.sendRaw(raw);
+          assert.ok(!receipt.successful);
+          const auth = status === 401 || status === 403;
+          const unknown = stage === 'submission' && !auth;
+          assert.equal(receipt.retryable, stage !== 'submission' && !auth);
+          assert.equal(receipt.attempts, 1);
+          const error = receipt.errors?.[0];
+          assert.ok(error);
+          assert.equal(error.code, `jmap.raw_${stage}_${unknown ? 'unknown' : 'failed'}`);
+          assert.equal(error.statusCode, status);
+          assert.equal(error.retryAfterMilliseconds, 7000);
+          assert.deepEqual(error.providerDetails, {
+            responseBody: body,
+            jmapErrorType: undefined,
+          });
+          let category = status === 429 ? 'rate-limit' : 'server-error';
+          if (unknown) category = 'unknown';
+          else if (auth) category = 'auth';
+          assert.equal(error.category, category);
+          assert.equal(context.uploads.length, 1);
+          assert.equal(
+            context.calls.filter((c) => c.name === 'Email/import').length,
+            stage === 'upload' ? 0 : 1,
+          );
+          assert.equal(
+            context.calls.filter((c) => c.name === 'EmailSubmission/set').length,
+            stage === 'submission' ? 1 : 0,
+          );
+        } finally {
+          await context.close();
+        }
+      });
     }
   }
 }

From b004976e30b645e78127b2571a2432d02e01b7c7 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:55:36 +0300
Subject: [PATCH 152/158] fix(ses): send custom and threading header fields

Custom header fields and the threading ones were dropped (known upstream
bug 10), so a reply lost its place in the thread. SES v2 takes them in
the Headers of Simple content since March 2024: up to 15 fields of up to
996 characters, printable ASCII, without the fields SES sets itself.
They go there with those fields left out and a Latin-1 value in RFC 2047
encoded words; more fields, or a longer one, fail the send before any
request.

The budget of ./ses goes from 6 to 6.5 KB, as it reached 6.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                 |  3 ++
 CLAUDE.md                    |  8 +++-
 docs/guide/known-issues.md   |  1 -
 docs/transports/ses.md       |  7 ++++
 scripts/size-budgets.json    |  2 +-
 src/ses/message-converter.js | 77 ++++++++++++++++++++++++++++++++++++
 tests/unit/ses.test.js       | 38 ++++++++++++++++++
 7 files changed, 132 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9572883..bcd5d45 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -331,6 +331,9 @@ fixed ones below.
   error and `timeout after 5000ms` a `server-error`. It now gives the category of
   `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
   `aborted` for an `AbortError`, which upstream counted as `network`.
+- **`./ses` sends custom and threading header fields** (an upstream bug): they were dropped, so a
+  reply lost its place in the thread. They go in the `Headers` of the message, up to the 15 SES
+  takes; the fields SES sets itself are left out.
 - **`./mailgun` sends an inline part under its Content-ID** (an upstream bug): Mailgun makes the
   file name of an inline part its Content-ID, and the file name was sent, so a `cid:` in the
   HTML matched nothing.
diff --git a/CLAUDE.md b/CLAUDE.md
index 7b09261..0f2c0e7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -146,8 +146,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
    as a substring.
 9. (fixed, see 25 and 30) resend and plunk slept between retries without the `AbortSignal`;
    ses, resend, sendgrid, mailgun and plunk parsed `Retry-After` but did not wait for it.
-10. ses: custom and threading headers are not sent. (`convertMessagesToBulk`, which nothing
-    called, is removed.)
+10. (fixed, see 82) ses: custom and threading headers were not sent. (`convertMessagesToBulk`,
+    which nothing called, is removed.)
 11. (fixed, see 71) resend: the `Idempotency-Key` came from `Math.random`.
 12. (fixed, see 72 and 73) `console.warn` in mime (DKIM `send-unsigned`) and plunk instead of
     an injected logger.
@@ -412,6 +412,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     Requests go as a buffer (upstream streamed them against a replay seen in Deno; Node's fetch
     does not replay a POST), and a raw message of a known size up to 4 MiB is read into one
     buffer after validation (`bufferRawUpload`). A raw message of unknown size still streams.
+82. ses (known bug 10): custom header fields and the threading ones were not sent, so a reply
+    lost its place in the thread. They go in the `Headers` of Simple content (SES v2, up to 15
+    fields of 996 characters, the ones SES sets left out, values beyond ASCII as encoded words);
+    more fail the send before any request.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index e8fec2a..d25cdb6 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -11,7 +11,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 ## HTTP providers and JMAP
 
 - `validateSsl` is accepted and never read (SES, Resend, SendGrid, Mailgun, Mailtrap, Plunk).
-- SES: custom and threading headers are not sent.
 - JMAP on Node 24: an authentication rejection (401) during the upload of a raw message whose
   size is not known ahead becomes a retryable network error, as Node's `fetch` reports an early
   answer to a streamed body so. Requests, and raw messages of a known size up to 4 MiB, go from a
diff --git a/docs/transports/ses.md b/docs/transports/ses.md
index bf0da49..df341bd 100644
--- a/docs/transports/ses.md
+++ b/docs/transports/ses.md
@@ -230,6 +230,13 @@ Tags are particularly powerful in SES as they enable detailed tracking and
 analytics through CloudWatch metrics. You can set default tags at the transport
 level and additional tags per message for comprehensive categorization.
 
+Custom header fields and the threading fields (`inReplyTo`, `references`) go in
+the `Headers` of the message, which SES takes for up to 15 fields of up to 996
+characters each; a message with more fails before any request.  The fields SES
+sets itself (From, To, Cc, Bcc, Reply-To, Subject, Date, Message-ID,
+MIME-Version, Content-Type, Content-Disposition and Return-Path) are left out,
+and SES gives the message a Message-ID of its own.
+
 ## Bulk email sending
 
 For sending newsletters, notifications, or other bulk emails, the SES transport
diff --git a/scripts/size-budgets.json b/scripts/size-budgets.json
index 3d31507..2bf6d94 100644
--- a/scripts/size-budgets.json
+++ b/scripts/size-budgets.json
@@ -3,7 +3,7 @@
   "./mime": 7,
   "./smtp": 20,
   "./jmap": 12.5,
-  "./ses": 6,
+  "./ses": 6.5,
   "./resend": 5.5,
   "./sendgrid": 5.5,
   "./mailgun": 5.5,
diff --git a/src/ses/message-converter.js b/src/ses/message-converter.js
index 9834da8..271757e 100644
--- a/src/ses/message-converter.js
+++ b/src/ses/message-converter.js
@@ -1,15 +1,36 @@
 // Ported from upyo v0.7.0 (packages/ses/src/message-converter.ts)
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
+const { Buffer } = require('node:buffer');
 const { formatQuotedMailbox: formatAddress } = require('../core/address.js');
 const { readAttachmentContent } = require('../core/attachment.js');
 const { toBase64 } = require('../internal/base64.js');
 const {
   convertAttachments,
   formatAddresses,
+  visitCustomHeaders,
   withCalendarAttachment,
 } = require('../internal/provider.js');
 
+// The header fields SES sets itself and refuses in Headers, lower-cased.
+const SES_HEADERS = new Set([
+  'bcc',
+  'cc',
+  'content-disposition',
+  'content-type',
+  'date',
+  'from',
+  'message-id',
+  'mime-version',
+  'reply-to',
+  'return-path',
+  'subject',
+  'to',
+]);
+// The most fields SES takes in Headers, and the longest field it takes.
+const MAX_SES_HEADERS = 15;
+const MAX_SES_HEADER_LENGTH = 996;
+
 const convertMessage = async (message, config, signal) => {
   const destination = {};
 
@@ -94,6 +115,9 @@ const createSimpleContent = async (message, signal) => {
     };
   }
 
+  const headers = convertHeaders(message);
+  if (headers.length > 0) content.Headers = headers;
+
   const attachments = withCalendarAttachment(message);
 
   if (attachments.length > 0) {
@@ -103,6 +127,59 @@ const createSimpleContent = async (message, signal) => {
   return content;
 };
 
+/**
+ * The custom and threading header fields of a message as SES takes them in
+ * Headers: the fields it sets itself left out, a value outside printable
+ * ASCII in RFC 2047 encoded words.
+ *
+ * @param message The message being converted.
+ * @returns The fields, as `Name` and `Value`.
+ * @throws {RangeError} If there are more fields than SES takes, or one is
+ * longer than it takes.
+ */
+const convertHeaders = (message) => {
+  const headers = [];
+  visitCustomHeaders(
+    message,
+    (name) => SES_HEADERS.has(name.toLowerCase()),
+    (name, value) => {
+      if (value === '') return;
+      const encoded = encodeHeaderValue(value);
+      if (name.length + encoded.length > MAX_SES_HEADER_LENGTH) {
+        throw new RangeError(`SES takes a header field of at most 996 characters: ${name}`);
+      }
+      headers.push({ Name: name, Value: encoded });
+    },
+  );
+  if (headers.length > MAX_SES_HEADERS) {
+    throw new RangeError(
+      `SES takes at most ${MAX_SES_HEADERS} custom header fields, and the message has ${headers.length}.`,
+    );
+  }
+  return headers;
+};
+
+// A value of Latin-1 text, as a Headers object holds it, in encoded words of
+// at most 45 bytes of UTF-8 each when it is not printable ASCII.
+const encodeHeaderValue = (value) => {
+  if (/^[ -~]*$/.test(value)) return value;
+  let encoded = '';
+  let start = 0;
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    const length = value.charCodeAt(i) < 0x80 ? 1 : 2;
+    if (bytes + length > 45) {
+      encoded += `${encoded === '' ? '' : ' '}${encodeWord(value.slice(start, i))}`;
+      start = i;
+      bytes = 0;
+    }
+    bytes += length;
+  }
+  return `${encoded === '' ? '' : `${encoded} `}${encodeWord(value.slice(start))}`;
+};
+
+const encodeWord = (text) => `=?UTF-8?B?${Buffer.from(text, 'utf8').toString('base64')}?=`;
+
 const convertAttachment = async (attachment, signal) => {
   const contentBytes = await readAttachmentContent(attachment.content, signal);
   const converted = {
diff --git a/tests/unit/ses.test.js b/tests/unit/ses.test.js
index dd39d06..77c5bff 100644
--- a/tests/unit/ses.test.js
+++ b/tests/unit/ses.test.js
@@ -237,3 +237,41 @@ test('SES: sendMany reads a batch at a time, not its whole input first', async (
   }
   assert.strictEqual(input.read, 2);
 });
+
+test('SES: custom and threading header fields go in Headers, those SES sets left out', async () => {
+  const config = createSesConfig({ authentication });
+  const converted = await convertMessage(
+    message({
+      headers: {
+        'X-Campaign': 'spring',
+        'X-Label': 'Café crème',
+        'Return-Path': 'bounce@example.com',
+        'X-Empty': '',
+      },
+      inReplyTo: '<parent@example.com>',
+    }),
+    config,
+  );
+  assert.deepStrictEqual(converted.Content.Simple.Headers, [
+    { Name: 'x-campaign', Value: 'spring' },
+    { Name: 'x-label', Value: `=?UTF-8?B?${Buffer.from('Café crème').toString('base64')}?=` },
+    { Name: 'In-Reply-To', Value: '<parent@example.com>' },
+  ]);
+  const plain = await convertMessage(message(), config);
+  assert.strictEqual(plain.Content.Simple.Headers, undefined);
+});
+
+test('SES: more header fields than SES takes fail the send before any request', async (t) => {
+  let requests = 0;
+  await withFetch(t, async () => {
+    requests++;
+    return new Response('{"MessageId":"m1"}', { status: 200 });
+  });
+  const headers = {};
+  for (let index = 0; index < 16; index++) headers[`X-Field-${index}`] = 'value';
+  const transport = new SesTransport({ authentication, retries: 0 });
+  const receipt = await transport.send(message({ headers }));
+  assert.strictEqual(receipt.successful, false);
+  assert.match(receipt.errorMessages[0], /at most 15 custom header fields/);
+  assert.strictEqual(requests, 0);
+});

From 3263056ab10dd9bc51feb03f3610da4f073eaaf2 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 21:58:51 +0300
Subject: [PATCH 153/158] fix(smtp)!: drop cram-md5 and refuse an unknown AUTH
 method when made

cram-md5 was a method of the SmtpAuth type of upstream (known bug 5) and
failed at the first send, as any method the connection did not know.
It is removed from the type, as the user decided: CRAM-MD5 is obsolete,
its server keeps a password equivalent, and AUTH goes over TLS here
anyway. SmtpTransport now refuses an unknown method, or one of the other
kind of credentials, with a TypeError when it is made (checkAuthMethod).
The docs no longer say a password's method is detected: it is PLAIN.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  3 +++
 CLAUDE.md                  |  6 +++++-
 docs/guide/known-issues.md |  4 ----
 docs/transports/smtp.md    |  7 ++++---
 src/smtp/config.js         | 17 ++++++++++++++++-
 src/smtp/index.d.ts        |  6 +++---
 src/smtp/smtp-transport.js |  2 ++
 tests/types/smtp.test-d.ts |  7 +++++++
 tests/unit/smtp.test.js    | 30 +++++++++++++++++-------------
 9 files changed, 57 insertions(+), 25 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bcd5d45..51f94a4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -331,6 +331,9 @@ fixed ones below.
   error and `timeout after 5000ms` a `server-error`. It now gives the category of
   `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
   `aborted` for an `AbortError`, which upstream counted as `network`.
+- **`./smtp` refuses an authentication method it does not have when it is made** (an upstream
+  bug): `cram-md5` was in the type and failed at the first send. It is gone from the type, and an
+  unknown `method` throws a `TypeError` from the constructor.
 - **`./ses` sends custom and threading header fields** (an upstream bug): they were dropped, so a
   reply lost its place in the thread. They go in the `Headers` of the message, up to the 15 SES
   takes; the fields SES sets itself are left out.
diff --git a/CLAUDE.md b/CLAUDE.md
index 0f2c0e7..b692c9a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -136,7 +136,7 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 3. `validateSsl` is accepted and never read (ses, resend, sendgrid, mailgun, mailtrap, plunk).
 4. (fixed, see 38) SMTP AUTH PLAIN and LOGIN encoded with `btoa`, which fails on non-Latin-1
    credentials; so did Basic auth in jmap and mailgun.
-5. `cram-md5` is in the `SmtpAuth` type but not implemented.
+5. (fixed, see 83) `cram-md5` was in the `SmtpAuth` type but not implemented.
 6. (fixed, see 63) DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) was imported as PKCS#8 and
    failed.
 7. pool: `continueOnSuccess` is never read.
@@ -416,6 +416,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     lost its place in the thread. They go in the `Headers` of Simple content (SES v2, up to 15
     fields of 996 characters, the ones SES sets left out, values beyond ASCII as encoded words);
     more fail the send before any request.
+83. smtp (known bug 5): `cram-md5` was a `method` of the type and failed at the first send, as
+    did any method the connection did not know. It is gone from the type (an obsolete mechanism
+    whose server keeps a password equivalent, where AUTH goes over TLS anyway), and
+    `SmtpTransport` refuses an unknown method when it is made (`checkAuthMethod`).
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index d25cdb6..9ed5ab2 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -4,10 +4,6 @@ The transport layer is ported from [upyo](https://github.com/dahlia/upyo) 0.7.0
 behavior, bugs included, until each bug is fixed on its own with a test. This page lists the ones
 still open; the fixed ones are in the [changelog](https://github.com/Alexis-Technologies/mailer/blob/main/CHANGELOG.md).
 
-## SMTP
-
-- `cram-md5` is in the `SmtpAuth` type but not implemented.
-
 ## HTTP providers and JMAP
 
 - `validateSsl` is accepted and never read (SES, Resend, SendGrid, Mailgun, Mailtrap, Plunk).
diff --git a/docs/transports/smtp.md b/docs/transports/smtp.md
index 4b28f2a..e4af661 100644
--- a/docs/transports/smtp.md
+++ b/docs/transports/smtp.md
@@ -518,9 +518,10 @@ const outlookTransport = new SmtpTransport({
 ```
 
 When using services like Gmail, you'll need to generate an app-specific password
-rather than using your regular account password.  The transport automatically
-detects server capabilities and chooses the appropriate authentication method
-if you don't specify one.
+rather than using your regular account password.  Without `method`, a password
+signs in with PLAIN, and OAuth 2.0 credentials with XOAUTH2 when the server
+offers it, OAUTHBEARER otherwise.  CRAM-MD5 is not supported, and a method the
+transport does not know is refused when the transport is made.
 
 > [!IMPORTANT]
 > SMTP authentication requires a secure connection (`secure: true`, or a
diff --git a/src/smtp/config.js b/src/smtp/config.js
index 3cbaabb..be4e4b8 100644
--- a/src/smtp/config.js
+++ b/src/smtp/config.js
@@ -16,6 +16,7 @@ const { checkDkimConfig } = require('../mime/dkim/types.js');
  */
 const createSmtpConfig = (config) => {
   checkDkimConfig(config.dkim);
+  checkAuthMethod(config.auth);
   const port = config.port ?? 587;
 
   return {
@@ -37,4 +38,18 @@ const createSmtpConfig = (config) => {
   };
 };
 
-module.exports = { createSmtpConfig };
+// The mechanisms of each kind of credentials; an unknown one is refused when
+// the transport is made rather than at the first send.
+const PASSWORD_METHODS = new Set(['plain', 'login']);
+const OAUTH2_METHODS = new Set(['xoauth2', 'oauthbearer']);
+
+const checkAuthMethod = (auth) => {
+  if (auth?.method == null) return;
+  const methods =
+    'accessToken' in auth || 'refreshToken' in auth ? OAUTH2_METHODS : PASSWORD_METHODS;
+  if (!methods.has(auth.method)) {
+    throw new TypeError(`Unsupported authentication method: ${auth.method}`);
+  }
+};
+
+module.exports = { checkAuthMethod, createSmtpConfig };
diff --git a/src/smtp/index.d.ts b/src/smtp/index.d.ts
index 5f56a1e..6021d3d 100644
--- a/src/smtp/index.d.ts
+++ b/src/smtp/index.d.ts
@@ -138,7 +138,7 @@ export interface SmtpConfig extends TransportDependencies {
  * const passwordAuth: SmtpAuth = {
  *   user: 'username@domain.com',
  *   pass: 'password',
- *   method: 'plain' // or 'login', 'cram-md5'
+ *   method: 'plain' // or 'login'
  * };
  *
  * // OAuth 2.0 with a (possibly refreshing) access token
@@ -173,7 +173,7 @@ export type OAuth2TokenProvider = (signal?: AbortSignal) => string | Promise<str
  * const auth: SmtpUserPassAuth = {
  *   user: 'username@domain.com',
  *   pass: 'password',
- *   method: 'plain' // or 'login', 'cram-md5'
+ *   method: 'plain' // or 'login'
  * };
  * ```
  */
@@ -190,7 +190,7 @@ export interface SmtpUserPassAuth {
    * Authentication method.
    * @default "plain"
    */
-  readonly method?: 'plain' | 'login' | 'cram-md5';
+  readonly method?: 'plain' | 'login';
 }
 /**
  * OAuth 2.0 authentication configuration using a directly supplied access
diff --git a/src/smtp/smtp-transport.js b/src/smtp/smtp-transport.js
index c3cb519..072ee02 100644
--- a/src/smtp/smtp-transport.js
+++ b/src/smtp/smtp-transport.js
@@ -23,6 +23,7 @@ const { SmtpAttachmentReplayError } = require('./message-stream.js');
 const { SmtpDeliveryUnknownError } = require('./data-stream.js');
 const { checkDkimConfig } = require('../mime/dkim/types.js');
 const { checkDkimKeys } = require('../mime/dkim/sign.js');
+const { checkAuthMethod } = require('./config.js');
 const { parseEnhancedSmtpStatusCode } = require('./smtp-status-code.js');
 const { TLSSocket } = require('node:tls');
 const { warnDegradation } = require('../internal/log.js');
@@ -126,6 +127,7 @@ class SmtpTransport {
   constructor(config) {
     checkDkimConfig(config.dkim);
     checkDkimKeys(config.dkim);
+    checkAuthMethod(config.auth);
     this.config = config;
     const poolSize = config.poolSize ?? 5;
     if (
diff --git a/tests/types/smtp.test-d.ts b/tests/types/smtp.test-d.ts
index 5c83bcd..e8bf2b1 100644
--- a/tests/types/smtp.test-d.ts
+++ b/tests/types/smtp.test-d.ts
@@ -20,6 +20,13 @@ const transport = new SmtpTransport({
   tls: { rejectUnauthorized: true, minVersion: 'TLSv1.2' },
 });
 expectAssignable<RawTransport<'smtp'>>(transport);
+// cram-md5 was never implemented, and is not a method.
+expectError(
+  new SmtpTransport({
+    host: 'smtp.example.com',
+    auth: { user: 'a', pass: 'b', method: 'cram-md5' },
+  }),
+);
 expectAssignable<VerifiableTransport<'smtp'>>(transport);
 expectAssignable<AsyncDisposable>(transport);
 
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index acbcc22..6d3a481 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -208,20 +208,24 @@ test('SMTP: AUTH LOGIN rejected at the method or at the user name', async () =>
   }
 });
 
-test('SMTP: an unsupported AUTH method fails the send', async () => {
-  const server = new MockSmtpServer();
-  const port = await server.start();
-  server.setCapabilities(['AUTH PLAIN LOGIN CRAM-MD5']);
-  try {
-    const transport = new SmtpTransport({
-      host: 'localhost',
-      port,
-      pool: false,
-      auth: { user: 'alex', pass: 'secret', method: 'cram-md5' },
+test('SMTP: an unsupported AUTH method is refused when the transport is made', () => {
+  // cram-md5 was in the type of upstream and never implemented.
+  for (const auth of [
+    { user: 'alex', pass: 'secret', method: 'cram-md5' },
+    { user: 'alex', pass: 'secret', method: 'xoauth2' },
+    { user: 'alex', accessToken: 'token', method: 'plain' },
+  ]) {
+    assert.throws(() => new SmtpTransport({ host: 'localhost', auth }), {
+      name: 'TypeError',
+      message: `Unsupported authentication method: ${auth.method}`,
     });
-    assert.match(await failureOf(transport), /Unsupported authentication method: cram-md5/);
-  } finally {
-    await server.stop();
+  }
+  for (const auth of [
+    { user: 'alex', pass: 'secret', method: 'login' },
+    { user: 'alex', accessToken: 'token', method: 'oauthbearer' },
+    { user: 'alex', pass: 'secret' },
+  ]) {
+    assert.ok(new SmtpTransport({ host: 'localhost', auth }));
   }
 });
 

From a6a2bd8d88241eb3ec220207826e5b141f189b6d Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 22:01:31 +0300
Subject: [PATCH 154/158] fix: refuse validateSsl false, which fetch cannot
 honor

ses, resend, sendgrid, mailgun, mailtrap and plunk accepted validateSsl
and never read it (known upstream bug 3), so a caller who set it to
false believed certificates went unchecked. Node's fetch checks every
certificate and has no switch for it without undici, so false now throws
a TypeError that points to a fetch of the caller's own with an undici
dispatcher, as the user decided; true or absent change nothing. The
check sits in internal/validate-ssl.js, so the other providers do not
bundle it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                       |  4 ++++
 CLAUDE.md                          |  9 +++++++--
 docs/guide/known-issues.md         |  1 -
 docs/transports/ses.md             | 16 +++++++++++++++-
 src/internal/validate-ssl.js       | 21 +++++++++++++++++++++
 src/mailgun/config.js              |  4 +++-
 src/mailgun/index.d.ts             |  4 +++-
 src/mailtrap/config.js             |  4 +++-
 src/mailtrap/index.d.ts            |  4 +++-
 src/plunk/config.js                |  4 +++-
 src/plunk/index.d.ts               |  4 +++-
 src/resend/config.js               |  4 +++-
 src/resend/index.d.ts              |  4 +++-
 src/sendgrid/config.js             |  4 +++-
 src/sendgrid/index.d.ts            |  4 +++-
 src/ses/config.js                  |  4 +++-
 src/ses/index.d.ts                 |  5 ++++-
 tests/unit/internal.test.js        | 22 ++++++++++++++++++++++
 tests/unit/mailgun-config.test.js  |  6 ++++--
 tests/unit/plunk-config.test.js    |  6 ++++--
 tests/unit/resend-config.test.js   |  6 ++++--
 tests/unit/sendgrid-config.test.js |  6 ++++--
 tests/unit/ses-config.test.js      |  6 ++++--
 23 files changed, 126 insertions(+), 26 deletions(-)
 create mode 100644 src/internal/validate-ssl.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 51f94a4..aef4d93 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -331,6 +331,10 @@ fixed ones below.
   error and `timeout after 5000ms` a `server-error`. It now gives the category of
   `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
   `aborted` for an `AbortError`, which upstream counted as `network`.
+- **`validateSsl: false` throws instead of being ignored** (an upstream bug, `./ses`, `./resend`,
+  `./sendgrid`, `./mailgun`, `./mailtrap`, `./plunk`): `fetch` checks every certificate, so the
+  option never did anything. `false` now throws a `TypeError` that suggests a `fetch` of your
+  own with an undici dispatcher for a test server.
 - **`./smtp` refuses an authentication method it does not have when it is made** (an upstream
   bug): `cram-md5` was in the type and failed at the first send. It is gone from the type, and an
   unknown `method` throws a `TypeError` from the constructor.
diff --git a/CLAUDE.md b/CLAUDE.md
index b692c9a..6962009 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -133,7 +133,8 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
    `multipart/related`.
 2. (fixed, see 79) mailgun: an inline attachment was sent under its `filename`, not its
    `contentId` (`message-converter.js`), so a `cid:` in the HTML did not match it.
-3. `validateSsl` is accepted and never read (ses, resend, sendgrid, mailgun, mailtrap, plunk).
+3. (fixed, see 84) `validateSsl` was accepted and never read (ses, resend, sendgrid, mailgun,
+   mailtrap, plunk).
 4. (fixed, see 38) SMTP AUTH PLAIN and LOGIN encoded with `btoa`, which fails on non-Latin-1
    credentials; so did Basic auth in jmap and mailgun.
 5. (fixed, see 83) `cram-md5` was in the `SmtpAuth` type but not implemented.
@@ -420,6 +421,10 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     did any method the connection did not know. It is gone from the type (an obsolete mechanism
     whose server keeps a password equivalent, where AUTH goes over TLS anyway), and
     `SmtpTransport` refuses an unknown method when it is made (`checkAuthMethod`).
+84. ses, resend, sendgrid, mailgun, mailtrap, plunk (known bug 3): `validateSsl: false` was
+    accepted and ignored, so a caller believed certificates went unchecked. Node's fetch has no
+    switch for it without undici, so `false` throws a `TypeError` that points to a `fetch` of
+    the caller's own (`checkValidateSsl`); true or absent changes nothing.
 
 ## Repository layout
 
@@ -432,7 +437,7 @@ src/
   internal/         private modules shared by subpaths, not in the exports map (redact.js,
                     redact-addresses.js, unsent.js, delivery-unknown.js, http.js,
                     config.js, loopback.js, body.js, sleep.js, log.js, base64.js,
-                    headers.js, provider.js, batch.js)
+                    headers.js, provider.js, batch.js, validate-ssl.js)
 tests/
   unit/*.test.js    node:test suites, one per area (<subpath>-<module>.test.js for a subpath)
   helpers/<sub>/    shared test code of a subpath (fake servers, fixtures builders)
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index 9ed5ab2..d3f9857 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -6,7 +6,6 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
 
 ## HTTP providers and JMAP
 
-- `validateSsl` is accepted and never read (SES, Resend, SendGrid, Mailgun, Mailtrap, Plunk).
 - JMAP on Node 24: an authentication rejection (401) during the upload of a raw message whose
   size is not known ahead becomes a retryable network error, as Node's `fetch` reports an early
   answer to a streamed body so. Requests, and raw messages of a known size up to 4 MiB, go from a
diff --git a/docs/transports/ses.md b/docs/transports/ses.md
index df341bd..e29ae86 100644
--- a/docs/transports/ses.md
+++ b/docs/transports/ses.md
@@ -405,7 +405,21 @@ const testTransport = new SesTransport({
   region: process.env.SES_TEST_REGION ?? 'us-east-1',
   timeout: 10000,
   retries: 1, // Fewer retries for faster test execution
-  validateSsl: false, // For testing with local endpoints
+});
+```
+
+`validateSsl: false` throws a `TypeError`, as `fetch` checks every
+certificate.  To reach a local endpoint with a self-signed certificate, pass a
+`fetch` of your own whose undici dispatcher skips the check:
+
+```js
+// @noErrors
+const { Agent, fetch } = require('undici');
+
+const insecure = new Agent({ connect: { rejectUnauthorized: false } });
+const localTransport = new SesTransport({
+  authentication: { type: 'credentials', accessKeyId: 'test', secretAccessKey: 'test' },
+  fetch: (url, init) => fetch(url, { ...init, dispatcher: insecure }),
 });
 ```
 
diff --git a/src/internal/validate-ssl.js b/src/internal/validate-ssl.js
new file mode 100644
index 0000000..9533298
--- /dev/null
+++ b/src/internal/validate-ssl.js
@@ -0,0 +1,21 @@
+// Not ported from upyo: the check of `validateSsl`, in a module of its own so
+// that only the providers that take the option bundle it.
+
+/**
+ * Checks `validateSsl`, which the global fetch cannot honor when false: it
+ * checks every certificate, and Node gives no switch for it without undici.
+ *
+ * @param validateSsl The option, as configured.
+ * @throws {TypeError} If it is anything but true or absent.
+ * @internal
+ */
+const checkValidateSsl = (validateSsl) => {
+  if (validateSsl === undefined || validateSsl === true) return;
+  throw new TypeError(
+    '`validateSsl: false` cannot be honored, as fetch checks every certificate; for a test ' +
+      'server, pass a `fetch` of your own whose undici dispatcher does not, such as an Agent ' +
+      'with `connect: { rejectUnauthorized: false }`.',
+  );
+};
+
+module.exports = { checkValidateSsl };
diff --git a/src/mailgun/config.js b/src/mailgun/config.js
index 5f34f6b..610265d 100644
--- a/src/mailgun/config.js
+++ b/src/mailgun/config.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
+const { checkValidateSsl } = require('../internal/validate-ssl.js');
 
 /**
  * Creates a resolved Mailgun configuration by applying default values to optional fields.
@@ -15,6 +16,7 @@ const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../in
  * @internal
  */
 const createMailgunConfig = (config) => {
+  checkValidateSsl(config.validateSsl);
   const region = config.region ?? 'us';
   const baseUrl = config.baseUrl ?? getDefaultBaseUrl(region);
 
@@ -29,7 +31,7 @@ const createMailgunConfig = (config) => {
     logger: config.logger,
     retries: config.retries ?? 3,
     concurrency: config.concurrency ?? 1,
-    validateSsl: config.validateSsl ?? true,
+    validateSsl: true,
     headers: config.headers ?? {},
     tracking: config.tracking ?? true,
     clickTracking: config.clickTracking ?? true,
diff --git a/src/mailgun/index.d.ts b/src/mailgun/index.d.ts
index b3a790a..65a085c 100644
--- a/src/mailgun/index.d.ts
+++ b/src/mailgun/index.d.ts
@@ -76,7 +76,9 @@ export interface MailgunConfig extends TransportDependencies {
    */
   readonly concurrency?: number;
   /**
-   * Whether to validate SSL certificates.
+   * Must be true or left out: fetch checks every certificate, and `false`
+   * throws a `TypeError`.  For a test server with a self-signed certificate,
+   * pass a `fetch` whose undici dispatcher skips the check.
    *
    * @default true
    */
diff --git a/src/mailtrap/config.js b/src/mailtrap/config.js
index 0a46dde..e79cfb3 100644
--- a/src/mailtrap/config.js
+++ b/src/mailtrap/config.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
+const { checkValidateSsl } = require('../internal/validate-ssl.js');
 
 const DEFAULT_SEND_BASE_URL = 'https://send.api.mailtrap.io';
 const DEFAULT_SANDBOX_BASE_URL = 'https://sandbox.api.mailtrap.io';
@@ -16,6 +17,7 @@ const DEFAULT_USER_AGENT = '@alexify/mailer/mailtrap';
  * @throws {RangeError} If `sandbox` is `true` and `inboxId` is missing.
  */
 const createMailtrapConfig = (config) => {
+  checkValidateSsl(config.validateSsl);
   const sandbox = config.sandbox ?? false;
 
   if (sandbox && !isValidInboxId(config.inboxId)) {
@@ -36,7 +38,7 @@ const createMailtrapConfig = (config) => {
     generateId: config.generateId,
     logger: config.logger,
     retries: config.retries ?? 3,
-    validateSsl: config.validateSsl ?? true,
+    validateSsl: true,
     headers: config.headers == null ? {} : { ...config.headers },
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
diff --git a/src/mailtrap/index.d.ts b/src/mailtrap/index.d.ts
index f43f7ec..3c8c91e 100644
--- a/src/mailtrap/index.d.ts
+++ b/src/mailtrap/index.d.ts
@@ -87,7 +87,9 @@ export interface MailtrapConfig extends TransportDependencies {
    */
   readonly retries?: number;
   /**
-   * Whether to validate SSL certificates.
+   * Must be true or left out: fetch checks every certificate, and `false`
+   * throws a `TypeError`.  For a test server with a self-signed certificate,
+   * pass a `fetch` whose undici dispatcher skips the check.
    *
    * @default true
    */
diff --git a/src/plunk/config.js b/src/plunk/config.js
index 3318937..daaa2f9 100644
--- a/src/plunk/config.js
+++ b/src/plunk/config.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
+const { checkValidateSsl } = require('../internal/validate-ssl.js');
 
 /**
  * Creates a resolved Plunk configuration by applying default values to optional fields.
@@ -15,6 +16,7 @@ const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../in
  * @internal
  */
 const createPlunkConfig = (config) => {
+  checkValidateSsl(config.validateSsl);
   const resolved = {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? 'https://next-api.useplunk.com',
@@ -24,7 +26,7 @@ const createPlunkConfig = (config) => {
     logger: config.logger,
     retries: config.retries ?? 3,
     concurrency: config.concurrency ?? 1,
-    validateSsl: config.validateSsl ?? true,
+    validateSsl: true,
     headers: config.headers ?? {},
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
diff --git a/src/plunk/index.d.ts b/src/plunk/index.d.ts
index 05955b8..ce05428 100644
--- a/src/plunk/index.d.ts
+++ b/src/plunk/index.d.ts
@@ -66,7 +66,9 @@ export interface PlunkConfig extends TransportDependencies {
    */
   readonly concurrency?: number;
   /**
-   * Whether to validate SSL certificates.
+   * Must be true or left out: fetch checks every certificate, and `false`
+   * throws a `TypeError`.  For a test server with a self-signed certificate,
+   * pass a `fetch` whose undici dispatcher skips the check.
    *
    * @default true
    */
diff --git a/src/resend/config.js b/src/resend/config.js
index ecb2ba1..f25635b 100644
--- a/src/resend/config.js
+++ b/src/resend/config.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
+const { checkValidateSsl } = require('../internal/validate-ssl.js');
 
 /**
  * Creates a resolved Resend configuration by applying default values to optional fields.
@@ -15,6 +16,7 @@ const { checkRequestOptions, checkSecureUrl } = require('../internal/config.js')
  * @internal
  */
 const createResendConfig = (config) => {
+  checkValidateSsl(config.validateSsl);
   const resolved = {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? 'https://api.resend.com',
@@ -23,7 +25,7 @@ const createResendConfig = (config) => {
     generateId: config.generateId,
     logger: config.logger,
     retries: config.retries ?? 3,
-    validateSsl: config.validateSsl ?? true,
+    validateSsl: true,
     headers: config.headers ?? {},
   };
   checkRequestOptions(resolved.timeout, resolved.retries);
diff --git a/src/resend/index.d.ts b/src/resend/index.d.ts
index c77381c..e535e51 100644
--- a/src/resend/index.d.ts
+++ b/src/resend/index.d.ts
@@ -52,7 +52,9 @@ export interface ResendConfig extends TransportDependencies {
    */
   readonly retries?: number;
   /**
-   * Whether to validate SSL certificates.
+   * Must be true or left out: fetch checks every certificate, and `false`
+   * throws a `TypeError`.  For a test server with a self-signed certificate,
+   * pass a `fetch` whose undici dispatcher skips the check.
    *
    * @default true
    */
diff --git a/src/sendgrid/config.js b/src/sendgrid/config.js
index 8032b73..659087b 100644
--- a/src/sendgrid/config.js
+++ b/src/sendgrid/config.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../internal/config.js');
+const { checkValidateSsl } = require('../internal/validate-ssl.js');
 
 /**
  * Creates a resolved SendGrid configuration by applying default values to optional fields.
@@ -15,6 +16,7 @@ const { checkConcurrency, checkRequestOptions, checkSecureUrl } = require('../in
  * @internal
  */
 const createSendGridConfig = (config) => {
+  checkValidateSsl(config.validateSsl);
   const resolved = {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl ?? 'https://api.sendgrid.com/v3',
@@ -24,7 +26,7 @@ const createSendGridConfig = (config) => {
     logger: config.logger,
     retries: config.retries ?? 3,
     concurrency: config.concurrency ?? 1,
-    validateSsl: config.validateSsl ?? true,
+    validateSsl: true,
     headers: config.headers ?? {},
     clickTracking: config.clickTracking ?? true,
     openTracking: config.openTracking ?? true,
diff --git a/src/sendgrid/index.d.ts b/src/sendgrid/index.d.ts
index e17e64f..c898608 100644
--- a/src/sendgrid/index.d.ts
+++ b/src/sendgrid/index.d.ts
@@ -61,7 +61,9 @@ export interface SendGridConfig extends TransportDependencies {
    */
   readonly concurrency?: number;
   /**
-   * Whether to validate SSL certificates.
+   * Must be true or left out: fetch checks every certificate, and `false`
+   * throws a `TypeError`.  For a test server with a self-signed certificate,
+   * pass a `fetch` whose undici dispatcher skips the check.
    *
    * @default true
    */
diff --git a/src/ses/config.js b/src/ses/config.js
index b29e69d..d8944ec 100644
--- a/src/ses/config.js
+++ b/src/ses/config.js
@@ -2,6 +2,7 @@
 // https://github.com/dahlia/upyo — MIT, Copyright 2025 Hong Minhee
 
 const { checkRequestOptions } = require('../internal/config.js');
+const { checkValidateSsl } = require('../internal/validate-ssl.js');
 
 /**
  * Creates a resolved SES configuration with default values applied.
@@ -32,6 +33,7 @@ const { checkRequestOptions } = require('../internal/config.js');
 const AWS_REGION = /^[a-z]{2}(?:-[a-z]+)+-\d+$/;
 
 const createSesConfig = (config) => {
+  checkValidateSsl(config.validateSsl);
   const resolved = {
     authentication: config.authentication,
     region: config.region ?? 'us-east-1',
@@ -40,7 +42,7 @@ const createSesConfig = (config) => {
     generateId: config.generateId,
     logger: config.logger,
     retries: config.retries ?? 3,
-    validateSsl: config.validateSsl ?? true,
+    validateSsl: true,
     headers: config.headers ?? {},
     configurationSetName: config.configurationSetName,
     defaultTags: config.defaultTags ?? {},
diff --git a/src/ses/index.d.ts b/src/ses/index.d.ts
index 37e2028..3e13dd2 100644
--- a/src/ses/index.d.ts
+++ b/src/ses/index.d.ts
@@ -101,7 +101,10 @@ export interface SesConfig extends TransportDependencies {
    */
   readonly retries?: number;
   /**
-   * Whether to validate SSL certificates.
+   * Must be true or left out: fetch checks every certificate, and `false`
+   * throws a `TypeError`.  For a test server with a self-signed certificate,
+   * pass a `fetch` whose undici dispatcher skips the check.
+   *
    * @default true
    */
   readonly validateSsl?: boolean;
diff --git a/tests/unit/internal.test.js b/tests/unit/internal.test.js
index b6c6cde..8dda94d 100644
--- a/tests/unit/internal.test.js
+++ b/tests/unit/internal.test.js
@@ -523,3 +523,25 @@ test('Internal: concurrency must be a positive integer', () => {
     assert.throws(() => checkConcurrency(concurrency), RangeError, String(concurrency));
   }
 });
+
+test('Internal: every provider that took validateSsl refuses false', () => {
+  const transports = [
+    [
+      require('../../src/ses/index.js').SesTransport,
+      { authentication: { type: 'credentials', accessKeyId: 'A', secretAccessKey: 'S' } },
+    ],
+    [require('../../src/resend/index.js').ResendTransport, { apiKey: 're_key' }],
+    [require('../../src/sendgrid/index.js').SendGridTransport, { apiKey: 'SG.key' }],
+    [
+      require('../../src/mailgun/index.js').MailgunTransport,
+      { apiKey: 'key', domain: 'mg.example.com' },
+    ],
+    [require('../../src/mailtrap/index.js').MailtrapTransport, { token: 'token' }],
+    [require('../../src/plunk/index.js').PlunkTransport, { apiKey: 'sk_key' }],
+  ];
+  for (const [Transport, config] of transports) {
+    assert.throws(() => new Transport({ ...config, validateSsl: false }), /fetch checks every/);
+    assert.ok(new Transport({ ...config, validateSsl: true }));
+    assert.ok(new Transport(config));
+  }
+});
diff --git a/tests/unit/mailgun-config.test.js b/tests/unit/mailgun-config.test.js
index 23b7fe2..3dee99a 100644
--- a/tests/unit/mailgun-config.test.js
+++ b/tests/unit/mailgun-config.test.js
@@ -48,7 +48,6 @@ describe('MailgunConfig', () => {
       baseUrl: 'https://custom.api.com/v3',
       timeout: 15000,
       retries: 5,
-      validateSsl: false,
       headers: { 'X-Custom': 'value' },
       tracking: false,
       clickTracking: false,
@@ -63,7 +62,10 @@ describe('MailgunConfig', () => {
     assert.equal(resolved.baseUrl, 'https://custom.api.com/v3');
     assert.equal(resolved.timeout, 15000);
     assert.equal(resolved.retries, 5);
-    assert.equal(resolved.validateSsl, false);
+    // Changed after the port: fetch cannot skip the check of a certificate, so
+    // `validateSsl: false` is refused rather than accepted and ignored.
+    assert.equal(resolved.validateSsl, true);
+    assert.throws(() => createMailgunConfig({ ...config, validateSsl: false }), TypeError);
     assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
     assert.equal(resolved.tracking, false);
     assert.equal(resolved.clickTracking, false);
diff --git a/tests/unit/plunk-config.test.js b/tests/unit/plunk-config.test.js
index 6f0411e..fb5270e 100644
--- a/tests/unit/plunk-config.test.js
+++ b/tests/unit/plunk-config.test.js
@@ -27,7 +27,6 @@ describe('createPlunkConfig', () => {
       baseUrl: 'https://plunk.example.com/api',
       timeout: 60000,
       retries: 5,
-      validateSsl: false,
       headers: { 'X-Custom-Header': 'value' },
     };
 
@@ -37,7 +36,10 @@ describe('createPlunkConfig', () => {
     assert.equal(resolved.baseUrl, 'https://plunk.example.com/api');
     assert.equal(resolved.timeout, 60000);
     assert.equal(resolved.retries, 5);
-    assert.equal(resolved.validateSsl, false);
+    // Changed after the port: fetch cannot skip the check of a certificate, so
+    // `validateSsl: false` is refused rather than accepted and ignored.
+    assert.equal(resolved.validateSsl, true);
+    assert.throws(() => createPlunkConfig({ ...config, validateSsl: false }), TypeError);
     assert.deepEqual(resolved.headers, { 'X-Custom-Header': 'value' });
   });
 
diff --git a/tests/unit/resend-config.test.js b/tests/unit/resend-config.test.js
index 11f9f13..141d857 100644
--- a/tests/unit/resend-config.test.js
+++ b/tests/unit/resend-config.test.js
@@ -27,7 +27,6 @@ describe('createResendConfig', () => {
       baseUrl: 'https://custom.resend.com',
       timeout: 60000,
       retries: 5,
-      validateSsl: false,
       headers: { 'X-Custom': 'value' },
     };
 
@@ -37,7 +36,10 @@ describe('createResendConfig', () => {
     assert.equal(resolved.baseUrl, 'https://custom.resend.com');
     assert.equal(resolved.timeout, 60000);
     assert.equal(resolved.retries, 5);
-    assert.equal(resolved.validateSsl, false);
+    // Changed after the port: fetch cannot skip the check of a certificate, so
+    // `validateSsl: false` is refused rather than accepted and ignored.
+    assert.equal(resolved.validateSsl, true);
+    assert.throws(() => createResendConfig({ ...config, validateSsl: false }), TypeError);
     assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
   });
 
diff --git a/tests/unit/sendgrid-config.test.js b/tests/unit/sendgrid-config.test.js
index 1b871d5..8bd3cb4 100644
--- a/tests/unit/sendgrid-config.test.js
+++ b/tests/unit/sendgrid-config.test.js
@@ -31,7 +31,6 @@ describe('SendGridConfig', () => {
       baseUrl: 'https://custom.sendgrid.com/v3',
       timeout: 15000,
       retries: 5,
-      validateSsl: false,
       headers: { 'X-Custom': 'value' },
       clickTracking: false,
       openTracking: false,
@@ -45,7 +44,10 @@ describe('SendGridConfig', () => {
     assert.equal(resolved.baseUrl, 'https://custom.sendgrid.com/v3');
     assert.equal(resolved.timeout, 15000);
     assert.equal(resolved.retries, 5);
-    assert.equal(resolved.validateSsl, false);
+    // Changed after the port: fetch cannot skip the check of a certificate, so
+    // `validateSsl: false` is refused rather than accepted and ignored.
+    assert.equal(resolved.validateSsl, true);
+    assert.throws(() => createSendGridConfig({ ...config, validateSsl: false }), TypeError);
     assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
     assert.equal(resolved.clickTracking, false);
     assert.equal(resolved.openTracking, false);
diff --git a/tests/unit/ses-config.test.js b/tests/unit/ses-config.test.js
index 5662f82..d2757eb 100644
--- a/tests/unit/ses-config.test.js
+++ b/tests/unit/ses-config.test.js
@@ -36,7 +36,6 @@ test('createSesConfig preserves provided values', () => {
     region: 'eu-west-1',
     timeout: 15000,
     retries: 5,
-    validateSsl: false,
     headers: { 'X-Custom': 'value' },
     configurationSetName: 'test-config-set',
     defaultTags: { environment: 'test' },
@@ -48,7 +47,10 @@ test('createSesConfig preserves provided values', () => {
   assert.equal(resolved.region, 'eu-west-1');
   assert.equal(resolved.timeout, 15000);
   assert.equal(resolved.retries, 5);
-  assert.equal(resolved.validateSsl, false);
+  // Changed after the port: fetch cannot skip the check of a certificate, so
+  // `validateSsl: false` is refused rather than accepted and ignored.
+  assert.equal(resolved.validateSsl, true);
+  assert.throws(() => createSesConfig({ ...config, validateSsl: false }), TypeError);
   assert.deepEqual(resolved.headers, { 'X-Custom': 'value' });
   assert.equal(resolved.configurationSetName, 'test-config-set');
   assert.deepEqual(resolved.defaultTags, { environment: 'test' });

From 9d27caf82f6739394b25b87b8c3a824800804fd2 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Fri, 16 Oct 2026 22:03:04 +0300
Subject: [PATCH 155/158] fix(pool)!: refuse continueOnSuccess, which would
 deliver a message twice

continueOnSuccess was accepted and never read (known upstream bug 7);
honored, it would send a message that went out through one transport
again through the others, against the guard of the pool against double
delivery. As the user decided, it is gone from the PoolConfig and
ResolvedPoolConfig types, and continueOnSuccess: true throws a TypeError
when the pool is made.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md               | 3 +++
 CLAUDE.md                  | 5 ++++-
 docs/guide/known-issues.md | 4 ----
 src/pool/config.js         | 9 ++++++++-
 src/pool/index.d.ts        | 6 ------
 tests/types/pool.test-d.ts | 8 ++++++++
 tests/unit/pool.test.js    | 9 +++++++++
 7 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aef4d93..4f98a0c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -331,6 +331,9 @@ fixed ones below.
   error and `timeout after 5000ms` a `server-error`. It now gives the category of
   `classifyReceiptError`, which reads them as whole words (a timeout is `timeout`), and
   `aborted` for an `AbortError`, which upstream counted as `network`.
+- **`./pool` refuses `continueOnSuccess`** (an upstream bug): the option was accepted and never
+  read, and honored it would deliver a sent message again through the other transports. It is
+  gone from the type, and `true` throws a `TypeError`.
 - **`validateSsl: false` throws instead of being ignored** (an upstream bug, `./ses`, `./resend`,
   `./sendgrid`, `./mailgun`, `./mailtrap`, `./plunk`): `fetch` checks every certificate, so the
   option never did anything. `false` now throws a `TypeError` that suggests a `fetch` of your
diff --git a/CLAUDE.md b/CLAUDE.md
index 6962009..0867012 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -140,7 +140,7 @@ Copyright 2025 Hong Minhee; the notice is in `LICENSE`): one subpath per upyo pa
 5. (fixed, see 83) `cram-md5` was in the `SmtpAuth` type but not implemented.
 6. (fixed, see 63) DKIM: a PKCS#1 PEM (`BEGIN RSA PRIVATE KEY`) was imported as PKCS#8 and
    failed.
-7. pool: `continueOnSuccess` is never read.
+7. (fixed, see 85) pool: `continueOnSuccess` was never read.
 8. (fixed, see 44, 45 and 48 to 52) otel: `_active_sends` was not decremented after `sendMany`
    and drifted under sampling; `durationBuckets` and `auto` were ignored; `recordRetry` was
    never called; `sendMany` buffered its whole input; `defaultErrorClassifier` matched `"auth"`
@@ -425,6 +425,9 @@ fails without it; ported tests that pinned the old behavior say "Changed after t
     accepted and ignored, so a caller believed certificates went unchecked. Node's fetch has no
     switch for it without undici, so `false` throws a `TypeError` that points to a `fetch` of
     the caller's own (`checkValidateSsl`); true or absent changes nothing.
+85. pool (known bug 7): `continueOnSuccess` was accepted and never read; honored, it would send
+    a message that went out through one transport again through the others. It is gone from
+    the type, and `continueOnSuccess: true` throws a `TypeError` when the pool is made.
 
 ## Repository layout
 
diff --git a/docs/guide/known-issues.md b/docs/guide/known-issues.md
index d3f9857..e91e54d 100644
--- a/docs/guide/known-issues.md
+++ b/docs/guide/known-issues.md
@@ -10,7 +10,3 @@ still open; the fixed ones are in the [changelog](https://github.com/Alexis-Tech
   size is not known ahead becomes a retryable network error, as Node's `fetch` reports an early
   answer to a streamed body so. Requests, and raw messages of a known size up to 4 MiB, go from a
   buffer and are not affected.
-
-## Decorators
-
-- `./pool`: `continueOnSuccess` is never read.
diff --git a/src/pool/config.js b/src/pool/config.js
index 28a9873..ac62f97 100644
--- a/src/pool/config.js
+++ b/src/pool/config.js
@@ -9,6 +9,14 @@
  * @throws {Error} If the configuration is invalid.
  */
 const createPoolConfig = (config) => {
+  // Upstream accepted it and never read it; honored, it would send a message
+  // that went out through one transport again through the others.
+  if (config.continueOnSuccess) {
+    throw new TypeError(
+      '`continueOnSuccess` is not supported: it would deliver a sent message again through ' +
+        'the other transports.',
+    );
+  }
   if (!config.transports || config.transports.length === 0) {
     throw new Error('Pool must have at least one transport');
   }
@@ -45,7 +53,6 @@ const createPoolConfig = (config) => {
     transports: resolvedTransports,
     maxRetries: config.maxRetries ?? enabledCount - 1,
     timeout: config.timeout,
-    continueOnSuccess: config.continueOnSuccess ?? false,
     random: config.random,
     generateId: config.generateId,
     logger: config.logger,
diff --git a/src/pool/index.d.ts b/src/pool/index.d.ts
index 30154fa..54dafca 100644
--- a/src/pool/index.d.ts
+++ b/src/pool/index.d.ts
@@ -105,11 +105,6 @@ export interface PoolConfig<TProviderId extends string = string> extends IdOptio
    * If not specified, no timeout is applied.
    */
   readonly timeout?: number;
-  /**
-   * Whether to continue trying other transports after a successful send
-   * when using selector-based strategy. Defaults to false.
-   */
-  readonly continueOnSuccess?: boolean;
   /**
    * The source of the random choices, a function like `Math.random` (for
    * tests, a deterministic one).
@@ -130,7 +125,6 @@ export interface ResolvedPoolConfig<TProviderId extends string = string> {
   readonly transports: readonly ResolvedTransportEntry<TProviderId>[];
   readonly maxRetries: number;
   readonly timeout?: number;
-  readonly continueOnSuccess: boolean;
   readonly random?: () => number;
   readonly generateId?: IdOptions['generateId'];
 }
diff --git a/tests/types/pool.test-d.ts b/tests/types/pool.test-d.ts
index 4d4c9d8..28861fb 100644
--- a/tests/types/pool.test-d.ts
+++ b/tests/types/pool.test-d.ts
@@ -43,3 +43,11 @@ for (const strategy of [
 }
 expectAssignable<PoolConfig>({ strategy: new RoundRobinStrategy(), transports: [] });
 expectError(new PoolTransport({ strategy: 'random', transports: [] }));
+// continueOnSuccess was never read, and honored would deliver a message twice.
+expectError(
+  new PoolTransport({
+    strategy: 'priority',
+    transports: [{ transport: new MockTransport() }],
+    continueOnSuccess: true,
+  }),
+);
diff --git a/tests/unit/pool.test.js b/tests/unit/pool.test.js
index 0bc85d8..3b73618 100644
--- a/tests/unit/pool.test.js
+++ b/tests/unit/pool.test.js
@@ -249,3 +249,12 @@ test('Pool: round-robin goes on across sends and batches', async () => {
   assert.strictEqual(first.getSentMessagesCount(), 2);
   assert.strictEqual(second.getSentMessagesCount(), 2);
 });
+
+test('Pool: continueOnSuccess, which would deliver a message twice, is refused', () => {
+  const transports = [{ transport: new MockTransport() }];
+  assert.throws(
+    () => new PoolTransport({ strategy: 'priority', transports, continueOnSuccess: true }),
+    { name: 'TypeError', message: /deliver a sent message again/ },
+  );
+  assert.ok(new PoolTransport({ strategy: 'priority', transports, continueOnSuccess: false }));
+});

From 5e612f2dfd53179def6593dd34b91ccc0a494a92 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Sat, 17 Oct 2026 16:15:01 +0300
Subject: [PATCH 156/158] docs: put @alexify/mailer first in the comparison,
 pinned and in teal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The comparison now opens with a column for @alexify/mailer itself, filled
from the code of this branch: the transport as built, the reliability layer
as 🔜 with a footnote to the plan, and deliveryUnknown noted on retry and
failover. custom.css tints the column in the brand teal and, from 768px,
pins it beside the features.

The matrix moves to separate borders, as collapsed ones belong to the table
and let scrolled text show through the seam of a pinned cell, and the
titles of the group rows stick while the table scrolls sideways.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                     |   3 +-
 CLAUDE.md                        |   9 +-
 docs/.vitepress/theme/custom.css |  57 +++++++-
 docs/comparison.json             | 237 ++++++++++++++++++++++++++++++-
 docs/guide/comparison.md         | 145 ++++++++++---------
 scripts/comparison.js            |  21 +--
 6 files changed, 387 insertions(+), 85 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f98a0c..e2090c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -79,7 +79,8 @@ fixed ones below.
   Mailpit (`pnpm test:mailpit`) and real providers (`pnpm test:e2e`).
 - **CI** on GitHub Actions and a VitePress documentation site at
   [mailerat.vercel.app](https://mailerat.vercel.app/), with a comparison of 14 Node.js email
-  libraries generated from `docs/comparison.json`.
+  libraries generated from `docs/comparison.json`, @alexify/mailer in its first column, tinted
+  in the brand teal and pinned beside the features.
 
 ### Security
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 0867012..a2b2102 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -662,9 +662,12 @@ published to npm, and lint/format do not cover it.
   between `<!-- comparison:start -->` and `<!-- comparison:end -->` is rendered by
   `pnpm docs:comparison` from `docs/comparison.json` (`legend`, `groups[].rows[]`,
   `libraries[].cells[rowId] = { mark, text, note? }`). Edit the data, never the table; CI fails on
-  a diff. The page takes the full width through `.VPDoc:has(.ml-matrix)` in `custom.css`. The
-  findings in cells come from reading the code and, except for emailjs, were not reproduced; the
-  page says so, and a bug claim should be reproduced before it is made stronger.
+  a diff. The first library of the data is @alexify/mailer itself (this repository, with 🔜 for
+  the roadmap), which `custom.css` tints in the brand teal as the second column and pins beside
+  the features from 768px up; keep its cells true to the code when behavior changes. The page
+  takes the full width through `.VPDoc:has(.ml-matrix)` in `custom.css`. The findings in cells
+  come from reading the code and, except for emailjs, were not reproduced; the page says so, and
+  a bug claim should be reproduced before it is made stronger.
 - The brand is a teal "envelope" mark (`#0D6B63`, `#4CC2B5` on dark; a placeholder until a final
   logo): `docs/public/logo-mark*.svg`, `favicon.svg` (follows `prefers-color-scheme`),
   `favicon.png` and `logo.png` (the 1200×630 og:image, rendered from SVG with `rsvg-convert`).
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index 90f678a..5a4d388 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -62,18 +62,25 @@
 }
 
 /* ─── The comparison matrix (/guide/comparison): one wide table ─────────────
- * It scrolls sideways with the feature names pinned on the left and the group
- * rows set apart. Sticky cells need an opaque background that follows the
- * zebra stripes of the default theme. */
+ * It scrolls sideways with the feature names pinned on the left, the
+ * @alexify/mailer column tinted (and pinned beside them where there is room)
+ * and the group rows set apart. Sticky cells need an opaque background that
+ * follows the zebra stripes of the default theme, and borders of their own:
+ * collapsed borders belong to the table, and the text scrolling under a pinned
+ * cell shows through their seam. Each cell draws its right and bottom border,
+ * the first row and column the outer edges. */
 .vp-doc .ml-matrix table {
   display: block;
   max-height: 85vh;
   overflow: auto;
+  border-collapse: separate;
+  border-spacing: 0;
 }
 .vp-doc .ml-matrix th,
 .vp-doc .ml-matrix td {
   min-width: 8.5rem;
   padding: 5px 9px;
+  border-width: 0 1px 1px 0;
   font-size: 12.5px;
   line-height: 1.4;
   vertical-align: top;
@@ -82,6 +89,7 @@
   position: sticky;
   top: 0;
   z-index: 2;
+  border-top-width: 1px;
   background-color: var(--vp-c-bg-soft);
 }
 .vp-doc .ml-matrix th:first-child,
@@ -90,6 +98,7 @@
   left: 0;
   z-index: 1;
   min-width: 11rem;
+  border-left-width: 1px;
   background-color: var(--vp-c-bg);
   font-weight: 600;
 }
@@ -100,6 +109,42 @@
 .vp-doc .ml-matrix tr:nth-child(2n) td:first-child {
   background-color: var(--vp-c-bg-soft);
 }
+/* The column of @alexify/mailer, the first library of the data: the tint is an
+ * image over the background colour, so a pinned cell stays opaque, and a teal
+ * bar tops its name. */
+.vp-doc .ml-matrix th:nth-child(2),
+.vp-doc .ml-matrix td:nth-child(2) {
+  background-image: linear-gradient(var(--vp-c-brand-soft), var(--vp-c-brand-soft));
+}
+.vp-doc .ml-matrix thead th:nth-child(2) {
+  box-shadow: inset 0 3px 0 var(--vp-c-brand-3);
+}
+/* Two pinned columns take 20rem, too much of a phone: from a tablet up the
+ * features get a fixed width, the left offset of the column after them. */
+@media (min-width: 768px) {
+  .vp-doc .ml-matrix th:first-child,
+  .vp-doc .ml-matrix td:first-child {
+    width: 11rem;
+  }
+  .vp-doc .ml-matrix th:nth-child(2),
+  .vp-doc .ml-matrix td:nth-child(2) {
+    position: sticky;
+    left: 11rem;
+    z-index: 1;
+    background-color: var(--vp-c-bg);
+    box-shadow: inset -2px 0 0 var(--vp-c-brand-3);
+  }
+  .vp-doc .ml-matrix tr:nth-child(2n) td:nth-child(2) {
+    background-color: var(--vp-c-bg-soft);
+  }
+  .vp-doc .ml-matrix thead th:nth-child(2) {
+    z-index: 3;
+    background-color: var(--vp-c-bg-soft);
+    box-shadow:
+      inset 0 3px 0 var(--vp-c-brand-3),
+      inset -2px 0 0 var(--vp-c-brand-3);
+  }
+}
 .vp-doc .ml-matrix td code {
   font-size: 11.5px;
 }
@@ -111,6 +156,12 @@
   text-transform: uppercase;
   color: var(--vp-c-text-2);
 }
+/* A group cell spans the whole table, so it cannot stick: its title does. */
+.vp-doc .ml-matrix tr.ml-matrix-group strong {
+  display: inline-block;
+  position: sticky;
+  left: 9px;
+}
 
 /* The page of the matrix uses the whole width next to the sidebar instead of
  * the reading column, and drops the outline on the right. */
diff --git a/docs/comparison.json b/docs/comparison.json
index c147bdb..2886df6 100644
--- a/docs/comparison.json
+++ b/docs/comparison.json
@@ -1,5 +1,5 @@
 {
-  "legend": "✅ in the code · ⚠️ partial, or only on the provider side · ❌ none · 🔜 planned by the author, no code yet · — does not apply. Every cell was decided by reading the source of the project as of 2026-10-07, not its README.",
+  "legend": "✅ in the code · ⚠️ partial, or only on the provider side · ❌ none · 🔜 planned by the author, no code yet · — does not apply. Every cell was decided by reading the source of the project as of 2026-10-07, not its README; the column of @alexify/mailer is this repository as of 2026-10-17.",
   "groups": [
     {
       "title": "Runtimes (from imports and CI, not run)",
@@ -270,6 +270,241 @@
     }
   ],
   "libraries": [
+    {
+      "id": "mailer",
+      "name": "@alexify/mailer",
+      "direction": "unified + reliability",
+      "url": "https://github.com/Alexis-Technologies/mailer",
+      "cells": {
+        "nodeMin": {
+          "mark": "✅",
+          "text": "≥22, CI on 22 and 24"
+        },
+        "deno": {
+          "mark": "❌",
+          "text": "not a target"
+        },
+        "bun": {
+          "mark": "❌",
+          "text": "not a target"
+        },
+        "edge": {
+          "mark": "❌",
+          "text": "not a target yet"
+        },
+        "browser": {
+          "mark": "❌",
+          "text": "by design"
+        },
+        "smtp": {
+          "mark": "✅",
+          "text": "PIPELINING, SIZE, DSN"
+        },
+        "sendmail": {
+          "mark": "❌"
+        },
+        "jmap": {
+          "mark": "✅",
+          "text": "RFC 8620/8621"
+        },
+        "httpProviders": {
+          "text": "8"
+        },
+        "failover": {
+          "mark": "✅",
+          "text": "RR, weighted, priority; no health yet",
+          "note": "A failure after which the provider may have taken the message is marked `deliveryUnknown`: `./retry` does not retry it and `./pool` does not fail over with it."
+        },
+        "smtpPool": {
+          "mark": "✅",
+          "text": "on by default, 5"
+        },
+        "retry": {
+          "mark": "✅",
+          "text": "jitter, `Retry-After`, no blind resend",
+          "note": "A failure after which the provider may have taken the message is marked `deliveryUnknown`: `./retry` does not retry it and `./pool` does not fail over with it."
+        },
+        "rateLimit": {
+          "mark": "⚠️",
+          "text": "`sendMany` concurrency; token bucket planned"
+        },
+        "circuitBreaker": {
+          "mark": "🔜",
+          "text": "one probe in half-open",
+          "note": "On the [roadmap](/guide/why#the-plan) of the reliability layer: designed, with no code yet."
+        },
+        "timeout": {
+          "mark": "✅",
+          "text": "`signal` + timeout over the body"
+        },
+        "queue": {
+          "mark": "🔜",
+          "text": "MongoDB outbox, BullMQ driver",
+          "note": "On the [roadmap](/guide/why#the-plan) of the reliability layer: designed, with no code yet."
+        },
+        "attachments": {
+          "mark": "⚠️",
+          "text": "bytes, Promise, Blob, chunk factory"
+        },
+        "streaming": {
+          "mark": "⚠️",
+          "text": "SMTP; HTTP providers buffer"
+        },
+        "inline": {
+          "mark": "✅",
+          "text": "multipart/related"
+        },
+        "rawMime": {
+          "mark": "⚠️",
+          "text": "SMTP/JMAP only"
+        },
+        "ical": {
+          "mark": "✅",
+          "text": "every METHOD"
+        },
+        "unicode": {
+          "mark": "⚠️",
+          "text": "SMTPUTF8, no automatic punycode"
+        },
+        "listUnsubscribe": {
+          "mark": "⚠️",
+          "text": "manual header; one-click planned"
+        },
+        "templates": {
+          "mark": "❌",
+          "text": "none, by design"
+        },
+        "reactEmail": {
+          "mark": "🔜",
+          "text": "optional adapter",
+          "note": "On the [roadmap](/guide/why#the-plan) of the reliability layer: designed, with no code yet."
+        },
+        "batch": {
+          "mark": "✅",
+          "text": "native: Resend, Mailtrap, JMAP; concurrency elsewhere"
+        },
+        "scheduled": {
+          "mark": "🔜",
+          "text": "a delay in the queue",
+          "note": "On the [roadmap](/guide/why#the-plan) of the reliability layer: designed, with no code yet."
+        },
+        "tags": {
+          "mark": "⚠️",
+          "text": "tags in 7 providers"
+        },
+        "tracking": {
+          "mark": "⚠️",
+          "text": "config only"
+        },
+        "idempotency": {
+          "mark": "⚠️",
+          "text": "Resend, Lettermint, Maileroo; outbox key planned"
+        },
+        "dkim": {
+          "mark": "✅",
+          "text": "RSA + Ed25519, streaming, over-signing"
+        },
+        "oauth2": {
+          "mark": "✅",
+          "text": "refresh, OAUTHBEARER"
+        },
+        "arc": {
+          "mark": "❌"
+        },
+        "dsn": {
+          "mark": "✅"
+        },
+        "proxy": {
+          "mark": "⚠️",
+          "text": "HTTP through an injected `fetch`; SMTP no"
+        },
+        "verify": {
+          "mark": "⚠️",
+          "text": "SMTP/JMAP only"
+        },
+        "smtpAuth": {
+          "text": "PLAIN, LOGIN, XOAUTH2, OAUTHBEARER"
+        },
+        "tlsPolicy": {
+          "mark": "✅",
+          "text": "`requireTls`, SNI, CA, cert, `minVersion`"
+        },
+        "webhooks": {
+          "mark": "🔜",
+          "text": "SES (SNS) first, signature required",
+          "note": "On the [roadmap](/guide/why#the-plan) of the reliability layer: designed, with no code yet."
+        },
+        "inbound": {
+          "mark": "❌",
+          "text": "out of scope"
+        },
+        "suppression": {
+          "mark": "🔜",
+          "text": "per tenant, before the queue",
+          "note": "On the [roadmap](/guide/why#the-plan) of the reliability layer: designed, with no code yet."
+        },
+        "domains": {
+          "mark": "❌",
+          "text": "out of scope"
+        },
+        "addressValidation": {
+          "mark": "⚠️",
+          "text": "RFC 5322/6531 syntax"
+        },
+        "providerLogs": {
+          "mark": "—"
+        },
+        "apiCoverage": {
+          "mark": "—"
+        },
+        "multiChannel": {
+          "mark": "❌",
+          "text": "out of scope"
+        },
+        "otel": {
+          "mark": "✅",
+          "text": "decorator: spans + metrics"
+        },
+        "hooks": {
+          "mark": "⚠️",
+          "text": "decorators, `onRetry`, a pino-like logger"
+        },
+        "mock": {
+          "mark": "✅",
+          "text": "`./mock`"
+        },
+        "auditLog": {
+          "mark": "🔜",
+          "text": "append-only, crypto-shredding",
+          "note": "On the [roadmap](/guide/why#the-plan) of the reliability layer: designed, with no code yet."
+        },
+        "types": {
+          "mark": "✅",
+          "text": "hand-written, tsd"
+        },
+        "deps": {
+          "text": "0"
+        },
+        "moduleFormat": {
+          "text": "CJS, ESM `import`"
+        },
+        "license": {
+          "text": "MIT"
+        },
+        "version": {
+          "text": "0.0.1 (unreleased)"
+        },
+        "lastCommit": {
+          "text": "2026-10 (in development)"
+        },
+        "tests": {
+          "text": "126 / ~1440"
+        },
+        "maintainer": {
+          "text": "1 author, Alexis Technologies"
+        }
+      }
+    },
     {
       "id": "nodemailer",
       "name": "Nodemailer 10",
diff --git a/docs/guide/comparison.md b/docs/guide/comparison.md
index 0033f11..0cc7a96 100644
--- a/docs/guide/comparison.md
+++ b/docs/guide/comparison.md
@@ -6,7 +6,9 @@ emailjs), unified libraries over many providers (Upyo, unemail, sently), SMTP fo
 (worker-mailer, edge-mailer), a MIME builder (MIMEText) and the official SDKs of the providers
 (Resend, SendGrid, Mailgun, Postmark, Mailtrap, Amazon SES). It follows the idea of
 [Upyo's own comparison](https://upyo.org/why), with every feature in one table rather than a few
-convenient libraries in a few convenient rows.
+convenient libraries in a few convenient rows. @alexify/mailer itself is the first column, in teal
+and, on a wide screen, pinned beside the features as the table scrolls, so every row reads against
+it.
 
 ## What the table shows
 
@@ -33,6 +35,7 @@ convenient libraries in a few convenient rows.
 <thead>
 <tr>
 <th>Feature</th>
+<th><a href="https://github.com/Alexis-Technologies/mailer">@alexify/mailer</a><br><sub>unified + reliability</sub></th>
 <th><a href="https://github.com/nodemailer/nodemailer">Nodemailer 10</a><br><sub>SMTP/MIME</sub></th>
 <th><a href="https://github.com/eleith/emailjs">emailjs 5</a><br><sub>SMTP</sub></th>
 <th><a href="https://github.com/dahlia/upyo">Upyo</a><br><sub>unified</sub></th>
@@ -50,79 +53,80 @@ convenient libraries in a few convenient rows.
 </tr>
 </thead>
 <tbody>
-<tr class="ml-matrix-group"><td colspan="15"><strong>Runtimes (from imports and CI, not run)</strong></td></tr>
-<tr><td>Node.js, minimum version</td><td>✅ ≥20</td><td>⚠️ ≥18, CI 20+</td><td>✅ ≥20</td><td>✅ ≥20.11</td><td>✅ ≥18</td><td>❌ Workers only</td><td>⚠️ needs a connector of your own</td><td>✅ no <code>engines</code> field</td><td>✅ ≥20</td><td>✅ ≥12</td><td>✅ ≥18</td><td>✅ ≥18</td><td>✅ ≥16.20</td><td>✅ ≥20</td></tr>
-<tr><td>Deno</td><td>❌ not declared</td><td>❌ not declared</td><td>✅ CI: deno test</td><td>⚠️ HTTP drivers, not SMTP</td><td>✅ <code>Deno.connect</code></td><td>❌</td><td>✅ edge-mailer/deno</td><td>⚠️ browser-entry</td><td>⚠️ <code>fetch</code>, not tested</td><td>⚠️ through Node compatibility</td><td>⚠️ not declared</td><td>⚠️ <code>fetch</code>, not declared</td><td>⚠️ not declared</td><td>⚠️ through <code>npm:</code></td></tr>
-<tr><td>Bun</td><td>✅ CI: test:bun</td><td>❌ not declared</td><td>✅ CI: bun test</td><td>✅ CI: bun</td><td>✅ CI: bun test</td><td>❌</td><td>❌ no connector</td><td>⚠️ browser-entry</td><td>⚠️ fetch</td><td>⚠️ through Node compatibility</td><td>⚠️ not declared</td><td>⚠️ not declared</td><td>⚠️ not declared</td><td>⚠️ through Node compatibility</td></tr>
-<tr><td>Cloudflare Workers / edge</td><td>⚠️ only with <code>nodejs_compat</code></td><td>❌</td><td>⚠️ HTTP packages yes, SMTP no</td><td>⚠️ HTTP + 3 Cloudflare drivers, no SMTP</td><td>✅ HTTP + SMTP (cloudflare:sockets)</td><td>✅ the only target</td><td>✅ no <code>node:*</code></td><td>⚠️ browser-entry</td><td>⚠️ <code>fetch</code>, not tested</td><td>⚠️ <code>fs</code>, axios; not declared</td><td>⚠️ <code>fetch</code> mode</td><td>⚠️ declared in 5.0.0</td><td>❌ <code>http</code>/<code>https</code> agents</td><td>⚠️ explicit credentials needed</td></tr>
-<tr><td>Browser</td><td>❌</td><td>❌</td><td>⚠️ no target, no tests</td><td>✅ HTTP drivers only</td><td>⚠️ throws</td><td>❌</td><td>❌</td><td>✅ browser-bundle</td><td>⚠️ secret key in the client</td><td>❌</td><td>✅ needs a CORS proxy</td><td>❌</td><td>❌</td><td>✅ explicit credentials</td></tr>
-<tr class="ml-matrix-group"><td colspan="15"><strong>Transports and delivery reliability</strong></td></tr>
-<tr><td>SMTP client</td><td>✅ SMTP + LMTP</td><td>✅ no LMTP</td><td>✅ PIPELINING, SIZE, DSN</td><td>✅ own implementation</td><td>✅ own implementation</td><td>✅</td><td>✅</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr><td>Sendmail / local binary</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr><td>JMAP</td><td>❌</td><td>❌</td><td>✅ RFC 8620/8621</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr><td>HTTP providers, count</td><td>1 (SES, needs the SDK)</td><td>0</td><td>8</td><td>18 + http + 2 CF</td><td>14 + CF binding</td><td>0</td><td>0</td><td>—</td><td>1</td><td>1</td><td>1</td><td>1</td><td>1</td><td>1</td></tr>
-<tr><td>Failover between providers</td><td>⚠️ host DNS fallback only</td><td>❌</td><td>✅ RR, weighted, priority</td><td>✅ fallback, RR, weighted, tee</td><td>✅ fallback + weighted</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ multi-region endpoint on the AWS side</td></tr>
-<tr><td>SMTP connection pool</td><td>✅ max 5, 100 msg</td><td>❌ one connection</td><td>✅ on by default</td><td>✅ off by default</td><td>✅ off by default</td><td>❌</td><td>✅</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
-<tr><td>Retry / backoff</td><td>⚠️ requeue in the pool only</td><td>⚠️ 1 retry on 450/451</td><td>✅ jitter, Retry-After</td><td>✅ 5 modes, jitter</td><td>✅ no jitter, retries SMTP 5xx</td><td>❌</td><td>❌ <code>retryHint</code> only</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>✅ standard / adaptive</td></tr>
-<tr><td>Rate limiting</td><td>✅ <code>rateLimit</code> in the pool</td><td>❌</td><td>⚠️ <code>sendMany</code> only</td><td>✅ token bucket</td><td>⚠️ pool + <code>sendBulk</code></td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>⚠️ contact importer only</td><td>❌</td><td>⚠️ 429 → error</td><td>❌</td><td>⚠️ adaptive retry</td></tr>
-<tr><td>Circuit breaker</td><td>❌</td><td>❌</td><td>❌</td><td>✅ half-open without a single probe</td><td>⚠️ <code>cooldownMs</code></td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr><td>Timeout / AbortSignal</td><td>⚠️ timeouts, no <code>AbortSignal</code></td><td>⚠️ timeout, no signal</td><td>✅ <code>signal</code> + timeout</td><td>⚠️ signal for HTTP, not SMTP</td><td>⚠️ SMTP connect only</td><td>⚠️ socket timeouts</td><td>✅ signal on connect and send</td><td>—</td><td>⚠️ signal, no timeout</td><td>⚠️ global signal only</td><td>⚠️ timeout, no signal</td><td>⚠️ 180 s timeout</td><td>⚠️ hard 10 s</td><td>✅ <code>abortSignal</code> + <code>requestTimeout</code></td></tr>
-<tr><td>Persistent queue (survives a restart)</td><td>❌</td><td>❌</td><td>❌</td><td>🔜 planned</td><td>❌</td><td>❌</td><td>⚠️ sample outbox only</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr class="ml-matrix-group"><td colspan="15"><strong>Messages</strong></td></tr>
-<tr><td>Attachments</td><td>✅ path, URL, Buffer, stream, data-URI</td><td>⚠️ path, stream, no URL</td><td>⚠️ bytes, Blob, File, factory</td><td>⚠️ bytes, string, URL</td><td>⚠️ bytes + path</td><td>⚠️ base64 only</td><td>⚠️ string, bytes, Blob</td><td>⚠️ base64 only</td><td>⚠️ base64 or URL</td><td>⚠️ base64, helper for <code>Buffer</code></td><td>✅ Buffer, Blob, stream, 50 MB</td><td>✅ base64</td><td>✅ string / Buffer</td><td>✅ <code>Uint8Array</code> or Raw MIME</td></tr>
-<tr><td>Streaming large attachments</td><td>⚠️ SMTP yes; DKIM and SES buffer</td><td>✅</td><td>⚠️ SMTP only</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ accepts a stream</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr><td>Inline images (CID)</td><td>✅ multipart/related</td><td>⚠️ manual Content-ID</td><td>⚠️ mixed, not related; Mailgun bug</td><td>⚠️ mixed, not related</td><td>⚠️ HTTP: 3 providers only</td><td>❌</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr>
-<tr><td>Sending raw MIME</td><td>✅</td><td>❌</td><td>⚠️ SMTP/JMAP only</td><td>⚠️ smtp driver only</td><td>❌</td><td>❌</td><td>❌</td><td>— builds MIME only</td><td>❌</td><td>❌</td><td>✅ <code>/messages.mime</code></td><td>❌</td><td>❌</td><td>✅ <code>Content.Raw</code></td></tr>
-<tr><td>iCalendar</td><td>✅ <code>icalEvent</code> + METHOD</td><td>⚠️ manual</td><td>✅ every METHOD</td><td>🔜 planned</td><td>❌</td><td>❌</td><td>✅</td><td>⚠️ as an attachment</td><td>❌</td><td>❌</td><td>⚠️ as an attachment</td><td>⚠️ as an attachment</td><td>⚠️ as an attachment</td><td>⚠️ through Raw MIME</td></tr>
-<tr><td>Unicode / IDN</td><td>✅ punycode + SMTPUTF8</td><td>⚠️ Q-encoding, no punycode</td><td>⚠️ SMTPUTF8, no automatic punycode</td><td>⚠️ RFC 2047/2231</td><td>⚠️ one RFC 2047 word</td><td>⚠️ RFC 2047</td><td>⚠️ SMTPUTF8, no punycode</td><td>⚠️ Subject as one B-word</td><td>⚠️ UTF-8 JSON</td><td>⚠️ UTF-8 JSON</td><td>❌</td><td>❌</td><td>⚠️ UTF-8 JSON</td><td>⚠️ Charset, no IDN</td></tr>
-<tr><td>List-Unsubscribe</td><td>✅ <code>list.unsubscribe</code></td><td>❌</td><td>⚠️ manual header</td><td>✅ RFC 8058 oneClick</td><td>❌</td><td>⚠️ headers</td><td>⚠️ headers</td><td>❌</td><td>⚠️ headers, topics</td><td>⚠️ headers, asm</td><td>⚠️ headers</td><td>⚠️ headers</td><td>⚠️ headers</td><td>✅ <code>ListManagementOptions</code></td></tr>
-<tr><td>Built-in templates</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ <code>Renderer</code> interface</td><td>✅ <code>{{var}}</code> + plugins</td><td>❌</td><td>❌</td><td>❌</td><td>✅ Templates API</td><td>✅ dynamic templates</td><td>✅ Templates API</td><td>✅ Templates API</td><td>✅ Templates API</td><td>✅ Templates API</td></tr>
-<tr><td>React Email</td><td>❌</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr><td>Batch / bulk</td><td>❌</td><td>❌</td><td>✅ native: Resend, Mailtrap, JMAP</td><td>✅ <code>sendBatch</code></td><td>⚠️ <code>sendBulk</code>, SendGrid bug</td><td>⚠️ queue per session</td><td>✅</td><td>—</td><td>✅ up to 100, no attachments</td><td>✅ personalizations</td><td>⚠️ <code>recipient-variables</code></td><td>✅ batch + bulk API</td><td>✅ batchSend, 500</td><td>✅ <code>SendBulkEmail</code></td></tr>
-<tr><td>Scheduled sending</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ 8 drivers</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>✅</td><td>✅ up to 3 days</td><td>❌</td><td>⚠️ campaigns only</td><td>❌</td></tr>
-<tr><td>Tags / metadata</td><td>⚠️ headers; tags on SES only</td><td>⚠️ headers</td><td>⚠️ tags in 7 providers</td><td>✅</td><td>⚠️ headers only</td><td>⚠️ headers</td><td>⚠️ headers</td><td>⚠️ headers</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr>
-<tr><td>Open/click tracking</td><td>❌</td><td>❌</td><td>⚠️ config only</td><td>✅ 10 drivers</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>⚠️ per domain</td><td>✅</td><td>✅</td><td>✅</td><td>⚠️ per domain</td><td>✅ per-message override</td></tr>
-<tr><td>Idempotency key</td><td>❌</td><td>❌</td><td>⚠️ Resend, Lettermint, Maileroo</td><td>✅ middleware + providers</td><td>⚠️ decorator; batch bypasses it</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr class="ml-matrix-group"><td colspan="15"><strong>Security and authentication</strong></td></tr>
-<tr><td>DKIM signing in the library</td><td>✅ RSA-SHA256</td><td>❌</td><td>✅ RSA + Ed25519, streaming</td><td>✅ RSA + Ed25519, SMTP only</td><td>⚠️ body canonicalization bug</td><td>❌</td><td>✅ RSA</td><td>❌</td><td>⚠️ keys through the API</td><td>⚠️ whitelabel, generic</td><td>⚠️ keys through the API</td><td>⚠️ keys through the API</td><td>⚠️ domain DNS records</td><td>⚠️ Easy / BYO DKIM</td></tr>
-<tr><td>OAuth2 for SMTP</td><td>✅ refresh + service account</td><td>⚠️ bearer token only</td><td>✅ refresh, OAUTHBEARER</td><td>⚠️ callback, no refresh</td><td>✅ refresh client</td><td>❌</td><td>⚠️ no refresh</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
-<tr><td>ARC</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
-<tr><td>DSN</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
-<tr><td>Proxy</td><td>⚠️ HTTP CONNECT, SOCKS through a module</td><td>❌</td><td>❌</td><td>⚠️ custom <code>fetch</code></td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>⚠️ <code>baseUrl</code> only</td><td>⚠️ axios proxy</td><td>✅</td><td>⚠️ custom fetch + undici</td><td>⚠️ environment only</td><td>⚠️ through <code>requestHandler</code></td></tr>
-<tr><td><code>verify()</code> / connection check</td><td>✅</td><td>⚠️ VRFY, not a check</td><td>⚠️ SMTP/JMAP only</td><td>⚠️ <code>isAvailable()</code>, nominal</td><td>✅</td><td>❌</td><td>⚠️ <code>probe()</code> without auth</td><td>—</td><td>—</td><td>—</td><td>⚠️ domain DNS only</td><td>⚠️ <code>getServer()</code></td><td>⚠️ <code>getAllAccounts()</code></td><td>⚠️ <code>GetAccount</code></td></tr>
-<tr><td>SMTP AUTH mechanisms</td><td>PLAIN, LOGIN, CRAM-MD5, XOAUTH2</td><td>CRAM-MD5, LOGIN, PLAIN, XOAUTH2</td><td>PLAIN, LOGIN, XOAUTH2, OAUTHBEARER</td><td>PLAIN, LOGIN, CRAM-MD5, XOAUTH2</td><td>PLAIN, LOGIN, CRAM-MD5, XOAUTH2</td><td>PLAIN, LOGIN, CRAM-MD5</td><td>PLAIN, LOGIN, CRAM-MD5, XOAUTH2</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
-<tr><td>SMTP TLS policies</td><td>✅ REQUIRETLS, SNI, no DANE</td><td>⚠️ STARTTLS accepts any certificate</td><td>✅ <code>requireTls</code>, CA, cert, <code>minVersion</code></td><td>✅ <code>requireTLS</code>, off by default</td><td>✅ <code>requireTLS</code> by default with auth</td><td>⚠️ falls back to plaintext + AUTH</td><td>✅ <code>tlsPolicy</code> ×4, REQUIRETLS</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
-<tr class="ml-matrix-group"><td colspan="15"><strong>Platform features (events, domains, provider API)</strong></td></tr>
-<tr><td>Webhooks: parsing and signature verification</td><td>❌</td><td>❌</td><td>❌</td><td>🔜 planned</td><td>✅ 10 parsers, HMAC in 5</td><td>❌</td><td>❌</td><td>—</td><td>✅ standardwebhooks</td><td>✅ ECDSA</td><td>⚠️ CRUD, no verification</td><td>⚠️ CRUD + types, no verification</td><td>✅ HMAC verify</td><td>❌ SNS signature not in the SDK</td></tr>
-<tr><td>Inbound mail</td><td>❌</td><td>❌</td><td>❌</td><td>🔜 planned</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>⚠️ parser with a bug</td><td>⚠️ routes</td><td>✅</td><td>✅</td><td>❌ legacy <code>client-ses</code> only</td></tr>
-<tr><td>Suppression / bounce API</td><td>❌</td><td>❌</td><td>❌</td><td>🔜 planned</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>⚠️ generic client</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr>
-<tr><td>Domain management (API)</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>⚠️ generic client</td><td>✅</td><td>✅</td><td>✅</td><td>✅ identities</td></tr>
-<tr><td>Address validation</td><td>⚠️ parser only</td><td>⚠️ parser only</td><td>⚠️ RFC 5322/6531 syntax</td><td>⚠️ regex</td><td>⚠️ regex</td><td>❌</td><td>❌ syntax assert</td><td>❌</td><td>❌</td><td>❌</td><td>✅ <code>/v4/address/validate</code></td><td>❌</td><td>❌</td><td>✅ <code>GetEmailAddressInsights</code></td></tr>
-<tr><td>Sending log on the provider side</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>✅ logs API</td><td>⚠️ generic /v3/messages</td><td>✅ logs API</td><td>⚠️ events, opens, clicks</td><td>⚠️ <code>emailLogs</code></td><td>⚠️ event destinations + archiving</td></tr>
-<tr><td>Provider API coverage</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>18 namespaces, ~117 calls</td><td>only mail/send typed; ~251 endpoints in USAGE.md</td><td>21 clients, ~155 calls</td><td>85 methods</td><td>~126 calls</td><td>116 commands</td></tr>
-<tr><td>Multi-channel: SMS, WhatsApp, push</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>✅ SMS, WhatsApp, webpush, FCM</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr class="ml-matrix-group"><td colspan="15"><strong>Observability and extensibility</strong></td></tr>
-<tr><td>OpenTelemetry</td><td>❌</td><td>❌</td><td>✅ decorator: spans + metrics</td><td>⚠️ <code>withLogger</code></td><td>⚠️ hooks + <code>consoleObserver</code></td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ <code>middlewareStack</code></td></tr>
-<tr><td>Hooks / middleware</td><td>✅ <code>use(compile|stream)</code></td><td>⚠️ logger function</td><td>⚠️ decorators, LogTape</td><td>✅ Middleware pipeline</td><td>✅ hooks + plugins</td><td>⚠️ logger</td><td>✅ <code>onEvent</code></td><td>⚠️ <code>dump()</code></td><td>⚠️ <code>console.error</code></td><td>⚠️ <code>setClient</code></td><td>❌</td><td>❌</td><td>❌</td><td>✅ logger + <code>middlewareStack</code></td></tr>
-<tr><td>Mock / test mode</td><td>✅ <code>jsonTransport</code>, <code>streamTransport</code>, Ethereal</td><td>⚠️ <code>Message#read()</code></td><td>✅ <code>@upyo/mock</code></td><td>✅ mock + Mailpit</td><td>⚠️ preview, Mailpit</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>✅ <code>sandboxMode</code></td><td>✅ <code>testmode</code></td><td>⚠️ Sandbox server</td><td>✅ <code>Sandbox API</code></td><td>⚠️ <code>TestRenderEmailTemplate</code></td></tr>
-<tr><td>Local audit log / event journal</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ events, not stored</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
-<tr class="ml-matrix-group"><td colspan="15"><strong>Quality, license, maturity</strong></td></tr>
-<tr><td>TypeScript types</td><td>✅ built in</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅ hand-written <code>.d.ts</code></td><td>✅</td><td>✅</td><td>✅</td><td>✅ generated</td></tr>
-<tr><td>Runtime dependencies</td><td>0</td><td>0</td><td>0–1 (@noble/hashes)</td><td>0</td><td>0</td><td>0</td><td>0</td><td>4</td><td>2</td><td>2+ (axios)</td><td>3 (axios)</td><td>0</td><td>2 (axios, qs)</td><td>9</td></tr>
-<tr><td>Module format</td><td>ESM + CJS</td><td>ESM only</td><td>ESM + CJS + JSR</td><td>ESM only</td><td>ESM only</td><td>ESM + CJS</td><td>ESM + CJS + JSR</td><td>ESM + CJS</td><td>ESM + CJS</td><td>CJS only</td><td>ESM + CJS</td><td>CJS only</td><td>CJS only</td><td>ESM + CJS</td></tr>
-<tr><td>License</td><td>MIT-0</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>Apache-2.0</td></tr>
-<tr><td>Version (2026-10-07)</td><td>10.0.16</td><td>5.0.3</td><td>0.7.0 (unreleased; release 0.6.0)</td><td>0.7.0</td><td>1.2.2</td><td>1.2.1</td><td>0.8.5</td><td>3.0.24 (tag 3.0.28)</td><td>6.32.1</td><td>8.1.6</td><td>14.0.2</td><td>5.1.0</td><td>4.10.0 (HEAD ahead)</td><td>3.1147.0</td></tr>
-<tr><td>Last commit</td><td>2026-10-07</td><td>2026-08-26</td><td>2026-09-09</td><td>2026-09-02</td><td>2026-08-19</td><td>2025-11-15</td><td>2026-09-08</td><td>2026-01-28</td><td>2026-10-06</td><td>2025-09-19</td><td>2026-10-07</td><td>2026-07-10</td><td>2026-10-07</td><td>2026-10-06</td></tr>
-<tr><td>Tests: files / cases</td><td>61 / ~1330</td><td>15 / ~153</td><td>109 / ~1300</td><td>40 / ~773</td><td>66 / ~532</td><td>4 / ~189</td><td>14 / ~258</td><td>6 / ~30</td><td>39 / ~441</td><td>43 / ~450</td><td>49 files</td><td>23 (16 integration)</td><td>55 files</td><td>2 smoke (the rest in the monorepo)</td></tr>
-<tr><td>Owner / maintenance risk</td><td>1 maintainer</td><td>no SECURITY.md</td><td>1 main author</td><td>1 author</td><td>1 author, 0.1 → 1.2 in ~80 days</td><td>1 author</td><td>1 author, 0.x</td><td>no SECURITY.md</td><td>vendor</td><td>vendor, old toolchain</td><td>vendor</td><td>vendor</td><td>vendor</td><td>vendor</td></tr>
+<tr class="ml-matrix-group"><td colspan="16"><strong>Runtimes (from imports and CI, not run)</strong></td></tr>
+<tr><td>Node.js, minimum version</td><td>✅ ≥22, CI on 22 and 24</td><td>✅ ≥20</td><td>⚠️ ≥18, CI 20+</td><td>✅ ≥20</td><td>✅ ≥20.11</td><td>✅ ≥18</td><td>❌ Workers only</td><td>⚠️ needs a connector of your own</td><td>✅ no <code>engines</code> field</td><td>✅ ≥20</td><td>✅ ≥12</td><td>✅ ≥18</td><td>✅ ≥18</td><td>✅ ≥16.20</td><td>✅ ≥20</td></tr>
+<tr><td>Deno</td><td>❌ not a target</td><td>❌ not declared</td><td>❌ not declared</td><td>✅ CI: deno test</td><td>⚠️ HTTP drivers, not SMTP</td><td>✅ <code>Deno.connect</code></td><td>❌</td><td>✅ edge-mailer/deno</td><td>⚠️ browser-entry</td><td>⚠️ <code>fetch</code>, not tested</td><td>⚠️ through Node compatibility</td><td>⚠️ not declared</td><td>⚠️ <code>fetch</code>, not declared</td><td>⚠️ not declared</td><td>⚠️ through <code>npm:</code></td></tr>
+<tr><td>Bun</td><td>❌ not a target</td><td>✅ CI: test:bun</td><td>❌ not declared</td><td>✅ CI: bun test</td><td>✅ CI: bun</td><td>✅ CI: bun test</td><td>❌</td><td>❌ no connector</td><td>⚠️ browser-entry</td><td>⚠️ fetch</td><td>⚠️ through Node compatibility</td><td>⚠️ not declared</td><td>⚠️ not declared</td><td>⚠️ not declared</td><td>⚠️ through Node compatibility</td></tr>
+<tr><td>Cloudflare Workers / edge</td><td>❌ not a target yet</td><td>⚠️ only with <code>nodejs_compat</code></td><td>❌</td><td>⚠️ HTTP packages yes, SMTP no</td><td>⚠️ HTTP + 3 Cloudflare drivers, no SMTP</td><td>✅ HTTP + SMTP (cloudflare:sockets)</td><td>✅ the only target</td><td>✅ no <code>node:*</code></td><td>⚠️ browser-entry</td><td>⚠️ <code>fetch</code>, not tested</td><td>⚠️ <code>fs</code>, axios; not declared</td><td>⚠️ <code>fetch</code> mode</td><td>⚠️ declared in 5.0.0</td><td>❌ <code>http</code>/<code>https</code> agents</td><td>⚠️ explicit credentials needed</td></tr>
+<tr><td>Browser</td><td>❌ by design</td><td>❌</td><td>❌</td><td>⚠️ no target, no tests</td><td>✅ HTTP drivers only</td><td>⚠️ throws</td><td>❌</td><td>❌</td><td>✅ browser-bundle</td><td>⚠️ secret key in the client</td><td>❌</td><td>✅ needs a CORS proxy</td><td>❌</td><td>❌</td><td>✅ explicit credentials</td></tr>
+<tr class="ml-matrix-group"><td colspan="16"><strong>Transports and delivery reliability</strong></td></tr>
+<tr><td>SMTP client</td><td>✅ PIPELINING, SIZE, DSN</td><td>✅ SMTP + LMTP</td><td>✅ no LMTP</td><td>✅ PIPELINING, SIZE, DSN</td><td>✅ own implementation</td><td>✅ own implementation</td><td>✅</td><td>✅</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr><td>Sendmail / local binary</td><td>❌</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr><td>JMAP</td><td>✅ RFC 8620/8621</td><td>❌</td><td>❌</td><td>✅ RFC 8620/8621</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr><td>HTTP providers, count</td><td>8</td><td>1 (SES, needs the SDK)</td><td>0</td><td>8</td><td>18 + http + 2 CF</td><td>14 + CF binding</td><td>0</td><td>0</td><td>—</td><td>1</td><td>1</td><td>1</td><td>1</td><td>1</td><td>1</td></tr>
+<tr><td>Failover between providers</td><td>✅ RR, weighted, priority; no health yet<sup>1</sup></td><td>⚠️ host DNS fallback only</td><td>❌</td><td>✅ RR, weighted, priority</td><td>✅ fallback, RR, weighted, tee</td><td>✅ fallback + weighted</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ multi-region endpoint on the AWS side</td></tr>
+<tr><td>SMTP connection pool</td><td>✅ on by default, 5</td><td>✅ max 5, 100 msg</td><td>❌ one connection</td><td>✅ on by default</td><td>✅ off by default</td><td>✅ off by default</td><td>❌</td><td>✅</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
+<tr><td>Retry / backoff</td><td>✅ jitter, <code>Retry-After</code>, no blind resend<sup>1</sup></td><td>⚠️ requeue in the pool only</td><td>⚠️ 1 retry on 450/451</td><td>✅ jitter, Retry-After</td><td>✅ 5 modes, jitter</td><td>✅ no jitter, retries SMTP 5xx</td><td>❌</td><td>❌ <code>retryHint</code> only</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>✅ standard / adaptive</td></tr>
+<tr><td>Rate limiting</td><td>⚠️ <code>sendMany</code> concurrency; token bucket planned</td><td>✅ <code>rateLimit</code> in the pool</td><td>❌</td><td>⚠️ <code>sendMany</code> only</td><td>✅ token bucket</td><td>⚠️ pool + <code>sendBulk</code></td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>⚠️ contact importer only</td><td>❌</td><td>⚠️ 429 → error</td><td>❌</td><td>⚠️ adaptive retry</td></tr>
+<tr><td>Circuit breaker</td><td>🔜 one probe in half-open<sup>2</sup></td><td>❌</td><td>❌</td><td>❌</td><td>✅ half-open without a single probe</td><td>⚠️ <code>cooldownMs</code></td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr><td>Timeout / AbortSignal</td><td>✅ <code>signal</code> + timeout over the body</td><td>⚠️ timeouts, no <code>AbortSignal</code></td><td>⚠️ timeout, no signal</td><td>✅ <code>signal</code> + timeout</td><td>⚠️ signal for HTTP, not SMTP</td><td>⚠️ SMTP connect only</td><td>⚠️ socket timeouts</td><td>✅ signal on connect and send</td><td>—</td><td>⚠️ signal, no timeout</td><td>⚠️ global signal only</td><td>⚠️ timeout, no signal</td><td>⚠️ 180 s timeout</td><td>⚠️ hard 10 s</td><td>✅ <code>abortSignal</code> + <code>requestTimeout</code></td></tr>
+<tr><td>Persistent queue (survives a restart)</td><td>🔜 MongoDB outbox, BullMQ driver<sup>2</sup></td><td>❌</td><td>❌</td><td>❌</td><td>🔜 planned</td><td>❌</td><td>❌</td><td>⚠️ sample outbox only</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr class="ml-matrix-group"><td colspan="16"><strong>Messages</strong></td></tr>
+<tr><td>Attachments</td><td>⚠️ bytes, Promise, Blob, chunk factory</td><td>✅ path, URL, Buffer, stream, data-URI</td><td>⚠️ path, stream, no URL</td><td>⚠️ bytes, Blob, File, factory</td><td>⚠️ bytes, string, URL</td><td>⚠️ bytes + path</td><td>⚠️ base64 only</td><td>⚠️ string, bytes, Blob</td><td>⚠️ base64 only</td><td>⚠️ base64 or URL</td><td>⚠️ base64, helper for <code>Buffer</code></td><td>✅ Buffer, Blob, stream, 50 MB</td><td>✅ base64</td><td>✅ string / Buffer</td><td>✅ <code>Uint8Array</code> or Raw MIME</td></tr>
+<tr><td>Streaming large attachments</td><td>⚠️ SMTP; HTTP providers buffer</td><td>⚠️ SMTP yes; DKIM and SES buffer</td><td>✅</td><td>⚠️ SMTP only</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ accepts a stream</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr><td>Inline images (CID)</td><td>✅ multipart/related</td><td>✅ multipart/related</td><td>⚠️ manual Content-ID</td><td>⚠️ mixed, not related; Mailgun bug</td><td>⚠️ mixed, not related</td><td>⚠️ HTTP: 3 providers only</td><td>❌</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr>
+<tr><td>Sending raw MIME</td><td>⚠️ SMTP/JMAP only</td><td>✅</td><td>❌</td><td>⚠️ SMTP/JMAP only</td><td>⚠️ smtp driver only</td><td>❌</td><td>❌</td><td>❌</td><td>— builds MIME only</td><td>❌</td><td>❌</td><td>✅ <code>/messages.mime</code></td><td>❌</td><td>❌</td><td>✅ <code>Content.Raw</code></td></tr>
+<tr><td>iCalendar</td><td>✅ every METHOD</td><td>✅ <code>icalEvent</code> + METHOD</td><td>⚠️ manual</td><td>✅ every METHOD</td><td>🔜 planned</td><td>❌</td><td>❌</td><td>✅</td><td>⚠️ as an attachment</td><td>❌</td><td>❌</td><td>⚠️ as an attachment</td><td>⚠️ as an attachment</td><td>⚠️ as an attachment</td><td>⚠️ through Raw MIME</td></tr>
+<tr><td>Unicode / IDN</td><td>⚠️ SMTPUTF8, no automatic punycode</td><td>✅ punycode + SMTPUTF8</td><td>⚠️ Q-encoding, no punycode</td><td>⚠️ SMTPUTF8, no automatic punycode</td><td>⚠️ RFC 2047/2231</td><td>⚠️ one RFC 2047 word</td><td>⚠️ RFC 2047</td><td>⚠️ SMTPUTF8, no punycode</td><td>⚠️ Subject as one B-word</td><td>⚠️ UTF-8 JSON</td><td>⚠️ UTF-8 JSON</td><td>❌</td><td>❌</td><td>⚠️ UTF-8 JSON</td><td>⚠️ Charset, no IDN</td></tr>
+<tr><td>List-Unsubscribe</td><td>⚠️ manual header; one-click planned</td><td>✅ <code>list.unsubscribe</code></td><td>❌</td><td>⚠️ manual header</td><td>✅ RFC 8058 oneClick</td><td>❌</td><td>⚠️ headers</td><td>⚠️ headers</td><td>❌</td><td>⚠️ headers, topics</td><td>⚠️ headers, asm</td><td>⚠️ headers</td><td>⚠️ headers</td><td>⚠️ headers</td><td>✅ <code>ListManagementOptions</code></td></tr>
+<tr><td>Built-in templates</td><td>❌ none, by design</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ <code>Renderer</code> interface</td><td>✅ <code>{{var}}</code> + plugins</td><td>❌</td><td>❌</td><td>❌</td><td>✅ Templates API</td><td>✅ dynamic templates</td><td>✅ Templates API</td><td>✅ Templates API</td><td>✅ Templates API</td><td>✅ Templates API</td></tr>
+<tr><td>React Email</td><td>🔜 optional adapter<sup>2</sup></td><td>❌</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr><td>Batch / bulk</td><td>✅ native: Resend, Mailtrap, JMAP; concurrency elsewhere</td><td>❌</td><td>❌</td><td>✅ native: Resend, Mailtrap, JMAP</td><td>✅ <code>sendBatch</code></td><td>⚠️ <code>sendBulk</code>, SendGrid bug</td><td>⚠️ queue per session</td><td>✅</td><td>—</td><td>✅ up to 100, no attachments</td><td>✅ personalizations</td><td>⚠️ <code>recipient-variables</code></td><td>✅ batch + bulk API</td><td>✅ batchSend, 500</td><td>✅ <code>SendBulkEmail</code></td></tr>
+<tr><td>Scheduled sending</td><td>🔜 a delay in the queue<sup>2</sup></td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ 8 drivers</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>✅</td><td>✅ up to 3 days</td><td>❌</td><td>⚠️ campaigns only</td><td>❌</td></tr>
+<tr><td>Tags / metadata</td><td>⚠️ tags in 7 providers</td><td>⚠️ headers; tags on SES only</td><td>⚠️ headers</td><td>⚠️ tags in 7 providers</td><td>✅</td><td>⚠️ headers only</td><td>⚠️ headers</td><td>⚠️ headers</td><td>⚠️ headers</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr>
+<tr><td>Open/click tracking</td><td>⚠️ config only</td><td>❌</td><td>❌</td><td>⚠️ config only</td><td>✅ 10 drivers</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>⚠️ per domain</td><td>✅</td><td>✅</td><td>✅</td><td>⚠️ per domain</td><td>✅ per-message override</td></tr>
+<tr><td>Idempotency key</td><td>⚠️ Resend, Lettermint, Maileroo; outbox key planned</td><td>❌</td><td>❌</td><td>⚠️ Resend, Lettermint, Maileroo</td><td>✅ middleware + providers</td><td>⚠️ decorator; batch bypasses it</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr class="ml-matrix-group"><td colspan="16"><strong>Security and authentication</strong></td></tr>
+<tr><td>DKIM signing in the library</td><td>✅ RSA + Ed25519, streaming, over-signing</td><td>✅ RSA-SHA256</td><td>❌</td><td>✅ RSA + Ed25519, streaming</td><td>✅ RSA + Ed25519, SMTP only</td><td>⚠️ body canonicalization bug</td><td>❌</td><td>✅ RSA</td><td>❌</td><td>⚠️ keys through the API</td><td>⚠️ whitelabel, generic</td><td>⚠️ keys through the API</td><td>⚠️ keys through the API</td><td>⚠️ domain DNS records</td><td>⚠️ Easy / BYO DKIM</td></tr>
+<tr><td>OAuth2 for SMTP</td><td>✅ refresh, OAUTHBEARER</td><td>✅ refresh + service account</td><td>⚠️ bearer token only</td><td>✅ refresh, OAUTHBEARER</td><td>⚠️ callback, no refresh</td><td>✅ refresh client</td><td>❌</td><td>⚠️ no refresh</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
+<tr><td>ARC</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
+<tr><td>DSN</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
+<tr><td>Proxy</td><td>⚠️ HTTP through an injected <code>fetch</code>; SMTP no</td><td>⚠️ HTTP CONNECT, SOCKS through a module</td><td>❌</td><td>❌</td><td>⚠️ custom <code>fetch</code></td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>⚠️ <code>baseUrl</code> only</td><td>⚠️ axios proxy</td><td>✅</td><td>⚠️ custom fetch + undici</td><td>⚠️ environment only</td><td>⚠️ through <code>requestHandler</code></td></tr>
+<tr><td><code>verify()</code> / connection check</td><td>⚠️ SMTP/JMAP only</td><td>✅</td><td>⚠️ VRFY, not a check</td><td>⚠️ SMTP/JMAP only</td><td>⚠️ <code>isAvailable()</code>, nominal</td><td>✅</td><td>❌</td><td>⚠️ <code>probe()</code> without auth</td><td>—</td><td>—</td><td>—</td><td>⚠️ domain DNS only</td><td>⚠️ <code>getServer()</code></td><td>⚠️ <code>getAllAccounts()</code></td><td>⚠️ <code>GetAccount</code></td></tr>
+<tr><td>SMTP AUTH mechanisms</td><td>PLAIN, LOGIN, XOAUTH2, OAUTHBEARER</td><td>PLAIN, LOGIN, CRAM-MD5, XOAUTH2</td><td>CRAM-MD5, LOGIN, PLAIN, XOAUTH2</td><td>PLAIN, LOGIN, XOAUTH2, OAUTHBEARER</td><td>PLAIN, LOGIN, CRAM-MD5, XOAUTH2</td><td>PLAIN, LOGIN, CRAM-MD5, XOAUTH2</td><td>PLAIN, LOGIN, CRAM-MD5</td><td>PLAIN, LOGIN, CRAM-MD5, XOAUTH2</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
+<tr><td>SMTP TLS policies</td><td>✅ <code>requireTls</code>, SNI, CA, cert, <code>minVersion</code></td><td>✅ REQUIRETLS, SNI, no DANE</td><td>⚠️ STARTTLS accepts any certificate</td><td>✅ <code>requireTls</code>, CA, cert, <code>minVersion</code></td><td>✅ <code>requireTLS</code>, off by default</td><td>✅ <code>requireTLS</code> by default with auth</td><td>⚠️ falls back to plaintext + AUTH</td><td>✅ <code>tlsPolicy</code> ×4, REQUIRETLS</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td></tr>
+<tr class="ml-matrix-group"><td colspan="16"><strong>Platform features (events, domains, provider API)</strong></td></tr>
+<tr><td>Webhooks: parsing and signature verification</td><td>🔜 SES (SNS) first, signature required<sup>2</sup></td><td>❌</td><td>❌</td><td>❌</td><td>🔜 planned</td><td>✅ 10 parsers, HMAC in 5</td><td>❌</td><td>❌</td><td>—</td><td>✅ standardwebhooks</td><td>✅ ECDSA</td><td>⚠️ CRUD, no verification</td><td>⚠️ CRUD + types, no verification</td><td>✅ HMAC verify</td><td>❌ SNS signature not in the SDK</td></tr>
+<tr><td>Inbound mail</td><td>❌ out of scope</td><td>❌</td><td>❌</td><td>❌</td><td>🔜 planned</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>⚠️ parser with a bug</td><td>⚠️ routes</td><td>✅</td><td>✅</td><td>❌ legacy <code>client-ses</code> only</td></tr>
+<tr><td>Suppression / bounce API</td><td>🔜 per tenant, before the queue<sup>2</sup></td><td>❌</td><td>❌</td><td>❌</td><td>🔜 planned</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>⚠️ generic client</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr>
+<tr><td>Domain management (API)</td><td>❌ out of scope</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>—</td><td>✅</td><td>⚠️ generic client</td><td>✅</td><td>✅</td><td>✅</td><td>✅ identities</td></tr>
+<tr><td>Address validation</td><td>⚠️ RFC 5322/6531 syntax</td><td>⚠️ parser only</td><td>⚠️ parser only</td><td>⚠️ RFC 5322/6531 syntax</td><td>⚠️ regex</td><td>⚠️ regex</td><td>❌</td><td>❌ syntax assert</td><td>❌</td><td>❌</td><td>❌</td><td>✅ <code>/v4/address/validate</code></td><td>❌</td><td>❌</td><td>✅ <code>GetEmailAddressInsights</code></td></tr>
+<tr><td>Sending log on the provider side</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>✅ logs API</td><td>⚠️ generic /v3/messages</td><td>✅ logs API</td><td>⚠️ events, opens, clicks</td><td>⚠️ <code>emailLogs</code></td><td>⚠️ event destinations + archiving</td></tr>
+<tr><td>Provider API coverage</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>—</td><td>18 namespaces, ~117 calls</td><td>only mail/send typed; ~251 endpoints in USAGE.md</td><td>21 clients, ~155 calls</td><td>85 methods</td><td>~126 calls</td><td>116 commands</td></tr>
+<tr><td>Multi-channel: SMS, WhatsApp, push</td><td>❌ out of scope</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>✅ SMS, WhatsApp, webpush, FCM</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr class="ml-matrix-group"><td colspan="16"><strong>Observability and extensibility</strong></td></tr>
+<tr><td>OpenTelemetry</td><td>✅ decorator: spans + metrics</td><td>❌</td><td>❌</td><td>✅ decorator: spans + metrics</td><td>⚠️ <code>withLogger</code></td><td>⚠️ hooks + <code>consoleObserver</code></td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ <code>middlewareStack</code></td></tr>
+<tr><td>Hooks / middleware</td><td>⚠️ decorators, <code>onRetry</code>, a pino-like logger</td><td>✅ <code>use(compile|stream)</code></td><td>⚠️ logger function</td><td>⚠️ decorators, LogTape</td><td>✅ Middleware pipeline</td><td>✅ hooks + plugins</td><td>⚠️ logger</td><td>✅ <code>onEvent</code></td><td>⚠️ <code>dump()</code></td><td>⚠️ <code>console.error</code></td><td>⚠️ <code>setClient</code></td><td>❌</td><td>❌</td><td>❌</td><td>✅ logger + <code>middlewareStack</code></td></tr>
+<tr><td>Mock / test mode</td><td>✅ <code>./mock</code></td><td>✅ <code>jsonTransport</code>, <code>streamTransport</code>, Ethereal</td><td>⚠️ <code>Message#read()</code></td><td>✅ <code>@upyo/mock</code></td><td>✅ mock + Mailpit</td><td>⚠️ preview, Mailpit</td><td>❌</td><td>❌</td><td>—</td><td>❌</td><td>✅ <code>sandboxMode</code></td><td>✅ <code>testmode</code></td><td>⚠️ Sandbox server</td><td>✅ <code>Sandbox API</code></td><td>⚠️ <code>TestRenderEmailTemplate</code></td></tr>
+<tr><td>Local audit log / event journal</td><td>🔜 append-only, crypto-shredding<sup>2</sup></td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>⚠️ events, not stored</td><td>—</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td></tr>
+<tr class="ml-matrix-group"><td colspan="16"><strong>Quality, license, maturity</strong></td></tr>
+<tr><td>TypeScript types</td><td>✅ hand-written, tsd</td><td>✅ built in</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td><td>✅ hand-written <code>.d.ts</code></td><td>✅</td><td>✅</td><td>✅</td><td>✅ generated</td></tr>
+<tr><td>Runtime dependencies</td><td>0</td><td>0</td><td>0</td><td>0–1 (@noble/hashes)</td><td>0</td><td>0</td><td>0</td><td>0</td><td>4</td><td>2</td><td>2+ (axios)</td><td>3 (axios)</td><td>0</td><td>2 (axios, qs)</td><td>9</td></tr>
+<tr><td>Module format</td><td>CJS, ESM <code>import</code></td><td>ESM + CJS</td><td>ESM only</td><td>ESM + CJS + JSR</td><td>ESM only</td><td>ESM only</td><td>ESM + CJS</td><td>ESM + CJS + JSR</td><td>ESM + CJS</td><td>ESM + CJS</td><td>CJS only</td><td>ESM + CJS</td><td>CJS only</td><td>CJS only</td><td>ESM + CJS</td></tr>
+<tr><td>License</td><td>MIT</td><td>MIT-0</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>Apache-2.0</td></tr>
+<tr><td>Version (2026-10-07)</td><td>0.0.1 (unreleased)</td><td>10.0.16</td><td>5.0.3</td><td>0.7.0 (unreleased; release 0.6.0)</td><td>0.7.0</td><td>1.2.2</td><td>1.2.1</td><td>0.8.5</td><td>3.0.24 (tag 3.0.28)</td><td>6.32.1</td><td>8.1.6</td><td>14.0.2</td><td>5.1.0</td><td>4.10.0 (HEAD ahead)</td><td>3.1147.0</td></tr>
+<tr><td>Last commit</td><td>2026-10 (in development)</td><td>2026-10-07</td><td>2026-08-26</td><td>2026-09-09</td><td>2026-09-02</td><td>2026-08-19</td><td>2025-11-15</td><td>2026-09-08</td><td>2026-01-28</td><td>2026-10-06</td><td>2025-09-19</td><td>2026-10-07</td><td>2026-07-10</td><td>2026-10-07</td><td>2026-10-06</td></tr>
+<tr><td>Tests: files / cases</td><td>126 / ~1440</td><td>61 / ~1330</td><td>15 / ~153</td><td>109 / ~1300</td><td>40 / ~773</td><td>66 / ~532</td><td>4 / ~189</td><td>14 / ~258</td><td>6 / ~30</td><td>39 / ~441</td><td>43 / ~450</td><td>49 files</td><td>23 (16 integration)</td><td>55 files</td><td>2 smoke (the rest in the monorepo)</td></tr>
+<tr><td>Owner / maintenance risk</td><td>1 author, Alexis Technologies</td><td>1 maintainer</td><td>no SECURITY.md</td><td>1 main author</td><td>1 author</td><td>1 author, 0.1 → 1.2 in ~80 days</td><td>1 author</td><td>1 author, 0.x</td><td>no SECURITY.md</td><td>vendor</td><td>vendor, old toolchain</td><td>vendor</td><td>vendor</td><td>vendor</td><td>vendor</td></tr>
 </tbody>
 </table>
 
 </div>
 
-✅ in the code · ⚠️ partial, or only on the provider side · ❌ none · 🔜 planned by the author, no code yet · — does not apply. Every cell was decided by reading the source of the project as of 2026-10-07, not its README.
-
+✅ in the code · ⚠️ partial, or only on the provider side · ❌ none · 🔜 planned by the author, no code yet · — does not apply. Every cell was decided by reading the source of the project as of 2026-10-07, not its README; the column of @alexify/mailer is this repository as of 2026-10-17.
 
+1. A failure after which the provider may have taken the message is marked <code>deliveryUnknown</code>: <code>./retry</code> does not retry it and <code>./pool</code> does not fail over with it.
+2. On the <a href="/guide/why#the-plan">roadmap</a> of the reliability layer: designed, with no code yet.
 
 <!-- comparison:end -->
 
@@ -130,6 +134,11 @@ convenient libraries in a few convenient rows.
 
 - **From the code, not the README.** Every cell was decided by reading the source of a local
   clone of each project as of 2026-10-07.
+- **The column of @alexify/mailer is this repository,** as of 2026-10-17. ✅ and ⚠️ are code that
+  is here: the transport ported from upyo, with the upstream bugs fixed since. 🔜 is the
+  reliability layer of [the plan](/guide/why#the-plan), designed but with no code yet. Its gaps
+  are shown as such: no Deno, Bun or edge runtime, no rate limit beyond the concurrency of
+  `sendMany`, and streaming only over SMTP.
 - **Defects were not reproduced,** except in emailjs, which was run against fake SMTP servers. A
   cell that names a bug is a finding from reading the code; reproduce it before relying on it.
 - **Runtimes were not run.** Deno, Bun and Workers support is inferred from imports, `exports`
diff --git a/scripts/comparison.js b/scripts/comparison.js
index 016b1c3..e17a008 100644
--- a/scripts/comparison.js
+++ b/scripts/comparison.js
@@ -1,14 +1,17 @@
 /**
- * The feature matrix of docs/guide/comparison.md: one table, the alternatives
- * in columns, the features in rows grouped by area, rendered from
- * docs/comparison.json into the region between `<!-- comparison:start -->`
- * and `<!-- comparison:end -->`, so the table and the data cannot drift (CI
- * regenerates it and fails on a diff). A cell is `{ mark, text, note? }`: the
- * mark is one of ✅ ⚠️ ❌ 🔜 —, the text a few words (backticks become code),
- * and a note becomes a numbered footnote under the table.
+ * The feature matrix of docs/guide/comparison.md: one table, @alexify/mailer
+ * and the alternatives in columns, the features in rows grouped by area,
+ * rendered from docs/comparison.json into the region between
+ * `<!-- comparison:start -->` and `<!-- comparison:end -->`, so the table and
+ * the data cannot drift (CI regenerates it and fails on a diff). A cell is
+ * `{ mark, text, note? }`: the mark is one of ✅ ⚠️ ❌ 🔜 —, the text a few
+ * words (backticks become code), and a note becomes a numbered footnote under
+ * the table.
  *
- * Every cell of the data was decided by reading the source of the project
- * (see the page for the method); edit the data, not the table.
+ * The first library of the data is @alexify/mailer: custom.css tints the
+ * second column of the table in the brand colour and pins it beside the
+ * features. Every cell of the data was decided by reading the source of the
+ * project (see the page for the method); edit the data, not the table.
  *
  * Run: pnpm docs:comparison
  */

From 7b81d7b4922e35045a5d602d93a868f58f7fbe67 Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Sat, 17 Oct 2026 16:20:46 +0300
Subject: [PATCH 157/158] chore(release): v1.0.0

The first release: the transport layer ported from upyo 0.7.0, with the
upstream bugs fixed since. The version goes to 1.0.0 in package.json and
src/version.js, CHANGELOG turns [Unreleased] into [1.0.0] with a section
on upgrading from upyo 0.7, and the work-in-progress notes, the package
description, llms.txt, SECURITY.md and the comparison now say what 1.0
holds and that the reliability layer is still being designed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                  | 49 +++++++++++++++++++++++++++--------
 CLAUDE.md                     |  6 ++---
 README.md                     |  8 +++---
 SECURITY.md                   |  6 ++---
 docs/.vitepress/config.mts    |  6 ++---
 docs/comparison.json          |  4 +--
 docs/guide/comparison.md      | 14 +++++-----
 docs/guide/getting-started.md |  6 ++---
 docs/guide/why.md             |  4 +--
 docs/public/llms.txt          |  4 +--
 package.json                  |  4 +--
 src/version.js                |  2 +-
 12 files changed, 70 insertions(+), 43 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e2090c8..5a2bd2c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,11 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-The transport layer, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0 (MIT, © 2025
-Hong Minhee): the code is upstream's, converted to CommonJS with hand-written types and no
-runtime dependency, one subpath per upstream package. Upstream's known bugs are fixed one by one:
-the open ones are on the [Known issues](https://mailerat.vercel.app/guide/known-issues) page, the
-fixed ones below.
+## [1.0.0] - 2026-10-17
+
+The first release: the transport layer, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0
+(MIT, © 2025 Hong Minhee). The code is upstream's, converted to CommonJS with hand-written types
+and no runtime dependency, one subpath per upstream package. Upstream's known bugs are fixed one
+by one: the open ones are on the [Known issues](https://mailerat.vercel.app/guide/known-issues)
+page, the fixed ones below. The reliability layer (a persistent queue, an audit log, delivery
+events) is being designed and is not in this release.
+
+### Upgrading from upyo 0.7
+
+The messages, the `Transport` contract and the options of each transport are upyo's. What changes
+for code written against upyo 0.7:
+
+- **One package, a subpath per upstream package.** `@upyo/core` is the root entry,
+  `@upyo/smtp` is `@alexify/mailer/smtp`, and so on for every transport and decorator;
+  `@upyo/opentelemetry` is `./otel` and `@upyo/logtape` is `./logger`. The package is CommonJS,
+  with the same names importable from ESM, and needs Node.js 22 or newer; Deno, Bun and browsers
+  are not targets.
+- **A failed receipt may carry `deliveryUnknown: true`:** the provider may have taken the message
+  before the failure. Such a receipt is never retryable; reconcile it rather than send the message
+  again.
+- **`./otel` uses the providers you pass** (`tracerProvider`, `meterProvider`) and names its
+  metrics and attributes after the semantic conventions (see Changed). `auto`, `serviceName`,
+  `serviceVersion` and `metrics.samplingRate` throw a `TypeError`.
+- **`./logger` takes any pino-like logger** in place of a LogTape one.
+- **Options that never did anything throw:** `continueOnSuccess: true` of `./pool`,
+  `validateSsl: false` of the HTTP providers and `method: 'cram-md5'` of `./smtp`.
+- **Input is checked where it is made:** an address domain is held to host-name characters, a
+  display name may not hold a line break, a provider URL must be HTTPS (plain HTTP only to a
+  loopback host), an SES region must look like one, and `timeout` and `retries` must be
+  non-negative numbers.
 
 ### Added
 
@@ -377,6 +404,10 @@ fixed ones below.
   was never called. Through the new `onRetry`, each retry of the wrapped transport or of a
   `./retry` inside it now adds a `retry` event and to `mailer.retry.count` on the span, and to
   a new counter of retries, and still reaches the caller's own `onRetry`.
+- **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
+  (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
+  any step or after DATA; the greeting waits for a complete line; and a UTF-8 character split
+  across two chunks of a reply stays whole.
 
 ### Changed
 
@@ -396,9 +427,5 @@ fixed ones below.
   `./resend`, `./sendgrid`, `./mailgun`, `./plunk` and `./jmap` used to retry no 4xx at all, and
   waited without jitter, the first three without a cap.
 
-- **`./smtp` reads every well-formed reply** (upstream bugs): a final line that is the code alone
-  (`250`), which RFC 5321 allows, no longer leaves the client waiting for the socket timeout, at
-  any step or after DATA; the greeting waits for a complete line; and a UTF-8 character split
-  across two chunks of a reply stays whole.
-
-[unreleased]: https://github.com/Alexis-Technologies/mailer/commits/main
+[unreleased]: https://github.com/Alexis-Technologies/mailer/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/Alexis-Technologies/mailer/releases/tag/v1.0.0
diff --git a/CLAUDE.md b/CLAUDE.md
index a2b2102..ee0ab76 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,9 +17,9 @@ Nodemailer, emailjs or Upyo, made of two parts:
 
 It has zero runtime dependencies and runs on Node.js ≥ 22 only (no browser entry).
 
-**Status: the transport is ported, the reliability layer is being designed.** The root entry
-exports the message model and the transport contract of upyo, each transport and decorator is a
-subpath. The reliability layer (queue, audit log, delivery events) has no API yet; its direction
+**Status: 1.0.0 is the ported transport, the reliability layer is being designed.** The root
+entry exports the message model and the transport contract of upyo, each transport and decorator
+is a subpath, and their API is under semver from 1.0.0. The reliability layer (queue, audit log, delivery events) has no API yet; its direction
 is in "Roadmap" below.
 
 It is maintained by Alexis Technologies and set up like the sibling libraries
diff --git a/README.md b/README.md
index c4e8a76..dc39a8b 100644
--- a/README.md
+++ b/README.md
@@ -12,10 +12,10 @@ and HTTP providers, and on top of them what the other libraries leave to the app
 persistent queue and outbox, an audit log, one model of delivery events, suppression and
 idempotency. Zero runtime dependencies.
 
-> 🚧 **Work in progress.** The transport layer is here, ported from
-> [upyo](https://github.com/dahlia/upyo) 0.7.0: messages, MIME and DKIM, SMTP, Amazon SES and seven
-> more HTTP providers, JMAP, and the pool, retry, OpenTelemetry, logger and mock transports. The
-> reliability layer (queue, audit log, delivery events) is being designed.
+> **Status: 1.0 is the transport layer,** ported from [upyo](https://github.com/dahlia/upyo) 0.7.0:
+> messages, MIME and DKIM, SMTP, Amazon SES and seven more HTTP providers, JMAP, and the pool,
+> retry, OpenTelemetry, logger and mock transports. The reliability layer (queue, audit log,
+> delivery events) is being designed and comes in later releases.
 
 ### 📖 [Read the documentation →](https://mailerat.vercel.app/)
 
diff --git a/SECURITY.md b/SECURITY.md
index 45ef67f..7003714 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -6,7 +6,7 @@ Only the latest published version receives fixes.
 
 | Version | Supported |
 |---|---|
-| 0.x | ✅ |
+| 1.x | ✅ |
 
 ## Reporting a vulnerability
 
@@ -28,8 +28,8 @@ timeline once the report is confirmed.
 
 ## Threat model
 
-The mailer is still being designed, and this section will be completed with it. The principles it
-is designed around:
+The transport layer is built and the reliability layer is being designed; this section will be
+completed with it. The principles both are designed around:
 
 - **Message content is untrusted data.** Addresses, display names, subjects, headers, file names
   and bodies can come from users. A CR or LF in any header field is rejected rather than encoded
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index b6844bd..2792539 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -7,9 +7,9 @@ const { version } = createRequire(import.meta.url)('../../package.json') as { ve
 
 const ogTitle = '@alexify/mailer — email for Node.js, with a reliability layer';
 const ogDescription =
-  'Zero-dependency email for Node.js: its own SMTP client, MIME builder, DKIM and HTTP ' +
-  'providers, with a reliability layer on top — a persistent queue, an audit log, delivery ' +
-  'events, suppression and idempotency.';
+  'Zero-dependency email for Node.js: its own SMTP client, MIME builder, DKIM, Amazon SES and ' +
+  'seven more HTTP providers, JMAP, failover, retries and OpenTelemetry; a reliability layer ' +
+  '(persistent queue, audit log, delivery events) is next.';
 const repo = 'https://github.com/Alexis-Technologies/mailer';
 const base = '/';
 const hostname = 'https://mailerat.vercel.app/';
diff --git a/docs/comparison.json b/docs/comparison.json
index 2886df6..babe372 100644
--- a/docs/comparison.json
+++ b/docs/comparison.json
@@ -492,10 +492,10 @@
           "text": "MIT"
         },
         "version": {
-          "text": "0.0.1 (unreleased)"
+          "text": "1.0.0"
         },
         "lastCommit": {
-          "text": "2026-10 (in development)"
+          "text": "2026-10 (this release)"
         },
         "tests": {
           "text": "126 / ~1440"
diff --git a/docs/guide/comparison.md b/docs/guide/comparison.md
index 0cc7a96..697b049 100644
--- a/docs/guide/comparison.md
+++ b/docs/guide/comparison.md
@@ -1,10 +1,10 @@
 # Compared with alternatives
 
-@alexify/mailer is being built in the place of the libraries below, with a reliability layer none
-of them has. The table compares fourteen solutions in five directions: SMTP clients (Nodemailer,
-emailjs), unified libraries over many providers (Upyo, unemail, sently), SMTP for edge runtimes
-(worker-mailer, edge-mailer), a MIME builder (MIMEText) and the official SDKs of the providers
-(Resend, SendGrid, Mailgun, Postmark, Mailtrap, Amazon SES). It follows the idea of
+@alexify/mailer is an email library in the place of the libraries below, built towards a
+reliability layer none of them has. The table compares fourteen solutions in five directions: SMTP
+clients (Nodemailer, emailjs), unified libraries over many providers (Upyo, unemail, sently), SMTP
+for edge runtimes (worker-mailer, edge-mailer), a MIME builder (MIMEText) and the official SDKs of
+the providers (Resend, SendGrid, Mailgun, Postmark, Mailtrap, Amazon SES). It follows the idea of
 [Upyo's own comparison](https://upyo.org/why), with every feature in one table rather than a few
 convenient libraries in a few convenient rows. @alexify/mailer itself is the first column, in teal
 and, on a wide screen, pinned beside the features as the table scrolls, so every row reads against
@@ -114,8 +114,8 @@ it.
 <tr><td>Runtime dependencies</td><td>0</td><td>0</td><td>0</td><td>0–1 (@noble/hashes)</td><td>0</td><td>0</td><td>0</td><td>0</td><td>4</td><td>2</td><td>2+ (axios)</td><td>3 (axios)</td><td>0</td><td>2 (axios, qs)</td><td>9</td></tr>
 <tr><td>Module format</td><td>CJS, ESM <code>import</code></td><td>ESM + CJS</td><td>ESM only</td><td>ESM + CJS + JSR</td><td>ESM only</td><td>ESM only</td><td>ESM + CJS</td><td>ESM + CJS + JSR</td><td>ESM + CJS</td><td>ESM + CJS</td><td>CJS only</td><td>ESM + CJS</td><td>CJS only</td><td>CJS only</td><td>ESM + CJS</td></tr>
 <tr><td>License</td><td>MIT</td><td>MIT-0</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>MIT</td><td>Apache-2.0</td></tr>
-<tr><td>Version (2026-10-07)</td><td>0.0.1 (unreleased)</td><td>10.0.16</td><td>5.0.3</td><td>0.7.0 (unreleased; release 0.6.0)</td><td>0.7.0</td><td>1.2.2</td><td>1.2.1</td><td>0.8.5</td><td>3.0.24 (tag 3.0.28)</td><td>6.32.1</td><td>8.1.6</td><td>14.0.2</td><td>5.1.0</td><td>4.10.0 (HEAD ahead)</td><td>3.1147.0</td></tr>
-<tr><td>Last commit</td><td>2026-10 (in development)</td><td>2026-10-07</td><td>2026-08-26</td><td>2026-09-09</td><td>2026-09-02</td><td>2026-08-19</td><td>2025-11-15</td><td>2026-09-08</td><td>2026-01-28</td><td>2026-10-06</td><td>2025-09-19</td><td>2026-10-07</td><td>2026-07-10</td><td>2026-10-07</td><td>2026-10-06</td></tr>
+<tr><td>Version (2026-10-07)</td><td>1.0.0</td><td>10.0.16</td><td>5.0.3</td><td>0.7.0 (unreleased; release 0.6.0)</td><td>0.7.0</td><td>1.2.2</td><td>1.2.1</td><td>0.8.5</td><td>3.0.24 (tag 3.0.28)</td><td>6.32.1</td><td>8.1.6</td><td>14.0.2</td><td>5.1.0</td><td>4.10.0 (HEAD ahead)</td><td>3.1147.0</td></tr>
+<tr><td>Last commit</td><td>2026-10 (this release)</td><td>2026-10-07</td><td>2026-08-26</td><td>2026-09-09</td><td>2026-09-02</td><td>2026-08-19</td><td>2025-11-15</td><td>2026-09-08</td><td>2026-01-28</td><td>2026-10-06</td><td>2025-09-19</td><td>2026-10-07</td><td>2026-07-10</td><td>2026-10-07</td><td>2026-10-06</td></tr>
 <tr><td>Tests: files / cases</td><td>126 / ~1440</td><td>61 / ~1330</td><td>15 / ~153</td><td>109 / ~1300</td><td>40 / ~773</td><td>66 / ~532</td><td>4 / ~189</td><td>14 / ~258</td><td>6 / ~30</td><td>39 / ~441</td><td>43 / ~450</td><td>49 files</td><td>23 (16 integration)</td><td>55 files</td><td>2 smoke (the rest in the monorepo)</td></tr>
 <tr><td>Owner / maintenance risk</td><td>1 author, Alexis Technologies</td><td>1 maintainer</td><td>no SECURITY.md</td><td>1 main author</td><td>1 author</td><td>1 author, 0.1 → 1.2 in ~80 days</td><td>1 author</td><td>1 author, 0.x</td><td>no SECURITY.md</td><td>vendor</td><td>vendor, old toolchain</td><td>vendor</td><td>vendor</td><td>vendor</td><td>vendor</td></tr>
 </tbody>
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index df49def..9991f3b 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -1,8 +1,8 @@
 # Getting Started
 
-::: warning Work in progress
-The transport layer, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0, is
-here: messages, SMTP, eight HTTP providers, JMAP and the decorators. The reliability
+::: tip Status
+Version 1.0 is the transport layer, ported from [upyo](https://github.com/dahlia/upyo)
+0.7.0: messages, SMTP, eight HTTP providers, JMAP and the decorators. The reliability
 layer (queue, audit log, delivery events) is still being designed.
 :::
 
diff --git a/docs/guide/why.md b/docs/guide/why.md
index 08ab6bb..2f5bdd9 100644
--- a/docs/guide/why.md
+++ b/docs/guide/why.md
@@ -1,7 +1,7 @@
 # Why @alexify/mailer?
 
-::: warning Work in progress
-The transport layer is here, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0. The
+::: tip Status
+Version 1.0 is the transport layer, ported from [upyo](https://github.com/dahlia/upyo) 0.7.0. The
 reliability layer is being designed: the direction below is settled, its API is not.
 :::
 
diff --git a/docs/public/llms.txt b/docs/public/llms.txt
index 1ba510e..0e2da44 100644
--- a/docs/public/llms.txt
+++ b/docs/public/llms.txt
@@ -6,8 +6,8 @@
 > audit log, one model of delivery events, suppression and idempotency.
 
 Key facts:
-- Status: work in progress. The transport layer is ported from upyo 0.7.0 (MIT); the
-  reliability layer (queue, audit log, delivery events) is being designed
+- Status: 1.0 is the transport layer, ported from upyo 0.7.0 (MIT); the reliability layer
+  (queue, audit log, delivery events) is being designed and is not released yet
 - Package (npm): `@alexify/mailer`, installed with `npm install @alexify/mailer`
 - Node.js >= 22 only; CommonJS with ESM named-import interop; hand-written d.ts per entry
 - Zero runtime dependencies: the transports are built on `node:*` modules and `fetch`; the
diff --git a/package.json b/package.json
index 6ec5c8a..f94795f 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@alexify/mailer",
-  "version": "0.0.1",
-  "description": "Zero-dependency email for Node.js: its own SMTP client, MIME builder, DKIM and HTTP providers, with a reliability layer on top — a persistent queue, an audit log, delivery events, suppression and idempotency",
+  "version": "1.0.0",
+  "description": "Zero-dependency email for Node.js: its own SMTP client, MIME builder, DKIM, Amazon SES and seven more HTTP providers, JMAP, failover, retries and OpenTelemetry; a reliability layer (persistent queue, audit log, delivery events) is next",
   "license": "MIT",
   "author": "Alex Dolid <dolid.sasha@gmail.com>",
   "repository": {
diff --git a/src/version.js b/src/version.js
index 01e944c..7b424aa 100644
--- a/src/version.js
+++ b/src/version.js
@@ -3,4 +3,4 @@
 // require of package.json would bundle the whole manifest into ./otel.
 // tests/unit/version.test.js keeps it equal to package.json, and the release
 // process bumps both.
-module.exports = { name: '@alexify/mailer', version: '0.0.1' };
+module.exports = { name: '@alexify/mailer', version: '1.0.0' };

From ae633f0053467e9846f6b905959ad0a2a8d260fd Mon Sep 17 00:00:00 2001
From: Alex Dolid <dolid.sasha@gmail.com>
Date: Sat, 17 Oct 2026 16:39:27 +0300
Subject: [PATCH 158/158] test(smtp): take EPIPE and ECONNABORTED from a client
 that has gone

SmtpConnection#quit() sends QUIT and closes without waiting for the 221,
so the mock SMTP server's reply to QUIT can meet a closed socket: EPIPE
on Linux, ECONNABORTED on Windows. Only ECONNRESET, what macOS reports,
was taken as the client leaving; the others became an uncaught 'error'
and failed "a pooled connection whose reset fails is replaced" on every
CI job while it passed on macOS. A new test emits each code on a server
socket, so the rule is checked on every platform.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                              | 12 ++++++++----
 tests/helpers/smtp/mock-smtp-server.js | 16 ++++++++++-----
 tests/unit/smtp.test.js                | 27 ++++++++++++++++++++++++++
 3 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index ee0ab76..94f92e8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -645,10 +645,14 @@ change. **This file wins** if they ever disagree.
   inbox is shared; `docker compose -f tests/mailpit/docker-compose.yml up -d` and
   `MAILPIT_SMTP_HOST`/`MAILPIT_API_URL`) and `tests/e2e/` (`pnpm test:e2e`, each suite skipped
   until its provider's variables are set; Stalwart for JMAP in `tests/e2e/jmap/`).
-- **Platform-dependent tests:** the mock SMTP server tolerates a client's connection reset (macOS
-  and Windows send an RST where Linux sends a FIN); the JMAP test of a 401 to a raw message of
-  unknown size, which streams, is `todo` on Node 24 (known upstream bug 14). `tests/unit/export-parity.test.js` also
-  checks that every d.ts using `AsyncDisposable` references `esnext.disposable` itself.
+- **Platform-dependent tests:** the mock SMTP server takes a client that has gone as no failure:
+  a reset (`ECONNRESET`; macOS and Windows send an RST where Linux sends a FIN) and a reply
+  written after the client closed (`EPIPE` on Linux, `ECONNABORTED` on Windows), which the 221 to
+  `QUIT` can always meet, as `quit()` does not wait for it; macOS reports neither, so only CI
+  catches a new one, and Docker (`node:22-bookworm-slim`) reproduces Linux. The JMAP test of a
+  401 to a raw message of unknown size, which streams, is `todo` on Node 24 (known upstream bug
+  14). `tests/unit/export-parity.test.js` also checks that every d.ts using `AsyncDisposable`
+  references `esnext.disposable` itself.
 
 ## Documentation site
 
diff --git a/tests/helpers/smtp/mock-smtp-server.js b/tests/helpers/smtp/mock-smtp-server.js
index 6eb20a6..f640220 100644
--- a/tests/helpers/smtp/mock-smtp-server.js
+++ b/tests/helpers/smtp/mock-smtp-server.js
@@ -5,6 +5,12 @@ const { Buffer } = require('node:buffer');
 const { EventEmitter } = require('node:events');
 const { createServer } = require('node:net');
 
+// What a socket reports once the client has gone: a reset (ECONNRESET), or a
+// reply written after the client closed, which is EPIPE on Linux and
+// ECONNABORTED on Windows. SmtpConnection#quit() sends QUIT and closes without
+// waiting for the 221, so the reply to QUIT can always meet one of them.
+const CLIENT_GONE = new Set(['ECONNRESET', 'EPIPE', 'ECONNABORTED']);
+
 class MockSmtpServer extends EventEmitter {
   server;
   port;
@@ -81,11 +87,11 @@ class MockSmtpServer extends EventEmitter {
       });
 
       socket.on('error', (error) => {
-        // A client may reset the connection as it leaves: macOS and Windows send
-        // an RST when a socket closes with unread data, Linux usually a FIN. That
-        // is no failure of the server, and an 'error' event nobody listens to
-        // would throw.
-        if (error.code === 'ECONNRESET' && this.listenerCount('error') === 0) return;
+        // A client may reset the connection as it leaves (macOS and Windows send
+        // an RST when a socket closes with unread data, Linux usually a FIN), or
+        // close it before a reply is written. That is no failure of the server,
+        // and an 'error' event nobody listens to would throw.
+        if (CLIENT_GONE.has(error.code) && this.listenerCount('error') === 0) return;
         this.emit('error', error);
       });
 
diff --git a/tests/unit/smtp.test.js b/tests/unit/smtp.test.js
index 6d3a481..3e19dcd 100644
--- a/tests/unit/smtp.test.js
+++ b/tests/unit/smtp.test.js
@@ -663,6 +663,33 @@ test('SMTP: a pooled connection whose reset fails is replaced, and an abort reje
   }
 });
 
+test('SMTP: the mock server takes a client that has gone as no failure of its own', async () => {
+  const { connect } = require('node:net');
+  const server = new MockSmtpServer();
+  const port = await server.start();
+  const client = connect(port, '127.0.0.1');
+  try {
+    while (server.connections.size === 0) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    const [socket] = server.connections;
+    const failure = (code) => Object.assign(new Error(`write ${code}`), { code });
+    // A reply written after the client closed: EPIPE on Linux, ECONNABORTED
+    // on Windows, ECONNRESET on macOS.
+    for (const code of ['ECONNRESET', 'EPIPE', 'ECONNABORTED']) {
+      assert.doesNotThrow(() => socket.emit('error', failure(code)), code);
+    }
+    assert.throws(() => socket.emit('error', failure('EACCES')), { code: 'EACCES' });
+    const heard = [];
+    server.on('error', (error) => heard.push(error.code));
+    socket.emit('error', failure('EPIPE'));
+    assert.deepStrictEqual(heard, ['EPIPE']);
+  } finally {
+    client.destroy();
+    await server.stop();
+  }
+});
+
 test('SMTP: an idle pooled connection does not keep the process alive', async () => {
   const { spawn } = require('node:child_process');
   const path = require('node:path');