fastmail

Quick Start

Invoke tools via CLI using the Bash tool:

# Install dependencies first (one-time setup)
cd <skill-directory>
uv venv .venv && uv pip install -r requirements.txt
# Or: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

# Email: List mailboxes
.venv/bin/python scripts/cli.py list_mailboxes

# Email: Send
.venv/bin/python scripts/cli.py send_email \
  '{"to": [{"email": "[email protected]"}], "subject": "Hi", "text_body": "Message"}'

# Calendar: List events
.venv/bin/python scripts/cli.py list_events \
  '{"start_date": "2024-01-01", "end_date": "2024-01-31"}'

# Calendar: Create event with reminder
.venv/bin/python scripts/cli.py create_event_with_reminder \
  '{"title": "Meeting", "start": "2024-01-15T10:00:00+07:00", "end": "2024-01-15T11:00:00+07:00", "reminders": [{"minutesBefore": 15}, {"minutesBefore": 60}]}'

# List all available tools
.venv/bin/python scripts/cli.py --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)

Bulk Email Tools (3 total)

Calendar Tools (10 total)

Reminder Tools (4 total)

Common Examples

# Check inbox (limit 10)
.venv/bin/python scripts/cli.py list_emails '{"limit": 10}'

# Search for emails
.venv/bin/python scripts/cli.py search_emails '{"query": "invoice"}'

# Get specific email content
.venv/bin/python scripts/cli.py get_email '{"email_id": "xxx"}'

# Get email thread/conversation
.venv/bin/python scripts/cli.py get_thread '{"email_id": "xxx"}'

# Bulk operations
.venv/bin/python scripts/cli.py bulk_move_emails '{"email_ids": ["id1", "id2"], "target_mailbox_id": "archive"}'
.venv/bin/python scripts/cli.py bulk_delete_emails '{"email_ids": ["id1", "id2", "id3"]}'

# Create recurring event (daily for 10 days)
.venv/bin/python scripts/cli.py create_recurring_event \
  '{"title": "Standup", "start": "2024-01-01T09:00:00", "end": "2024-01-01T09:30:00", "recurrence": "daily", "recurrence_count": 10}'

# Calendar invitations
.venv/bin/python scripts/cli.py list_invitations
.venv/bin/python scripts/cli.py respond_to_invitation '{"event_id": "xxx", "response": "accept"}'

Decision Tree

Need to manage email?

• List/search: listemails or searchemails
• Read content: get_email
• View conversation: get_thread
• Send/reply: sendemail or replyemail
• Organize: moveemail, setlabels, delete_email
• Bulk actions: bulkmoveemails, bulksetlabels, bulkdeleteemails

Need to manage calendar?

• View: listcalendars or listevents
• Create: createevent or createrecurring_event
• Modify: update_event
• Delete: delete_event
• Invitations: listinvitations, respondto_invitation

Need reminders?

• Add to existing event: addeventreminder
• Create event + reminder: createeventwith_reminder (faster)
• Manage: listeventreminders, removeeventreminder

Output Format

All tools return JSON:

{
  "success": true,
  "result": {
    /* tool-specific response */
  }
}

Environment Variables

Setup:

export FASTMAIL_API_TOKEN="your-api-token"
export FASTMAIL_USERNAME="[email protected]"
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: ./references/TOOLS.md
• Setup help: Fastmail Settings → Privacy & Security → Integrations
• JMAP docs: https://jmap.io/
• CalDAV RFC: https://datatracker.ietf.org/doc/html/rfc4791