SkillHub

fastmail-suite

v0.1.4

Secure, safe-by-default Fastmail integration (email, contacts, calendar) via JMAP + CalDAV. Use when you want to verify Fastmail setup, triage/search email, inspect threads, read/search contacts, view upcoming events, or (only when explicitly enabled) send email and create/reschedule/cancel calendar...

Sourced from ClawHub, Authored by TassieDaddy

Installation

Please help me install the skill `fastmail-suite` from SkillHub official store. npx skills add TassieDaddy/fastmail-suite

Fastmail Suite

Use the bundled scripts (stdlib-only) to interact with Fastmail safely.

Quick start

Set credentials/tokens:

# JMAP token (Mail + Contacts scopes)
export FASTMAIL_TOKEN='…'

# CalDAV app password (calendar)
export FASTMAIL_CALDAV_USER='you@yourdomain'
export FASTMAIL_CALDAV_PASS='app-password'

# Optional: redact output (default is 1)
export FASTMAIL_REDACT=1

Verify setup:

python3 skills/fastmail-suite/scripts/suite.py status

Suite CLI (v0.2)

Status / onboarding checks

python3 skills/fastmail-suite/scripts/suite.py status

Expected style: - Mail (JMAP): OK / MISSING TOKEN / AUTH FAILED - Calendar (CalDAV): OK / MISSING APP PASSWORD / AUTH FAILED - Contacts (JMAP): OK / MISSING TOKEN / AUTH FAILED

Inbox triage

python3 skills/fastmail-suite/scripts/suite.py triage today
python3 skills/fastmail-suite/scripts/suite.py triage last-7d

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.

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"

Supported query tokens: - from:foo - subject:bar - has:attachment - last:7d (and other Nd forms) - before:YYYY-MM-DD - after:YYYY-MM-DD - Bare words → subject/body text search

Thread summary

python3 skills/fastmail-suite/scripts/suite.py thread <email-id>
python3 skills/fastmail-suite/scripts/suite.py thread <thread-id>
python3 skills/fastmail-suite/scripts/suite.py thread "school invoice"

Shows concise thread summary: - participants, - rough timeline, - latest 1–2 messages with short plain-text summary.

Other existing scripts

Email (JMAP)

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 <email-id>

Contacts (JMAP)

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 <contact-id>

Calendar (CalDAV)

python3 skills/fastmail-suite/scripts/fastmail.py calendar calendars
python3 skills/fastmail-suite/scripts/fastmail.py calendar upcoming --days 7

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.
  • FASTMAIL_CALDAV_USER / FASTMAIL_CALDAV_PASS — Fastmail app password for calendar (CalDAV).
  • FASTMAIL_REDACT — controls redaction of output (default 1 = redacted).
  • FASTMAIL_ENABLE_WRITES — 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).

  • Separation of roles
    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.
  • suite.py status 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.