mailchannels-sdk 1.0.0 → 1.2.0

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

@@ -0,0 +1,143 @@
+# Error Handling
+
+The JS SDK uses a **result-based** error style. Every method returns either a
+`DataResponse<T>` or a `SuccessResponse` — the SDK never throws for API errors.
+
+```ts
+type DataResponse<T> =
+  | { data: T;    error: null }
+  | { data: null; error: ErrorResponse }
+
+type SuccessResponse = {
+  success: boolean
+  error: ErrorResponse | null
+}
+```
+
+Always destructure and check `error` before using the result:
+
+```ts
+const { data, error } = await mc.emails.queue({ ... })
+
+if (error) {
+  // error.message    — human-readable description
+  // error.type       — stable string identifier (see table below)
+  // error.statusCode — HTTP status code, or null for non-HTTP errors
+  // error.response   — Response body (Object) for 4xx/5xx errors
+  console.error(error.message, error.type, error.statusCode)
+  return
+}
+// data is non-null here
+console.log(data.requestId)
+```
+
+### Error Types
+
+| `error.type` | HTTP status | Meaning |
+| --- | --- | --- |
+| `'invalid_request_error'` | 400 | Bad payload, validation errors. |
+| `'authentication_error'` | 401 | Invalid or missing API key. |
+| `'permission_error'` | 403 | Feature not enabled or account limits. |
+| `'not_found'` | 404 | Resource not found. |
+| `'conflict_error'` | 409 | Duplicate webhook, duplicate suppression, etc. |
+| `'payload_too_large_error'` | 413 | Over the 30 MB limit. |
+| `'unprocessable_entity_error'` | 422 | Semantically invalid request. |
+| `'rate_limit_error'` | 429 | Too many requests — slow down. |
+| `'internal_server_error'` | 500 | Generic server-side failure. |
+| `'validation_error'` | `null` | Client-side validation failed before any HTTP call. |
+| `'application_error'` | `null` | Unexpected JS/network error (e.g. fetch failed). |
+| `'api_error'` | varies | Fallback for unmapped status codes. |
+
+### 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.
+
+```ts
+const { data, error } = await mc.emails.queue(message)
+
+if (error) {
+  switch (error.type) {
+    case 'payload_too_large_error':
+      // Split recipient list or shrink attachments, then retry.
+      break
+    case 'rate_limit_error':
+      // Back off and retry — check error.statusCode === 429.
+      break
+    case 'invalid_request_error':
+    case 'validation_error':
+      // Application bug — fix the payload, don't retry blindly.
+      console.error('Invalid payload:', error.message)
+      break
+    case 'authentication_error':
+      // Wrong API key. Don't retry.
+      console.error('Invalid authentication:', error.message)
+      break
+    case 'permission_error':
+      // Feature gated or sub-account suspended. Don't retry.
+      console.error('Permission denied:', error.message)
+      break
+    case 'internal_server_error':
+    case 'application_error':
+      // Transient — retry with exponential backoff.
+      break
+    default:
+      console.error('Unexpected error:', error.message)
+  }
+}
+```
+
+### Client-Side Validation Errors (`validation_error`)
+
+These produce `error.type === 'validation_error'` and `error.statusCode === null` before
+any HTTP call:
+
+- Missing `from`, `to` / `personalizations`, `subject`, body content.
+- Empty collections.
+- Reserved headers in `headers`.
+- Non-string header values.
+- `campaignId` too long or containing spaces.
+- `personalizations` with `transactional: false` and multiple recipients.
+- Invalid DKIM field combinations.
+
+Failing early gives a precise error rather than a vague 400.
+
+### Retrying and Idempotency
+
+| Error type | Safe to retry? |
+| --- | --- |
+| `invalid_request_error`, `authentication_error`, `permission_error`, `conflict_error`, `payload_too_large_error`, `validation_error` | **No** — caller problem; fix the input or credentials. |
+| `rate_limit_error` | Yes, after backing off. |
+| `internal_server_error`, `application_error` | Yes, with exponential backoff. |
+
+The API has no idempotency keys, so retrying `emails.send()` or `emails.queue()` after a
+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
+
+`new MailChannels('')` (empty or missing key) throws synchronously:
+
+```ts
+try {
+  const mc = new MailChannels(process.env.MAILCHANNELS_API_KEY)
+  // ...
+}
+catch (err) {
+  // err.message === 'Missing MailChannels API key.'
+}
+```
+
+`Attachment.fromBlob` (invalid object type) throws when called synchronously:
+
+```ts
+try {
+  const attachment = await Attachment.fromBlob(blob1, { filename: "file.pdf" })
+  // ...
+}
+catch (err) {
+  // err.message === 'Unable to create attachment: expected a Blob.'
+}
+```
+
+Almost all other failure modes surface through the `error` field in the returned result object.

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

@@ -0,0 +1,114 @@
+# Metrics and Usage
+
+The metrics module exposes the operational view of your traffic. Usage exposes
+billing-period totals.
+
+### Time-Series Metrics
+
+The four time-series methods share the same `MetricsOptions` parameter shape: optional
+`startTime`, `endTime`, `campaignId`, and `interval`.
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels('YOUR-API-KEY')
+
+const { data, error } = await mc.metrics.volume({
+  startTime: '2026-04-01',
+  endTime:   '2026-05-01T00:00:00Z',
+  interval:  'day',        // 'hour' | 'day' | 'week' | 'month' (default 'day')
+  campaignId: 'welcome'   // optional filter
+})
+
+// Date objects are also accepted
+const { data: last7d, error: error7days } = await mc.metrics.volume({
+  startTime: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),  // 7 days ago
+  endTime:   new Date(),
+  interval:  'day'
+})
+if (error) { /*...*/ }
+
+// Same parameter shape — pass the same options to any of these:
+const { data: engagement, error: engErr }   = await mc.metrics.engagement({ interval: 'day' })
+const { data: perf,       error: perfErr }  = await mc.metrics.performance({ interval: 'day' })
+const { data: behaviour,  error: behErr }   = await mc.metrics.recipientBehaviour({ interval: 'day' })
+```
+
+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
+
+Each response includes both totals **and** a `buckets` object grouped by metric name, each
+containing a list of `{ count, periodStart }` rows aligned to `interval`.
+
+```ts
+const { data, error } = await mc.metrics.volume({ interval: 'day' })
+if (error) { /*...*/ }
+
+for (const bucket of data?.buckets.processed ?? []) {
+  console.log(bucket.periodStart, bucket.count)
+}
+```
+
+#### Volume Buckets
+
+`data.buckets` has `processed`, `delivered`, `dropped`.
+
+#### Engagement Buckets
+
+`data.buckets` has `open`, `click`, `uniqueOpen`, `uniqueClick`, `openTrackingDelivered`,
+`clickTrackingDelivered`, `uniqueOpenTrackingDelivered`, `uniqueClickTrackingDelivered`.
+
+#### Performance Buckets
+
+`data.buckets` has `processed`, `delivered`, `bounced`, `complained`.
+
+#### Recipient Behaviour Buckets
+
+`data.buckets` has `unsubscribed`, `unsubscribeDelivered`.
+
+### Sender Metrics
+
+`mc.metrics.senders()` lists per-sender totals grouped either by campaign or sub-account.
+
+```ts
+const { data, error } = await mc.metrics.senders(
+  'campaigns',           // required: 'campaigns' | 'sub-accounts'
+  {
+    startTime:  '2026-04-01',
+    endTime:    '2026-05-01',
+    limit:      50,          // 1..1000, default 10
+    offset:     0,
+    sortOrder:  'desc'       // 'asc' | 'desc', default desc (by processed + dropped)
+  }
+)
+if (error) { /*...*/ }
+
+for (const sender of data?.senders ?? []) {
+  console.log(sender.name, sender.processed, sender.bounced)
+}
+```
+
+Senders with **zero traffic in the time range are omitted** from the response.
+
+### Usage
+
+```ts
+const { data: usage, error } = await mc.metrics.usage()
+if (error) { /*...*/ }
+
+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
+
+- **Daily dashboard**: `mc.metrics.volume({ interval: 'day' })` plus
+  `mc.metrics.engagement({ interval: 'day' })` over the same range.
+- **Campaign post-mortem**: pass `campaignId` on each call, then read totals and buckets.
+- **Top senders by sub-account**: `mc.metrics.senders('sub-accounts', { sortOrder: 'desc' })`.
+- **Billing reconciliation**: `mc.metrics.usage()` plus each sub-account's
+  `mc.subAccounts.getUsage(handle)` should sum within the parent's limit.

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

@@ -0,0 +1,91 @@
+# SDK Overview
+
+The `mailchannels-sdk` npm package exports a `MailChannels` class. Instantiate it once with
+your API key and use the attached module properties for every operation.
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels(process.env.MAILCHANNELS_API_KEY)
+    
+// Send email
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Hello',
+  text: 'Plain text body.'
+})
+```
+
+### Module Inventory
+
+| Property | What it does |
+| --- | --- |
+| `mc.emails` | Send (`send`) and queue (`queue`) email. |
+| `mc.domains` | Check domain auth posture; manage hosted DKIM keys via `mc.domains.dkim`. |
+| `mc.webhooks` | Enroll, validate, inspect batches, verify signatures. |
+| `mc.subAccounts` | Manage sub-accounts (multi-tenant). |
+| `mc.metrics` | Volume, engagement, performance, recipient-behaviour, sender metrics. |
+| `mc.suppressions` | List, create, delete suppression entries. |
+
+### 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
+fully-resolved outgoing message with its own `to` / `cc` / `bcc`, per-recipient template
+variables, header overrides, and so on. The top-level `from` / `subject` / `html` / `text`
+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`
+
+| Method | Server behaviour | When to use                                                                       |
+| --- | --- |-----------------------------------------------------------------------------------|
+| `emails.send()` | Synchronous — full per-recipient processing in the request. Returns per-personalization `results` with `messageId` and `status`. Supports `dryRun`. | When you need the rendered output back immediately for small numbers of messages. |
+| `emails.queue()` | Queued — per-recipient work runs in the background. Returns `requestId` and `queuedAt` immediately. | Most production sends: web handlers, background workers, high throughput.         |
+
+`emails.sendAsync()` is a deprecated alias for `queue()` — use `queue()` in new code.
+
+### Response Shape
+
+Every SDK method returns one of two shapes:
+
+```ts
+// Methods that return data:
+type DataResponse<T> =
+  | { data: T;    error: null }
+  | { data: null; error: ErrorResponse }
+
+// Methods that confirm an operation:
+type SuccessResponse = {
+  success: boolean
+  error: ErrorResponse | null
+}
+```
+
+Always check `error` before using `data` or `success`:
+
+```ts
+const { data, error } = await mc.emails.queue({ ... })
+if (error) {
+  console.error(error.message, error.type, error.statusCode)
+  return
+}
+console.log(data.requestId)
+```
+
+### Configuration
+
+```ts
+const mc = new MailChannels('YOUR-API-KEY', {
+  baseUrl: 'https://api.mailchannels.net', // rarely needed
+  timeout: 120000,                          // ms, default 120s; false to disable
+  retry: false,                             // ofetch retry options
+  signal: controller.signal                 // AbortSignal for cancellation
+})
+```
+
+Missing API key throws synchronously at construction time. All
+other errors surface as `error` in the returned result object.

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

@@ -0,0 +1,221 @@
+# Sending Email
+
+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
+
+```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: 'recipient@example.net',
+  subject: 'Hello',
+  text: 'Plain text body.',
+  html: '<p>HTML body.</p>'
+})
+
+if (error) throw new Error(error.message)
+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
+
+All recipient fields (`to`, `from`, `cc`, `bcc`, `replyTo`, `envelopeFrom`) accept multiple formats
+interchangeably. Note: `from`, `replyTo`, `envelopeFrom` must be single
+recipient values (a string or an object) and do NOT accept array:
+
+```ts
+const r1 = 'recipient@example.net'                                          // string
+const r2 = 'Jane Smith <recipient@example.net>'                             // display-name string
+const r3 = { email: 'recipient@example.net', name: 'Jane Smith' }          // object
+const r4 = ['a@example.net', { email: 'b@example.net', name: 'Bob' }]      // array
+```
+
+### Per-Recipient Personalization
+
+`personalizations` is the advanced form — each entry is one fully-rendered outgoing message
+with optional per-recipient overrides:
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  subject: 'Your update',
+  text: 'Hello!',
+  personalizations: [
+    {
+      to: 'alice@example.net',
+      subject: "Alice's update"  // overrides root subject
+    },
+    {
+      to: 'bob@example.net'       // inherits root subject
+    }
+  ]
+})
+```
+
+Per-personalization overridable fields: `to`, `cc`, `bcc`, `from`, `subject`, `replyTo`,
+`envelopeFrom`, `headers`, `dkim`, `template.data`.
+
+### 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.
+
+| Field | Type | When to use |
+| --- | --- | --- |
+| `html` | `string` | HTML body. Shorthand for a `text/html` content part. |
+| `text` | `string` | Plain text body. Shorthand for a `text/plain` content part. |
+| `content` | `EmailsSendContent[]` | Explicit list of `{ type, value }` parts. Required when using non-standard MIME types or when you need strict ordering. |
+
+Mixing rules: you cannot include a `text/html` entry in `content` when `html` is also set,
+and cannot include `text/plain` when `text` is also set.
+
+```ts
+// Shorthand — simplest form for most sends
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Hello',
+  text: 'Plain text fallback.',
+  html: '<p>HTML body.</p>'
+})
+
+// Explicit content array — use when you need a non-standard MIME type
+// or want precise control over part ordering
+const { data: data1, error: err1 } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Hello',
+  content: [
+    { type: 'text/plain', value: 'Plain text fallback.' },
+    { type: 'text/html',  value: '<p>HTML body.</p>' }
+  ]
+})
+
+// Mixed — shorthand + extra content parts (no type collision)
+const { data: data2, error: err2 } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Hello',
+  text: 'Plain text fallback.',
+  html: '<p>HTML body.</p>',
+  content: [
+    { type: 'text/calendar', value: iCalString }  // additional part; no text/plain or text/html here
+  ]
+})
+```
+
+### 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:
+
+```ts
+const { data, error } = await mc.emails.send(
+  {
+    from: 'sender@example.com',
+    to: 'recipient@example.net',
+    subject: 'Preview {{name}}',
+    text: 'Hello {{name}}',
+    template: { type: 'mustache', data: { name: 'World' } }
+  },
+  true  // dryRun
+)
+if (error) { /* ... */ }
+
+// data.rendered is a string[] — one rendered message per personalization
+console.log(data?.rendered?.[0])
+```
+
+`emails.queue()` does **not** support dry-run.
+
+### When To Pick Which
+
+| Situation                                                        | Method |
+|------------------------------------------------------------------| --- |
+| Web request handler, background worker, high throughput          | `mc.emails.queue()` |
+| Sending to many recipients in one call                           | `mc.emails.queue()` |
+| 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
+
+```ts
+const { data, error } = await mc.emails.send({ ... })
+if (error) { /* ... */ }
+
+data?.results?.forEach(r => {
+  console.log(r.messageId, r.status, r.reason)
+  // r.status is 'sent' or 'failed'
+  // 'sent' is a temporary status; final outcome arrives via webhooks
+})
+```
+
+### 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.
+  See [custom-headers](custom-headers.md).
+- **Payload size limit**: 30 MB total (headers + body + attachments). The API returns
+  `payload_too_large_error` with `statusCode: 413`.
+- **Per-personalization limits**: up to 1000 `to` recipients per personalization, 1000
+  personalizations per call, 1000 attachments per call.
+- **Non-transactional sends** require exactly one recipient per personalization and DKIM
+  signing. See [unsubscribe](unsubscribe.md).
+- **`campaignId`**: ≤ 48 UTF-8 characters, no spaces. Validated before the request leaves
+  the client.
+- **Click tracking** only rewrites `<a>` tags whose URL is non-empty, starts with
+  `http`/`https`, and does not have `clicktracking="off"`.
+- **No idempotency keys**: retrying after a transient failure can duplicate sends. Build
+  idempotency into the caller (e.g. a unique `campaignId` + recipient-set check) when
+  at-most-once delivery matters.
+
+### Tracking
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Tracked',
+  html: '<p>Hello <a href="https://example.com">click here</a></p>',
+  tracking: {
+    open:  { enable: true },
+    click: { enable: true }
+  }
+})
+```
+
+Open and click tracking require a subscription that supports them.
+
+### 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.
+The name must match an **active** custom tracking domain registered for that
+scope — see [custom-tracking-domains](custom-tracking-domains.md) for
+registration and DNS verification.
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Tracked with a custom domain',
+  html: "<p>Hello <a href='https://example.com'>click here</a></p>",
+  tracking: {
+    click: {
+      enable: true,
+      customDomainName: 'newsletter-clicks'
+    }
+  },
+  unsubscribe: {
+    customDomainName: 'newsletter-unsubscribe'
+  }
+})
+```

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

@@ -0,0 +1,129 @@
+# Sub-Accounts
+
+Sub-accounts are first-class on MailChannels. Use them for tenants, customers, or isolated
+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
+
+A handle uniquely identifies a sub-account. Rules:
+
+- 3–128 characters.
+- **Lowercase alphanumeric only.** No hyphens, underscores, or uppercase.
+- Unique per parent account.
+- If omitted on create, a random handle is generated.
+
+### Lifecycle
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels('PARENT-ACCOUNT-API-KEY')
+
+// Create
+const { data: sub, error: createError } = await mc.subAccounts.create('Client A', 'clienta')
+if (createError) { /*...*/ }
+
+// List (paginated; default limit 1000)
+const { data: page, error: listErr } = await mc.subAccounts.list({ limit: 100, offset: 0 })
+if (listErr) { /*...*/ }
+
+
+// Suspend / activate
+const { error: suspendErr } = await mc.subAccounts.suspend('clienta')
+if (suspendErr) { /*...*/ }
+
+const { error: activateErr } = await mc.subAccounts.activate('clienta')
+if (activateErr) { /*...*/ }
+
+// Delete
+const { error: deleteError } = await mc.subAccounts.delete('clienta')
+if (deleteError) { /*...*/ }
+```
+
+### Credentials
+
+Each sub-account has its own API keys and SMTP passwords.
+
+```ts
+// API keys
+const { data: createdKey, error: createErr } = await mc.subAccounts.apiKeys.create('clienta')
+if (createErr) { /*...*/ }
+// Store createdKey.key immediately — only returned once
+
+const { data: keys, error: listErr } = await mc.subAccounts.apiKeys.list('clienta')
+if (listErr) { /*...*/ }
+
+const { error: deleteErr } = await mc.subAccounts.apiKeys.delete('clienta', storedKeyId)
+if (deleteErr) { /*...*/ }
+
+// SMTP passwords
+const { data: createdPwd, error: createPwdErr } = await mc.subAccounts.smtpPasswords.create('clienta')
+if  (createPwdErr) { /*...*/ }
+// Store createdPwd.smtpPassword immediately — only returned once
+
+const { data: passwords, error: listPwdErr } = await mc.subAccounts.smtpPasswords.list('clienta')
+if (listPwdErr) { /*...*/ }
+
+const { error: deletePwdErr } = await mc.subAccounts.smtpPasswords.delete('clienta', storedPasswordId)
+if (deletePwdErr) { /*...*/ }
+```
+
+**Listed keys and passwords are redacted.** The full secret is only returned once, at
+create time. Store it immediately or rotate. Each sub-account has server-side caps on how
+many API keys and SMTP passwords it can hold — once at the cap, create returns
+`unprocessable_entity_error`; delete an unused credential first.
+
+### Limits
+
+Per-sub-account monthly send caps. A sub-account without a limit inherits the parent's
+capacity.
+
+```ts
+const { error: setLimitErr } = await mc.subAccounts.limits.set('clienta', { sends: 100_000 })
+if (setLimitErr) { /*...*/ }
+
+const { data: limit, error: getLimitErr } = await mc.subAccounts.limits.get('clienta')
+if (getLimitErr) { /*...*/ }
+
+const { error: deleteLimitErr } = await mc.subAccounts.limits.delete('clienta')   // back to inheriting parent
+if (deleteLimitErr) { /*...*/ }
+```
+
+### Usage
+
+```ts
+const { data: parentUsage } = await mc.metrics.usage()
+const { data: subUsage }    = await mc.subAccounts.getUsage('clienta')
+
+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
+
+Create a separate `MailChannels` instance with the sub-account's API key:
+
+```ts
+const subClient = new MailChannels('SUB-ACCOUNT-API-KEY')
+
+const { error } = await subClient.emails.queue({
+  from: 'sender@client.example',
+  to: 'recipient@example.net',
+  subject: 'From a tenant',
+  text: 'Hello'
+})
+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
+
+When creating suppressions on the parent, set `addToSubAccounts: true` to also copy entries
+into every sub-account. See [suppressions](suppressions.md).