mailchannels-sdk 1.0.0 → 1.2.0

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

@@ -0,0 +1,91 @@
+---
+name: mailchannels-js
+description: JavaScript/TypeScript SDK for the MailChannels Email API (npm `mailchannels-sdk`; `import { MailChannels } from 'mailchannels-sdk'`). Use when sending or queueing email, working with attachments, mustache templates, unsubscribe, custom headers, DKIM keys, sub-accounts, domain checks, metrics, usage, suppressions, or webhooks (incl. signature verification); also configuring clients, testing with the built-in simulator, and error handling. Skip when (a) developing the SDK itself — defer to the repo's root AGENTS.md; (b) the user is in a non-JavaScript/TypeScript language — MailChannels publishes separate SDKs for other ecosystems and the JS types/patterns here don't apply.
+---
+
+# MailChannels JavaScript SDK
+
+This skill helps you write **JavaScript/TypeScript** code that uses the `mailchannels-sdk`
+package (npm: `mailchannels-sdk`, importable as `import { MailChannels } from 'mailchannels-sdk'`).
+It is specific to the official JavaScript SDK — MailChannels publishes separate SDKs for
+other languages and their APIs differ.
+
+> **Scope.** This skill is for *consuming* the JS SDK from application code. Working **on**
+> the SDK (adding features, fixing bugs, releasing the package) is a different job.
+>  If the user is working in a Python, Go, Ruby, PHP, Rust, or shell context, this skill does not apply.
+
+## How To Use This Skill
+
+The body of each topic lives in [`resources/`](resources/). Read this file for context and
+the decision tree, then load only the resource files that match the task. Don't preload
+everything.
+
+### Decision Tree
+
+Start at the top; descend until you hit a leaf, then read the linked resource. If multiple
+branches apply (e.g. "send + attachments + templates"), read each leaf.
+
+```
+You're about to write JS/TS SDK code. What does it need to do?
+
+├── Get oriented — what is the SDK, what are the entry points?
+│   → resources/overview.md
+│
+├── Set up the client (API keys, base URL, options, lifecycle)
+│   → resources/clients-and-transport.md
+│
+├── Send email
+│   → resources/sending.md
+│   ├── …with file / bytes / URL / inline-image attachments?
+│   │   → resources/attachments.md
+│   ├── …with a mustache template + per-recipient data?
+│   │   → resources/templates.md
+│   ├── …with an unsubscribe link or List-Unsubscribe header?
+│   │   → resources/unsubscribe.md
+│   └── …with custom X-… headers?
+│       → resources/custom-headers.md
+│
+├── Manage hosted DKIM keys (create / list / rotate / revoke)
+│   → resources/dkim.md
+│
+├── Validate a sender domain's auth posture (DKIM/SPF/Lockdown/DNS)
+│   → resources/domain-checks.md
+│
+├── Multi-tenant work — sub-accounts, their credentials, limits, usage
+│   → resources/sub-accounts.md
+│
+├── Query analytics (volume, engagement, performance, senders) or
+│   current-period usage
+│   → resources/metrics-and-usage.md
+│
+├── Manage the suppression list (list, create, delete)
+│   → resources/suppressions.md
+│
+├── Receive or manage delivery-event webhooks (enroll, validate,
+│   inspect batches, verify signatures)
+│   → resources/webhooks.md
+│
+├── Catch / log / retry SDK or API errors
+│   → resources/error-handling.md
+│
+└── Write tests without hitting the real API
+    → resources/testing.md
+```
+
+## Style Conventions In The Resources
+
+- The example code in the resources are largely compatible with both JavaScript and TypeScript.
+  Double check before copying that you don't need to strip type annotations or alter imports.
+- The JS SDK uses a **result-based** error style: every method returns `{ data, error }`
+  (`DataResponse<T>`) or `{ success, error }` (`SuccessResponse`). Check `error` before
+  using `data`. The SDK never throws for API errors — only for missing API key at
+  construction time.
+- All methods are `async` and return Promises. There are no sync variants.
+- All recipient and sender addresses use the IANA-reserved `example.com` / `example.net`
+  domains. Replace before running.
+
+## Beyond This Skill
+
+When a resource leaves something ambiguous, the SDK source itself is the final authority.
+The published `mailchannels-sdk` package on npm also ships with its own README and TypeScript
+type definitions — hover-docs in your editor are authoritative for parameter shapes.

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

@@ -0,0 +1,113 @@
+# Attachments
+
+MailChannels expects every attachment to be Base64-encoded with a `filename` and ideally a
+MIME `type`. Use the `Attachment` static helpers — they encode for you and infer the MIME
+type from the filename.
+
+### From In-Memory Bytes
+
+`fromBytes` is synchronous and accepts any `ArrayBuffer` or `Uint8Array`:
+
+```ts
+import { MailChannels, Attachment } from 'mailchannels-sdk'
+
+const mc = new MailChannels('YOUR-API-KEY')
+
+const report = Attachment.fromBytes(
+  new Uint8Array([...csvBytes]),
+  {
+    filename: 'report.csv',
+    type: 'text/csv'           // optional; inferred from filename when omitted
+  }
+)
+
+// Also accepts ArrayBuffer:
+const pdf = Attachment.fromBytes(arrayBuffer, { filename: 'doc.pdf' })
+
+const { data, error } = await mc.emails.queue({
+  from: 'billing@example.com',
+  to: 'recipient@example.net',
+  subject: 'Your invoice',
+  text: 'See attached.',
+  attachments: [report, pdf]
+})
+```
+
+### 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:
+
+```ts
+const blob = new Blob(['Hello world'], { type: 'text/plain' })
+const attachment = await Attachment.fromBlob(blob, { filename: 'hello.txt' })
+```
+
+### Inline Images (CID References)
+
+Pass `disposition: 'inline'` and a `contentId` to embed an image inside the HTML body:
+
+```ts
+const logo = Attachment.fromBytes(bytes, {
+  filename: 'logo.png',
+  disposition: 'inline',
+  contentId: 'company-logo'
+})
+
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Inline image',
+  html: "<img src='cid:company-logo' alt='Company logo'>",
+  attachments: [logo]
+})
+```
+
+### Attachment Options
+
+Both `fromBytes` and `fromBlob` accept an `AttachmentOptions` object:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `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
+
+The `attachments` field accepts `(EmailsSendAttachment | Promise<EmailsSendAttachment>)[]`,
+so you can pass unresolved promises and the SDK will await them before sending:
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Reports',
+  text: 'Reports attached.',
+  attachments: [
+    Attachment.fromBlob(blob1, { filename: 'q1.pdf' }),   // Promise<...>
+    Attachment.fromBlob(blob2, { filename: 'q2.pdf' })    // Promise<...>
+  ]
+})
+```
+
+### 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
+
+If you need to construct one by hand:
+
+```ts
+const attachment: EmailsSendAttachment = {
+  content: Buffer.from(new Uint8Array(bytes)).toString("base64"),
+  filename: 'report.pdf',
+  type: 'application/pdf'        // recommended but optional
+}
+```
+
+`content` and `filename` are required. `type` is recommended.

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

@@ -0,0 +1,98 @@
+# Clients and Transport
+
+The JS SDK requires explicit client instantiation — there is no module-level singleton or
+environment-variable auto-configuration. Create one `MailChannels` instance per credential
+set and reuse it for the lifetime of the process.
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+import process from 'node:process'
+
+const mc = new MailChannels(process.env.MAILCHANNELS_API_KEY)
+```
+
+A missing or empty API key throws synchronously at construction:
+
+```ts
+new MailChannels('')   // throws Error: "Missing MailChannels API key."
+```
+
+### Constructor Options
+
+```ts
+// new MailChannels(apiKey: string, options?: MailChannelsClientOptions)
+```
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `baseUrl` | `string` | `https://api.mailchannels.net` | Only override if MailChannels gives you a specific alternate endpoint (sandbox, regional URL). |
+| `timeout` | `number \| false` | `120000` (ms) | Pass `false` to disable the timeout entirely. |
+| `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
+
+Never share a parent key and a sub-account key on the same instance. Create a separate
+`MailChannels` for each credential:
+
+```ts
+const parent  = new MailChannels(process.env.PARENT_API_KEY)
+const tenantA = new MailChannels(process.env.TENANT_A_API_KEY)
+const tenantB = new MailChannels(process.env.TENANT_B_API_KEY)
+
+const { data: accounts, error: listErr } = await parent.subAccounts.list()
+if (listErr) { /*...*/ }
+
+const { data: queueA, error: queueErrA } = await tenantA.emails.queue({ ... })
+if (queueErrA) { /*...*/ }
+
+const { data: queueB, error: queueErrB } = await tenantB.emails.queue({ ... })
+if (queueErrB) { /*...*/ }
+```
+
+### Request Cancellation
+
+Pass an `AbortSignal` to cancel in-flight requests:
+
+```ts
+const controller = new AbortController()
+
+const mc = new MailChannels(apiKey, { signal: controller.signal })
+
+// Later:
+controller.abort()
+```
+
+### Headers Sent On Every Request
+
+The SDK sets these on every request and they cannot be overridden via `MailChannelsClientOptions`:
+
+- `X-API-Key: <your key>`
+- `Accept: application/json`
+- `Content-Type: application/json`
+- `User-Agent: mailchannels-node/<version>`
+
+### 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
+`_fetch<T>()` (a `protected` method).
+
+```ts
+import { MailChannelsClient } from 'mailchannels-sdk'
+
+class InstrumentedClient extends MailChannelsClient {
+  protected override async _fetch<T>(path: string, options: FetchOptions<'json'>) {
+    const start = performance.now()
+    try {
+      const result = await super._fetch<T>(path, options)
+      recordLatency(path, performance.now() - start)
+      return result
+    }
+    catch (err) {
+      recordError(path)
+      throw err
+    }
+  }
+}
+```

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

@@ -0,0 +1,64 @@
+# Custom Headers
+
+Use `headers` for application-specific metadata, tracking IDs, campaign tags, or any
+custom `X-…` header.
+
+### Root vs Per-Personalization
+
+- **Root `headers`**: applied to every personalization.
+- **Per-personalization `headers`**: applied only to that personalization.
+- **If the same header appears in both, the personalization value wins.**
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  subject: 'Hello',
+  text: 'Hello',
+  headers: {
+    'X-Campaign-ID': 'newsletter-2026-05',
+    'X-Project': 'growth'
+  },
+  personalizations: [
+    {
+      to: 'alice@example.net',
+      headers: { 'X-Tier': 'pro' }
+    },
+    {
+      to: 'bob@example.net',
+      headers: { 'X-Tier': 'free', 'X-Campaign-ID': 'growth-override' }
+    }
+  ]
+})
+```
+
+### 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
+checked case-insensitively, so `From`, `from`, and `FROM` are all rejected.
+
+| Reserved header | Set via payload field |
+| --- | --- |
+| `From` | `from` |
+| `To` | `personalizations[].to` |
+| `CC` | `personalizations[].cc` or root `cc` |
+| `BCC` | `personalizations[].bcc` or root `bcc` |
+| `Subject` | `subject` (root) or `personalizations[].subject` |
+| `Reply-To` | `replyTo` (root) or `personalizations[].replyTo` |
+| `DKIM-Signature` | `dkim.domain` / `dkim.selector` / `dkim.privateKey` |
+| `Content-Type`, `Content-Transfer-Encoding` | `content[].type` and encoding the API chooses |
+| `Message-ID` | Returned in `results[].messageId` |
+| `Authentication-Results`, `Received` | Generated by the API |
+
+This list mirrors the SDK's `RESERVED_HEADER_NAMES` set — keep them in sync if MailChannels
+changes the list upstream.
+
+### 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
+
+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/custom-tracking-domains.md

@@ -0,0 +1,83 @@
+# Custom Tracking Domains
+
+Register your own hostname for click tracking, open tracking, or unsubscribe
+links instead of MailChannels' shared domains. Once a domain is `active`,
+select it by `name` via `customDomainName` on the send payload — see
+[sending.md](sending.md#custom-tracking-domains).
+
+## Register A Domain
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels('YOUR-API-KEY')
+
+const { data, error } = await mc.domains.customTracking.create(
+  'newsletter-clicks',     // label used at send time, ^[a-z0-9-]+$, max 64
+  'click.example.com',
+  'click'                 // click | open | unsubscribe
+)
+```
+
+Before this can complete, `hostname` needs a CNAME record pointing to
+`links.mailchannels.net`.
+
+## DNS Verification Is A Two-Step, Non-Error Flow
+
+`create()` and `update()` (when re-activating a disabled domain) return one
+of two shapes in `data` — both are 2xx responses, not errors:
+
+- **Registered**: `dnsSetupRequired: false` with `name`, `hostname`, `scope`,
+  `status`, `createdAt` are all present..
+- **Pending**: `dnsSetupRequired: true` with `token`, `txtRecordName`,
+  `txtRecordValue`, `instructions` is present (a CNAME-only failure can omit the TXT
+  fields; a fresh registration includes all of them).
+
+Add the TXT record alongside the CNAME, wait for propagation, then call
+`create()` again with the same `name`/`hostname`/`scope`.
+
+If DNS still isn't in place on retry, MailChannels responds `422` instead of
+`202` — that's a real error status, so the SDK returns an `error` object.
+The same pending-verification body is on `error.response`:
+
+```ts
+const { data, error } = await mc.domains.customTracking.create(
+  'newsletter-clicks',
+  'click.example.com',
+  'click'
+)
+
+if (error) {
+  if (error.statusCode === 422 && error.response) {
+    console.log(error.response.instructions)
+  }
+  return;
+}
+```
+
+## List, Update, Delete
+
+```ts
+// List
+const { data: listData, error: listError } = await mc.domains.customTracking.list({
+  scope: 'click',       // optional filter
+  status: 'active',     // optional filter: active | disabled
+  limit: 100,
+  offset: 0
+})
+
+// Update
+const { data: updateData, error: updateError } = await mc.domains.customTracking.update(
+  'click.example.com',
+  'click',
+  { status: 'disabled' }   // or { name: 'new-label' } to rename
+)
+
+// Delete
+const { success, error: deleteError } = await mc.domains.customTracking.delete('click.example.com', 'click')
+```
+
+Deleting a domain takes effect immediately — tracking links and unsubscribe
+URLs already sent using that domain stop working right away. Re-activating a
+domain whose DNS verification has since lapsed goes through the same
+pending-result flow as `create()`.

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

@@ -0,0 +1,148 @@
+# DKIM
+
+MailChannels can host the **private** DKIM key for you. You publish the **public** key in
+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
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels('YOUR-API-KEY')
+
+const { data, error } = await mc.domains.dkim.create('example.com', {
+  selector: 'mcdkim',
+  algorithm: 'rsa',    // only 'rsa' is currently supported
+  length: 2048         // 1024 or 2048; default 2048; multiples of 1024
+})
+
+if (error) throw new Error(error.message)
+
+for (const record of data?.dnsRecords ?? []) {
+  console.log(record.name, record.type, record.value)
+  // e.g. mcdkim._domainkey.example.com  TXT  "v=DKIM1; k=rsa; p=MIIBIj..."
+}
+```
+
+The returned `data.dnsRecords` contains TXT records you must publish in DNS.
+
+### List, Filter, And Include DNS Records
+
+```ts
+const { data, error } = await mc.domains.dkim.list('example.com', {
+  selector: 'mcdkim',          // optional; returns at most one
+  status: 'active',            // 'active' | 'retired' | 'revoked' | 'rotated'
+  includeDnsRecord: true,      // include suggested DNS record per key
+  limit: 10,
+  offset: 0
+})
+```
+
+### Key Lifecycle
+
+| Status | Meaning |
+| --- | --- |
+| `active` | Currently used for signing. |
+| `rotated` | Being rotated out. Still valid for signing for a 3-day grace period; auto-changes to `retired` 2 weeks after rotation. |
+| `retired` | No longer in use. |
+| `revoked` | Marked compromised. Stop using immediately. |
+
+#### Update status directly
+
+```ts
+const { success, error } = await mc.domains.dkim.updateStatus('example.com', {
+  selector: 'mcdkim',
+  status: 'revoked'      // 'revoked' | 'retired' | 'rotated'
+})
+```
+
+Only `active` keys can move to `rotated`. Only `revoked`, `retired`, and `rotated` are
+valid update targets.
+
+#### Rotate (recommended for routine rollover)
+
+```ts
+const { data, error } = await mc.domains.dkim.rotate('example.com', 'mcdkim', {
+  newKey: { selector: 'mcdkim2' }
+})
+
+// data.new     is the new key info; data.rotated is the old one.
+// data.rotated.gracePeriodExpiresAt says when signing with it stops.
+```
+
+Rotation:
+
+1. Marks the existing key `rotated` (still valid for **3 days** — cut-off in
+   `gracePeriodExpiresAt`).
+2. Creates a new active key with the new selector, reusing the same algorithm and key
+   length.
+3. The rotated key is auto-retired **2 weeks** after 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
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Signed',
+  text: 'Signed by hosted DKIM.',
+  dkim: {
+    domain: 'example.com',
+    selector: 'mcdkim'
+  }
+})
+```
+
+If `dkim.selector` is set without `dkim.domain`, MailChannels takes the domain from the
+`from` address.
+
+### Sending With A Customer-Managed Key
+
+If you keep the private key yourself, pass it Base64-encoded (PEM headers are stripped
+automatically):
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Signed',
+  text: 'Signed by my own DKIM key.',
+  dkim: {
+    domain: 'example.com',
+    selector: 'mcdkim',
+    privateKey: '<base64-encoded-or-PEM-private-key>'
+  }
+})
+```
+
+`dkim` can also be set per-personalization to override the root value.
+
+### DNS Publication
+
+MailChannels does not host the public DKIM DNS record — you do. The SDK returns the exact
+record to publish in `data.dnsRecords`:
+
+| Field | Value |
+| --- | --- |
+| `name` | DNS host. Always `{selector}._domainkey.{domain}`. |
+| `type` | Always `TXT`. |
+| `value` | Public key material. **Publish verbatim** — do not re-wrap, strip quotes, or split lines. |
+
+#### Required Steps
+
+1. **Create** with `mc.domains.dkim.create(domain, { selector })`. Capture `dnsRecords`.
+2. **Resolve the DNS zone** in your provider's API.
+3. **Create or update** the TXT record at `record.name` with `record.value`. Use a short
+   TTL (300 s) so future rotations propagate quickly.
+4. **Wait for propagation**, then verify with `mc.domains.check(domain, { dkim: [{ selector }] })`.
+   The `dkim[].verdict` must be `'passed'` before sending real traffic.
+5. **For rotations**, leave the old TXT record in place until `gracePeriodExpiresAt`.
+
+### 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

@@ -0,0 +1,100 @@
+# Domain Checks
+
+Use `mc.domains.check()` to confirm a sender domain is properly authenticated before
+sending from it. The check covers four things:
+
+- **DKIM** — does the domain publish a DKIM public key matching the selectors MailChannels
+  signs with?
+- **SPF** — is MailChannels in the domain's SPF record?
+- **Sender-domain DNS** — does the domain have at least one `A` or `MX` record? Receivers
+  reject mail without either as **SDNF** ("Sender Domain Not Found").
+- **Domain Lockdown** — a MailChannels feature that ties a sending domain to your account
+  so other MailChannels customers cannot spoof it.
+
+### Basic Check
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels('YOUR-API-KEY')
+
+const { data, error } = await mc.domains.check('example.com')
+
+if (error) throw new Error(error.message)
+
+console.log(data?.spf?.verdict)            // 'passed' | 'failed' | …
+console.log(data?.domainLockdown?.verdict) // 'passed' | 'failed'
+console.log(data?.senderDomain?.verdict)   // 'passed' | 'failed'
+console.log(data?.dkim)                    // array of per-selector results
+console.log(data?.references)             // support links if anything failed
+```
+
+### With Specific DKIM Settings
+
+If you don't pass `dkim`, MailChannels uses all stored keys for the domain. To target
+specific selectors:
+
+```ts
+const { data, error } = await mc.domains.check('example.com', {
+  dkim: [
+    {
+      domain: 'example.com',
+      selector: 'mcdkim-2025'
+    },
+    {
+      domain: 'example.com',
+      selector: 'mcdkim-2026'
+    }
+  ]
+})
+```
+
+You can pass up to **10** DKIM settings per call.
+
+If you only need to provide a single DKIM setting, you may pass it as an object instead
+of an array:
+
+```ts
+const { data, error } = await mc.domains.check('example.com', {
+  dkim: {
+    domain: 'example.com',
+    selector: 'mcdkim'
+  }
+})
+```
+
+#### DKIM Settings Resolution Rules
+
+| Provided fields | Behavior |
+| --- | --- |
+| `domain`, `selector`, `privateKey` all present | Verify with the provided key. |
+| `domain`, `selector` | Use the stored private key for that domain + selector. |
+| `domain` only | Use **all** stored keys for that domain. |
+| `selector` only | Use the `domain` from the request body. |
+| `privateKey` set | `selector` is required too. |
+| `dkim` empty / absent | Use all stored keys for the request domain. |
+
+### With A Sender ID (Domain Lockdown)
+
+If your lockdown record uses `senderid=` or `sidw=` fields, pass the sender identity:
+
+```ts
+const { data, error } = await mc.domains.check('example.com', {
+  senderId: 'example|domain|example.com'
+})
+```
+
+If your lockdown record uses `auth=` (account-wide authorization), omit `senderId`.
+
+### 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
+
+- During onboarding for every new sending domain.
+- In CI after rotating DKIM keys, to verify the new DNS record propagated.
+- In a periodic monitoring job (verdicts can drift if DNS changes).