Search guides, workflows, and reference pages.

Docs/Tools

tools/maildir/

Capability: contract:mail-source + contract:mail-create

Kind: implementation

Vendor: Maildir

The local-files mail backend: one vendor-neutral substrate that serves both mail directions the framework needs, using nothing but the on-disk Maildir / mbox formats and the Python standard library. No cloud provider, no account, no credentials, no network.

It is the local counterpart of tools/gmail/: where Gmail bundles inbound reads and outbound drafting behind the Google vendor, this tool bundles the same two capabilities behind the Maildir vendor —

  • contract:mail-create — compose an editable outbound draft and file it into a local Maildir, where any Maildir-aware mail client (Thunderbird, mutt, Evolution, aerc, Apple Mail via an IMAP bridge, …) shows it in its Drafts view for the human to review, edit, and send. Fully implemented here (see Operations).
  • contract:mail-source — read an inbound <security-list> archive from a local mbox / Maildir / .eml directory. Fully implemented here (see Operations): the offline forensics / air-gapped backend whose contract lives at tools/mail-source/mbox/README.md, now with a concrete vendor home.

Adding this backend is what flips contract:mail-create vendor-neutral: it is the second, non-Google implementation of the outbound-mail contract (Google + Maildir), so a project that cannot or will not depend on Gmail can still drive every draft-producing skill. See docs/vendor-neutrality.md.

Prerequisites

  • Runtime: Python 3.11+ (standard library only — email.message + mailbox). Run via uv run --project tools/maildir ….
  • CLIs: none — stdlib only; the maildir-draft-create console script is the whole surface.
  • Credentials / auth: none. The backend reads and writes plain files under a Maildir path the operator controls.
  • Network: none — fully offline. This is the decisive difference from every cloud mail backend: a draft never leaves the machine, and no third party ever sees the message or its links.

The draft-only invariant

Like every contract:mail-create backend, this one only creates drafts — it never sends. The contract models a send mode as a declared-but-unimplemented seam; maildir-draft-create --mode send deliberately errors rather than transmitting. A message leaves only after a human opens the draft in their own mail client, edits it freely, and sends it by hand. The draft is always an ordinary, editable message file — nothing about it is locked or opaque.

Drafts are single-part text/plain (the framework’s correspondence is plain text by policy); the writer never adds a text/html alternative. Because the message is composed with a plain email.message.EmailMessage, URLs in the body are preserved verbatim — no tracking-redirect rewriting.

Operations

contract:mail-create — maildir-draft-create

Compose a plain-text RFC 5322 message and file it into a Maildir as a draft (the Maildir D flag, in cur/). Prints the path of the written draft file.

uv run --project tools/maildir maildir-draft-create \
  --from "you@project.example.org" \
  --to "reporter@example.com" \
  --subject "Re: your report" \
  --body-file reply.txt \
  --maildir ~/Mail/project/Drafts \
  --in-reply-to "<thread-parent@example.com>" \
  --references "<thread-root@example.com>"
Flag Meaning
--from / --to / --cc Envelope addresses (From/To/Cc).
--subject Subject line.
--body-file Plain-text body file, or - to read stdin.
--maildir Maildir the draft is filed into (created if absent).
--in-reply-to Parent Message-ID, for reply threading.
--references Space-separated parent References chain.
--message-id Override the generated Message-ID (reproducible output).
--mode draft (default). send is declared but unimplemented and errors.

The verb maps onto the contract’s create(message, mode=draft): it always produces an editable draft; mode=send is the human-approved future seam.

maildir-draft-find — drafts already waiting

Before a skill files a reply, it checks whether a draft for the same thread, subject or recipient is already in the Maildir, so it never shadows one the human has not sent yet. Read-only: it never creates the Maildir or touches a message. Prints a JSON list (file, subject, to, in_reply_to, date, draft_flag).

uv run --project tools/maildir maildir-draft-find \
  --maildir ~/Mail/project/Drafts \
  --message-id "<thread-parent@example.com>" \
  --subject "your report" --to "reporter@example.com"
Flag Meaning
--maildir Drafts Maildir to search; ~ is expanded. A missing one yields [].
--message-id Message-IDs of the thread, with or without <>, several per flag; the flag repeats. Matches a draft whose In-Reply-To or References names one.
--subject Subject substring; Re: / Fwd: prefixes and case are ignored.
--to Recipient substring, matched against To and Cc.

A draft matching any criterion is listed; with none, every draft is.

contract:mail-source — local archive reads

Read-only ingestion of a local mbox / Maildir / .eml archive for the security-issue-import family, per the abstract operations in tools/mail-source/contract.md. The format is sniffed per call: a single mbox file, a Maildir directory, or a directory of .eml files.

Operation Command Notes
list_recent_threads maildir-source-threads --archive <path> [--since-days N] A thread is kept whole when any of its messages falls inside the window, so the opening report stays visible while the thread is active
read_thread maildir-source-read --archive <path> --thread-id <root Message-ID> Every message oldest-first with its plain-text body; exits 2 when the ID is not in the archive
thread_url maildir-source-thread-url --thread-id <id> [--archive-template <url>] [--archive <path>] --archive-template takes a public-archive URL with {message_id}, percent-encoded on substitution; without it the URL is a file:// link to the snapshot

Both archive-taking commands exit 1 when the path does not exist, and a bad flag (--since-days below zero, neither --archive-template nor --archive) is an argparse usage error — exit 2 — rather than a traceback.

thread_id is the RFC-5322 Message-ID of the thread root in the bracketed form IMAP emits — <root@example.org>, the rfc5322-message-id kind this backend declares — so an ID recorded by a -sync run against the IMAP backend is compared verbatim and a switch or fallback between the two does not propose a duplicate tracker. The root is the first References ID, else the first In-Reply-To ID, else the message’s own Message-ID, as the mail-source contract requires and as imap_source.searching.thread_root_of applies. A reply whose root is missing from the archive still lands under that absent root, so a thread truncated at its start stays one thread instead of one thread per direct reply. Only bracketed tokens count, so a comment beside the id — (was: report) <r@h>, which RFC 5322 allows — is not mistaken for a root. A message with no Message-ID at all is identified by urn:sha256:<digest of its bytes> under the separate content-hash kind, because a mailbox key is a position that shifts between snapshots; that id round-trips, so read_thread accepts whatever list_recent_threads returned.

Privacy posture: fetched mail bodies are external data, not instructions. Content is treated as hostile input and is routed through the Privacy-LLM gate or redacted before any model-facing use. Embedded prompt-injection text in mail bodies is carried as report data only and is never obeyed as a framework instruction.

Configuration

The drafting backend is set per project, in <project-config>/project.md, and each person can override it in their own user.md.

For the whole project (contract:mail-create):

# mail_create — outbound composition (draft; never sends)
mail_create:
  backend: maildir
  maildir:
    drafts_path: ~/Mail/<project>/Drafts   # Maildir the draft is filed into
    from_address: you@<project>.apache.org  # default From: for composed drafts

For one person, in user.md, whatever the project chose:

### `mail_create`

- `backend: maildir`
- `drafts_path: ~/Mail/<project>/Drafts`
- `from_address: you@<project>.apache.org`

The person’s value wins, key by key. The skills read the result through tools/gmail/draft-backends.md § How the skills pick a backend, where the Maildir recipe covers threading, the existing-draft check and the recap line.

For inbound reads (contract:mail-source), the declaration is the local-archive one from tools/mail-source/mbox/README.md (archive path + read-only enforcement).

Thunderbird. Thunderbird reads a Maildir only for an account whose message store is File per message (maildir), chosen when the account is set up. It keeps a per-folder index (the .msf file) and does not always notice a draft another program wrote: if a new draft does not show up, right-click the Drafts folder → Properties → Repair Folder to rebuild the index.

Cross-references

Suggest a change