Read-only Postfix troubleshooting MCP server that diagnoses why mail is stuck and prescribes provider-specific recovery steps.
Run a one-call doctor diagnosis combining queue, qshape, log stats, DNS checks, and prioritized findings with next steps.
Check DNS authentication: MX, SPF (syntax, lookup limit, IP authorization), DKIM selector keys, DMARC, and PTR/FCrDNS.
Inspect delivery-relevant non-default Postfix config (relayhost, TLS, SASL, limits, queue lifetimes) with secrets redacted.
Summarize the queue: counts per queue, top recipient/sender domains, grouped delay reasons, oldest message.
List queued messages filtered by queue, recipient domain, sender, reason text, category, or minimum age.
Build a qshape-style matrix by recipient or sender domain across message-age buckets.
Aggregate the mail log over a time window: totals, per-domain outcomes, still-failing domains, deferral/bounce causes, DKIM selectors seen.
Trace a single message (by queue ID or email) through the log to its final status.
Track per-destination deferral rates over time with an improving/worsening/flat direction.
Look up recovery playbooks for Gmail, Microsoft, and Yahoo by ID, pasted SMTP reply, or by scanning the server's current failures.
List postsleuth's failure reason categories and their hints.
Provides Gmail/Google Workspace delivery troubleshooting: recognizes Gmail SMTP deferrals and rejections such as 421 4.7.28 rate limits and 5.7.26–5.7.32 SPF/DKIM/DMARC failures, and returns Postfix-specific recovery playbooks, retry guidance, and links to Google's official documentation.
Why isn't Postfix delivering? postsleuth reads the queue (postqueue -j), the mail log and DNS, groups every stuck message by why it is stuck, and tells you what to do next. It works as a CLI and as an MCP server, so an AI agent can investigate a mail server without being able to touch it.
Demo uses generated snapshot data (testdata/gen.py) via --queue-file / --log.
go install github.com/Blackman99/postsleuth/cmd/postsleuth@latestor grab a binary for Linux, macOS or Windows from Releases.
Related MCP server: WolfTech DNS MCP Server
postsleuth doctor # queue + qshape + log + SPF/DKIM/DMARC/PTR, with next steps
postsleuth queue --domain .outlook.com
postsleuth shape --by sender # who filled the deferred queue
postsleuth trend --domain gmail.com # deferral rate over time — getting better?
postsleuth playbook # Gmail 4.7.28, Outlook S3150, Yahoo [TSS04]…: the provider's way back
postsleuth message F543B5DFCE # one queued message: route, DKIM, headers, redacted
postsleuth trace bob@example.org # one message, start to finish (from the log)
postsleuth dns example.com --ip 203.0.113.7When Gmail, Microsoft or Yahoo is the one refusing you, playbook (and the PLAYBOOK section of doctor) names the provider code, says whether Postfix's retries can succeed, and gives ordered recovery steps written for Postfix with links to the provider's own pages: 18 playbooks, from Gmail's 4.7.28 rate limit and 5.7.26 DMARC failures to Outlook.com's S3150 block list (SNDS, JMRP) and Yahoo's [TSS09]. postsleuth playbook --reply "…" looks up a single reply.
When one message is the question, message QUEUE_ID reads its envelope and headers with postcat -e -h -q (never the body) and shows which queue it sits in and since when, each recipient's status and delay reason, the Received: route with TLS, whether its DKIM signature aligns with From:, and header problems that get mail refused, such as bulk mail without RFC 8058 one-click unsubscribe. Output is redacted by default: domains stay, local parts become [user-1]@example.com, the subject and display names are hidden, credential headers are removed. --unredacted exists on the CLI only.
Postfix in a container or on another box: --wrap "docker exec -i mailserver" or run it over ssh.
{"mcpServers": {"postsleuth": {"command": "postsleuth", "args": ["mcp"]}}}All tools are read-only, and postfix_queue_message is always redacted. Requeue, flush, hold and delete exist only when the server is started with --allow-mutations, and each call still needs confirm: true.
Check the DNS records receivers use to accept or reject your mail: MX, SPF (syntax, 10-lookup limit, whether the sending IP is authorised), DKIM selector keys (presence, key size), DMARC policy and reporting, PTR with forward confirmation (FCrDNS) against myhostname.
Inputs: ips, domain, selectors. Returns: checks, domain, sending_ips
Delivery-relevant non-default Postfix settings from postconf -n (relayhost, TLS policy, SASL, concurrency/rate limits, queue lifetimes, domains, milters). Secret-looking values are redacted.
Returns: note, settings
One-call diagnosis of a Postfix server: queue summary, qshape of the deferred queue, log outcomes for the window, DNS authentication checks, and a list of findings with next steps.
Inputs: ips, since, domain, skip_dns. Returns: dns, log, queue, shape, +11 more
Aggregate the Postfix mail log over a time window: totals (received, sent, deferred attempts, bounced, expired, smtpd rejects), per-domain outcomes, domains still failing, grouped deferral reasons and bounce causes with category and hint, and DKIM selectors seen in signing logs.
Inputs: top, since, domain. Returns: since, stats, source
Follow one message through the log by queue ID or email address: every line for each matching queue ID (smtpd, cleanup, qmgr, smtp/local, bounce notifications) and its final status.
Inputs: query (required), limit, since. Returns: source, messages
Per-destination deferral rate over time buckets from the mail log: sent/deferred counts and rate per bucket, plus a direction (improving / worsening / flat / insufficient_data) comparing the early vs late half of the window. Use to see whether Gmail/Outlook/etc. is getting better or worse.
Inputs: top, since, bucket, domain. Returns: since, trend, source
Recovery playbooks for the big mailbox providers: Gmail / Google Workspace (421 4.7.28 rate limit, 5.7.26-5.7.32 SPF/DKIM/DMARC, PTR, TLS, reputation), Microsoft Outlook.com / Microsoft 365 (S3150 block list with SNDS/JMRP, 5.7.606-649 banned IP, 5.7.511, 4.7.650, SC/DY/OU/RP codes, 5.7.515, 5.7.705-750) and Yahoo / AOL ([TSS04]/[TS*] deferrals, [TSS09], [BL21]/[BL23], 5.7.9). Each playbook says what the code means, whether Postfix will retry or retrying is pointless, ordered steps (Postfix-specific, e.g. a dedicated transport with destination_concurrency_limit = 1 for Gmail 4.7.28; never flush the queue at a throttling receiver), and the provider's official pages. Modes: with no arguments, scans the queue and the mail log (since, default 24h) and returns the playbooks for what is failing here with evidence counts and affected domains; with reply, looks up one pasted SMTP reply without reading the server; with id, returns one playbook. Read-only: it never contacts the providers or changes the queue.
Inputs: id, reply, since, domain, +1 more. Returns: mode, lookup, server, playbook, +1 more
List queued messages (queue ID, queue, arrival time, size, sender, recipients with delay reasons), filtered by queue, recipient domain, sender, reason text, reason category or minimum age.
Inputs: limit, queue, domain, sender, +3 more. Returns: matched, messages, returned
One queued message, from its queue file (postcat -e -h; the body is never read): which queue it is in, arrival time and size, every envelope recipient with its state (pending / delivered / canceled) and, for pending ones, the delay reason with category, hint and provider playbook; the Received route oldest first (hosts, IPs, TLS, per-hop delay); DKIM signatures and whether they align with the From: domain; the primary headers; and notes (missing Message-ID/Date, unaligned DKIM, bulk mail without one-click unsubscribe, null sender, on hold). Always redacted: local parts become [user-N] (domains kept), display names, subjects and free-text headers are hidden, credential-like headers removed.
Inputs: queue_id (required). Returns: age, dkim, hops, notes, +13 more
qshape-style matrix of a queue: rows are recipient (or sender) domains, columns are message age buckets in minutes (5,10,20,...,1280+). Shows which destination is backing up and since when.
Inputs: by, top, queue. Returns: by, rows, text, queue, +2 more
Summarise the Postfix queue (postqueue -j): counts per queue, top recipient and sender domains, delay reasons grouped and classified with hints, oldest message.
Inputs: top, queue. Returns: bytes, reasons, by_queue, messages, +7 more
List the failure categories postsleuth assigns to delay/bounce reasons, with the hint for each.
Returns: categories
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Scored across 12 tools
Queue tools split cleanly by granularity (summary/counts, shape/age matrix, list/filtered rows, message/full detail), and log tools split cleanly by axis (stats/aggregate, trace/single message, trend/time buckets). The only mild overlaps are postfix_doctor, which bundles summary + log stats + DNS into one call, and postfix_queue_summary vs postfix_log_stats, which both report deferral reasons with hints; descriptions make the intended use distinct enough to avoid misselection.
Eleven tools follow a clean postfix_<component>_<action-or-object> snake_case pattern (queue_summary, log_trace, queue_message, config). The single mail_dns_check breaks the postfix_ prefix, a minor inconsistency but still readable and semantically sensible.
12 tools is well within the ideal band for a Postfix diagnostics server, and each tool earns its place by covering a distinct facet (queue, log, DNS, config, provider playbooks, reference data). No filler or redundant variants.
The read-only diagnostic surface is thorough: queue inspection across four granularities, log aggregation/tracing/trending, DNS authentication checks, config review, and provider-specific recovery playbooks. The main gap is actionability — no tools to retry, flush, hold, or remove queued messages — though the server explicitly frames itself as read-only, so this is a minor, workable gap.
Free, read-only email and DNS checks: SPF, DKIM, DMARC, MX, DNS records, blocklists, domain health.
Check a domain's DMARC, SPF and DKIM, build SPF records, explain bounces, read DMARC reports.
Free, no login: verify an email address, check SPF/DKIM/DMARC, explain SMTP errors, build SPF/DMARC.
Check SPF, DKIM, DMARC and MX of any domain, and read the DMARC reports of domains you monitor.
