Quickstart

Before anything else, read the safety model — it is the point of the project. The short version: every mutating command is dry-run until you pass --execute, and nothing can ever delete mail.

Install

Not yet on npm — install from a clone (bun ≥ 1.1):

git clone https://github.com/ahmadatallah/fast-classifier.git
cd fast-classifier
bun install
bun run build && bun link   # puts `fast-classifier` and `fast-classifier-mcp` on your PATH

(Or skip building and run straight from source: bun src/cli/main.ts <command>.)

Get a scoped Fastmail token

In Fastmail: Settings → Privacy & Security → Integrations → API tokens. Scope it to Mail read + write only — no contacts, calendars, files, or sending. Use a read-only token if you only run analyze/plan.

Two transports, two tokens

The JMAP API token and the MCP endpoint token are different credentials — one does not work against the other’s endpoint. See Transports for the comparison.

Tokens live in the environment only — the config loader rejects credentials in config files:

cp .env.example .env        # bun loads .env automatically; otherwise export in your shell
export FASTMAIL_API_TOKEN=...   # JMAP transport (the default)
export FASTMAIL_MCP_TOKEN=...   # MCP transport (-p mcp)

The canonical loop

Recon, build your rules from your inbox, then execute:

1. Write a starter config:

   fast-classifier init                # writes a starter fast-classifier.config.ts

2. Read-only recon — who fills the inbox:

   fast-classifier analyze             # top senders and root domains

3. Build your rules from your inbox:

   fast-classifier suggest             # catalog-backed rule suggestions + unknown domains

   suggest matches your top domains against a built-in catalog of well-known senders in 12 generic categories and prints a paste-ready config fragment; domains it does not recognize are listed for you to decide. Paste what you accept into fast-classifier.config.ts.

4. Check coverage:

   fast-classifier plan                # coverage % + top unmatched senders

5. Edit fast-classifier.config.ts — add rules for the top unmatched senders and the unknown domains suggest surfaced — then run plan again. Iterate until coverage is where you want it. This flywheel is how the origin session reached 87% coverage without training anything.

6. Sweep bulk mail — dry run first, inspect the report, then execute:

   fast-classifier sweep               # dry run — inspect the report
   fast-classifier sweep --execute     # label + archive bulk mail

7. File everything the rules match:

   fast-classifier file --execute

8. Surface what needs a human reply:

   fast-classifier needs-action

9. Prove the run did what the plan said:

   fast-classifier verify --cleared newsletter@example.com --label 'Inbox/Dev>=1'

Next steps

• Configuration — categories, rules, keep-list, and building your config from your inbox.
• CLI reference — every command and flag.
• MCP server — drive the same pipelines from an agent.
• See examples/ for a full real-world config.