Fastmail
@dmc/fastmailv2026.09.15.1
01README
Fastmail email-organization pipeline over JMAP — scan every sender (flagging bulk/newsletter mail via RFC 2369/8058 List-* headers), generate ready-to-paste Sieve scripts that sort senders into nested folders, and plan/apply message moves — with audit, rule-coverage, apply-plan, and inbox-analysis reports.
02Models
@dmc/fastmailv2026.09.15.1fastmail.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiToken? | string | Read-only Fastmail JMAP API token (Bearer). Preferred for all read methods. Optional if writeToken is set — a write token also has read scope. At least one of apiToken/writeToken is required. |
| writeToken? | string | Write-scoped Fastmail token. Required by email_move (execute:true), and used as the read token when apiToken is unset. Leave unset (with apiToken set) to keep the model read-only. |
| sessionUrl | string | JMAP session discovery URL (defaults to Fastmail) |
fn email_senders(scopes: array)
Scan ALL senders across one or more scopes (whole mailbox or recent N), grouping by sender and recording bulk-ness (List-Id / List-Unsubscribe) as a per-sender attribute. Fan-out: writes one 'senders' resource per scope.
| Argument | Type | Description |
|---|---|---|
| scopes | array | One or more scopes to scan; each writes a 'senders' resource. |
fn sieve_generate(setups: array, output: object)
Generate Fastmail Sieve scripts from email_senders scans. Config-driven fan-out: each setup categorizes senders into (nested) folders, sweeps leftover bulk into a fallback category, and leaves unmatched personal mail in the Inbox. Optionally merges setups into one combined script.
| Argument | Type | Description |
|---|---|---|
| setups | array | |
| output | object | Assembles all fastmail setups into one custom-sieve resource (two paste-slots). |
fn email_plan(setups: array, mailboxRole: string, inMailbox?: string, after?: string, before?: string, maxMessages?: number, name: string)
Plan applying the sieve to existing mail: classify a mailbox's messages to destination folders using the SAME rules as sieve_generate, producing a message-id → destination mapping for manual review (executed later by email_move). Read-only — moves nothing.
| Argument | Type | Description |
|---|---|---|
| setups | array | Same setups as sieve_generate — the plan applies the identical rules. |
| mailboxRole | string | Mailbox to apply the sieve to (default 'inbox'; 'archive' to fix old |
| inMailbox? | string | Explicit mailbox id (overrides role). |
| after? | string | ISO date; only plan mail received after this. |
| before? | string | ISO date; only plan mail received before this. |
| maxMessages? | number | Cap of newest messages to plan (default: all). |
| name | string | Plan resource instance name. |
fn email_analyze(setups: array, mailboxRole: string, inMailbox?: string, maxMessages?: number, name: string, scopes?: any)
Analyze a mailbox against the CURRENT rules (read-only): report overall composition and the senders that would still be LEFT in the inbox — the rule-candidate list that drives the pre-build tuning loop. Writes an 'analysis' resource. Moves nothing.
| Argument | Type | Description |
|---|---|---|
| setups | array | Same setups as sieve_generate — analysis applies the identical rules to see what's covered vs left behind. |
| mailboxRole | string | Mailbox to analyze (default 'inbox'). |
| inMailbox? | string | Explicit mailbox id (overrides role). |
| maxMessages? | number | Cap of newest messages to analyze (default: all). |
| name | string | Analysis resource instance name. |
| scopes? | any | Ignored; present so the shared config file is accepted by strict input validation. |
fn email_headers(from: string, inMailbox?: string, limit: number, name: string)
Diagnostic (read-only): dump the full header list of sample messages matching a `from` filter to a 'headers' resource — for discovering a robust header to build a rule on.
| Argument | Type | Description |
|---|---|---|
| from | string | Sender substring to sample (JMAP from filter). |
| inMailbox? | string | Restrict to a mailbox id. |
| limit | number | |
| name | string | Resource instance name. |
fn email_move(source: string, execute: boolean, forceMove: boolean, labelOnly: boolean, batchSize: number)
Apply the sieve plan by moving messages to their destination folders (JMAP Email/set mailboxIds). DEFAULT DRY-RUN — moves nothing and just reports. `execute: true` performs the moves and REQUIRES a write-scoped token. Always gate behind a manual-approval step.
| Argument | Type | Description |
|---|---|---|
| source | string | Plan resource name to execute (from email_plan). |
| execute | boolean | false = dry-run (moves nothing, just reports). true = perform the moves — REQUIRES a write-scoped token. |
| forceMove | boolean | Remove the source mailbox even for keep (skipInbox:false) rules. Use when |
| labelOnly | boolean | Only ADD the target label; never remove any mailbox. Use for an all-mail |
| batchSize | number |
Resources
senders(30d)— All senders in a scanned scope with per-sender bulk attributes (from email_senders)
sieve(30d)— Generated Fastmail Sieve script (and metadata) organizing senders into folders
plan(7d)— Apply-sieve plan: message id → destination folder for existing mail, per the same rules
analysis(7d)— Standalone inbox analysis: what current rules cover vs the senders left behind (the rule-candidate to-do list)
headers(1d)— Diagnostic: full header lists of sample messages, for designing header-based rules
03Reports
@dmc/fastmail-analyzemethod
fastmail_analyze.ts
Analyze a mailbox against the current rules: composition, the senders that would still be left in the inbox split into rule candidates vs kept-by-design, and what's already covered.
emailfastmailanalyzerules
@dmc/fastmail-auditmethod
fastmail_audit.ts
Summarize an email_senders scan: sender volume, bulk-ness, unsubscribe availability, and volume concentration.
emailinboxaudit
@dmc/fastmail-coveragemethod
fastmail_coverage.ts
Per-setup rule coverage from sieve_generate: senders filed vs. uncategorized (fell to the bulk fallback), with a ranked list of uncategorized senders to write rules for.
emailfastmailcoverage
@dmc/fastmail-planmethod
fastmail_plan.ts
Review an apply-sieve plan: destinations, counts, and sample messages that email_move would relocate. Read this before approving/executing a move.
emailfastmailapply-sievereview
04Previous Versions
2026.09.14.1
Modified 1 models. Added 1 reports
2026.08.29.2
05Stats
A
100 / 100
Downloads
0
Archive size
188.2 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
06Platforms
07Labels