mailchannels-sdk 1.0.0 → 1.2.0

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

@@ -0,0 +1,91 @@
+# Suppressions
+
+A suppression list keeps known-bad or opted-out recipients out of future sends. MailChannels
+suppresses by recipient + suppression type + source.
+
+### Create Entries
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels('YOUR-API-KEY')
+
+const { success, error } = await mc.suppressions.create({
+  entries: [
+    {
+      recipient: 'out@example.net',
+      types: ['non-transactional'],          // optional; defaults to non-transactional
+      notes: 'Imported from preference center'  // optional, max 1024 chars
+    },
+    {
+      recipient: 'complainer@example.net',
+      types: ['transactional', 'non-transactional']
+    }
+  ],
+  addToSubAccounts: true   // parent only; copies entries to every sub-account
+})
+```
+
+Constraints:
+
+- **Atomic**: either every entry in the request is added, or none are.
+- A single request can carry at most **1000** entries combined across the parent and any
+  sub-accounts.
+- Each `recipient` is up to 255 characters; `notes` up to 1024.
+- `types` items must be `'transactional'` or `'non-transactional'`.
+- If any entry already exists, the API returns `conflict_error`.
+
+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
+
+```ts
+const { data, error } = await mc.suppressions.list({
+  recipient:     'recipient@example.net',   // exact-match filter
+  source:        'api',                      // see source values below
+  createdAfter:  '2026-04-01',
+  createdBefore: '2026-05-01T00:00:00Z',
+  limit:         100,                        // 1..1000, default 1000
+  offset:        0
+})
+
+// Date objects are also accepted
+const { data: recent } = await mc.suppressions.list({
+  createdAfter:  new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),  // 7 days ago
+  createdBefore: new Date()
+})
+```
+
+`source` values:
+
+- `'api'` — explicitly created via the API.
+- `'unsubscribe_link'` — recipient used the hosted unsubscribe URL.
+- `'list_unsubscribe'` — recipient used a one-click `List-Unsubscribe` header.
+- `'hard_bounce'` — bounced as undeliverable.
+- `'spam_complaint'` — recipient reported spam at their provider.
+
+Date formats accepted: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SSZ`, or a `Date` object.
+
+### Delete An Entry
+
+Warning:
+Do not remove entries from the suppression list if the recipient has not explicitly opted back in.
+This may cause deliverability issues and violate anti-spam laws and our policies.
+
+```ts
+const { error: delApiErr } =  await mc.suppressions.delete('recipient@example.net', 'api')
+const { error: delAllErr } = await mc.suppressions.delete('recipient@example.net', 'all')  // all sources
+```
+
+If `source` is omitted it defaults to `'api'`. Use `'all'` to remove every suppression for
+that recipient regardless of origin.
+
+### Patterns
+
+- **Preference center opt-out**: set `type` according to the email category, e.g. `non-transactional` for marketing 
+  emails, `transactional` for order updates, and so on. 
+  Configure `addToSubAccounts` depending on whether the preference applies to all sub-accounts or just the parent account.
+  Add a note to indicate the source, e.g. "Opted out via preference center".
+- **Migrating from another ESP**: bulk-create with `addToSubAccounts: true` so every tenant
+  inherits the list.

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

@@ -0,0 +1,97 @@
+# Mustache Templates
+
+MailChannels templates are **send-payload fields**, not a template CRUD resource. There is
+no "create template" endpoint. To use a template:
+
+1. Set `template: { type: 'mustache', data: { ... } }` on the root options.
+2. Provide per-recipient variable overrides in each personalization's `template.data`.
+
+The only supported template type is `'mustache'`.
+
+### Single Recipient
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels('YOUR-API-KEY')
+
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'jane@example.net',
+  subject: 'Hello {{name}}',
+  text: 'Hello {{name}}',
+  html: '<p>Hello {{name}}</p>',
+  template: {
+    type: 'mustache',
+    data: { name: 'Jane' }
+  }
+})
+```
+
+### 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
+(personalization wins on conflict):
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  subject: 'Hi {{name}}',
+  text: 'Hi {{name}}, you are on the {{plan}} plan.',
+  template: {
+    type: 'mustache',
+    data: { plan: 'Free' }   // root default
+  },
+  personalizations: [
+    {
+      to: 'jane@example.net',
+      template: { data: { name: 'Jane', plan: 'Pro' } }  // overrides plan
+    },
+    {
+      to: 'alex@example.net',
+      template: { data: { name: 'Alex' } }               // inherits plan: 'Free'
+    }
+  ]
+})
+```
+
+### Allowed Template Variable Value Types
+
+Keys are strings. Values may be:
+
+- `string`
+- `boolean`
+- `number`
+- array of any of the above
+- plain object (nested maps with string keys and any of the above as values)
+
+`null`, `undefined`, and class instances are rejected with a `validation_error` before
+the request leaves the client.
+
+### 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
+
+Use `dryRun: true` on `emails.send()` to render and validate without delivering:
+
+```ts
+const { data, error } = await mc.emails.send(
+  {
+    from: 'sender@example.com',
+    to: 'recipient@example.net',
+    subject: 'Hello {{name}}',
+    text: 'Hello {{name}}',
+    template: { type: 'mustache', data: { name: 'World' } }
+  },
+  true  // dryRun
+)
+
+// data.rendered is a string[] — one rendered message per personalization
+```
+
+Dry-run is the right way to confirm that a template renders correctly before shipping.
+`emails.queue()` does not support dry-run.

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

@@ -0,0 +1,95 @@
+# Testing
+
+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
+
+Start the simulator as a background process before your test run:
+
+```bash
+npx mailchannels-sdk simulate --port 8787 --silent
+```
+
+| Flag | Env var | Default |
+| --- | --- | --- |
+| `-p` / `--port` | `MAILCHANNELS_SIMULATOR_PORT` | `8787` |
+| `-h` / `--host` | `MAILCHANNELS_SIMULATOR_HOST` | (system default) |
+| `-s` / `--silent` | — | `false` |
+
+In CI or npm scripts, use `start-server-and-test` or `concurrently` to manage the process
+alongside your test runner:
+
+```bash
+# package.json script example
+"test:integration": "start-server-and-test 'npx mailchannels-sdk simulate --silent' http://localhost:8787 vitest"
+```
+
+### Example Test (Vitest / Jest)
+
+Point the `MailChannels` client at the running simulator via `baseUrl`:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { MailChannels } from 'mailchannels-sdk'
+
+// Simulator must already be running: npx mailchannels-sdk simulate --port 8787 --silent
+const mc = new MailChannels('test-key', { baseUrl: 'http://localhost:8787' })
+
+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
+need the simulator at all:
+
+```ts
+it('rejects reserved headers', async () => {
+  const mc = new MailChannels('test-key', { baseUrl: 'http://localhost:9999' })
+
+  const { error } = await mc.emails.queue({
+    from: 'sender@example.com',
+    to: 'recipient@example.net',
+    subject: 'Test',
+    text: 'Hello',
+    headers: { 'From': 'evil@attacker.example' }  // reserved header
+  })
+
+  expect(error?.type).toBe('validation_error')
+})
+```
+
+No network call is made because the error is caught before `_fetch` runs.
+
+### 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:
+
+```ts
+const { data, error } = await mc.emails.send(
+  {
+    from: 'sender@example.com',
+    to: 'preview@example.net',
+    subject: 'Hi {{name}}',
+    text: 'Hi {{name}}',
+    template: { type: 'mustache', data: { name: 'Alice' } }
+  },
+  true
+)
+
+expect(error).toBeNull()
+expect(data?.rendered?.[0]).toContain('Hi Alice')
+```

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

@@ -0,0 +1,73 @@
+# Unsubscribe
+
+MailChannels offers two complementary unsubscribe mechanisms — an in-body unsubscribe link,
+and the standard `List-Unsubscribe` / `List-Unsubscribe-Post` headers. They are not
+alternatives. A non-transactional (bulk / marketing / notification) send should use
+**both**: the headers let inbox providers surface a one-click "Unsubscribe" button in their
+UI, and the in-body link is what recipients see and click inside the message body. Major
+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
+
+Use the literal placeholder string `{{mc-unsubscribe-url}}` inside a mustache HTML body.
+MailChannels substitutes a hosted one-click unsubscribe URL at render time.
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Newsletter',
+  html: `
+    <p>Hello!</p>
+    <p><a href="{{mc-unsubscribe-url}}">Unsubscribe</a></p>
+  `,
+  template: { type: 'mustache' }
+})
+```
+
+The `template` field must be present for `{{mc-unsubscribe-url}}` to be substituted.
+
+### `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
+to render their "Unsubscribe" button next to the sender name.
+
+**Always include the in-body link in the same payload** so the message is fully compliant
+on both surfaces:
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Marketing message',
+  html: `
+    <p>Today's update…</p>
+    <p><a href="{{mc-unsubscribe-url}}">Unsubscribe</a></p>
+  `,
+  template: { type: 'mustache' },
+  transactional: false,
+  dkim: {
+    domain: 'example.com',
+    selector: 'mcdkim'
+  }
+})
+```
+
+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
+
+| Message type | In-body link | `transactional: false` headers |
+| --- | --- | --- |
+| Transactional (receipts, password resets, confirmations) | No | No (keep the default `true`). |
+| Bulk / marketing / newsletter / notification | **Yes** | **Yes** — combine both in the same payload. |
+
+There is essentially no situation where you'd want headers but not the in-body link; if
+you're sending non-transactional mail, you need both.
+
+Both modes require DKIM signing. See [dkim](dkim.md) for how to create the underlying key.

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

@@ -0,0 +1,174 @@
+# Webhooks
+
+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
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels('YOUR-API-KEY')
+
+const { error: createError } = await mc.webhooks.create('https://example.com/mailchannels/events')
+if (createError) { /*...*/ }
+
+const { data: webhooks, error: listError } = await mc.webhooks.list() // enrolled URLs
+if (listError) { /*...*/ }
+
+const { error: deleteError } = await mc.webhooks.deleteAll() // removes ALL enrolled webhooks
+if (deleteError) { /*...*/ }
+```
+
+There is no per-URL delete — `deleteAll()` removes every enrolled webhook for the account.
+Enroll the replacement first if you're swapping URLs.
+
+If the endpoint is already enrolled, `create()` returns `conflict_error`.
+
+### Validate
+
+`mc.webhooks.validate()` sends a synthetic test request to **every** enrolled webhook and
+reports each one's response. Useful as a deploy check.
+
+```ts
+const { data, error } = await mc.webhooks.validate('deploy-smoke-test')  // requestId optional, max 28 chars
+if (error) {
+    console.error('Webhook validation failed:', error.message)
+    return
+}
+
+if (data?.allPassed) {
+  console.log('All webhooks responded with 2xx')
+}
+for (const entry of data?.results ?? []) {
+  console.log(entry.webhook, entry.result, entry.response)
+}
+```
+
+The test payload carries `event: 'test'` and a hardcoded sender of `test@mailchannels.com`.
+
+### 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.
+
+```ts
+const { data, error } = await mc.webhooks.batches({
+  statuses:      ['4xx', '5xx', 'no_response'],  // '1xx' | '2xx' | '3xx' | '4xx' | '5xx' | 'no_response'
+  createdAfter:  '2026-05-20',
+  createdBefore: '2026-05-25',                   // range cannot exceed 31 days
+  webhook:       'https://example.com/mailchannels/events',
+  limit:         500,                             // 1..500, default 500
+  offset:        0
+})
+
+// Date objects are also accepted
+const { data: recent } = await mc.webhooks.batches({
+  createdAfter:  new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),  // 7 days ago
+  createdBefore: new Date()
+})
+```
+
+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
+
+```ts
+const { data, error } = await mc.webhooks.resendBatch(12345)
+
+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)
+
+MailChannels signs every webhook request with an Ed25519 signature. `Webhooks.verify()`
+does the full verification — content digest, freshness, and signature — in one call.
+**Always verify before processing.**
+
+```ts
+import { Webhooks } from 'mailchannels-sdk'
+
+// In your HTTP handler (example using Node.js / Express):
+app.post('/mailchannels/events', express.raw({ type: '*/*' }), async (req, res) => {
+  const { data, error } = await Webhooks.verify({
+    payload: req.body.toString(),  // raw string body — do NOT pass the parsed JSON object
+    headers: req.headers as Record<string, string>
+  })
+
+  if (error) {
+    return res.status(401).send('Invalid signature')
+  }
+
+  // data is a typed array of webhook events
+  for (const event of data) {
+    console.log(event.event, event.email, event.requestId)
+  }
+
+  res.sendStatus(200)
+})
+```
+
+`Webhooks.verify()` is a **static method** — you can call it without a `MailChannels`
+instance (no API key needed). It is also available as an instance method on
+`mc.webhooks.verify()`.
+
+`verify()` checks all three things in one call:
+
+1. **Content-Digest** — SHA-256 of the raw body matches the header.
+2. **Freshness** — `created` timestamp is within the default replay window (less than 300 s old)
+3. **Signature** — Ed25519 verifies against the public key for the given `keyId`.
+
+**`payload` must be the raw request body string.** Do not pass the parsed JSON object or
+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
+
+By default `verify()` fetches and caches the public key automatically from MailChannels.
+You can supply it yourself to avoid the outbound call:
+
+```ts
+const { data: keyData, error: getKeyErr } = await mc.webhooks.getSigningKey(keyId)
+if (getKeyErr) { /*...*/ }
+
+const { data, error } = await Webhooks.verify({
+  payload: rawBody,
+  headers,
+  publicKey: keyData?.key,
+  cache: false   // disable built-in caching when you manage the key yourself
+})
+if (error) { /*...*/ }
+```
+
+Cache the key — it only changes on rotation, and MailChannels may publish multiple active
+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
+
+After successful verification `data` is typed as an array of webhook events. Common shared
+fields:
+
+| Field | Type | Notes                                                                                                                                                   |
+| --- | --- |---------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `event` | `string` | `'processed'` / `'delivered'` / `'open'` / `'click'` / `'hard-bounced'` / `'soft-bounced'` / `'dropped'` / `'complained'` / `'unsubscribed'` / `'test'` |
+| `email` | `string` | Sender email address.                                                                                                                                   |
+| `customerHandle` | `string` | Your MailChannels account (or sub-account) handle.                                                                                                      |
+| `timestamp` | `number` | Unix timestamp.                                                                                                                                         |
+| `requestId` | `string` | Correlates to the `requestId` from `queue()` / `send()`.                                                                                                |
+| `smtpId` | `string` | SMTP message ID.                                                                                                                                        |
+| `campaignId` | `string?` | Present when `campaignId` was set on the send.                                                                                                          |
+| `recipients` | `string[]?` | All recipients in the personalization.                                                                                                                  |
+| `status` | `string?` | The SMTP status code received for the message. Use for system logic. Present on `hard-bounced`, `soft-bounced` events.                                  |
+| `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
+
+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
+on a worker.

package/README.md

@@ -9,12 +9,12 @@
 [![TypeScript][typescript-src]][typescript-href]
 [![Node.js][node-src]][node-href]
 
-> Built and tested against Email API `1.0.0`
+> Built and tested against Email API `1.4.0`
 
-Node.js SDK to integrate [MailChannels Email API](https://docs.mailchannels.net/email-api) into your JavaScript or TypeScript server-side applications.
+Node.js SDK to integrate [MailChannels Email API](https://docs.mailchannels.com/email-api) into your JavaScript or TypeScript server-side applications.
 
 <!-- #region overview -->
-This library provides a simple way to interact with the [MailChannels Email API](https://docs.mailchannels.net/email-api). It is written in TypeScript and can be used in both JavaScript and TypeScript projects and in different runtimes.
+This library provides a simple way to interact with the [MailChannels Email API](https://docs.mailchannels.com/email-api). It is written in TypeScript and can be used in both JavaScript and TypeScript projects and in different runtimes.
 <!-- #endregion overview -->
 
 - [✨ Release Notes](https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-js/src/HEAD/CHANGELOG.md)
@@ -28,13 +28,14 @@ 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 an AI agent](#using-with-an-ai-agent)
 - ⚖️ [License](#license)
 - 💻 [Development](#development)
 
 ## <a name="features">🚀 Features</a>
 
 <!-- #region features -->
-This SDK fully supports all features and operations available in the [MailChannels Email API](https://docs.mailchannels.net/email-api). It is actively maintained to ensure compatibility and to quickly add support for new API features as they are released.
+This SDK fully supports all features and operations available in the [MailChannels Email API](https://docs.mailchannels.com/email-api). It is actively maintained to ensure compatibility and to quickly add support for new API features as they are released.
 
 Some of the things you can do with the SDK:
 
@@ -168,6 +169,7 @@ const { data, error } = await mailchannels.emails.send({
 - Email sends and async sends
 - Domain checks
 - DKIM key create, list, rotate, and update
+- Custom tracking domain create, list, update, and delete
 - Webhook enrollment, listing, validation, signing key lookup, and batch inspection
 - Sub-account lifecycle, API keys, SMTP passwords, limits, and usage
 - Engagement, performance, recipient behaviour, sender, volume, and usage metrics
@@ -178,10 +180,74 @@ const { data, error } = await mailchannels.emails.send({
 - State is in-memory only and is reset when the process stops
 - Any non-empty `X-API-Key` is accepted, with separate in-memory state per API key
 - Webhook responses are simulated locally, but the simulator does not yet emit real webhook callbacks to your application
+- Custom tracking domain verification is simulated, but the simulator does not yet check DNS records
 
 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-an-ai-agent">🤖 Using with an AI agent</a>
+
+This repository ships a complete agent skill at
+[`.agents/skills/mailchannels-js/`](.agents/skills/mailchannels-js/).
+It teaches an AI coding agent how to use the `mailchannels-sdk` package
+correctly by breaking the documentation down into focused
+per-topic files with a decision tree so the agent loads only the
+parts the task actually needs.
+
+Layout:
+
+```
+.agents/skills/mailchannels-js/
+├── SKILL.md              # entry point: scope, decision tree, conventions
+└── resources/            # focused recipes (sending, attachments, webhooks, …)
+```
+
+Every file is plain Markdown. The skill works with any agent that can be
+pointed at a directory of context files — Claude Code, Cursor, Codex CLI,
+Aider, Continue, and similar tools all consume it without modification.
+
+### Install
+
+The skill ships inside the `mailchannels-sdk` npm package. Use `npm pack` to
+download the tarball, extract it, and copy the skill directory wherever your
+agent looks for skills, rules, or context files:
+
+```bash
+# Make a temp directory to hold the tarball and extracted files:
+mkdir /tmp/mc-js-sdk
+
+# Pin the version to match the SDK you have installed — omit the pin to
+# grab the latest release:
+npm pack --pack-destination /tmp/mc-js-sdk mailchannels-sdk
+
+# Extract the tarball:
+tar -xzf /tmp/mc-js-sdk/mailchannels-sdk-*.tgz -C /tmp/mc-js-sdk
+
+# Replace the destination with your agent's path:
+mkdir -p <your-agent's-skills-dir>
+cp -r /tmp/mc-js-sdk/package/.agents/skills/mailchannels-js <your-agent's-skills-dir>/
+
+# Clean up:
+rm -r /tmp/mc-js-sdk
+```
+
+Re-run the same commands when you upgrade the SDK so the skill stays in step
+with the installed version.
+
+Common destinations:
+
+| Agent | Where to put it |
+| --- | --- |
+| Claude Code | `.claude/skills/` (project) or `~/.claude/skills/` (user) |
+| Cursor | `.cursor/rules/` (or attach files inline with `@`) |
+| Codex CLI | referenced from the project's `AGENTS.md` |
+| Aider | referenced from the conventions file in `.aider.conf.yml` |
+| Continue | registered as a custom context provider |
+
+If your tool isn't listed, look for the equivalent of "skill", "rule",
+"context bundle", or "conventions file" — any mechanism that lets the agent
+read a directory of Markdown will work.
+
 ## <a name="license">⚖️ License</a>
 
 [MIT License](https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-js/src/HEAD/LICENSE)