readdle/spark-cli-skills/use-spark

Using spark

spark is a CLI for the Spark email client. Use it to query the user's mailbox, calendar, contacts, meetings, and team data.

Running spark

spark <command> [options]

Environment: spark is a thin client that talks over IPC to the user's running Spark Desktop app - it does not ship its own mailbox, network stack, or credentials. Run it directly on the user's computer against the live Spark Desktop process. Do not try to execute it inside a sandbox, container, CI runner, or any environment isolated from the user's desktop session - it will fail to connect. If Spark Desktop is not running, ask the user to launch it instead of retrying.

JSON output: add --json to any command to get its result as JSON instead of text - the same data, with full (untruncated) values, snake_case keys, and ISO 8601 dates. A failure prints {"error": {"message": "…"}} on stdout and exits non-zero. Prefer the default text when you only need to read the result; use --json when you need to process it (e.g. spark emails --json | jq '.emails[].id'). Fields are only ever added, never renamed or removed.

Commands

accounts

List all configured accounts with their aliases, calendars, teams, and shared inboxes. Each account and shared inbox shows its access level in parentheses, which controls what operations Spark can perform.

spark accounts

Run this first to discover what accounts, calendars, and teams are available, and to check their access levels.

Access levels:

Access levels are configured separately for each account and each shared inbox in Spark Desktop under Settings -> AI Agents. Shared inboxes can have a different access level than the parent account - for example, a personal account may have triage access while a shared inbox under the same team is read-only or disabled.

If a command requires a higher access level than the account or shared inbox has, it returns an error with instructions on how to change the level.

folders

List folders with message counts. Output includes folder identifiers in parentheses - use these as arguments to emails and search. Mailboxes backed by a Google account show (Gmail labels) on the Email Account or Shared Inbox header. Teams show the team name as a usable identifier for emails.

spark folders                        # all accounts
spark folders user@example.com       # single account

emails

List emails with metadata (ID, From, Date, Subject, Flags). Supports pagination and Gmail-style filters.

spark emails                                                   # Unified Inbox
spark emails user@example.com:Archive                          # specific folder
spark emails "My Team"                                         # all shared threads in a team
spark emails --filter "from:alice@co.com is:unread"             # filtered
spark emails --filter "newer_than:7d has:attachment"            # recent with attachments
spark emails --page 2 --page-size 20                           # pagination
spark emails --order ascending                                 # oldest first
spark emails --new-senders                                     # show only new sender emails

GateKeeper filtering: When viewing the Inbox with GateKeeper in explicit mode, new sender emails are automatically filtered out and a "New Senders" count is shown at the top. Use --new-senders to view those emails. Use contact-action acceptContact <email> or contact-action blockContact <email> to accept or block a sender.

Folder identifier formats (run folders to see available ones):

Filter operators (combinable, Gmail-style):

search

Two modes:

• With a topic (keyword mode): Hybrid keyword + semantic search returning up to 20 emails with full bodies, sorted by relevance.
• Without a topic (list mode): Paged compact table of every email matching --filter / --in across all folders and all accounts, sorted newest first. Same output as emails, but the default scope is "all folders" instead of the Unified Inbox. Trash, Spam, and Blocked are excluded (matching Spark's search field) unless --in explicitly targets one of those folders.

spark search "quarterly report"
spark search "API integration" --filter "from:alice@co.com"
spark search "budget" --in user@example.com:Archive
spark search "vacation" --in user@example.com              # all folders in account
 
# Keywordless list mode - filter across every folder
spark search --filter "from:alice@co.com"                  # every email from alice, all folders
spark search --filter "from:alice@co.com" --in user@example.com
spark search --filter "is:unread newer_than:7d" --page 2

Use `search` with a topic when the user asks about content - it returns email bodies so you can answer questions. Use `search` without a topic when you need to filter emails (especially by `from:`) across every folder - emails only sees the Unified Inbox so it can't answer questions like "every email from alice@co.com, anywhere". Use emails for plain browsing of Inbox / one folder.

thread

Print every message in a thread - headers, full plain-text bodies, and attachment info. After the thread summary line, lists custom (non-system) folder labels once for the whole thread, using qualified names like account@domain.com:MyLabel (same style as folders).

spark thread 1114                          # by message ID from emails/search output
spark thread --download-attachments 1114   # also fetch attachments via IMAP
spark thread "https://sparkmailapp.com/dpl/bl?token=ABC..."  # by Spark deep link

The positional argument accepts either a numeric message ID (the ID: line) or a Spark deep link (the Link: line) printed by a previous run - https://sparkmailapp.com/dpl/bl?token=..., readdle-spark://bl=..., or readdlespark://bl=....

A Reply-To: line appears only when that header points somewhere other than From - mailing lists and website contact forms carry the real correspondent there. draft --reply-to already addresses the reply to it, so don't pass --to yourself.

Each message's Attachments: block is a table with columns ID, Name, Size, MIME Type, and Path. The ID column is the attachment's stable pk - feed it to attachment to read the file contents (auto-downloads if necessary). The Path column shows the local file or (not downloaded, ...) for attachments not yet fetched.

Use emails or search to find message IDs (the ID column), then thread to read the full conversation. Use folders to list valid label identifiers for action attachLabel / detachLabel.

attachment

Read a single email attachment by its ID (pk) from the thread Attachments table. The file is auto-downloaded if it isn't cached locally yet.

spark attachment 42                          # print metadata (ID, Name, Size, MIME Type, Path, Message ID)
spark attachment 42 --stream > report.pdf    # write raw file bytes to stdout