kuzymail — Mail with managed attention

What it is

kuzymail is the mail layer of the kuzys suite. The CLI kuzymail handles send, sync, list, search, and per-message inspection over a notmuch-indexed Maildir; the daemon kuzymaild adds managed-attention mode, where incoming mail is detected, classified by rules, and injected into the receiving agent (or surfaced to a human) on a configurable cadence rather than message-by-message.

Built on standards: IMAP for sync, SMTP for send, Maildir for storage, notmuch for indexing. Nothing proprietary about the transport or the local format; you can walk away with your mail at any time.

Per-profile, per-account

Each profile holds one or more accounts. State lives at ~/.local/state/kuzymail/profiles/<profile>/accounts/<account>/; secrets at ~/.config/kuzymail/secrets/profiles/<profile>/accounts/<account>.env. Configuration is per-account, so a single human can run distinct workflows for distinct mailboxes, and an agent profile stays cleanly isolated from anyone else on the host.

Sending

Send a plain-text mail from a profile/account:

$ kuzymail send \ --profile vrubin \ --account raven \ --to annabel@theraven.cloud \ --subject "Re: bookclub Wed" \ --body "On the way — joining at 00:55 UTC."

Send-side policy is configurable per account: external-recipient handling, attribute requirements, escalation levels, alias controls. The defaults are conservative; agents do not get to send to external recipients without an explicit --allow-external.

Managed attention

For agent profiles, the kuzymaild daemon adds a layer between incoming mail and the agent session. Instead of waking the agent on every message, kuzymaild applies rules — hours windows, subject matchers, attribute filters — and a coalescing window (min_inject_interval, digest mode) so that a busy mailbox surfaces as a few well-shaped injections rather than dozens of interruptions.

Two detection modes are supported: poll, a fast IMAP poll on a tunable interval; and idle, IMAP IDLE for near-immediate notification. Per-profile inject_wrapper routes the resulting attention event into the agent's runtime.

Three operational properties matter for production use:

Per-profile policy — each agent or profile can carry its own inject / coalesce / silence rules, so a high-attention profile and a quiet one share the same daemon without cross-interference.
Idempotency and duplicate suppression — the same message seen via poll, idle, or a retry path is not re-injected. The handling loop is responsible for "I have seen this", not the transport.
Archive / close path — managed mode is not only detection. The agent (or its operator) can open, decide no-action, archive, or close, according to per-profile policy, and the loop respects that decision instead of re-surfacing the same thread.

Reading

Standard inspection works through notmuch queries:

$ kuzymail sync --profile vrubin --account raven $ kuzymail list --profile vrubin --account raven \ --query "tag:unread" $ kuzymail show --profile vrubin --account raven \ --message-id "<abc...@example.org>"

Install

$ apt install kuzymail kuzymaild

Source and docs

gitlab.com/kuzys/kuzymail · Wiki · man kuzymail

Mail with managed attention.