CLI

brew install tropmail/tap/tropmail
go install github.com/tropmail/tropmail-cli@latest

Binaries for linux, macOS, and Windows on amd64 and arm64 are on each release. There is also a container image:

docker run --rm -e TROPMAIL_API_KEY -e TROPMAIL_MAILBOX_ID ghcr.io/tropmail/tropmail ls --json

Source: github.com/tropmail/tropmail-cli

Getting started

tropmail auth login          # prompts, stores the key in the OS keyring
tropmail mailboxes           # list inbox UUIDs this key can see
tropmail                     # opens the inbox

auth login checks the key with the API before saving it, so a typo fails immediately. If the key sees exactly one inbox, that id is remembered on the profile. Otherwise pass --mailbox or set TROPMAIL_MAILBOX_ID.

The inbox

Running tropmail with no arguments opens a two-pane reader: the message list on the left, the rendered body on the right.

Markdown is rendered in the reader. The next page loads in the background as you approach the end of the list.

Scripting

Every subcommand takes --json. Mail commands need a mailbox UUID (--mailbox, TROPMAIL_MAILBOX_ID, or the unique inbox remembered at login).

# List inboxes
tropmail mailboxes --json | jq -r '.mailboxes[].id'

# The subject of every unread message
tropmail ls --mailbox "$MAILBOX_ID" --status Open --json | jq -r '.emails[].subject'

# Read the newest message as plain markdown
tropmail read --mailbox "$MAILBOX_ID" "$(tropmail ls --mailbox "$MAILBOX_ID" --limit 1 --json | jq -r '.emails[0].id')" --raw

# Favorite everything from one sender
tropmail search --mailbox "$MAILBOX_ID" "billing@stripe.com" --all --json \
  | jq -r '.emails[].id' \
  | xargs tropmail fav --mailbox "$MAILBOX_ID"

# Save every attachment on a message (default: ./downloads/<id-prefix>/)
tropmail attach download <email-id> --email
tropmail attach download <email-id> --email -o ./my-inbox

# Start a malware scan. Without --wait this returns while the scan is still running.
tropmail attach scan <attachment-id> --wait
tropmail attach info <attachment-id>

# Run a hook whenever mail arrives
tropmail watch --exec 'notify-send "TropMail" "$TROPMAIL_SUBJECT"'

watch prints one NDJSON object per new message under --json, and exposes $TROPMAIL_ID, $TROPMAIL_SUBJECT, $TROPMAIL_FROM, and $TROPMAIL_TIMESTAMP to the --exec hook.

Exit codes

Under --json, errors are written to stderr as JSON with the status, message, and request id.

Commands

Global flags: --json, --api-key, --base-url, --profile, --mailbox, --timeout, --no-color, --quiet, --throttle.

Configuration

Profiles live in ~/.tropmail/config.toml (or $TROPMAIL_CONFIG_DIR):

default_profile = "default"

[profiles.default]
email = "quiet-otter-1423@tropmail.com"
tier = "Pro"
# mailbox_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # set by login when unique
# base_url = "https://api.tropmail.com/api/v1"  # default; set only to override

API keys never go in that file. They go to the OS keyring, or a restricted credentials file on machines with no keyring. TROPMAIL_API_KEY overrides whatever is stored, which is what CI should use.

Message bodies are fetched for display and are not stored on disk. Attachments you download are written to ./downloads/<id-prefix>/ (or -o).

Requests stay within your account rate limit. Pass --throttle=false if you would rather manage that yourself.