Skip to content
← Public packages

@kody/postmark

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

FollowFork

Files

README.md

113 lines · 5.4 KB · Markdown

@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 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

  1. 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
StatusMeaningNext step
401Missing, invalid, or wrong token typeSave postmark (or postmark-account for /servers and /domains) at the secrets URL
422 + senderfrom is not a confirmed senderConfirm a sender signature or verify the domain, then pass from at call time
422 + streammessageStream does not exist on this serverOmit it (defaults to outbound) or pass a stream id from the server
429Rate limitBack 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 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 (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