agent-postmark

Postmark delivery triage CLI for AI agents

Language: Go
Version: 0.17.2
License: PolyForm Perimeter 1.0.0
Category: CLI Tool

A read-first Postmark triage CLI: why an email did not arrive, bounced, or was suppressed. Messages outbound and inbound, bounces, suppressions, opens and clicks, sender signatures and domain DKIM/SPF/Return-Path health, message streams, webhooks, servers and delivery stats — with account and server tokens the agent never sees.

Features

Focused investigations — investigate delivery, bounce, domain-health and stream-health answer the support question directly instead of leaving you to assemble it

Postmark's real scope model, not a flattened one — a profile holds an optional account token plus several server-token contexts, each with its own server id and default stream

Account and server tokens are independent — a profile can carry either, or both, matching how Postmark actually splits its APIs

Read-first — evidence gathering with no accidental sends or account mutations

Triage metadata stays visible — subject and addressing fields are there when you need them; list output omits bulky bodies, headers and attachments rather than hiding what triage depends on

Redaction where it matters — tokens, secrets, URL credentials and original raw email blobs are redacted by default

Rotate a token without touching profile metadata — profiles update --form replaces just the secret

One-shot setup — profiles setup registers the account token and several servers in a single command

Keychain-first — tokens are never printed back, and --form takes them through a native OS dialog

Structured errors — every failure classified fixable_by: agent|human|retry

Mock server — mockpostmark gives deterministic e2e fixtures

Install

Homebrew

$ brew install shhac/tap/agent-postmark

AI Agent Skill

$ npx skills add shhac/agent-skills --skill agent-postmark --global

GitHub Release (macOS)

$ curl -L https://github.com/shhac/agent-postmark/releases/latest/download/agent-postmark-darwin-arm64.tar.gz | tar xz

Go Install

$ go install github.com/shhac/agent-postmark/cmd/agent-postmark@latest

Build from Source

$ git clone https://github.com/shhac/agent-postmark.git && cd agent-postmark && make build

Getting Started

Postmark splits its API in two: account tokens reach servers, domains and sender signatures; server tokens reach one server's streams, messages, bounces, stats, webhooks and suppressions. agent-postmark models that split rather than flattening it, so a profile can hold either or both.

01 · Set up a whole profile in one command

$ agent-postmark profiles setup prod --form --account-token --server app:123:outbound --server billing:456:outbound

--form prompts for each token in a native OS dialog, outside argv and outside the LLM's context. Each server entry is name:id:stream.

02 · Or add the pieces separately

$ agent-postmark profiles servers add prod app --form --server-token --server-id 123 --stream outbound --default

Most APIs — messages, bounces, stats — are server-scoped. --default picks the profile's default server.

03 · Check the credentials

$ agent-postmark profiles check prod

Verifies stored account and server tokens against Postmark without printing them. profiles is the canonical group; auth is a hidden alias.

04 · Start from the question

$ agent-postmark investigate delivery --email user@example.com

Returns the delivery evidence rather than a list of endpoints to correlate by hand.

Usage

>_ Why did this address not receive it?

$ agent-postmark investigate delivery --email user@example.com

>_ What actually happened to this bounce?

$ agent-postmark investigate bounce 9001

>_ Is our sending domain healthy?

$ agent-postmark investigate domain-health example.com

>_ Is this stream behaving?

$ agent-postmark investigate stream-health --stream outbound

>_ Find recent messages to an address

$ agent-postmark messages search --to user@example.com --count 20

>_ Is this address suppressed?

$ agent-postmark suppressions check user@example.com

>_ Are our webhooks firing?

$ agent-postmark webhooks health

>_ What arrived inbound

$ agent-postmark messages inbound-search --recipient support@example.com