Skip to content
← Public packages

@kody/postmark

Send transactional email and manage Postmark servers, domains, and message search with dry-run mutations.

FollowFork

Files

AGENTS.md

95 lines · 3.1 KB · Markdown

@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

LaneCredentialNotes
Server (default)User secret postmarkX-Postmark-Server-Token for send, GET /server, message search
Account (optional)User secret postmark-accountX-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

ExportImport
action dispatcher (defaults to smoke-test) + re-exportskody:@kody/postmark
emailskody:@kody/postmark/emails
serverskody:@kody/postmark/servers
domainskody:@kody/postmark/domains
messageskody:@kody/postmark/messages
smoke-testkody:@kody/postmark/smoke-test
scheduled-server-healthkody:@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)

HelpersBehavior
All mutationsdryRun: true → { dryRun: true, method, path, body, tokenKind }
sendEmail, sendBatch, sendTemplateEmail, deleteServer, deleteDomain, rotateDkimAlso require confirm: true
postmarkCall writesDefault 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