# @kody/postmark — agent notes Human setup and intent live in [`README.md`](./README.md). This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by **name** only — never paste key values. Do not disable live webhooks or jobs. ## Auth | Lane | Credential | Notes | | --- | --- | --- | | Server (default) | User secret `postmark` | `X-Postmark-Server-Token` for send, `GET /server`, message search | | Account (optional) | User secret `postmark-account` | `X-Postmark-Account-Token` for `/servers` and `/domains` | Multi-account: `account: "work"` → `postmark-work` / `postmark-account-work`, or pass `secretName` / `accountSecretName`. Host: `api.postmarkapp.com`. Placeholders: `{{secret:postmark|scope=user}}`, `{{secret:postmark-account|scope=user}}`. ## Import paths | Export | Import | | --- | --- | | action dispatcher (defaults to smoke-test) + re-exports | `kody:@kody/postmark` | | emails | `kody:@kody/postmark/emails` | | servers | `kody:@kody/postmark/servers` | | domains | `kody:@kody/postmark/domains` | | messages | `kody:@kody/postmark/messages` | | smoke-test | `kody:@kody/postmark/smoke-test` | | scheduled-server-health | `kody:@kody/postmark/scheduled-server-health` | Low-level transport (`postmarkRequest`, `postmarkCall`, `PostmarkApiError`) is pinned to `https://api.postmarkapp.com`. Prefer named imports from the helper modules. Do not lead with `packages.invoke`. Do not invoke a personal `postmark` kody id. ## Smoke test (read-only) ```js import { smokeTest } from 'kody:@kody/postmark' export default async function main() { return await smokeTest() // without creds => { ok: true, live: false, setup: { ...URLs } } // with Server token => current server + recent outbound page; no writes } ``` ## Common snippets Read current server via root dispatcher: ```js import postmark from 'kody:@kody/postmark' export default async function main() { return await postmark({ action: 'get-server' }) } ``` Send with dry-run / confirm: ```js import { sendEmail } from 'kody:@kody/postmark/emails' export default async function main() { const preview = await sendEmail({ from: 'Name ', to: 'person@example.com', subject: 'Hello from Kody', htmlBody: '

It works!

', dryRun: true, }) // live: same args + confirm: true return preview } ``` ## dryRun / confirm (writes) | Helpers | Behavior | | --- | --- | | All mutations | `dryRun: true` → `{ dryRun: true, method, path, body, tokenKind }` | | `sendEmail`, `sendBatch`, `sendTemplateEmail`, `deleteServer`, `deleteDomain`, `rotateDkim` | Also require `confirm: true` | | `postmarkCall` writes | Default dry-run until `dryRun: false` | Never invent a default `from`. Pass a confirmed sender at call time. Server payloads strip `ApiTokens`. Leave `server-health` job `enabled: false` unless the user explicitly asks to enable it. ## Edge cases - 401 → wrong/missing token type (`postmark` vs `postmark-account`) - 422 sender → confirm signature / verify domain - 422 stream → omit `messageStream` or pass a real stream id - 429 → back off; prefer `sendBatch` for many messages