English Français العربية

Postsleuth

Community Other

Postfix delivery troubleshooting: queue grouped by deferral reason, qshape, mail log stats and traces, SPF/DKIM/DMARC/PTR checks. Read-only by default; requeue/flush/delete need an opt-in flag.

Source code Documentation

Install

The installation steps are in the documentation below. Documentation

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. postsleuth
  2. Install
  3. Use
  4. MCP

postsleuth

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.

Install

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

or grab a binary for Linux, macOS or Windows from Releases.

Use

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 trace bob@example.org   # one message, start to finish
postsleuth dns example.com --ip 203.0.113.7

When 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.

Postfix in a container or on another box: --wrap "docker exec -i mailserver" or run it over ssh.

MCP

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

All tools are read-only. Requeue, flush, hold and delete exist only when the server is started with --allow-mutations, and each call still needs confirm: true.

Docs · Website · Goal · Roadmap · MIT

Frequently asked questions

What is Postsleuth?

Postfix delivery troubleshooting: queue grouped by deferral reason, qshape, mail log stats and traces, SPF/DKIM/DMARC/PTR checks. Read-only by default; requeue/flush/delete need an opt-in flag.

How do I install Postsleuth?

Follow the installation steps in its documentation, shown on this page and in its repository.

Is Postsleuth open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Postsleuth?

It is published by Blackman99. AI.tn lists it but does not maintain or endorse it.

From the community awesome-mcp-servers lists and the project's GitHub repository. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.