fastmail-cli

CLI for Fastmail's JMAP API. Read, search, send, and manage emails from your terminal or AI assistant.

Features

Feature	Description
Email	List, search, read, send, reply, forward, threads
Mailboxes	List folders, move emails, mark spam/read
Contacts	Search contacts via CardDAV
Attachments	Download files, extract text, resize images
Text Extraction	56 formats via kreuzberg
Image Resizing	--max-size to resize images on download
Masked Email	Create, list, enable/disable aliases
MCP Server	Claude integration via Model Context Protocol
Shell Completions	Bash, Zsh, Fish, PowerShell
JSON Output	All commands output JSON for scripting

Quick Start

Installation

From GitHub Releases (recommended for mise)

# Add to mise config
mise use -g github:radiosilence/fastmail-cli

From Source

cargo install --git https://github.com/radiosilence/fastmail-cli

Authentication

1. Generate an API token at Fastmail Settings > Privacy & Security > Integrations > API tokens
2. Auth with the CLI:

fastmail-cli auth YOUR_TOKEN

Token is stored in ~/.config/fastmail-cli/config.toml with 0600 permissions.

Configuration

Credentials can be set via environment variables or config file. Env vars take precedence.

Environment variables:

export FASTMAIL_API_TOKEN="fmu1-..."      # Required for JMAP (email)
export FASTMAIL_USERNAME="you@fastmail.com"  # Required for CardDAV (contacts)
export FASTMAIL_APP_PASSWORD="xxxx..."    # Required for CardDAV (contacts)

Config file (~/.config/fastmail-cli/config.toml):

[core]
api_token = "fmu1-..."

[contacts]
username = "you@fastmail.com"
app_password = "xxxx..."

The auth command only sets [core].api_token. For contacts, add [contacts] section manually or use env vars.

Usage

All output is JSON for easy scripting with jq.

List Mailboxes

fastmail-cli list mailboxes

List Emails

# Default: INBOX, 50 emails
fastmail-cli list emails

# Specific mailbox and limit
fastmail-cli list emails --mailbox Sent --limit 10

Get Email Details

fastmail-cli get EMAIL_ID

Search

Search uses JMAP filter flags (all filters are ANDed together):

# Full-text search
fastmail-cli search --text "meeting notes"

# Filter by header fields
fastmail-cli search --from "alice@example.com"
fastmail-cli search --to "bob" --subject "project"

# Filter by mailbox
fastmail-cli search --mailbox Sent --limit 10

# Attachments and size
fastmail-cli search --has-attachment
fastmail-cli search --min-size 1000000  # > 1MB

# Date range (ISO 8601)
fastmail-cli search --after 2024-01-01 --before 2024-12-31

# Status filters
fastmail-cli search --unread
fastmail-cli search --flagged

# Pinned emails (shortcut for --flagged --mailbox INBOX)
fastmail-cli search --pinned

# Combine filters
fastmail-cli search --from "boss" --has-attachment --after 2024-06-01 --limit 20

Available flags: --text, --from, --to, --cc, --bcc, --subject, --body, --mailbox, --has-attachment, --min-size, --max-size, --before, --after, --unread, --flagged

Send Email

fastmail-cli send \
  --to "alice@example.com, bob@example.com" \
  --subject "Hello" \
  --body "Message body here"

# With CC/BCC
fastmail-cli send \
  --to "alice@example.com" \
  --cc "bob@example.com" \
  --bcc "secret@example.com" \
  --subject "Hello" \
  --body "Message"

Move Email

fastmail-cli move EMAIL_ID --to Archive
fastmail-cli move EMAIL_ID --to Trash

Mark as Spam

# Requires confirmation
fastmail-cli spam EMAIL_ID

# Skip confirmation
fastmail-cli spam EMAIL_ID -y

Mark as Read/Unread

# Mark as read
fastmail-cli mark-read EMAIL_ID

# Mark as unread
fastmail-cli mark-read EMAIL_ID --unread

Download Attachments

# Download to current directory
fastmail-cli download EMAIL_ID

# Download to specific directory
fastmail-cli download EMAIL_ID --output ~/Downloads

# Extract text content as JSON (PDF, DOCX, DOC, TXT)
fastmail-cli download EMAIL_ID --format json

# Resize images to max 500KB
fastmail-cli download EMAIL_ID --max-size 500K

Text extraction uses kreuzberg and supports 56 formats:

• Documents: PDF, DOC, DOCX, ODT, RTF
• Spreadsheets: XLS, XLSX, ODS, CSV, TSV
• Presentations: PPT, PPTX
• eBooks: EPUB, FB2
• Markup: HTML, XML, Markdown, RST, Org
• Data: JSON, YAML, TOML
• Email: EML, MSG
• Archives: ZIP, TAR, GZ, 7z
• Academic: BibTeX, LaTeX, Typst, Jupyter notebooks

Reply to Email

# Reply to sender only
fastmail-cli reply EMAIL_ID --body "Thanks for your message"

# Reply all
fastmail-cli reply EMAIL_ID --body "Thanks everyone" --all

# Reply with additional CC/BCC
fastmail-cli reply EMAIL_ID --body "Response" --cc "boss@example.com"

Forward Email

fastmail-cli forward EMAIL_ID \
  --to "colleague@example.com" \
  --body "FYI - see below"

Shell Completions

# Bash
fastmail-cli completions bash >> ~/.bashrc

# Zsh
fastmail-cli completions zsh >> ~/.zshrc

# Fish
fastmail-cli completions fish > ~/.config/fish/completions/fastmail-cli.fish

Contacts

Search your Fastmail contacts via CardDAV. Requires an app password (API tokens don't work for CardDAV).

# Set credentials
export FASTMAIL_USERNAME="you@fastmail.com"
export FASTMAIL_APP_PASSWORD="your-app-password"

# List all contacts
fastmail-cli contacts list

# Search by name, email, or organization
fastmail-cli contacts search "alice"

Generate an app password at Fastmail Settings > Privacy & Security > Integrations > App passwords.

Masked Email

Create disposable email addresses for signups. Requires Fastmail's masked email feature.

# List all masked emails
fastmail-cli masked list

# Create a new masked email
fastmail-cli masked create --domain "https://example.com" --description "Example Site"

# Create with custom prefix
fastmail-cli masked create --prefix "shopping" --description "Shopping sites"

# Enable/disable a masked email
fastmail-cli masked enable MASKED_EMAIL_ID
fastmail-cli masked disable MASKED_EMAIL_ID

# Delete (requires confirmation)
fastmail-cli masked delete MASKED_EMAIL_ID -y

Output Format

All commands output JSON with this structure:

{
  "success": true,
  "data": { ... },
  "message": "optional status message",
  "error": "error message if success=false"
}

Parsing with jq

# Get unread count for INBOX
fastmail-cli list mailboxes | jq '.data[] | select(.role == "inbox") | .unreadEmails'

# List email subjects
fastmail-cli list emails | jq '.data.emails[].subject'

# Get email body
fastmail-cli get EMAIL_ID | jq -r '.data.bodyValues | to_entries[0].value.value'

MCP Server (Claude Integration)

Run as an MCP server for use with Claude Desktop or other MCP clients:

fastmail-cli mcp

Configure in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "fastmail": {
      "command": "mise",
      "args": ["x", "--", "fastmail-cli", "mcp"],
      "env": {
        "FASTMAIL_API_TOKEN": "your-token-here",
        "FASTMAIL_USERNAME": "you@fastmail.com",
        "FASTMAIL_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Username and app password are optional - only needed for contact search (CardDAV requires app password, API tokens don't work).

The MCP server exposes 17 tools for email operations:

• Reading: list_mailboxes, list_emails, get_email, search_emails
• Actions: move_email, mark_as_read, mark_as_spam
• Sending: send_email, reply_to_email, forward_email (preview/confirm flow)
• Attachments: list_attachments, get_attachment (auto text extraction, image resizing)
• Contacts: search_contacts (requires app password)
• Masked Email: list_masked_emails, create_masked_email, enable_masked_email, disable_masked_email, delete_masked_email

Token can be set via FASTMAIL_API_TOKEN env var or config file.

Debug Logging

Enable debug output with RUST_LOG:

RUST_LOG=debug fastmail-cli list mailboxes

JMAP API

This CLI uses Fastmail's JMAP implementation. Key capabilities:

• urn:ietf:params:jmap:core
• urn:ietf:params:jmap:mail
• urn:ietf:params:jmap:submission
• https://www.fastmail.com/dev/maskedemail

For more on JMAP: jmap.io

License

MIT