mailchannels-sdk 1.3.0 → 1.4.0

package/.agents/skills/mailchannels-js/resources/sub-accounts.md

@@ -4,9 +4,7 @@ Sub-accounts are first-class on MailChannels. Use them for tenants, customers, o
 senders so that one customer's reputation, limits, and bad traffic don't contaminate the
 parent account or other tenants.
 
-> Sub-accounts are only available on parent accounts on the 100K and higher plans.
-
-### Handles
+## Handles
 
 A handle uniquely identifies a sub-account. Rules:
 
@@ -15,7 +13,7 @@ A handle uniquely identifies a sub-account. Rules:
 - Unique per parent account.
 - If omitted on create, a random handle is generated.
 
-### Lifecycle
+## Lifecycle
 
 ```ts
 import { MailChannels } from 'mailchannels-sdk'
@@ -43,7 +41,7 @@ const { error: deleteError } = await mc.subAccounts.delete('clienta')
 if (deleteError) { /*...*/ }
 ```
 
-### Credentials
+## Credentials
 
 Each sub-account has its own API keys and SMTP passwords.
 
@@ -76,7 +74,7 @@ create time. Store it immediately or rotate. Each sub-account has server-side ca
 many API keys and SMTP passwords it can hold — once at the cap, create returns
 `unprocessable_entity_error`; delete an unused credential first.
 
-### Limits
+## Limits
 
 Per-sub-account monthly send caps. A sub-account without a limit inherits the parent's
 capacity.
@@ -92,7 +90,7 @@ const { error: deleteLimitErr } = await mc.subAccounts.limits.delete('clienta')
 if (deleteLimitErr) { /*...*/ }
 ```
 
-### Usage
+## Usage
 
 ```ts
 const { data: parentUsage } = await mc.metrics.usage()
@@ -104,7 +102,7 @@ console.log(parentUsage?.total, parentUsage?.startDate, parentUsage?.endDate)
 `mc.metrics.usage()` is for the parent account. Use `mc.subAccounts.getUsage(handle)` for
 one specific sub-account.
 
-### Sending As A Sub-Account
+## Sending As A Sub-Account
 
 Create a separate `MailChannels` instance with the sub-account's API key:
 
@@ -123,7 +121,7 @@ if (error) { /*...*/ }
 This keeps the account boundary explicit in code and avoids hard-to-debug issues where the
 wrong key is used at the wrong call site.
 
-### Suppressions And Sub-Accounts
+## Suppressions And Sub-Accounts
 
 When creating suppressions on the parent, set `addToSubAccounts: true` to also copy entries
 into every sub-account. See [suppressions](suppressions.md).

package/.agents/skills/mailchannels-js/resources/suppressions.md

@@ -3,7 +3,7 @@
 A suppression list keeps known-bad or opted-out recipients out of future sends. MailChannels
 suppresses by recipient + suppression type + source.
 
-### Create Entries
+## Create Entries
 
 ```ts
 import { MailChannels } from 'mailchannels-sdk'
@@ -38,7 +38,7 @@ Constraints:
 All entries created via this endpoint have an inherent source of `'api'`.
 The endpoint does not have a field to set the source value.
 
-### List Entries
+## List Entries
 
 ```ts
 const { data, error } = await mc.suppressions.list({
@@ -67,7 +67,7 @@ const { data: recent } = await mc.suppressions.list({
 
 Date formats accepted: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SSZ`, or a `Date` object.
 
-### Delete An Entry
+## Delete An Entry
 
 Warning:
 Do not remove entries from the suppression list if the recipient has not explicitly opted back in.
@@ -81,7 +81,7 @@ const { error: delAllErr } = await mc.suppressions.delete('recipient@example.net
 If `source` is omitted it defaults to `'api'`. Use `'all'` to remove every suppression for
 that recipient regardless of origin.
 
-### Patterns
+## Patterns
 
 - **Preference center opt-out**: set `types` according to the email category, e.g. `non-transactional` for marketing
   emails, `transactional` for order updates, and so on.

package/.agents/skills/mailchannels-js/resources/templates.md

@@ -8,7 +8,7 @@ no "create template" endpoint. To use a template:
 
 The only supported template type is `'mustache'`.
 
-### Single Recipient
+## Single Recipient
 
 ```ts
 import { MailChannels } from 'mailchannels-sdk'
@@ -28,7 +28,7 @@ const { data, error } = await mc.emails.queue({
 })
 ```
 
-### Multiple Recipients With Per-Recipient Variables
+## Multiple Recipients With Per-Recipient Variables
 
 Each personalization renders independently with its own variables. Root-level
 `template.data` is the base; per-personalization `template.data` is merged on top
@@ -56,7 +56,7 @@ const { data, error } = await mc.emails.queue({
 })
 ```
 
-### Allowed Template Variable Value Types
+## Allowed Template Variable Value Types
 
 Keys are strings. Values may be:
 
@@ -69,12 +69,12 @@ Keys are strings. Values may be:
 `null`, `undefined`, and class instances are rejected with a `validation_error` before
 the request leaves the client.
 
-### Subject Templates
+## Subject Templates
 
 The root `subject` field is **also** mustache-rendered when a `template` is set. There is
 no separate subject template configuration.
 
-### Preview Without Sending
+## Preview Without Sending
 
 Use `dryRun: true` on `emails.send()` to render and validate without delivering:
 

package/.agents/skills/mailchannels-js/resources/testing.md

@@ -3,7 +3,7 @@
 The SDK ships a built-in API simulator that runs a local HTTP server mimicking the real
 MailChannels API. Use it for integration tests without hitting the live API.
 
-### Starting The Simulator
+## Starting The Simulator (CLI)
 
 Start the simulator as a background process before your test run:
 
@@ -25,12 +25,12 @@ alongside your test runner:
 "test:integration": "start-server-and-test 'npx mailchannels-sdk simulate --silent' http://localhost:8787 vitest"
 ```
 
-### Example Test (Vitest / Jest)
+### Example Test: CLI (Vitest / Jest)
 
 Point the `MailChannels` client at the running simulator via `baseUrl`:
 
 ```ts
-import { describe, it, expect } from 'vitest'
+import { it, expect } from 'vitest'
 import { MailChannels } from 'mailchannels-sdk'
 
 // Simulator must already be running: npx mailchannels-sdk simulate --port 8787 --silent
@@ -49,7 +49,54 @@ it('queues an email', async () => {
 })
 ```
 
-### Client-Side Validation Without A Simulator
+## Starting The Simulator (Programmatic)
+
+Import `createSimulator` from the `mailchannels-sdk/simulator` entrypoint and start the
+simulator directly within your code. This gives you deterministic control over its
+lifecycle, making it ideal for integration tests that need a fresh simulator instance
+per run or when running in CI without a separate background process.
+
+```ts
+import { createSimulator } from 'mailchannels-sdk/simulator'
+
+const simulator = createSimulator({ port: 8787, silent: true })
+const simulatorUrl = await simulator.listen()
+```
+
+### Example Test: Programmatic (Vitest / Jest)
+
+```ts
+import { afterAll, beforeAll, expect, it } from 'vitest'
+import { createSimulator } from 'mailchannels-sdk/simulator'
+import { MailChannels } from 'mailchannels-sdk'
+
+let simulator: ReturnType<typeof createSimulator>
+let mc: MailChannels
+
+beforeAll(async () => {
+  simulator = createSimulator({ port: 8787, silent: true })
+  const simulatorUrl = await simulator.listen()
+  mc = new MailChannels('test-key', { baseUrl: simulatorUrl })
+})
+
+afterAll(async () => {
+  await simulator.close()
+})
+
+it('queues an email', async () => {
+  const { data, error } = await mc.emails.queue({
+    from: 'sender@example.com',
+    to: 'recipient@example.net',
+    subject: 'Test',
+    text: 'Hello'
+  })
+
+  expect(error).toBeNull()
+  expect(data?.requestId).toBeDefined()
+})
+```
+
+## Client-Side Validation Without A Simulator
 
 The SDK validates payloads before making any HTTP call — `validation_error` results are
 returned synchronously (no network required). Tests for client-side validation rules don't
@@ -73,7 +120,7 @@ it('rejects reserved headers', async () => {
 
 No network call is made because the error is caught before `_fetch` runs.
 
-### Dry Run For Template Assertions
+## Dry Run For Template Assertions
 
 Use `emails.send(options, true)` (dry-run) against the real API in a staging pipeline to
 assert templates render correctly before shipping:

package/.agents/skills/mailchannels-js/resources/unsubscribe.md

@@ -10,7 +10,7 @@ inbox providers (Gmail, Yahoo, etc.) effectively require both for bulk senders.
 Both mechanisms require the message to have **exactly one recipient per personalization**
 and to be **DKIM-signed**.
 
-### In-Body Unsubscribe Link
+## In-Body Unsubscribe Link
 
 Use the literal placeholder string `{{mc-unsubscribe-url}}` inside a mustache HTML body.
 MailChannels substitutes a hosted one-click unsubscribe URL at render time.
@@ -30,7 +30,7 @@ const { data, error } = await mc.emails.queue({
 
 The `template` field must be present for `{{mc-unsubscribe-url}}` to be substituted.
 
-### `List-Unsubscribe` Headers (Non-Transactional)
+## `List-Unsubscribe` Headers (Non-Transactional)
 
 Setting `transactional: false` tells MailChannels to add `List-Unsubscribe` and
 `List-Unsubscribe-Post` headers automatically. These headers are what inbox providers read
@@ -60,7 +60,7 @@ const { data, error } = await mc.emails.queue({
 If `transactional: false` is set but a personalization has more than one recipient,
 the SDK returns a `validation_error` before making any HTTP call.
 
-### When To Use Which
+## When To Use Which
 
 | Message type | In-body link | `transactional: false` headers |
 | --- | --- | --- |

package/.agents/skills/mailchannels-js/resources/webhooks.md

@@ -3,7 +3,7 @@
 MailChannels posts batched delivery events to a URL you register. Events cover both
 `emails.send()` and `emails.queue()` sends and use the same payload shape.
 
-### Enroll And Manage
+## Enroll And Manage
 
 ```ts
 import { MailChannels } from 'mailchannels-sdk'
@@ -25,7 +25,7 @@ Enroll the replacement first if you're swapping URLs.
 
 If the endpoint is already enrolled, `create()` returns `conflict_error`.
 
-### Validate
+## Validate
 
 `mc.webhooks.validate()` sends a synthetic test request to **every** enrolled webhook and
 reports each one's response. Useful as a deploy check.
@@ -47,7 +47,7 @@ for (const entry of data?.results ?? []) {
 
 The test payload carries `event: 'test'` and a hardcoded sender of `test@mailchannels.com`.
 
-### Inspect Batches
+## Inspect Batches
 
 `mc.webhooks.batches()` returns up to 500 batch summaries with status, status code,
 duration, and event count. Use it to investigate failed deliveries.
@@ -72,7 +72,7 @@ const { data: recent } = await mc.webhooks.batches({
 Time formats accepted: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SSZ`, or a `Date` object. If neither `createdAfter`
 nor `createdBefore` is set, the default range is the last 3 days.
 
-### Resend A Batch
+## Resend A Batch
 
 ```ts
 const { data, error } = await mc.webhooks.resendBatch(12345)
@@ -83,7 +83,7 @@ console.log(data?.statusCode, data?.duration)
 A successful call means the resend attempt completed — not that your webhook returned 2xx.
 Check `data.statusCode` to see what your endpoint actually returned.
 
-### Verify Incoming Webhooks (Crucial)
+## Verify Incoming Webhooks (Crucial)
 
 MailChannels signs every webhook request with an Ed25519 signature. `Webhooks.verify()`
 does the full verification — content digest, freshness, and signature — in one call.
@@ -126,7 +126,7 @@ instance (no API key needed). It is also available as an instance method on
 the signature will never match. Use `req.body.toString()` (Express with raw middleware),
 `await request.text()` (Fetch API / Hono / Cloudflare Workers), or the framework equivalent.
 
-#### Supplying The Public Key Manually
+### Supplying The Public Key Manually
 
 By default `verify()` fetches and caches the public key automatically from MailChannels.
 You can supply it yourself to avoid the outbound call:
@@ -148,7 +148,7 @@ Cache the key — it only changes on rotation, and MailChannels may publish mult
 keys at once during a rollover. Always fetch by the `keyId` from the incoming request
 rather than holding a single "current" key.
 
-### Event Payload Shape
+## Event Payload Shape
 
 After successful verification `data` is typed as an array of webhook events. Common shared
 fields:
@@ -167,7 +167,7 @@ fields:
 | `reason` | `string?` | A human readable explanation of the status code. Do not use for system logic. Present on `hard-bounced`, `soft-bounced` events.                         |
 | `url` / `userAgent` / `ip` | `string?` | Present on `click` / `open` events.                                                                                                                     |
 
-### Responding
+## Responding
 
 Return any 2xx status code quickly. MailChannels treats anything else as a failure and may
 retry. Keep your handler thin: enqueue the event and return, then do the actual processing

package/README.md

@@ -9,7 +9,7 @@
 [![TypeScript][typescript-src]][typescript-href]
 [![Node.js][node-src]][node-href]
 
-> Built and tested against Email API `1.5.0`
+> Built and tested against Email API `1.6.0`
 
 Node.js SDK to integrate [MailChannels Email API](https://docs.mailchannels.com/email-api) into your JavaScript or TypeScript server-side applications.
 
@@ -28,6 +28,7 @@ This library provides a simple way to interact with the [MailChannels Email API]
 - 📚 [Usage](#usage)
 - 📐 [Naming Conventions](#naming-conventions)
 - 🧪 [Local simulator](#local-simulator)
+- 📬 [Using with Nodemailer](#using-with-nodemailer)
 - 🤖 [Using with an AI agent](#using-with-an-ai-agent)
 - ⚖️ [License](#license)
 - 💻 [Development](#development)
@@ -120,11 +121,22 @@ This package includes a local MailChannels simulator you can run via the CLI. It
 
 ### Start the simulator
 
+CLI:
+
 ```sh
 # default: http://127.0.0.1:8787
 npx mailchannels-sdk simulate
 ```
 
+Programmatically:
+
+```ts
+import { createSimulator } from 'mailchannels-sdk/simulator'
+
+const simulator = createSimulator()
+const simulatorUrl = await simulator.listen()
+```
+
 ### Options
 
 | Option            | Description             | Default     |
@@ -185,6 +197,65 @@ const { data, error } = await mailchannels.emails.send({
 The next planned expansion is outbound webhook delivery so client applications can test webhook ingestion flows against the simulator as well.
 <!-- #endregion simulator -->
 
+## <a name="using-with-nodemailer">📬 Using with Nodemailer</a>
+
+The SDK provides a transport for Nodemailer that allows you to send emails using the MailChannels Email API.
+
+### Install
+
+```sh
+# npm
+npm i mailchannels-sdk nodemailer && npm i -D @types/nodemailer
+
+# yarn
+yarn add mailchannels-sdk nodemailer && yarn add -D @types/nodemailer
+
+# pnpm
+pnpm add mailchannels-sdk nodemailer && pnpm add -D @types/nodemailer
+```
+
+### Sending
+
+```ts
+import nodemailer from 'nodemailer'
+import { mailchannelsTransport } from 'mailchannels-sdk/nodemailer'
+
+const transport = nodemailer.createTransport(
+  mailchannelsTransport({
+    apiKey: 'your-api-key',
+    sendMode: 'async', // 'async' or 'sync'. Default is 'async'
+    // SDK client options: `baseUrl`, `timeout`, `signal`, `retry`
+  })
+)
+
+transport.sendMail({
+  from: 'sender@example.com',
+  to: 'recipient@example.com',
+  subject: 'Hello from Nodemailer',
+  html: '<p>Hello World</p>',
+  mailchannels: {
+    // SDK send options: `campaignId`, `tracking`, `transactional`, `unsubscribe`
+  }
+}, (error, info) => {
+  if (error) {
+    console.error('Error sending email:', error)
+    return;
+  }
+  console.log('Sent message info:', info)
+})
+```
+
+### Limitations
+
+The MailChannels Nodemailer transport maps a subset of Nodemailer features to the MailChannels SDK. Some features are not supported or have limitations:
+
+- Only a single `replyTo` address is supported
+- Multiple DKIM signatures are not supported
+- For async sends (`sendMode: 'async'`), the response will have a `messageId` of `null`, and both the `accepted` and `rejected` arrays will be empty
+- Attachment `path`, `href` and other URL fields are not supported
+- MailChannels-specific send options must be passed via the augmented `mailchannels` field in the `sendMail` options
+- Some advanced Nodemailer behaviors may be ignored or transformed when mapped to the SDK
+
 ## <a name="using-with-an-ai-agent">🤖 Using with an AI agent</a>
 
 This repository ships a complete agent skill at
@@ -273,7 +344,7 @@ pnpm test:watch
 # Run typecheck
 pnpm test:types
 
-# Refresh API parity fixtures, specs, and README version note
+# Refresh API parity fixtures and README version note
 pnpm parity:fixtures
 
 # Run the local simulator