@kody/postmark
Send transactional email and manage Postmark servers, domains, and message search with dry-run mutations.
Files
@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.
- Open a server at 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.
- 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
- 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 secretspostmark-workandpostmark-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: trueon any mutation to return{ dryRun: true, method, path, body, tokenKind }without contacting Postmark sendEmail,sendBatch,sendTemplateEmail,deleteServer,deleteDomain, androtateDkimalso throw unlessconfirm: true- This package never stores a default
from. Pass the confirmed sender at call time - Server payloads strip
ApiTokensso tokens cannot leak through helpers - Package-owned
server-healthjob starts with"enabled": false
Agents: see AGENTS.md for import paths, smoke checks, and
send snippets.
Done when
postmark(Server API token) is saved; hostapi.postmarkapp.comis approved- Optional
postmark-accountsaved if you need/serversor/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
dryRunpreview andconfirm: true
Branding
community-icon.svg uses Postmark's official stamp from
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.