mailchannels-sdk 1.3.0 → 1.4.0

package/.agents/skills/mailchannels-js/SKILL.md

@@ -34,6 +34,10 @@ You're about to write JS/TS SDK code. What does it need to do?
 ├── Set up the client (API keys, base URL, options, lifecycle)
 │   → resources/clients-and-transport.md
 │
+├── Send through a framework's mail API instead of using the SDK directly
+│   └── …Nodemailer?
+│       → resources/plugins/nodemailer.md
+│
 ├── Send email
 │   → resources/sending.md
 │   ├── …with file / bytes / URL / inline-image attachments?

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

@@ -4,7 +4,7 @@ MailChannels expects every attachment to be Base64-encoded with a `filename` and
 MIME `type`. Use the `Attachment` static helpers — they encode for you and infer the MIME
 type from the filename.
 
-### From In-Memory Bytes
+## From In-Memory Bytes
 
 `fromBytes` is synchronous and accepts any `ArrayBuffer` or `Uint8Array`:
 
@@ -33,7 +33,7 @@ const { data, error } = await mc.emails.queue({
 })
 ```
 
-### From A Blob
+## From A Blob
 
 `fromBlob` is async and accepts any Web API `Blob`. The Blob's own `type` property is used
 as the MIME type unless you override it in options:
@@ -43,14 +43,13 @@ const blob = new Blob(['Hello world'], { type: 'text/plain' })
 const attachment = await Attachment.fromBlob(blob, { filename: 'hello.txt' })
 ```
 
-### Inline Images (CID References)
+## Inline Images (CID References)
 
-Pass `disposition: 'inline'` and a `contentId` to embed an image inside the HTML body:
+Pass a `contentId` to embed an image inside the HTML body:
 
 ```ts
 const logo = Attachment.fromBytes(bytes, {
   filename: 'logo.png',
-  disposition: 'inline',
   contentId: 'company-logo'
 })
 
@@ -63,7 +62,7 @@ const { data, error } = await mc.emails.queue({
 })
 ```
 
-### Attachment Options
+## Attachment Options
 
 Both `fromBytes` and `fromBlob` accept an `AttachmentOptions` object:
 
@@ -72,9 +71,8 @@ Both `fromBytes` and `fromBlob` accept an `AttachmentOptions` object:
 | `filename` | `string` | Required. MIME type is inferred from it when `type` is omitted. |
 | `type` | `string` | MIME type. Inferred from `filename` if omitted. For `fromBlob`, defaults to the Blob's own `type`. |
 | `contentId` | `string` | For `cid:` inline image references. |
-| `disposition` | `'attachment' \| 'inline'` | Defaults to `'attachment'`. |
 
-### Awaiting Attachments Lazily
+## Awaiting Attachments Lazily
 
 The `attachments` field accepts `(EmailsSendAttachment | Promise<EmailsSendAttachment>)[]`,
 so you can pass unresolved promises and the SDK will await them before sending:
@@ -92,13 +90,13 @@ const { data, error } = await mc.emails.queue({
 })
 ```
 
-### Limits
+## Limits
 
 - Up to **1000 attachments** per send.
 - Combined message + headers + attachments must stay under **30 MB**. Exceeding this
   returns `payload_too_large_error` (HTTP 413) in the `error` field.
 
-### Raw Attachment Shape
+## Raw Attachment Shape
 
 If you need to construct one by hand:
 

package/.agents/skills/mailchannels-js/resources/clients-and-transport.md

@@ -17,7 +17,7 @@ A missing or empty API key throws synchronously at construction:
 new MailChannels('')   // throws Error: "Missing MailChannels API key."
 ```
 
-### Constructor Options
+## Constructor Options
 
 ```ts
 // new MailChannels(apiKey: string, options?: MailChannelsClientOptions)
@@ -30,7 +30,7 @@ new MailChannels('')   // throws Error: "Missing MailChannels API key."
 | `retry` | `boolean \| number \| RetryOptions` | `false` | `ofetch` retry options. |
 | `signal` | `AbortSignal` | `undefined` | Propagated to every fetch call made by this instance. |
 
-### Multi-Tenant: One Client Per Credential
+## Multi-Tenant: One Client Per Credential
 
 Never share a parent key and a sub-account key on the same instance. Create a separate
 `MailChannels` for each credential:
@@ -50,7 +50,7 @@ const { data: queueB, error: queueErrB } = await tenantB.emails.queue({ ... })
 if (queueErrB) { /*...*/ }
 ```
 
-### Request Cancellation
+## Request Cancellation
 
 Pass an `AbortSignal` to cancel in-flight requests:
 
@@ -63,7 +63,7 @@ const mc = new MailChannels(apiKey, { signal: controller.signal })
 controller.abort()
 ```
 
-### Headers Sent On Every Request
+## Headers Sent On Every Request
 
 The SDK sets these on every request and they cannot be overridden via `MailChannelsClientOptions`:
 
@@ -72,7 +72,7 @@ The SDK sets these on every request and they cannot be overridden via `MailChann
 - `Content-Type: application/json`
 - `User-Agent: mailchannels-node/<version>`
 
-### Extending The Client
+## Extending The Client
 
 The `MailChannels` class extends the public `MailChannelsClient` base. If you need to
 intercept, proxy, or instrument requests you can subclass `MailChannelsClient` and override

package/.agents/skills/mailchannels-js/resources/custom-headers.md

@@ -3,7 +3,7 @@
 Use `headers` for application-specific metadata, tracking IDs, campaign tags, or any
 custom `X-…` header.
 
-### Root vs Per-Personalization
+## Root vs Per-Personalization
 
 - **Root `headers`**: applied to every personalization.
 - **Per-personalization `headers`**: applied only to that personalization.
@@ -31,7 +31,7 @@ const { data, error } = await mc.emails.queue({
 })
 ```
 
-### Reserved Headers — Never Set These
+## Reserved Headers — Never Set These
 
 MailChannels controls a fixed set of message headers. The SDK pre-validates and returns a
 `validation_error` client-side before any request that tries to set one. Header names are
@@ -53,12 +53,12 @@ checked case-insensitively, so `From`, `from`, and `FROM` are all rejected.
 This list mirrors the SDK's `RESERVED_HEADER_NAMES` set — keep them in sync if MailChannels
 changes the list upstream.
 
-### Case Sensitivity
+## Case Sensitivity
 
 Header names are treated case-insensitively by MailChannels. If two keys differ only by
 case, only one is used and the choice is unspecified. Pick one canonical casing per header.
 
-### Values
+## Values
 
 Both keys and values must be strings. A non-string value returns a `validation_error`
 before the request leaves the client.

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

@@ -4,7 +4,7 @@ MailChannels can host the **private** DKIM key for you. You publish the **public
 the domain's DNS as a TXT record. The public DNS record is **not** hosted by MailChannels —
 you must publish it yourself in whatever DNS provider holds the zone.
 
-### Create A Hosted Key
+## Create A Hosted Key
 
 ```ts
 import { MailChannels } from 'mailchannels-sdk'
@@ -27,7 +27,7 @@ for (const record of data?.dnsRecords ?? []) {
 
 The returned `data.dnsRecords` contains TXT records you must publish in DNS.
 
-### List, Filter, And Include DNS Records
+## List, Filter, And Include DNS Records
 
 ```ts
 const { data, error } = await mc.domains.dkim.list('example.com', {
@@ -39,7 +39,7 @@ const { data, error } = await mc.domains.dkim.list('example.com', {
 })
 ```
 
-### Key Lifecycle
+## Key Lifecycle
 
 | Status | Meaning |
 | --- | --- |
@@ -48,7 +48,7 @@ const { data, error } = await mc.domains.dkim.list('example.com', {
 | `retired` | No longer in use. |
 | `revoked` | Marked compromised. Stop using immediately. |
 
-#### Update status directly
+### Update status directly
 
 ```ts
 const { success, error } = await mc.domains.dkim.updateStatus('example.com', {
@@ -60,7 +60,7 @@ const { success, error } = await mc.domains.dkim.updateStatus('example.com', {
 Only `active` keys can move to `rotated`. Only `revoked`, `retired`, and `rotated` are
 valid update targets.
 
-#### Rotate (recommended for routine rollover)
+### Rotate (recommended for routine rollover)
 
 ```ts
 const { data, error } = await mc.domains.dkim.rotate('example.com', 'mcdkim', {
@@ -82,7 +82,7 @@ Rotation:
 **Publish the new DNS record before `gracePeriodExpiresAt`** or emails signed with the new
 key will fail DKIM at receiving providers.
 
-### Sending With A Hosted Key
+## Sending With A Hosted Key
 
 ```ts
 const { data, error } = await mc.emails.queue({
@@ -100,7 +100,7 @@ const { data, error } = await mc.emails.queue({
 If `dkim.selector` is set without `dkim.domain`, MailChannels takes the domain from the
 `from` address.
 
-### Sending With A Customer-Managed Key
+## Sending With A Customer-Managed Key
 
 If you keep the private key yourself, pass it Base64-encoded (PEM headers are stripped
 automatically):
@@ -121,7 +121,7 @@ const { data, error } = await mc.emails.queue({
 
 `dkim` can also be set per-personalization to override the root value.
 
-### DNS Publication
+## DNS Publication
 
 MailChannels does not host the public DKIM DNS record — you do. The SDK returns the exact
 record to publish in `data.dnsRecords`:
@@ -132,7 +132,7 @@ record to publish in `data.dnsRecords`:
 | `type` | Always `TXT`. |
 | `value` | Public key material. **Publish verbatim** — do not re-wrap, strip quotes, or split lines. |
 
-#### Required Steps
+### Required Steps
 
 1. **Create** with `mc.domains.dkim.create(domain, { selector })`. Capture `dnsRecords`.
 2. **Resolve the DNS zone** in your provider's API.
@@ -142,7 +142,7 @@ record to publish in `data.dnsRecords`:
    The `dkim[].verdict` must be `'passed'` before sending real traffic.
 5. **For rotations**, leave the old TXT record in place until `gracePeriodExpiresAt`.
 
-### Selector Format
+## Selector Format
 
 - 1–63 characters.
 - Lowercase letters, numbers, and `-` work everywhere. Avoid `_` in the selector itself.

package/.agents/skills/mailchannels-js/resources/domain-checks.md

@@ -11,7 +11,7 @@ sending from it. The check covers four things:
 - **Domain Lockdown** — a MailChannels feature that ties a sending domain to your account
   so other MailChannels customers cannot spoof it.
 
-### Basic Check
+## Basic Check
 
 ```ts
 import { MailChannels } from 'mailchannels-sdk'
@@ -29,7 +29,7 @@ console.log(data?.dkim)                    // array of per-selector results
 console.log(data?.references)             // support links if anything failed
 ```
 
-### With Specific DKIM Settings
+## With Specific DKIM Settings
 
 If you don't pass `dkim`, MailChannels uses all stored keys for the domain. To target
 specific selectors:
@@ -63,7 +63,7 @@ const { data, error } = await mc.domains.check('example.com', {
 })
 ```
 
-#### DKIM Settings Resolution Rules
+### DKIM Settings Resolution Rules
 
 | Provided fields | Behavior |
 | --- | --- |
@@ -74,7 +74,7 @@ const { data, error } = await mc.domains.check('example.com', {
 | `privateKey` set | `selector` is required too. |
 | `dkim` empty / absent | Use all stored keys for the request domain. |
 
-### With A Sender ID (Domain Lockdown)
+## With A Sender ID (Domain Lockdown)
 
 If your lockdown record uses `senderid=` or `sidw=` fields, pass the sender identity:
 
@@ -86,14 +86,14 @@ const { data, error } = await mc.domains.check('example.com', {
 
 If your lockdown record uses `auth=` (account-wide authorization), omit `senderId`.
 
-### Verdicts Reference
+## Verdicts Reference
 
 - DKIM, Domain Lockdown, A, and MX verdicts: `'passed'` or `'failed'`.
 - SPF has a richer set: `'passed'`, `'failed'`, `'soft failed'`, `'temporary error'`,
   `'permanent error'`, `'neutral'`, `'none'`, `'unknown'`.
 - `senderDomain` passes if **either** the A or MX check passes.
 
-### When To Use
+## When To Use
 
 - During onboarding for every new sending domain.
 - In CI after rotating DKIM keys, to verify the new DNS record propagated.

package/.agents/skills/mailchannels-js/resources/error-handling.md

@@ -31,7 +31,7 @@ if (error) {
 console.log(data.requestId)
 ```
 
-### Error Types
+## Error Types
 
 | `error.type` | HTTP status | Meaning |
 | --- | --- | --- |
@@ -48,7 +48,7 @@ console.log(data.requestId)
 | `'application_error'` | `null` | Unexpected JS/network error (e.g. fetch failed). |
 | `'api_error'` | varies | Fallback for unmapped status codes. |
 
-### Handling Patterns
+## Handling Patterns
 
 The `message` field is a human-readable description of the error, useful for logging and debugging,
 but it should not be parsed or used for control flow as it may change without warning. Instead, use the `type` field for error handling logic.
@@ -87,7 +87,7 @@ if (error) {
 }
 ```
 
-### Client-Side Validation Errors (`validation_error`)
+## Client-Side Validation Errors (`validation_error`)
 
 These produce `error.type === 'validation_error'` and `error.statusCode === null` before
 any HTTP call:
@@ -102,7 +102,7 @@ any HTTP call:
 
 Failing early gives a precise error rather than a vague 400.
 
-### Retrying and Idempotency
+## Retrying and Idempotency
 
 | Error type | Safe to retry? |
 | --- | --- |
@@ -114,7 +114,7 @@ The API has no idempotency keys, so retrying `emails.send()` or `emails.queue()`
 transient failure can produce a duplicate send. Build idempotency into the caller (e.g. a
 unique `campaignId` + recipient-set check) when at-most-once delivery matters.
 
-### SDK Exceptions
+## SDK Exceptions
 
 `new MailChannels('')` (empty or missing key) throws synchronously:
 

package/.agents/skills/mailchannels-js/resources/metrics-and-usage.md

@@ -3,7 +3,7 @@
 The metrics module exposes the operational view of your traffic. Usage exposes
 billing-period totals.
 
-### Time-Series Metrics
+## Time-Series Metrics
 
 The four time-series methods share the same `MetricsOptions` parameter shape: optional
 `startTime`, `endTime`, `campaignId`, and `interval`.
@@ -37,7 +37,7 @@ const { data: behaviour,  error: behErr }   = await mc.metrics.recipientBehaviou
 Time formats accepted: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SSZ`, or a `Date` object. Defaults: `startTime` is
 one month ago, `endTime` is now.
 
-#### Buckets
+### Buckets
 
 Each response includes both totals **and** a `buckets` object grouped by metric name, each
 containing a list of `{ count, periodStart }` rows aligned to `interval`.
@@ -51,24 +51,24 @@ for (const bucket of data?.buckets.processed ?? []) {
 }
 ```
 
-#### Volume Buckets
+### Volume Buckets
 
 `data.buckets` has `processed`, `delivered`, `dropped`.
 
-#### Engagement Buckets
+### Engagement Buckets
 
 `data.buckets` has `open`, `click`, `uniqueOpen`, `uniqueClick`, `openTrackingDelivered`,
 `clickTrackingDelivered`, `uniqueOpenTrackingDelivered`, `uniqueClickTrackingDelivered`.
 
-#### Performance Buckets
+### Performance Buckets
 
 `data.buckets` has `processed`, `delivered`, `bounced`, `complained`.
 
-#### Recipient Behaviour Buckets
+### Recipient Behaviour Buckets
 
 `data.buckets` has `unsubscribed`, `unsubscribeDelivered`.
 
-### Sender Metrics
+## Sender Metrics
 
 `mc.metrics.senders()` lists per-sender totals grouped either by campaign or sub-account.
 
@@ -92,7 +92,7 @@ for (const sender of data?.senders ?? []) {
 
 Senders with **zero traffic in the time range are omitted** from the response.
 
-### Usage
+## Usage
 
 ```ts
 const { data: usage, error } = await mc.metrics.usage()
@@ -104,7 +104,7 @@ console.log(usage?.total, usage?.startDate, usage?.endDate)
 For a specific sub-account, use `mc.subAccounts.getUsage(handle)` instead. See
 [sub-accounts](sub-accounts.md).
 
-### Common Patterns
+## Common Patterns
 
 - **Daily dashboard**: `mc.metrics.volume({ interval: 'day' })` plus
   `mc.metrics.engagement({ interval: 'day' })` over the same range.

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

@@ -17,7 +17,7 @@ const { data, error } = await mc.emails.queue({
 })
 ```
 
-### Module Inventory
+## Module Inventory
 
 | Property | What it does |
 | --- | --- |
@@ -28,7 +28,7 @@ const { data, error } = await mc.emails.queue({
 | `mc.metrics` | Volume, engagement, performance, recipient-behaviour, sender metrics. |
 | `mc.suppressions` | List, create, delete suppression entries. |
 
-### Key Concept: Personalizations
+## Key Concept: Personalizations
 
 A single `emails.send()` or `emails.queue()` call can produce **many individual messages**. 
 The `personalizations` array is the advanced form: each entry is one
@@ -39,7 +39,7 @@ act as defaults that each personalization can override.
 For simple sends the shorthand fields (`to`, `cc`, `bcc`, `html`, `text`) cover most cases
 without needing to write out personalizations explicitly.
 
-### `send` vs `queue`
+## `send` vs `queue`
 
 | Method | Server behaviour | When to use                                                                       |
 | --- | --- |-----------------------------------------------------------------------------------|
@@ -48,7 +48,7 @@ without needing to write out personalizations explicitly.
 
 `emails.sendAsync()` is a deprecated alias for `queue()` — use `queue()` in new code.
 
-### Response Shape
+## Response Shape
 
 Every SDK method returns one of two shapes:
 
@@ -76,7 +76,7 @@ if (error) {
 console.log(data.requestId)
 ```
 
-### Configuration
+## Configuration
 
 ```ts
 const mc = new MailChannels('YOUR-API-KEY', {

package/.agents/skills/mailchannels-js/resources/plugins/nodemailer.md

@@ -0,0 +1,112 @@
+# Nodemailer Integration
+
+The SDK ships a transport for Nodemailer so existing code that uses Nodemailer can be
+easily adapted to send via MailChannels Email API. The transport method
+`mailchannelsTransport` can be imported from `mailchannels-sdk/nodemailer`. This
+integration is optional — it requires the `nodemailer` package which the SDK does not
+include as a dependency.
+
+## 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)
+})
+```
+
+## Transport Options
+
+The transport accepts `apiKey` and `sendMode` options, as well as any SDK client
+options (`baseUrl`, `timeout`, `signal`, `retry`).
+
+Refer to the [clients-and-transport](../clients-and-transport.md) documentation for
+details and full explanations of each client option.
+
+## Field Mapping
+
+The transport converts Nodemailer `Mail.Options` in the `sendMail`
+call into the SDK's `EmailsSendOptions`. The HTTP request itself is
+entirely delegated to the SDK `MailChannelsClient`.
+
+| `Mail.Options` | `EmailsSendOptions` |
+| --- | --- |
+| `from` | `from` |
+| `to`, `cc`, `bcc` | `to`, `cc`, `bcc` (parsed into SDK `EmailsSendRecipient` objects or strings) |
+| `replyTo` | `replyTo` (if array, only the first address is used) |
+| `subject` | `subject` |
+| `text` | `text` |
+| `html` | `html` |
+| `headers` | `headers` (converted to a `Record<string,string>`) |
+| `attachments` | `attachments` (only inline buffers/strings supported — `path`/`href` are not supported) |
+| `icalEvent` | added as an attachment |
+| `dkim` | `dkim` (see DKIM notes below) |
+| `mailchannels` (augmented field on the send options) | merged into the SDK send params |
+
+### MailChannels-specific Options
+
+The SDK augments Nodemailer's `Mail.Options` type with a `mailchannels` property,
+allowing MailChannels-specific send options to be passed directly through the
+`sendMail` options object.
+
+Supported options: `campaignId`, `tracking`, `transactional`, `unsubscribe`
+
+Refer back to the original SKILL.md for links to full explanations of each field.
+
+### DKIM
+
+- Multiple DKIM signatures with the Nodemailer's `dkim.keys` field are not
+  supported; specify a single DKIM signature with `dkim.domainName`,
+  `dkim.keySelector`, and `dkim.privateKey`.
+- When providing `dkim.privateKey` as a `{ key, passphrase }` object the
+  transport attempts to convert it into a PEM via Node's `createPrivateKey`.
+- Only RSA private keys are supported
+
+## Errors and Result Structure
+
+The transport follows the Nodemailer `Transport` contract. The callback is
+called with an `error` object (if any; including SDK errors) and an `info` object
+with the following structure:
+
+```ts
+interface MailChannelsTransportInfo<T extends MailChannelsTransportSendMode> {
+  messageId: string | null; // null for async sends
+  accepted: string[]; // empty array for async sends
+  rejected: string[]; // empty array for async sends
+  envelope: MimeNode.Envelope; // `to` includes all recipients (to, cc, bcc)
+  response: (T extends "sync" ? EmailsSendResponse : EmailsQueueResponse) | null; // SDK response
+}
+```
+
+## Limitations
+
+- Only a single `replyTo` address is supported.
+- Multiple DKIM signatures are not supported; the API only supports RSA private keys.
+- Attachment `path`, `href`, and other URL-based attachment sources are not supported;
+  attachments should be provided as buffers or strings.
+- For async sends (`sendMode: 'async'`) the transport returns a `messageId` of `null`
+  and empty `accepted` / `rejected` arrays — this is an API limitation for queued sends.
+- MailChannels-specific options must be passed using the `mailchannels` augmentation on
+  the `sendMail` options object.

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

@@ -3,7 +3,7 @@
 Use `mc.emails.queue()` as the default. Switch to `mc.emails.send()` only when you
 specifically need immediate results for a small number of messages, or the dry-run preview.
 
-### Quickest Send
+## Quickest Send
 
 ```ts
 import { MailChannels } from 'mailchannels-sdk'
@@ -25,7 +25,7 @@ console.log(data.requestId)
 Provide both `text` and `html` whenever possible — receiving clients prefer the last
 matching content type and a plain-text fallback improves deliverability.
 
-### Recipient Formats
+## Recipient Formats
 
 All recipient fields (`to`, `from`, `cc`, `bcc`, `replyTo`, `envelopeFrom`) accept multiple formats
 interchangeably. Note: `from`, `replyTo`, `envelopeFrom` must be single
@@ -38,7 +38,7 @@ const r3 = { email: 'recipient@example.net', name: 'Jane Smith' }          // ob
 const r4 = ['a@example.net', { email: 'b@example.net', name: 'Bob' }]      // array
 ```
 
-### Per-Recipient Personalization
+## Per-Recipient Personalization
 
 `personalizations` is the advanced form — each entry is one fully-rendered outgoing message
 with optional per-recipient overrides:
@@ -63,7 +63,7 @@ const { data, error } = await mc.emails.queue({
 Per-personalization overridable fields: `to`, `cc`, `bcc`, `from`, `subject`, `replyTo`,
 `envelopeFrom`, `headers`, `dkim`, `template.data`.
 
-### Body Content Fields
+## Body Content Fields
 
 At least one of `html`, `text`, or `content` is required. The shorthand fields are the
 simplest form; `content` is the explicit array form for more control.
@@ -112,7 +112,7 @@ const { data: data2, error: err2 } = await mc.emails.queue({
 })
 ```
 
-### Dry Run (send endpoint only)
+## Dry Run (send endpoint only)
 
 `emails.send()` supports `dryRun: true`. The API validates and renders the message without
 delivering it. Useful for asserting templates render before launch:
@@ -136,7 +136,7 @@ console.log(data?.rendered?.[0])
 
 `emails.queue()` does **not** support dry-run.
 
-### When To Pick Which
+## When To Pick Which
 
 | Situation                                                        | Method |
 |------------------------------------------------------------------| --- |
@@ -145,7 +145,7 @@ console.log(data?.rendered?.[0])
 | Need the rendered message for inspection                         | `mc.emails.send(options, true)` |
 | Need `status` results immediately for a small number of messages | `mc.emails.send()` |
 
-### send() Response Details
+## send() Response Details
 
 ```ts
 const { data, error } = await mc.emails.send({ ... })
@@ -158,7 +158,7 @@ data?.results?.forEach(r => {
 })
 ```
 
-### Common Pitfalls
+## Common Pitfalls
 
 - **Reserved headers**: don't set `From`, `To`, `Subject`, `Reply-To`, `Message-ID`,
   `Content-Type`, `DKIM-Signature`, etc. in `headers`. Use the payload fields instead.
@@ -177,7 +177,7 @@ data?.results?.forEach(r => {
   idempotency into the caller (e.g. a unique `campaignId` + recipient-set check) when
   at-most-once delivery matters.
 
-### Tracking
+## Tracking
 
 ```ts
 const { data, error } = await mc.emails.queue({
@@ -194,7 +194,7 @@ const { data, error } = await mc.emails.queue({
 
 Open and click tracking require a subscription that supports them.
 
-### Custom Tracking Domains
+## Custom Tracking Domains
 
 Pass `customDomainName` on the `tracking` field (or on `unsubscribe`) to route those
 links through a domain you registered instead of the shared MailChannels domain.