Fastmail Suite
Use the bundled scripts (stdlib-only) to interact with Fastmail safely.
Quick start
Set credentials/tokens:
CODEBLOCK0
Verify setup:
CODEBLOCK1
Suite CLI (v0.2)
Status / onboarding checks
CODEBLOCK2
Expected style:
- -
Mail (JMAP): OK / MISSING TOKEN / INLINECODE2 - INLINECODE3 /
MISSING APP PASSWORD / INLINECODE5 - INLINECODE6 /
MISSING TOKEN / INLINECODE8
Inbox triage
CODEBLOCK3
Triage summarizes:
- - top senders,
- action-needed subject patterns (
invoice, bill, payment, due, confirm, action required, reminder, ...), - highlights for
friends.tas.edu.au and bill/payment-like items.
Search
CODEBLOCK4
Supported query tokens:
- - INLINECODE17
- INLINECODE18
- INLINECODE19
- INLINECODE20 (and other
Nd forms) - INLINECODE22
- INLINECODE23
- Bare words → subject/body text search
Thread summary
CODEBLOCK5
Shows concise thread summary:
- - participants,
- rough timeline,
- latest 1–2 messages with short plain-text summary.
Other existing scripts
Email (JMAP)
CODEBLOCK6
Contacts (JMAP)
CODEBLOCK7
Calendar (CalDAV)
CODEBLOCK8
Security & Credentials (important)
Fastmail Suite works with real Fastmail credentials, so the design is intentionally conservative.
Required
- -
FASTMAIL_TOKEN — Fastmail JMAP API token (Mail + Contacts scopes). Best practice is to use a read-only token for normal usage.
Optional but supported
- -
FASTMAIL_TOKEN_SEND — separate JMAP token with Email Submission scope for sending mail. Only used if you explicitly enable writes. - INLINECODE26 /
FASTMAIL_CALDAV_PASS — Fastmail app password for calendar (CalDAV). - INLINECODE28 — controls redaction of output (default
1 = redacted). - INLINECODE30 — when set to
1, enables write operations (send/move/update). Omit or set to 0 to keep read-only.
Safety model
- - Redaction is ON by default
Output is redacted unless you pass
--raw where supported.
FASTMAIL_REDACT=1 is the default.
- - Writes are OFF by default
The skill will not send/move/update anything unless
FASTMAIL_ENABLE_WRITES=1 and you have provided appropriate tokens (for example
FASTMAIL_TOKEN_SEND for sending mail).
You can keep a strict separation:
-
Email reading: FASTMAIL_TOKEN
-
Email sending: FASTMAIL_TOKEN_SEND (optional, only when writes are enabled)
-
Calendar: FASTMAIL_CALDAV_USER +
FASTMAIL_CALDAV_PASS (Fastmail app password)
- - Read-only mode is fully supported
You can run the entire suite (status, triage, search, thread, contacts, calendar read) with a
read-only JMAP token + calendar app password, without ever enabling writes.
Changelog
v0.1.1
- - Contacts commands (
list, search, get) tested against real Fastmail accounts. - INLINECODE44 now probes Contacts via JMAP and reports
Contacts (JMAP) health.
v0.2
- - Added
scripts/suite.py with onboarding status checks for JMAP + CalDAV. - Added mail workflows:
-
triage today
-
triage last-7d
-
search <query> with token parser (
from:,
subject:,
has:attachment,
last:,
before:,
after:)
-
thread <id-or-snippet> conversation summary
- - Added wrapper passthrough in
scripts/fastmail.py for suite .... - Added quick-start and usage examples for status/triage/search/thread.
Fastmail 套件
使用捆绑脚本（仅标准库）安全地与 Fastmail 交互。
快速开始
设置凭据/令牌：
bash
JMAP 令牌（邮件 + 联系人作用域）
export FASTMAIL_TOKEN=…
CalDAV 应用密码（日历）
export FASTMAIL
CALDAVUSER=you@yourdomain
export FASTMAIL
CALDAVPASS=app-password
可选：脱敏输出（默认为 1）
export FASTMAIL_REDACT=1
验证设置：
bash
python3 skills/fastmail-suite/scripts/suite.py status
套件 CLI (v0.2)
状态/入门检查
bash
python3 skills/fastmail-suite/scripts/suite.py status
预期样式：
- - 邮件 (JMAP): 正常 / 缺少令牌 / 认证失败
- 日历 (CalDAV): 正常 / 缺少应用密码 / 认证失败
- 联系人 (JMAP): 正常 / 缺少令牌 / 认证失败
收件箱分类
bash
python3 skills/fastmail-suite/scripts/suite.py triage today
python3 skills/fastmail-suite/scripts/suite.py triage last-7d
分类摘要：
- - 主要发件人，
- 需要操作的主题模式（invoice、bill、payment、due、confirm、action required、reminder……），
- 针对 friends.tas.edu.au 和账单/付款类项目的重点提示。
搜索
bash
python3 skills/fastmail-suite/scripts/suite.py search from:billing@ subject:invoice last:7d
python3 skills/fastmail-suite/scripts/suite.py search has:attachment before:2026-02-01 tax
python3 skills/fastmail-suite/scripts/suite.py search after:2026-02-01 reminder
支持的查询标记：
- - from:foo
- subject:bar
- has:attachment
- last:7d（以及其他 Nd 格式）
- before:YYYY-MM-DD
- after:YYYY-MM-DD
- 裸词 → 主题/正文文本搜索
会话摘要
bash
python3 skills/fastmail-suite/scripts/suite.py thread
python3 skills/fastmail-suite/scripts/suite.py thread
python3 skills/fastmail-suite/scripts/suite.py thread school invoice
显示简洁的会话摘要：
- - 参与者，
- 大致时间线，
- 最新 1–2 条消息及简短纯文本摘要。
其他现有脚本
邮件 (JMAP)
bash
python3 skills/fastmail-suite/scripts/fastmail.py mail inbox --limit 20
python3 skills/fastmail-suite/scripts/fastmail.py mail search invoice --limit 10
python3 skills/fastmail-suite/scripts/fastmail.py mail read
联系人 (JMAP)
bash
python3 skills/fastmail-suite/scripts/fastmail.py contacts list --limit 20
python3 skills/fastmail-suite/scripts/fastmail.py contacts search alice --limit 5
python3 skills/fastmail-suite/scripts/fastmail.py contacts get
日历 (CalDAV)
bash
python3 skills/fastmail-suite/scripts/fastmail.py calendar calendars
python3 skills/fastmail-suite/scripts/fastmail.py calendar upcoming --days 7
安全与凭据（重要）
Fastmail 套件使用真实的 Fastmail 凭据，因此设计上刻意保守。
必需
- - FASTMAIL_TOKEN — Fastmail JMAP API 令牌（邮件 + 联系人作用域）。最佳实践是使用只读令牌进行常规操作。
可选但支持
- - FASTMAILTOKENSEND — 单独的 JMAP 令牌，具有邮件提交作用域，用于发送邮件。仅在显式启用写入时使用。
- FASTMAILCALDAVUSER / FASTMAILCALDAVPASS — 用于日历（CalDAV）的 Fastmail 应用密码。
- FASTMAILREDACT — 控制输出的脱敏（默认 1 = 脱敏）。
- FASTMAILENABLE_WRITES — 设置为 1 时，启用写入操作（发送/移动/更新）。省略或设置为 0 以保持只读。
安全模型
输出默认脱敏，除非在支持的地方传递 --raw。FASTMAIL_REDACT=1 为默认值。
除非 FASTMAIL
ENABLEWRITES=1
并且 已提供适当的令牌（例如用于发送邮件的 FASTMAIL
TOKENSEND），否则该技能不会发送/移动/更新任何内容。
您可以保持严格分离：
-
邮件读取： FASTMAIL_TOKEN
-
邮件发送： FASTMAIL
TOKENSEND（可选，仅在启用写入时使用）
-
日历： FASTMAIL
CALDAVUSER + FASTMAIL
CALDAVPASS（Fastmail 应用密码）
您可以使用
只读 JMAP 令牌 + 日历应用密码运行整个套件（状态、分类、搜索、会话、联系人、日历读取），无需启用写入。
更新日志
v0.1.1
- - 联系人命令（list、search、get）已针对真实 Fastmail 账户进行测试。
- suite.py status 现在通过 JMAP 探测联系人并报告 联系人 (JMAP) 健康状态。
v0.2
- - 新增 scripts/suite.py，包含针对 JMAP + CalDAV 的入门 status 检查。
- 新增邮件工作流：
- triage today
- triage last-7d
- search
，带标记解析器（from:、subject:、has:attachment、last:、before:、after:）
- thread 会话摘要
- - 在 scripts/fastmail.py 中为 suite ... 添加包装传递。
- 添加状态/分类/搜索/会话的快速开始和使用示例。
