@kody/postmark
Send transactional email and manage Postmark servers, domains, and message search with dry-run mutations.
Files
@kody/postmark — agent notes
Human setup and intent live in 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)
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:
import postmark from 'kody:@kody/postmark'
export default async function main() {
return await postmark({ action: 'get-server' })
}Send with dry-run / confirm:
import { sendEmail } from 'kody:@kody/postmark/emails'
export default async function main() {
const preview = await sendEmail({
from: 'Name <hello@yourdomain.com>',
to: 'person@example.com',
subject: 'Hello from Kody',
htmlBody: '<p>It works!</p>',
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 (
postmarkvspostmark-account) - 422 sender → confirm signature / verify domain
- 422 stream → omit
messageStreamor pass a real stream id - 429 → back off; prefer
sendBatchfor many messages