// Use xin CLI to manage JMAP email (Fastmail-first). Covers search, read, send, drafts, labels, and automation.
| name | xin |
| description | Use xin CLI to manage JMAP email (Fastmail-first). Covers search, read, send, drafts, labels, and automation. |
| allowed-tools | Bash(xin:*) |
Agent-first JMAP CLI for Fastmail email management.
Generated from xin CLI v0.1.3
The xin command must be available on PATH. To check:
xin --version
If not built, see: https://github.com/onevcat/xin
# Store Fastmail API token (this bootstraps a minimal config if missing)
xin auth set-token fmu1-xxxxx
--plain only for quick human confirmation (not a stability contract)--plain output in automation# Get inbox items (per-email)
xin messages search "in:inbox" --max 200 \
| jq -r '.data.items[] | [.emailId, (.subject // "")] | @tsv'
# Example: pick only subjects matching "invoice" and archive them
xin messages search "in:inbox" --max 200 \
| jq -r '.data.items[]
| select((.subject // "") | test("invoice"; "i"))
| .emailId' \
| xargs -n 50 sh -c 'xin batch modify "$@" --remove inbox --add archive' _
xin supports a query sugar DSL (NOT Gmail-compatible):
# Mailbox
in:<mailbox> # resolves by role, then name (e.g. inbox, trash, junk)
# Basic operators
from:<text>
to:<text>
cc:<text>
bcc:<text>
subject:<text>
text:<text>
# State
seen:true|false # $seen keyword
flagged:true|false # $flagged keyword
# Attachments + time
has:attachment
after:<YYYY-MM-DD>
before:<YYYY-MM-DD>
# Boolean
-term # NOT (e.g., -in:trash)
or:(a | b) # OR
Quote multi-term queries: xin search "from:github subject:release".
Use --dry-run first for destructive commands:
xin batch modify <emailId> --remove inbox --add archive --dry-run
For long content, read from file using @/path:
xin send --to user@example.com --subject "Hello" --text @/tmp/body.txt
xin search # Search (thread-like by default)
xin messages # Per-email search commands
xin get # Get a single email
xin thread # Thread operations
xin attachment # Download an attachment
xin url # Print webmail URL(s) (Fastmail-only)
xin archive # Archive emails
xin read # Mark emails as read
xin unread # Mark emails as unread
xin trash # Move emails to trash
xin batch # Batch operations
xin inbox # Inbox-zero helpers
xin labels # Labels (mailboxes) operations
xin mailboxes # Mailboxes operations (alias of labels)
xin identities # Identities operations
xin send # Send an email
xin reply # Reply to an email by emailId (JMAP Email id)
xin drafts # Drafts operations
xin history # History / changes
xin watch # Watch for email changes (polling Email/changes; NDJSON stream)
xin config # Config file operations
xin auth # Credential helpers
High-level overview: commands.md
search - Search (thread-like by default)
messages - Per-email search commands
get - Get a single email
thread - Thread operations
attachment - Download an attachment
url - Print webmail URL(s) (Fastmail-only)
archive - Archive emails
read - Mark emails as read
unread - Mark emails as unread
trash - Move emails to trash
batch - Batch operations
inbox - Inbox-zero helpers
labels - Labels (mailboxes) operations
mailboxes - Mailboxes operations (alias of labels)
identities - Identities operations
send - Send an email
reply - Reply to an email by emailId (JMAP Email id)
drafts - Drafts operations
history - History / changes
watch - Watch for email changes (polling Email/changes; NDJSON stream)
config - Config file operations
auth - Credential helpers
For common workflows and examples, see common-tasks.
For JSON output schema, see JSON Schemas.
To see available subcommands and flags, run --help:
xin --help
xin search --help
xin inbox --help
xin inbox do --help
XIN_TOKEN or XIN_TOKEN_FILE - Bearer tokenXIN_BASE_URL or XIN_SESSION_URL - JMAP endpointXIN_BASIC_USER and XIN_BASIC_PASS - Basic auth (alternative to Bearer)xin url is Fastmail-only - generates Fastmail web URLsxinNotImplemented for Fastmail-specific features