Fastmail Suite

Secure, safe-by-default Fastmail integration (email, contacts, calendar) via JMAP + CalDAV. Use when you want to verify Fastmail setup, triage/search email,...

Security Scan

The skill appears to implement exactly the Fastmail JMAP/CalDAV functionality it advertises and requires only Fastmail-specific credentials; small metadata/documentation mismatches warrant caution but do not indicate malicious behavior.

Purpose & Capability

The name/description (Fastmail JMAP + CalDAV email/contacts/calendar tooling) matches the code and runtime instructions: the scripts talk to api.fastmail.com and caldav.fastmail.com, require Fastmail tokens/app-passwords, and implement read and optional write operations. No unrelated hostnames, cloud providers, or unrelated credentials are requested. One minor inconsistency: the registry metadata at the top lists no required environment variables, while SKILL.md and the code clearly require FASTMAIL_TOKEN (and optional FASTMAIL_TOKEN_SEND, FASTMAIL_CALDAV_* etc.).

Instruction Scope

SKILL.md instructs the agent/user to set Fastmail-specific env vars and run the included scripts; the scripts only access Fastmail endpoints and a small set of environment variables (tokens, redaction, base URLs, optional identity/account overrides). The instructions do not direct the agent to read arbitrary files, other credentials, or to transmit data to non-Fastmail endpoints. The wrapper uses subprocess to invoke bundled scripts (expected).

Install Mechanism

There is no install spec and the bundle is instruction/script-only (stdlib-only Python). No remote downloads, package installs, or archive extraction occur. The code is local and readable; nothing is fetched from unknown servers at install time.

Credentials

The environment variables the skill uses are proportional to its purpose: FASTMAIL_TOKEN for JMAP reads, FASTMAIL_TOKEN_SEND for submissions, FASTMAIL_CALDAV_USER/PASS for CalDAV, and flags for redaction/writes. Notes: (1) SKILL.md documents most of these, but the registry metadata did not declare required env vars — this discrepancy should be resolved before trusting automated installs. (2) The code reads a few additional optional envs (FASTMAIL_MAX_BODY_BYTES, FASTMAIL_BASE_URL, FASTMAIL_ACCOUNT_ID, FASTMAIL_IDENTITY_ID/EMAIL) that are reasonable for advanced configuration but are not listed in the top env table; they are optional and not sensitive beyond the tokens themselves.

Persistence & Privilege

The skill does not request permanent/system-level presence (always:false) and does not modify other skills or system-wide configuration. Autonomous invocation is allowed (platform default) but that is appropriate for a user-invocable integration. No evidence of privilege escalation or attempts to persist tokens beyond using the environment variables passed at runtime.

Assessment

This skill is coherent with its stated purpose: it talks only to Fastmail endpoints and needs Fastmail tokens/app-passwords. Before installing: (1) Prefer creating and supplying a read-only JMAP token (FASTMAIL_TOKEN) — avoid giving a full-equals-send token unless you explicitly enable writes. (2) Be cautious with FASTMAIL_ENABLE_WRITES=1 and FASTMAIL_TOKEN_SEND; only enable when you intend to perform sends/edits. (3) Note the metadata mismatch: the registry entry omitted required env vars while SKILL.md documents them; verify the SKILL.md is authentic and that you supply tokens only via secure channels. (4) Optionally audit the included Python files yourself (they are stdlib-only and readable) and run the scripts in an isolated environment if you are concerned. (5) If you need higher assurance, ask the author to update registry metadata to list required env vars and provide a homepage/source link for verification.

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.

Search

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.