Skip to content

v0.1.0

Choose a tag to compare

View all tags
@craigjmidwinter craigjmidwinter released this 29 Jul 03:12
· 47 commits to main since this release
v0.1.0
19f2bb3

First tagged release. mail-muncher gives a program its own read-only mailbox: it pulls messages from Gmail, evaluates each one against ordered composable rules, and writes the matches to a directory as byte-faithful .eml plus an optional markdown rendering with the headers as YAML frontmatter.

It requests exactly one OAuth scope, gmail.readonly. It cannot send, delete, label, or modify anything in the mailbox.

Install

go install github.com/craigjmidwinter/mail-muncher/cmd/mail-muncher@v0.1.0

What's in this release

  • Gmail provider — OAuth device flow, full scan, incremental history sync, and RAW message download.
  • Config loading and validation — mail-muncher validate checks a config without touching the network.
  • Filter engine — the full match-tree language: every combinator and predicate documented in filters. A rule can take its input from a plain text file another program owns, re-read at the start of every cycle, so the consuming program changes what it receives by editing one line.
  • Sinks — .eml and markdown, with attachments extracted alongside.
  • run and daemon — one-shot for cron or a polling loop, with a cycle lock and an instance lock so overlapping invocations cannot collide.
  • --json run manifests — a machine-readable record of every cycle on stdout, stderr reserved for logs. Field names are a documented contract; see the manifest reference.
  • mcp — a stdio MCP server over the archive exposing five tools: list_rules, list_messages, read_message, search_messages and sync.
  • Quarantine and failure policies — messages that cannot be delivered are parked rather than dropped, and counted in the manifest.
  • Claude Code plugin — the repo packages itself as an installable plugin bundling the MCP server.

Not in this release

IMAP is specified but not built. There is no provider: imap block; the config rejects any provider other than gmail. Gmail is the only implemented provider.

By design and not planned: writing to your mailbox (no labeling, deletion, sending or drafts), a UI, a real search index (search_messages is a case-insensitive substring scan, not a search engine), and any network listener.

Stability

Pre-1.0. The config schema is stable enough to write against, but treat it as subject to change until 1.0.

Docs: https://craigjmidwinter.github.io/mail-muncher/

Assets 2
Loading