Fastmail API Operations

Setup

On first use, read setup.md for account integration preferences, activation rules, and credential handling.

When to Use

User needs to automate Fastmail through API calls: mailbox management, message search, draft/send flows, identity settings, contact operations, or calendar events. Agent handles capability discovery, safe request construction, and high-impact confirmation.

Architecture

Memory lives in ~/fastmail-api/. See memory-template.md for structure.

~/fastmail-api/
├── memory.md         # Account context, IDs, and operating preferences
├── request-log.md    # High-impact API actions and outcomes
└── snapshots/        # Optional payload backups before bulk writes

Quick Reference

Use these files when you need details beyond core operating rules.

Topic	File
Setup flow	setup.md
Memory template	memory-template.md
Session and method call patterns	jmap-patterns.md
Mailbox and message workflows	mail-workflows.md
Contacts and calendar operations	calendar-contacts.md
Error handling and recovery	troubleshooting.md

Requirements

• curl
• jq
• FASTMAIL_API_TOKEN
• Optional: FASTMAIL_API_BASE (defaults to https://api.fastmail.com/jmap/api)

Never commit bearer tokens to repository files, shell history, or shared logs.

Data Storage

• ~/fastmail-api/memory.md for account ID, preferred defaults, and workflow context
• ~/fastmail-api/request-log.md for high-impact action history
• ~/fastmail-api/snapshots/ for payload backups before bulk updates

Core Rules

1. Discover Session Capabilities Before First Write

• Call the Fastmail JMAP session endpoint first to confirm apiUrl, primaryAccounts, and capability support.
• Cache discovered account IDs in memory to avoid writing to the wrong account.

curl -sS https://api.fastmail.com/jmap/session \
  -H "Authorization: Bearer $FASTMAIL_API_TOKEN" | jq

2. Build Method Calls with Explicit Account Scope

• Include using capabilities and account-specific IDs in each method call set.
• Use deterministic clientCallId values so retries can be traced safely.

curl -sS "${FASTMAIL_API_BASE:-https://api.fastmail.com/jmap/api}" \
  -H "Authorization: Bearer $FASTMAIL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "using": ["urn:ietf:params:jmap:mail", "urn:ietf:params:jmap:core"],
    "methodCalls": [
      ["Mailbox/get", {"accountId": "u123", "ids": null}, "c1"]
    ]
  }' | jq

3. Use Safe Pagination and Narrow Filters

• Do not run unbounded queries on large inboxes; always set limits and filters.
• Prefer Email/query plus Email/get windows over full mailbox dumps.

4. Confirm Destructive and Broad-Impact Actions

• Confirm before mailbox deletes, message moves affecting many threads, identity updates, or bulk calendar edits.
• For high-impact writes, record pre-change payloads in ~/fastmail-api/snapshots/.

5. Treat Partial Failures as First-Class Results

• Inspect notCreated, notUpdated, and method-level errors after every write.
• Report partial success explicitly and propose rollback or retry paths.

6. Redact Sensitive Data in Outputs

• Never print raw authorization headers or full token strings in normal responses.
• Redact addresses and subject lines when logs are shared outside trusted contexts.

7. Verify Post-Write State with Follow-Up Reads

• After writes, run targeted read calls (Mailbox/get, Email/get, Contact/get, CalendarEvent/get) to confirm final state.
• Only close tasks after state verification succeeds.

Safety Checklist

Before bulk updates, deletes, send flows, or identity changes:

1. Confirm target account ID and environment.
2. Capture a request snapshot for rollback context.
3. Confirm user intent for irreversible actions.
4. Execute smallest safe batch first.
5. Verify resulting state with read calls.

Fastmail API Traps

• Skipping session discovery can send writes to an incorrect account ID.
• Missing capabilities in using causes method failures that look like auth issues.
• Bulk message moves without filters can reorganize entire mailboxes accidentally.
• Assuming all writes succeeded without checking notUpdated hides partial failure.
• Logging bearer tokens in debugging output creates credential exposure risk.

External Endpoints

Only the official Fastmail JMAP endpoints below are used by this skill.

Endpoint	Data Sent	Purpose
https://api.fastmail.com/jmap/session	Bearer token in Authorization header	Discover API URLs, capabilities, and account IDs
https://api.fastmail.com/jmap/api	JMAP method payloads for mail, mailbox, identity, contacts, and calendar operations	Execute read and write workflows

No other data is sent externally.

Security & Privacy

Data that leaves your machine:

• Authenticated JMAP payloads for mailbox, message, contact, and calendar operations
• Message metadata required for requested queries and write actions

Data that stays local:

• Operational context in ~/fastmail-api/memory.md
• High-impact action history in ~/fastmail-api/request-log.md
• Optional payload snapshots in ~/fastmail-api/snapshots/

This skill does NOT:

• Send undeclared API traffic
• Store bearer tokens in repository files
• Execute destructive writes without explicit confirmation

Trust

By using this skill, mailbox and calendar operation data is sent to Fastmail infrastructure. Only install if you trust Fastmail with this operational data.

Related Skills

Install with clawhub install <slug> if user confirms:

• api - Build robust HTTP request and response workflows for complex APIs
• oauth - Handle token lifecycle and secure delegated authorization flows
• mail - Plan high-quality email workflows, tone, and delivery structure
• webhook - Orchestrate event-driven integrations that react to API-side changes

Feedback

• If useful: clawhub star fastmail-api
• Stay updated: clawhub sync