postsleuth docs

postsleuth answers one question: why isn't this Postfix server delivering mail? It reads the queue, the mail log and DNS, never changes anything unless you opt in, and speaks MCP so an AI agent can do the digging for you.

Install

go install github.com/Blackman99/postsleuth/cmd/postsleuth@latest

Or download a static binary (linux, darwin, windows; amd64 and arm64) from GitHub Releases, unpack it, and put postsleuth on your PATH. It has no runtime dependencies. On the mail host it calls the Postfix tools that are already there: postqueue, postconf and, only when you allow it, postsuper.

Quick start

postsleuth doctor                 # everything, with next steps
postsleuth queue                  # what is stuck and why
postsleuth shape                  # which destination, since when
postsleuth log --since 24h        # what happened
postsleuth trend --domain gmail.com # deferral rate over time
postsleuth playbook               # Gmail / Microsoft / Yahoo recovery steps
postsleuth trace bob@example.org  # one message, start to finish
postsleuth dns example.com --ip 203.0.113.7

Run it as a user that can read the mail log. On Debian and Ubuntu that is the adm group (sudo usermod -aG adm $USER). postqueue -j is allowed for every user by default (authorized_mailq_users).

For a worked example with real output, read Diagnosing stuck mail with postsleuth (中文版).

doctor

postsleuth doctor combines the queue summary, a qshape of the deferred queue, log outcomes and destination deferral trends for the window (--since, default 24h) and the DNS checks for your sending domain. It ends with a list of findings (including worsening high-volume destinations) and exits 1 if any is a problem.

postsleuth doctor [--since 24h] [--domain example.com] [--ip 203.0.113.7] [--selector mail] [--no-dns] [--no-log] [--json]

The sending domain defaults to myorigin (or mydomain). The sending IP defaults to smtp_bind_address, else the public A/AAAA records of myhostname when there is no relayhost. DKIM selectors are read from opendkim's "DKIM-Signature field added (s=…, d=…)" log lines, else common names are probed.

queue & shape

postsleuth queue [--queue deferred] [--domain .outlook.com] [--sender billing@] [--reason "4.7.28"] [--category rate_limit] [--min-age 2h]
postsleuth queue --list --category timeout --limit 20
postsleuth shape [deferred|active|hold|incoming|all] [--by sender] [--top 20]

The summary groups recipients by normalised delay reason (addresses, IPs and tracking IDs are stripped so identical failures group together), classifies each group, and lists the domains it affects. --domain with a leading dot also matches subdomains.

shape is the qshape view: rows are domains, columns are message age in minutes (5, 10, 20, … 1280, 1280+), each message counted once per domain. A row that fills the left columns is a fresh problem; one that fills the right is old. --by sender is how you find the compromised account behind a spam run.

log & trace

postsleuth log [--since 1h|24h|7d|all] [--domain gmail.com] [--top 15]
postsleuth trace 4F2A1C3B9
postsleuth trace bob@example.org --since 7d

log reports totals (received, sent, deferred attempts, bounced, expired, smtpd rejects), per-domain outcomes, domains whose latest attempt was a deferral ("still failing"), grouped deferral reasons, bounce causes and reject reasons, each with a category and hint. For the same data over time, use trend.

trace prints every line for each matching queue ID (smtpd, pickup, cleanup, qmgr, smtp/local, bounce) and its final status. Matching by address also pulls in the non-delivery notice Postfix generated for a bounce.

trend

postsleuth trend [--since 1h|24h|7d|all] [--domain gmail.com] [--bucket 15m|1h|4h|12h|1d] [--top 15]

trend buckets sent and deferred attempts by recipient domain over the window (bucket width defaults from --since: 15m for ≤2h, 1h for ≤24h, 4h for ≤3d, …). For each destination it shows the deferral rate per bucket and a direction — improving, worsening, flat, or insufficient_data — by comparing the early half of the window to the late half. Use it to answer "is Gmail getting better?" after you lower concurrency or wait out a rate limit. doctor surfaces worsening high-volume destinations as findings.

playbook

postsleuth playbook [--since 24h]            # playbooks for what is failing here, from the queue and the log
postsleuth playbook gmail|microsoft|yahoo    # only one provider
postsleuth playbook gmail-4.7.28             # one playbook, every step and link
postsleuth playbook --reply "421-4.7.28 Gmail has detected an unusual rate …" [--domain gmail.com]
postsleuth playbook --list

A category says what kind of failure it is. When the receiver is Gmail, Microsoft (Outlook.com, Hotmail, Microsoft 365) or Yahoo/AOL, the reply also names a provider code, and each provider has its own way back: Google's 4.7.28 recovery steps and Postmaster Tools, Microsoft's SNDS, JMRP and delist forms, Yahoo's Sender Hub and Complaint Feedback Loop. playbook recognises the provider from the MX that answered (*.google.com, *.protection.outlook.com, *.yahoodns.net…) or from the reply's own wording, picks the playbook for the code, and prints:

• what the code means and whether Postfix's retries can succeed (temporary) or are pointless (permanent);
• how much mail it is costing you: deferred attempts, bounces, queued recipients and the domains affected;
• ordered steps, written for Postfix (for Gmail 4.7.28: stop, then a dedicated gmail transport with gmail_destination_concurrency_limit = 1, then raise it one at a time);
• the provider's own pages for that code.

doctor shows the same playbooks in a compact PLAYBOOK section (the verdict, the evidence and the first step), adds an info finding per playbook with the full steps and links in --json, and queue / log point at the playbook under each matching reason. Playbooks never change anything and postsleuth never contacts the providers: signing in to SNDS or filing a delist request is yours to do.

PLAYBOOK 2 provider playbooks match what is failing here
  ! Gmail 4.7.28 · Gmail is rate limiting you: unusual rate of mail
         temporary (Postfix retries) · 82 deferred attempts · 150 queued · gmail.com, googlemail.com
      1  Send nothing to Gmail for at least 10 minutes. Don't flush the queue (postqueue -f, postsleuth
         flush): a burst of retries counts against you.
         + 5 more steps, 4 official links: postsleuth playbook gmail-4.7.28
  ✗ Microsoft S3150 · Outlook.com block list: your IP's network is blocked
         permanent (retrying won't help) · 38 deferred attempts · 14 bounced · 34 queued

The built-in playbooks (postsleuth playbook --list). Codes are taken from the providers' published error pages; a playbook only cites pages that exist.

Got a Gmail, Microsoft or Yahoo reply that finds no playbook? postsleuth playbook --reply "…" tells you; open an issue with the anonymised text.

dns

postsleuth dns [DOMAIN] [--ip 203.0.113.7] [--selector mail] [--helo mail.example.com] [--resolver 1.1.1.1]

MCP server

postsleuth mcp speaks the Model Context Protocol over stdio. Every tool is read-only and annotated as such.

On the mail host (Claude Code, Cursor, Claude Desktop…)

claude mcp add postsleuth -- postsleuth mcp

{"mcpServers": {"postsleuth": {"command": "postsleuth", "args": ["mcp"]}}}

From your laptop over SSH

{"mcpServers": {"postsleuth": {"command": "ssh", "args": ["-T", "mx1.example.com", "postsleuth", "mcp"]}}}

Use an SSH key and a user in the adm group. Nothing listens on the network.

Postfix in Docker (docker-mailserver, mailcow, …)

{"mcpServers": {"postsleuth": {"command": "postsleuth",
  "args": ["mcp", "--wrap", "docker exec -i mailserver"]}}}

--wrap prefixes every Postfix command, and also reads the container's log (maillog_file, /var/log/mail.log, /var/log/mail/mail.log…) through it. For mailcow, the Postfix container is usually mailcowdockerized-postfix-mailcow-1, and the log is easiest via --log-cmd "docker logs mailcowdockerized-postfix-mailcow-1".

Prompts that work well: "Why is mail to Gmail stuck?", "Outlook says S3150, what do I do?", "Which sender filled the deferred queue today?", "Did bob@example.org's message arrive?", "Is our SPF/DKIM/DMARC set up right for this IP?"

Tool reference

Each tool returns structured JSON (with an output schema) plus the same JSON as text.

Failure categories

Every delay reason, bounce text and reject is classified by its SMTP enhanced status code and wording. First match wins, in this order:

Seen a reply that lands in other? Open an issue with the (anonymised) text.

Where data comes from

• Queue: postqueue -j (Postfix 3.1+). Or a saved snapshot: --queue-file queue.json (- for stdin), handy for analysing a customer's server offline.
• Log: --log FILE (repeatable, .gz fine, - for stdin), or --log-cmd "journalctl -u postfix@- -o short-iso". Without either: Postfix's maillog_file, then /var/log/mail.log, /var/log/maillog, /var/log/mail/mail.log, /var/log/postfix.log, then journald (mail facility). Traditional syslog, RFC 3339 and journald short-iso timestamps are understood; multi-instance names like postfix-out/smtp too.
• Config: postconf -n and postconf -x. Parameters whose names look like secrets are redacted.
• DNS: the system resolver, or --resolver IP.

Changing the queue

postsleuth is read-only unless the process was started with --allow-mutations. That flag is chosen by whoever configures the MCP server, not by the agent, so a model cannot grant itself write access. When it is set:

• the CLI accepts flush, requeue, hold, release and delete;
• the MCP server adds the five tools above, annotated as non-read-only (delete as destructive), and each refuses to run without confirm: true;
• operations take explicit queue IDs (validated; ALL and anything starting with - is rejected). Commands are executed directly, never through a shell.

Before flushing a destination that is rate-limiting you (Gmail 4.7.28), don't: a burst of retries makes it worse. Fix the cause, wait, and let Postfix's backoff work.

JSON & exit codes

Every command takes --json. Exit codes: 0 fine · 1 problems found (doctor, or a failing check in dns) · 2 error or refused. NO_COLOR=1 or --no-color disables colour.

postsleuth doctor --json | jq '.findings[] | select(.severity=="problem") | .title'

Troubleshooting

"permission denied reading /var/log/mail.log"

Add the user to adm, run with sudo, or pass --log-cmd.

Every DNS record is "missing"

Your resolver is filtering or faking answers (some sandboxes and VPNs do). Try --resolver 1.1.1.1.

Log shows nothing for the last hour

Check the clock and time zone of the log; traditional syslog lines carry no year or zone and are read in local time.

"Flush service is not configured for destination"

postqueue -s only works for domains in fast_flush_domains. Flush by queue ID instead.

Source and issues: github.com/Blackman99/postsleuth · GOAL.md · ROADMAP.md · MIT