fastmail

A command-line interface for accessing Fastmail email, calendars, events, and todos from the terminal. fastmail uses JMAP for mail workflows and CalDAV for calendar and todo workflows, and it is designed to work well for both humans and AI agents.

Mental Model

• email, mailbox, and identity commands use Fastmail JMAP API tokens.
• calendar, event, and todo commands use Fastmail app passwords over CalDAV.
• Top-level help <command> and schema <command> commands make the CLI discoverable without reading the source.
• Machine-readable output is a core feature: use --output json, --output jsonl, --fields, --input-json, and --dry-run when scripting or delegating work to an agent.
• Useful aliases: mail for email, cal for calendar, ev for event, task for todo, and folder for mailbox.

Installation

# Install from source
go install github.com/shareup/fastmail@latest

# Or build locally
bin/build.sh

Quick Start

# Store your JMAP token and optionally your CalDAV app password
fastmail auth login

# See which accounts are configured
fastmail auth status

# Discover a command and its JSON schema
fastmail help event create
fastmail schema event create

# List mailboxes and recent email
fastmail mailbox list
fastmail email list --mailbox INBOX --limit 10

# Show a specific email
fastmail email show <id>

# Send an email
fastmail email send --to alice@example.com --subject "Hello" --body "Hi there"

# Create a draft
fastmail email create --to alice@example.com --subject "Draft" --body "Work in progress"

# Body from stdin
echo "Hello from a script" | fastmail email send --to alice@example.com --subject "Piped"

# View HTML body
fastmail email show <id> --html | w3m -dump -T text/html

# Download attachments
fastmail email download <id> --all --dir ./attachments/

# Send with attachment
fastmail email send --to alice@example.com --subject "Report" --body "See attached" --attach report.pdf

Calendar, event, and todo commands require a Fastmail app password:

# Add or update the app password later if needed
fastmail auth set-app-password

# List calendars and upcoming events
fastmail calendar list
fastmail event list --limit 10

# Show an event
fastmail event show <uid>

# Create an event
fastmail event create --summary "Meeting" --start "2025-07-01T10:00:00" --end "2025-07-01T11:00:00"

# Manage todos
fastmail todo list
fastmail todo create --summary "Pay invoice" --due "2026-05-12"
fastmail todo complete <uid>

Authentication

fastmail intentionally separates JMAP and CalDAV authentication because Fastmail does too.

JMAP API Tokens

Generate a token at Fastmail Settings > API Tokens.

JMAP tokens have two independent controls:

• A read-only toggle that blocks all JMAP writes.
• Capability scopes that control which JMAP APIs are available.

In practice:

• urn:ietf:params:jmap:mail enables mail and mailbox access. If the read-only toggle is off, this also enables draft creation, import, moves, flags, and deletes.
• urn:ietf:params:jmap:submission enables send, reply, and forward, and requires the mail capability too.
• A token with mail access but without submission access can manage mail state and drafts without being able to send as the user.

App Passwords (CalDAV)

Calendar, event, and todo commands use CalDAV, which requires an app password separate from the JMAP token. Generate one at Fastmail Settings > Device & App Passwords.

fastmail auth set-app-password    # add app password to an existing account
fastmail auth login               # or set it during login

Multi-Account Support

fastmail auth login                    # stored under your email address by default
fastmail auth login                    # login again with a different email
fastmail auth status                   # list all accounts (* = default)
fastmail auth default work@company.com # change the default account
fastmail email list --account work@company.com

Credentials are stored in ~/.fastmail/config.toml and written with 0600 permissions. If the file already has more open permissions, the CLI warns on stderr but still runs. fastmail auth login reads secrets without echoing them.

Runtime credential precedence is:

1. Command-line flags such as --token, --username, and --app-password
2. Environment variables such as FASTMAIL_TOKEN, FASTMAIL_USERNAME, and FASTMAIL_APP_PASSWORD
3. ~/.fastmail/config.toml

This matters for automation because --token and FASTMAIL_TOKEN work even when no default account has been configured yet.

Discovery And Automation

Use the top-level discovery commands when you are new to the CLI or when an agent needs to inspect valid inputs safely:

fastmail help email send
fastmail help event import
fastmail help todo create
fastmail schema email create
fastmail schema event update
fastmail schema todo update

Important automation features:

• --output json and --output jsonl produce machine-readable output.
• --fields trims large list and show responses to only the fields you need.
• --input-json is supported on email create, email send, event create, event update, todo create, and todo update.
• event create --input-json and event update --input-json accept RFC3339, YYYY-MM-DDTHH:MM:SS, and YYYY-MM-DD date strings, and unknown JSON keys are rejected.
• todo create --input-json and todo update --input-json accept the same date strings for start and due, and unknown JSON keys are rejected.
• --dry-run previews mutating commands before execution. For calendar, event, and todo mutations, dry-run is local-only and does not require CalDAV auth. Import dry-runs parse the ICS locally.

Examples:

fastmail email list --output json --fields "id,subject,from,receivedAt"
fastmail event create --schema
fastmail event create --input-json '{"summary":"Lunch","start":"2025-07-01","end":"2025-07-01","allDay":true}' --dry-run
fastmail todo create --input-json '{"summary":"Pay invoice","due":"2026-05-12"}' --dry-run

Commands

fastmail auth login|status|logout|default|set-app-password  Manage authentication
fastmail mailbox list|create|delete|rename                  Manage mailboxes (alias: folder)
fastmail identity list                                      List sender identities
fastmail calendar list|create|delete|rename                 Manage calendars (alias: cal)
fastmail event list|show|create|update|delete|import|export Manage events (alias: ev)
fastmail todo list|show|create|update|complete|delete|import|export Manage todos (alias: task)
fastmail contacts                                           Contact command namespace (alias: contact)
fastmail email list                                         List and filter emails (alias: mail)
fastmail email show <id>                                    Show full email (--html for HTML body)
fastmail email count                                        Count matching emails
fastmail email create                                       Create a draft email
fastmail email create reply <id>                            Create a draft reply
fastmail email create forward <id>                          Create a draft forward
fastmail email send                                         Send an email
fastmail email reply <id>                                   Reply to an email
fastmail email forward <id>                                 Forward an email
fastmail email move <id> <mailbox>                          Move email to a mailbox
fastmail email mark-read <id...>                            Mark as read
fastmail email mark-unread <id...>                          Mark as unread
fastmail email flag <id...>                                 Flag or unflag emails
fastmail email delete <id...>                               Delete email (trash or permanent)
fastmail email download <id> [name]                         Download attachments
fastmail email upload <file...>                             Upload files as blobs
fastmail email import <file...>                             Import .eml files into a mailbox
fastmail help [command...]                                  Show help for a command
fastmail schema <command...>                                Show JSON schema for a command
fastmail completion [bash|zsh|fish|powershell]              Generate shell completion
fastmail version [--full]                                   Show version information

Output Formats

All commands support --output / -o:

Format	Flag	Description
Auto	auto	Table for TTY, plain for pipes (default)
Plain	plain	Tab-separated, one item per line
Table	table	Aligned columns with header
JSON	json	JSON array for collection commands; single JSON object for single-item commands
JSONL	jsonl	JSON Lines (one object per line)

auto is the default and resolves to table output on a TTY and plain output in pipes. Machine-readable output preserves native JSON types where possible, so booleans remain booleans and counts and sizes remain numbers.

Use --fields to limit output fields. --quiet is available across the CLI for terser output, but the exact effect is command-specific, so check fastmail help <command> when scripting.

Development

bin/test.sh      # Run tests
bin/format.sh    # Format code
bin/build.sh     # Build binary

See AGENTS.md for the repo-level agent guide and CLAUDE.md for the original project guidance that it was adapted from.