agent-postmark

Postmark delivery triage CLI for AI agents

Language: Go
License: MIT
Category: CLI Tool

A read-first Postmark delivery and configuration triage CLI for AI agents. It focuses on sender signatures, domains, webhooks, delivery evidence, bounces, suppressions, stats, and inbound investigation rather than template deployment.

Features

Delivery investigation — search messages, inspect delivery details, bounces, and suppression status

Configuration checks — sender signatures, domains, DKIM, SPF, Return-Path, and webhooks

Read-first by default — operational evidence without accidental email sends or account mutations

Redaction-first output — message bodies, headers, recipient data, and API tokens are protected by default

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

Stats and trends — compact deliverability summaries by server, stream, and time range

Focused investigations — answer common support questions like why an email did not arrive

Install

Homebrew

$ brew install shhac/tap/agent-postmark

AI Agent Skill

$ npx skills add shhac/agent-postmark

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

agent-postmark stores Postmark credentials in named profiles. A profile holds an optional account token plus one or more server contexts, each with its own server token, ID, and default stream — so agents can investigate delivery without ever seeing the tokens.

01 · Add a profile with an account token

$ agent-postmark profiles add prod --form --account-token

--form prompts for the token in a native OS dialog, outside argv and outside the LLM context. The account token powers account-level APIs (signatures, domains).

02 · Add a server context

$ agent-postmark profiles servers add prod main --form --server-token --server-id <server-id> --stream outbound --default

Most APIs (messages, bounces, stats) are server-scoped. --default makes this the profile's default server; --stream sets the default message stream.

03 · Check credentials

$ agent-postmark profiles check prod

Verifies the stored account and server tokens against Postmark without printing them.

04 · Investigate delivery

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

Usage

>_ List sender signatures

$ agent-postmark signatures list

>_ List domains

$ agent-postmark domains list

>_ Verify DKIM

$ agent-postmark domains verify-dkim <domain-id>

>_ List webhooks

$ agent-postmark webhooks list --server <server-id>

>_ Search messages

$ agent-postmark messages search --to user@example.com --since 24h

>_ Check suppressions

$ agent-postmark suppressions check user@example.com

>_ Investigate domain health

$ agent-postmark investigate domain-health example.com