Fastmail

Manages Fastmail email and calendar via JMAP and CalDAV APIs. Use for emails (read, send, reply, search, organize, bulk operations, threads) or calendar (events, reminders, RSVP invitations). Timezone auto-detected from system.

Security Scan

The skill's code and runtime instructions appear to match the described Fastmail functionality, but registry metadata (claims of being instruction-only and listing no required env vars/binaries) conflicts with the included code and SKILL.md; a pre-scan injection pattern was also flagged in the packaged assets — verify before installing or granting credentials.

Purpose & Capability

The skill explicitly implements JMAP (email) and CalDAV (calendar) and requires Fastmail credentials, which fit the stated purpose. However the registry metadata claims no required env vars, 'instruction-only', and no required binaries, while SKILL.md and the code require environment variables (FASTMAIL_API_TOKEN, FASTMAIL_USERNAME, FASTMAIL_PASSWORD) and the README/SKILL.md instructs installing and running with Bun. The mismatch between declared metadata and actual requirements is incoherent and reduces trust.

Instruction Scope

SKILL.md and the CLI code instruct the agent to run local commands (bun install, bunx fastmail ...) and to read environment variables for credentials. Those actions are appropriate for a Fastmail integration. The instructions do not ask the agent to read unrelated system files or to exfiltrate data to unknown endpoints; network calls target Fastmail JMAP and CalDAV endpoints. However the pre-scan detected a 'base64-block' pattern (possible embedded asset or obfuscation) inside distributed files which could hide unexpected behavior — this is unusual and worth auditing.

Install Mechanism

There is no formal install spec in the registry, but SKILL.md asks the user to run 'bun install' and use 'bunx' to execute the bundled CLI. A large bundled dist/cli.js is included, which means substantial code will be present on disk if installed. Dependencies are standard (tsdav, uuid). The lack of an explicit, reproducible install manifest in the registry plus a bundled executable suggests you should inspect the bundled code (dist/cli.js) before running; bundlers sometimes inline large base64 blobs (flagged by the scanner) so confirm those blobs are benign.

Credentials

The environment variables required by the SKILL.md and code (FASTMAIL_API_TOKEN for JMAP; FASTMAIL_USERNAME and FASTMAIL_PASSWORD for CalDAV) are appropriate and expected for this purpose. The README notes tokens have full account access, which is significant but expected for API tokens. The concern is that the registry metadata omitted these required credentials entirely — an inconsistency that could trick users into granting secrets without realizing what is needed. Also verify the skill truly only uses those credentials for hosted Fastmail endpoints.

Persistence & Privilege

The skill does not request 'always: true' and does not claim to modify other skills or system-wide settings. It appears to run on demand via CLI and uses environment variables; autonomy and persistence are normal/default and present no additional red flags by themselves.

Scan Findings in Context

[base64-block] unexpected: The scanner flagged a base64 block pattern in the bundled files. Embedding base64 blobs in a bundled CLI can be benign (assets, polyfills), but it can also be used to hide data or code. Since this project includes a large compiled 'dist/cli.js', inspect the blob(s) to confirm they are not obfuscated malware or hidden network endpoints.

What to consider before installing

Do not install or run this skill until you verify its origin and inspect the bundled code. Specific steps: - Verify source: this skill lists no homepage and source is unknown; prefer skills with a verifiable repository or maintainer. - Confirm required credentials: SKILL.md and code require FASTMAIL_API_TOKEN (JMAP) and FASTMAIL_USERNAME + FASTMAIL_PASSWORD (CalDAV). Only provide an app-specific token/password with minimal required scope; do not use your primary password. - Audit the bundle: review dist/cli.js and any embedded/base64 content for unexpected endpoints, encoded scripts, or obfuscated behavior before running 'bun install' or executing the CLI. - Run in a sandbox: if you must test, run it in an isolated environment or container, and monitor outbound network calls to ensure they only go to Fastmail endpoints (api.fastmail.com, caldav.fastmail.com). - Use least privilege and rotate: generate a dedicated Fastmail API token/app-password for this skill and revoke/rotate it after testing. - If metadata/registry claims differ from the package (e.g., 'instruction-only' vs present code), treat that as a warning signal and reach out to the publisher or avoid using the skill until provenance is clarified.

Quick Start

Invoke tools via CLI:

# Install dependencies first
cd .opencode/skills/fastmail && bun install

# Email: List mailboxes
bunx fastmail list_mailboxes

# Email: Send
bunx fastmail send_email \
  '{"to": [{"email": "[e-mail]"}], "subject": "Hi", "text_body": "Message"}'

# Calendar: List events
bunx fastmail list_events \
  '{"start_date": "2024-01-01", "end_date": "2024-01-31"}'

# Calendar: Create event with reminder
bunx fastmail create_event_with_reminder \
  '{"title": "Meeting", "start": "2024-01-15T10:00:00", "end": "2024-01-15T11:00:00", "reminder_minutes": [15, 60]}'

# List all available tools
bunx fastmail --list

When to Use This Skill

• 📧 Check inbox or search emails
• 📧 Send, reply, or move emails
• 🏷️ Apply labels or organize mailbox
• 📅 View calendar or events
• 📅 Create, update, or delete events
• 🔔 Set event reminders or alarms

Email Tools (10 total)

Tool	Purpose
list_mailboxes	List all folders
list_emails	List emails in mailbox
get_email	Get full email content
get_thread	Get all emails in a conversation thread
search_emails	Search by text query
send_email	Send new email
reply_email	Reply to email
move_email	Move to folder
set_labels	Apply labels ($seen, $flagged)
delete_email	Delete (move to trash)

Bulk Email Tools (3 total)

Tool	Purpose
bulk_move_emails	Move multiple emails at once
bulk_set_labels	Apply labels to multiple emails
bulk_delete_emails	Delete multiple emails at once

Calendar Tools (10 total)

Tool	Purpose
list_calendars	List all calendars
list_events	List events by date range
get_event	Get event details
create_event	Create new event
update_event	Update existing event
delete_event	Delete event
search_events	Search by title/description
create_recurring_event	Create repeating event
list_invitations	List calendar invitations
respond_to_invitation	Accept/decline/maybe invitations

Reminder Tools (4 total)

Tool	Purpose
add_event_reminder	Add reminder to event
remove_event_reminder	Remove reminder(s)
list_event_reminders	List reminders for event
create_event_with_reminder	Create event + reminder in one call

Common Examples

# Check inbox (limit 10)
bunx fastmail list_emails '{"limit": 10}'

# Search for emails
bunx fastmail search_emails '{"query": "invoice"}'

# Get specific email content
bunx fastmail get_email '{"email_id": "xxx"}'

# Get email thread/conversation
bunx fastmail get_thread '{"email_id": "xxx"}'

# Bulk operations
bunx fastmail bulk_move_emails '{"email_ids": ["id1", "id2"], "target_mailbox_id": "archive"}'
bunx fastmail bulk_delete_emails '{"email_ids": ["id1", "id2", "id3"]}'

# Create recurring event (daily for 10 days)
bunx fastmail create_recurring_event \
  '{"title": "Standup", "start": "2024-01-01T09:00:00", "end": "2024-01-01T09:30:00", "recurrence": "daily", "recurrence_count": 10}'

# Calendar invitations
bunx fastmail list_invitations
bunx fastmail respond_to_invitation '{"event_id": "xxx", "response": "accept"}'

Decision Tree

Need to manage email?

• List/search → list_emails or search_emails
• Read content → get_email
• View conversation → get_thread
• Send/reply → send_email or reply_email
• Organize → move_email, set_labels, delete_email
• Bulk actions → bulk_move_emails, bulk_set_labels, bulk_delete_emails

Need to manage calendar?

• View → list_calendars or list_events
• Create → create_event or create_recurring_event
• Modify → update_event
• Delete → delete_event
• Invitations → list_invitations, respond_to_invitation

Need reminders?

• Add to existing event → add_event_reminder
• Create event + reminder → create_event_with_reminder (faster)
• Manage → list_event_reminders, remove_event_reminder

Output Format

All tools return JSON:

{
  "success": true,
  "data": { /* tool-specific response */ },
  "timestamp": "2024-01-15T10:00:00+07:00"
}

Environment Variables

Variable	Purpose	Required
FASTMAIL_API_TOKEN	Email via JMAP	Yes (for email)
FASTMAIL_USERNAME	Calendar via CalDAV	Yes (for calendar)
FASTMAIL_PASSWORD	Calendar app password	Yes (for calendar)
FASTMAIL_TIMEZONE	Calendar timezone (IANA format)	No (auto-detected)

Setup:

export FASTMAIL_API_TOKEN="your-api-token"
export FASTMAIL_USERNAME="[e-mail]"
export FASTMAIL_PASSWORD="your-app-password"
# Optional: Override timezone (defaults to system local timezone)
export FASTMAIL_TIMEZONE="America/New_York"  # or "Asia/Bangkok", "Europe/London", etc.

Timezone Support

⏰ Configurable calendar timezone

• Default: Auto-detects your system's local timezone
• Override: Set FASTMAIL_TIMEZONE environment variable
• Uses IANA timezone identifiers (e.g., America/New_York, Asia/Bangkok, Europe/London)
• Input times assumed in configured timezone
• Output times shown in configured timezone
• Stored internally as UTC
• Handles Daylight Saving Time (DST) automatically

See Also

• Detailed reference: .opencode/skills/fastmail/references/TOOLS.md
• Full guide: .opencode/skills/fastmail/README.md
• Setup help: Fastmail Settings → Privacy & Security → Integrations