Fastmail

Manage Fastmail via the fm CLI, which talks to Fastmail's JMAP API. All commands support --json for machine-readable output.

Prerequisites

Ensure fm is installed and authenticated:

bash
1fm --version    # Verify installation
2fm auth status  # Verify authentication

If not authenticated, run fm auth login and provide a Fastmail API token from https://app.fastmail.com/settings/security/tokens

Command Reference

Use fm describe to get the full command tree as JSON. Use fm <command> --help for detailed flag documentation.

Authentication

bash
1fm auth login     # Prompt for API token, store in keyring
2fm auth status    # Show authenticated user and account ID
3fm auth logout    # Remove stored token

Email Operations

bash
1# List and search
2fm inbox                                    # 20 most recent inbox emails
3fm email list --mailbox=Archive --limit=50  # List from specific mailbox
4fm email search "query" --from=addr --after=2026-01-01
5
6# Read
7fm email read <id>              # Text body (piped through pager)
8fm email read <id> --html       # HTML body
9fm email read <id> --headers    # All headers
10
11# Thread
12fm email thread <id>            # Full thread conversation
13
14# Send
15fm email send --to=addr --subject="Subject" --body="Body"
16fm email send --to=addr --subject="Subject" < body.txt
17fm email send --to=addr --subject="Subject" --attach=file.pdf
18fm email send --to=addr --subject="Subject" --html --body="<h1>Hi</h1>"
19
20# Reply and forward
21fm email reply <id> --body="Thanks!"
22fm email reply <id> --all           # Reply to all recipients
23fm email forward <id> --to=addr
24
25# Organize
26fm email move <id> Archive
27fm email delete <id>                # Move to Trash
28fm email delete <id> --permanent    # Permanently destroy
29fm email flag <id>                  # Star/flag
30fm email unflag <id>
31fm email mark-read <id>
32fm email mark-unread <id>
33
34# Attachments
35fm email attachment <email-id>              # Download all
36fm email attachment <email-id> <blob-id>    # Download specific
37fm email attachment <email-id> -o ./dir/    # Output directory

Mailboxes

bash
1fm mailbox list                         # List with unread/total counts
2fm mailbox create "Name"
3fm mailbox rename "OldName" "NewName"
4fm mailbox delete "Name"
5fm mailbox delete "Name" --force        # Delete with all emails

Masked Email

Fastmail's masked email feature creates disposable addresses.

bash
1fm masked-email list
2fm masked-email list --state=enabled    # Filter: enabled/disabled/pending/deleted
3fm masked-email create --domain=example.com --description="Signup"
4fm masked-email create --prefix=myprefix --domain=shop.com
5fm masked-email enable <id>
6fm masked-email disable <id>
7fm masked-email delete <id>

Identities

bash
1fm identity list    # Show sending identities (name, email, ID)

Sieve Filters

bash
1fm sieve list                              # List scripts with active status
2fm sieve get <id>                          # Print script content
3fm sieve set "name" filter.sieve           # Upload from file
4echo 'keep;' | fm sieve set "keep-all"     # Upload from stdin
5fm sieve activate <id>
6fm sieve deactivate
7fm sieve delete <id>
8fm sieve validate filter.sieve             # Check syntax without storing

Vacation Auto-Reply

bash
1fm vacation get
2fm vacation set --subject="Out of office" --body="Back on Monday"
3fm vacation set --from=2026-04-01 --to=2026-04-15
4fm vacation disable

Configuration

bash
1fm config init    # Create default ~/.config/fm/config.toml
2fm config show    # Display current settings
3fm config path    # Print config file location

Agent Introspection

bash
1fm describe       # Full command tree as JSON

Working with JSON Output

All commands accept --json for structured output suitable for piping and scripting:

bash
1# Get inbox as JSON
2fm inbox --json
3
4# Extract email IDs with jq
5fm email list --json | jq -r '.[].id'
6
7# Get masked email addresses
8fm masked-email list --json | jq -r '.[].email'
9
10# Get mailbox names and unread counts
11fm mailbox list --json | jq '.[] | {name, unreadEmails}'

Gotchas

• fm email search requires at least one positional query argument. Filters alone won't work -- pass "" as an empty query if you only want filter flags.
• fm email read pipes through $PAGER (or less) when stdout is a terminal. Use --json or pipe to another command to skip the pager.
• Masked email delete sets state to deleted (bounces mail) -- it doesn't destroy the record. There's no undo from deleted.
• Sieve scripts must be deactivated before deletion. fm sieve delete will fail on the active script.
• The --mailbox flag accepts both mailbox names and IDs. Names are matched case-sensitively.
• Token resolution order: --token flag > FASTMAIL_API_TOKEN env var > OS keyring.
• On headless servers without a keyring, use the FASTMAIL_API_TOKEN environment variable.

Fastmail JMAP Details

For advanced usage or debugging, see references/jmap.md.