Use the spark CLI to access the user's Spark email data - list emails, search by topic, read threads, check calendar events, find availability, look up contacts, and view team info. Use when the user asks about their emails, calendar, contacts, meetings, or scheduling.

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 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. Commands Command Description accounts List accounts, calendars, teams, shared inboxes, and access levels folders List folders/labels with message counts emails List emails with filters and pagination search Hybrid keyword + semantic search with full bodies thread Read full thread headers, bodies, attachments attachment Read a single email attachment by its ID (auto downloads) draft Create, edit, or delete an email draft (new, reply, forward, from template), or list account signatures templates List saved message templates (personal and team) template Show a single template by ID or name with its placeholders comment Post a team comment on a thread events List calendar events for a time range event Create, update, delete, or RSVP to a calendar event, including managing attendees / invitations availability Find free time slots, optionally with attendees contacts Search contacts by name or email team Show team info, members, shared inboxes, assignments meetings List meeting transcripts meeting Read a single meeting transcript action Perform actions on emails (archive, pin, snooze, assign, etc.) contact action Perform actions on contacts (block, accept, categorize, etc.) 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. Run this first to discover what accounts, calendars, and teams are available, and to check their access levels. Access levels: Level Allowed operations read only List, search, and read emails, threads, folders, events, contacts, meetings, teams triage Everything in read only plus all write operations: drafts, team comments, email actions (archive, move, pin, snooze, assign, etc.), contact actions (block, accept, categorize, etc.) send Everything in triage plus mail emitting operations: sending drafts ( action send , including scheduled "Send Later"), and the entire event command: event create / event update / event delete / event rsvp , including attaching or detaching attendees via add / remove and the iTIP REQUEST / UPDATE / CANCEL / REPLY mail that goes with them. 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 . emails List emails with metadata (ID, From, Date, Subject, Flags). Supports pagination and Gmail style filters. 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): Format Example Meaning Bare name Inbox , Archive Unified folder (cross account) email user@example.com Account inbox shorthand email:Folder user@example.com:Archive Specific account folder "Team Name" "My Team" All shared threads in a team (quote if spaces) shared@email:Inbox shared@co.com:Inbox Shared inbox open items (conversation view, matches Desktop) shared@email:Archive shared@co.com:Archive Shared inbox done/archived items (conversation view) shared@email:Folder shared@co.com:Label Other shared inbox folder / label Filter operators (combinable, Gmail style): Operator Example from:<addr from:alice@co.com to:<addr to:bob@co.com cc:<addr cc:team@co.com subject:<text subject:"quarterly report" before:yyyy/MM/dd before:2026/03/01 after:yyyy/MM/dd after:2026/01/01 newer than:Xd newer than:7d (also w , m , y ) older than:Xd older than:30d has:attachment also document , spreadsheet , presentation , reminder is:unread also read , starred , pinned , unreplied is:shared emails shared to any team (alias for is:shared email ) is:shared inbox open open items in shared inbox is:shared inbox done completed/closed items in shared inbox category:personal also priority , notification , newsletter , invitation , invitation response assigned to:me emails assigned to current user assigned to:<email emails assigned to specific teammate assigned to:unassigned shared inbox items with no assignee assigned to:other emails assigned to someone else (not me) assigned by:me emails delegated by current user filename:<name filename:report.pdf 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. Parameter Required Description <about No Search topic (positional). Omit to switch to list mode. filter No Gmail style filter (same operators as emails ) in No Scope: account, team, folder, or shared inbox. All folders if omitted. page No Page number, 1 based (default: 1). List mode only. page size No Emails per page (default: 50). List mode only. order No Sort order: ascending or descending . List mode only. 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 ). 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. Parameter Required Description <id Yes Attachment ID (pk) from the thread Attachments table. stream No Write the raw file bytes to stdout instead of metadata text. Useful inside sandboxed agents that can read the CLI's stdout but not local filesystem paths. The CLI streams the file in 64 KB chunks, so there is no practical size limit. To go the other way attach a file the app can't read pipe it into draft / comment with attach stream . Use thread to find attachment IDs (the ID column in the Attachments: table). The default text output is one Key: value per line, easy to parse from scripts. draft Requires: triage access level. Create a new email draft or edit an existing one. The body is written in markdown and converted to HTML. Parameter Required Description to No Recipient address (RFC822). Repeat for multiple. cc No CC address. Repeat for multiple. bcc No BCC address. Repeat for multiple. subject No Subject line. body Yes (new, no template ) Body content in markdown. Required for new drafts unless a template provides one. edit No Message ID of an existing draft to update. reply to No Message ID to reply to. Addresses the sender alone (or the Reply To: address when the message carries one). reply all No Message ID to reply to, keeping everyone else on the thread: the other To: recipients land in To, the original Cc: in CC, minus your own address. Mutually exclusive with reply to ; to / cc override the lists it builds. forward No Message ID to forward. delete No Message ID of a draft to delete permanently . Must be the only option on the command. Drafts have no Trash, so the deletion cannot be undone. A scheduled draft and a draft shared with teammates are both refused action unschedule or draft edit <pk unshare first. account No Account email to send from. Accepts a regular mail account, an alias, or a shared inbox email. attach No Absolute path to a file to attach. Repeat for multiple. The Spark app must be able to read the path; in the sandboxed App Store build a path outside the app's container can't be read and is rejected with a clear error pipe the file with attach stream instead. Max 25 MB per file. attach id No ID of an attachment on an existing email to copy onto this draft, from the Attachments table of thread <message id . Repeat for multiple. Use this to re send a file the user received replies don't inherit attachments (only forward does). attach stream No Attach a single file whose bytes are read from stdin, shown to recipients as <name . Use this when the file is outside the app's sandbox (the App Store build can't read arbitrary paths) it's the inbound twin of attachment stream . One streamed file per command; combin

use-spark