# @kody/postmark ## Intent Reusable Postmark helpers so Kody agents can send transactional email, inspect the current server, manage account servers and sending domains, and search outbound or inbound messages on **the caller's** Postmark account — not a shared platform inbox. Auth is a saved Server API token by default. Reads are free-form; mutations support `dryRun: true`, and sends or deletes also require `confirm: true`. This listing is meant to be forked. After you fork, save your own `postmark` credential and call the helpers in your account. There are no baked-in server tokens or from-addresses. Share https://kody.codes/@kody/postmark — never a `/community/{listing_id}` URL. Import the official package as `kody:@kody/postmark`. Do not invoke a personal `postmark` kody id; that can resolve a different account package. ## What it does - Send single, batch, and template transactional email (after `confirm: true`) - Read the current server; list/create/edit/delete account servers - Manage sending domains (DKIM / Return-Path verify, rotate, delete) - Search outbound and inbound messages and fetch message details - Read-only smoke / scheduled server-health wrapper (job starts disabled) ## Prerequisites / setup Default auth is a **Postmark Server API token** (secret-backed). There is no built-in platform OAuth app. Do not paste the token into chat. 1. Open a server at [account.postmarkapp.com/servers](https://account.postmarkapp.com/servers) and copy the Server API token from its **API Tokens** tab. Sending also needs a confirmed sender signature or verified domain on that server. 2. Save it in Kody: https://kody.codes/account/secrets/new?name=postmark&description=Postmark%20Server%20API%20token%20for%20sending%2C%20the%20current%20server%2C%20and%20message%20search&allowedHosts=api.postmarkapp.com&scope=user 3. In the account secrets UI, approve host **`api.postmarkapp.com`**. Saving the secret does not approve hosts by itself. ### Optional Account API token Listing every server, creating/deleting servers, and managing domains use `X-Postmark-Account-Token`. Copy that token from the account **API Tokens** tab (Account Owner / Admin only): https://kody.codes/account/secrets/new?name=postmark-account&description=Postmark%20Account%20API%20token%20for%20listing%20servers%20and%20managing%20domains&allowedHosts=api.postmarkapp.com&scope=user `GET /server`, sending, and message search stay on the Server token. ### Multi-account There are no hard-coded account aliases: - `account: "work"` reads secrets `postmark-work` and `postmark-account-work` - or pass `secretName: "postmark-work"` / `accountSecretName: "postmark-account-work"` https://kody.codes/account/secrets/new?name=postmark-work&description=Postmark%20Server%20API%20token%20for%20the%20work%20account&allowedHosts=api.postmarkapp.com&scope=user https://kody.codes/account/secrets/new?name=postmark-account-work&description=Postmark%20Account%20API%20token%20for%20the%20work%20account&allowedHosts=api.postmarkapp.com&scope=user ### Hosts, 401, and 422 | Status | Meaning | Next step | | --- | --- | --- | | 401 | Missing, invalid, or wrong token type | Save `postmark` (or `postmark-account` for `/servers` and `/domains`) at the secrets URL | | 422 + sender | `from` is not a confirmed sender | Confirm a sender signature or verify the domain, then pass `from` at call time | | 422 + stream | `messageStream` does not exist on this server | Omit it (defaults to `outbound`) or pass a stream id from the server | | 429 | Rate limit | Back off; batch with `sendBatch` when sending many messages | Approve **`api.postmarkapp.com`** on the secret. Host approval lives in the account security UI. ### Mutation safety (summary) - Pass `dryRun: true` on any mutation to return `{ dryRun: true, method, path, body, tokenKind }` without contacting Postmark - `sendEmail`, `sendBatch`, `sendTemplateEmail`, `deleteServer`, `deleteDomain`, and `rotateDkim` also throw unless `confirm: true` - This package never stores a default `from`. Pass the confirmed sender at call time - Server payloads strip `ApiTokens` so tokens cannot leak through helpers - Package-owned `server-health` job starts with `"enabled": false` Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, and send snippets. ## Done when - `postmark` (Server API token) is saved; host `api.postmarkapp.com` is approved - Optional `postmark-account` saved if you need `/servers` or `/domains` - Smoke test returns `{ ok: true, live: true, … }` with current server + recent outbound page (no writes), or `{ live: false }` plus setup URLs - Sends and deletes only run after `dryRun` preview and `confirm: true` ## Branding `community-icon.svg` uses Postmark's official stamp from [postmarkapp.com/images/logo-stamp-simple.svg](https://postmarkapp.com/images/logo-stamp-simple.svg) (yellow `#FFDE00` scalloped mark and letter). The paths are unmodified. Postmark® is a trademark of ActiveCampaign, LLC. This package is not affiliated with or endorsed by Postmark or ActiveCampaign. ## Docs - [Postmark API overview](https://postmarkapp.com/developer/api/overview) - [Email API](https://postmarkapp.com/developer/api/email-api) - [Server API](https://postmarkapp.com/developer/api/server-api) - [Servers API](https://postmarkapp.com/developer/api/servers-api) - [Domains API](https://postmarkapp.com/developer/api/domains-api) - [Messages API](https://postmarkapp.com/developer/api/messages-api)