Readdle Spark Claude Extension Spark Claude Extension

Using Spark

The Spark MCP extension exposes the user's mailbox, calendar, contacts, meetings, and team data as tools. Use it to answer questions about their Spark data and, when the account allows it, to act on it - draft messages, post team comments, triage threads, and manage contacts.

Access levels

Each account and shared inbox has its own access level, configured by the user in Spark Desktop under Settings > AI Agents. The accounts tool reports the current level for every account and shared inbox.

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 write tool is invoked against an account with insufficient access, the call returns a descriptive error explaining how to raise the level. Pass that on to the user verbatim and offer to retry once they have updated the setting, or perform the action in Spark Desktop directly.

Calling tools

Each tool is an MCP tool exposed by the spark server. Examples below use the notation:

tool_name { "param": "value", ... }

Map this to your runtime's tool-call syntax - the left side is the MCP tool name, the right side is the JSON arguments object.

Always call accounts once at the start of any non-trivial task to discover available accounts, calendars, teams, shared inboxes, and access levels. Call folders before passing folder identifiers to emails or search.

Tools

accounts

List all configured accounts with their calendars, teams, and shared inboxes. Output reports each account's and shared inbox's access level - check this before attempting any write tool. Takes no parameters.

accounts {}

Run first to discover what is available and which accounts allow triage actions.

folders

List folders with message counts. Output includes folder identifiers in parentheses - use those as the folder parameter for emails and as scope for 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.

folders {}
folders { "account": "user@example.com" }

emails

List emails with metadata (ID, From, Date, Subject, Flags). Supports pagination and Gmail-style filters. Does not return bodies - use search or thread when you need content.

emails {}                                                                         # Unified Inbox
emails { "folder": "user@example.com:Archive" }                                   # specific folder
emails { "folder": "My Team" }                                                    # team's shared threads
emails { "filter": "from:alice@co.com is:unread" }
emails { "filter": "newer_than:7d has:attachment" }
emails { "page": 2, "page_size": 20 }
emails { "order": "ascending" }
emails { "new_senders": true }

GateKeeper: When viewing the Inbox with GateKeeper in explicit mode, new-sender emails are filtered out and a "New Senders" count is shown at the top. Set new_senders: true to view them. Use contact-action with acceptContact or blockContact to accept or block a sender (requires triage).

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

Filter operators (combine space-separated inside the filter string):

search

Two modes, selected by whether you pass query:

• Topic mode (query set): hybrid keyword + semantic search returning up to 20 emails with full bodies, sorted by relevance. Use this when the user asks about a topic and you need content to answer.
• List mode (query omitted): a paged, compact table of every email matching filter/in across all folders in all accounts, newest first (same columns as emails). Trash, Spam, and Blocked are excluded unless in targets one of them. Use this to filter by metadata (especially from:) beyond the Unified Inbox that emails is limited to.

search { "query": "quarterly report" }
search { "query": "API integration", "filter": "from:alice@co.com" }
search { "query": "budget", "in": "user@example.com:Archive" }
search { "query": "vacation", "in": "user@example.com" }
search { "filter": "from:alice@co.com" }                       # list mode: every email from alice, all folders
search { "filter": "is:unread newer_than:7d", "page": 2 }

Use search with a query when the user asks about content (you need bodies). Use search without a query to filter across every folder - emails only sees the Unified Inbox, so it can't answer "every email from alice, anywhere". Use emails for plain browsing of the Inbox or a single folder.

thread

Read every message in a conversation - headers, plain-text bodies, attachment info. After the thread summary line, lists custom (non-system) folder labels once for the whole thread.

thread { "message_id": "1114" }
thread { "message_id": "1114", "download_attachments": true }

Each message's Attachments: block is a table with columns ID, Name, Size, and MIME Type. The ID is a stable integer - pass it to the attachment tool to read the file's bytes (images, PDFs, text, audio). Local filesystem paths are deliberately omitted because sandboxed MCP clients can't follow them; the attachment tool is the only path to attachment contents through this connection.

Find IDs with emails or search first, then call thread to read the full conversation.

attachment

Read a single email attachment by its ID and receive the file content directly through MCP - the server reads the bytes off disk and returns them as image, audio, text, or embedded-resource (binary blob) content blocks depending on the MIME type. Auto-downloads the file via IMAP if it isn't cached locally yet, so this works even for attachments whose thread row showed (not downloaded, ...).

This is the sandbox-friendly way to read attachments: clients never need to touch the local filesystem path printed in the thread output.

attachment { "id": 42 }

Returns a leading text block summarizing the attachment (name, size, MIME type, message ID), followed by the file content as one of:

• Image (image/*) - inline image content block, ready for vision.
• Audio (audio/*) - inline audio content block.
• Text (text/*, plus JSON/XML/NDJSON) - inline text content block with the file's UTF-8 contents.
• Anything else (PDF, ZIP, Office documents, etc.) - embedded resource content block with a base64 blob and the original MIME type.

Files larger than the configured cap (default 50 MB; override with the SPARK_ATTACHMENT_MAX_BYTES env var on the MCP server) are rejected with a clear error - ask the user to open the attachment in Spark Desktop instead.

Typical flow:

1. thread { "message_id": "<id>" } - find the attachment's ID in the Attachments: table.
2. attachment { "id": <attachment-id> } - read its bytes.

events

List calendar events for a time range. Defaults to today's remaining events.

events {}
events { "tomorrow": true }
events { "week": true }
events { "week": true, "in": "user@example.com" }
events { "week": true, "in": "user@example.com:Work" }
events { "start": "2026-03-16", "end": "2026-03-20" }

Call accounts to see available calendar accounts and calendar names.

availability

Find free time slots. Without attendees, shows the user's own availability. With attendees, computes mutual free windows. Working hours are 08:00-20:00, weekends skipped, events marked "free" are ignored.

availability {}
availability { "tomorrow": true }
availability { "week": true, "attendees": "alice@co.com" }
availability { "start": "2026-03-16", "end": "2026-03-20", "attendees": "a@co.com,b@co.com" }

contacts

Search contacts by name or email. Strict match first, then fuzzy fallback.

contacts { "query": "john" }
contacts { "query": "example.com" }

team

Show team info - metadata, shared inboxes with members, full member list, assigned emails, and assignment summary. Call without name to list available teams.

team {}
team { "name": "My Team" }

meetings

List meeting transcripts, newest first. Supports filtering and pagination.

meetings {}
meetings { "filter": "newer_than:30d" }
meetings { "filter": "subject:standup", "page_size": 10 }

Filter operators for meetings: subject:<text>, before:yyyy/MM/dd, after:yyyy/MM/dd, newer_than:Xd, older_than:Xd.

meeting

Read a single meeting transcript's summary. Optionally include the full transcript and/or user notes.

meeting { "meeting_id": "42" }
meeting { "meeting_id": "42", "transcript": true }
meeting { "meeting_id": "42", "notes": true }
meeting { "meeting_id": "42", "transcript": true, "notes": true }

templates

List saved Spark message templates - the drafts you can apply via draft's template parameter. Personal and team templates both appear; they round-trip from Spark Desktop.

templates {}
templates { "personal": true }
templates { "team": "Marketing" }
templates { "page": 2, "page_size": 20 }

Output columns: ID, Scope (Personal or team name), Name, Subject, Modified. Use the ID or Name with the template tool and with draft's template parameter.

template

Show a single template's full contents and its placeholder requirements. Run this before draft { "template": ... } so you know which placeholders to fill.

template { "ref": "123" }
template { "ref": "Welcome reply" }

Output includes scope, recipients, subject, body (HTML stripped to text), attachments, and a Placeholders: section listing every placeholder:

• [auto] - auto-fillable (recipient/self name), resolved from to/account when applied. Not overridable via placeholder.
• [manual] - free-form; must be passed as placeholder: ["<name>=<value>"] to draft.

If a name matches more than one template, the call errors with the matching IDs - disambiguate by ID.

draft

Requires triage access.

Create a new email draft or edit an existing one. The body is markdown and is converted to HTML. Seed a draft from an existing message with reply_to or forward, update an existing draft with edit, apply a saved template with template, and collaborate with teammates with the sharing parameters.

draft { "to": ["alice@example.com"], "subject": "Hello", "body": "Hi Alice, ..." }
draft { "to": ["alice@co.com", "bob@co.com"], "cc": ["carol@co.com"], "subject": "Meeting", "body": "..." }
draft { "edit": "1234", "subject": "Updated subject", "body": "Updated body" }
draft { "reply_to": "5678", "body": "Thanks for the update!" }
draft { "forward": "5678", "to": ["manager@co.com"], "body": "FYI" }
draft { "account": "john@gmail.com", "to": ["alice@co.com"], "subject": "Hi", "body": "..." }
draft { "to": ["alice@co.com"], "subject": "Report", "body": "See attached", "attach": ["/path/to/report.pdf"] }
draft { "to": ["alice@co.com"], "subject": "Files", "body": "Two files", "attach": ["/path/to/a.pdf", "/path/to/b.xlsx"] }

Apply a saved template (run template first to learn its manual placeholders):

draft { "template": "Cold outbound v3", "to": ["alice@co.com"], "placeholder": ["Project name=Acme Q3", "Deadline=Friday EOD"] }
draft { "template": "124", "edit": "9821", "placeholder": ["Project name=Acme Q3"] }

Share a draft and manage collaborators:

draft { "to": ["client@co.com"], "subject": "Proposal", "body": "...", "team": "Engineering", "user": ["alice@co.com", "bob@co.com"] }
draft { "edit": "1234", "team": "Engineering", "user": ["carol@co.com"], "allow_send": true }
draft { "edit": "1234", "remove_user": ["alice@co.com"], "user": ["dave@co.com"] }   # swap collaborators in one call
draft { "edit": "1234", "disallow_send": true }                                       # revoke send-on-behalf
draft { "edit": "1234", "unshare": true }

Use emails to find message IDs for edit, reply_to, and forward. Use accounts to find account emails for account - both personal accounts and shared inboxes are listed there, and either can be used as the from address when the account has triage access. Use team to list teams and members for team/user.

Templates. Run template { "ref": "<id|name>" } before draft { "template": ... } to discover required manual placeholders - a missing manual placeholder is a hard error before any draft is created. Explicit fields always win over template fields.

Threading is critical. When a message belongs to an existing conversation, you must pass reply_to with the last message in that thread - that is what attaches the draft to the conversation (correct In-Reply-To/References headers, same thread in the recipient's mailbox). Without reply_to the draft starts a brand new thread, which is almost always wrong when the user said "reply", "respond", "follow up", or "ping" within an existing conversation. Use thread to inspect the conversation and pick the most recent message's ID.

Follow-ups (no reply yet). When following up on a thread whose most recent message is your own outgoing one (e.g. "nudge Alice - she never replied"), use that outgoing message's ID as reply_to so the follow-up stays attached as a bump rather than a new cold email.

Sharing. Sharing is triggered by the presence of team or user; teams with exactly one other active member auto-share with everyone, otherwise user is required. To change collaborators or the send-on-behalf setting on an existing shared draft, pass edit together with the sharing params - the change is applied to the existing share. Content edits (to/cc/bcc/subject/body/attach) and sharing updates (team/user/remove_user/allow_send/disallow_send) must be issued as separate calls, and unshare cannot be combined with either.

comment

Requires triage access.

Post a team comment (chat message) on a thread. If the thread isn't yet shared, it is shared automatically. Supports text comments, file attachments, or both. Use edit to update an existing comment.

comment { "message_id": "1234", "body": "Looks good, let's proceed." }
comment { "message_id": "1234", "body": "Please review this", "team": "Engineering" }
comment { "message_id": "1234", "body": "FYI", "team": "Engineering", "user": ["alice@co.com", "bob@co.com"] }
comment { "message_id": "1234", "attach": ["/path/to/screenshot.png"] }
comment { "message_id": "1234", "body": "See attached", "attach": ["/path/to/report.pdf", "/path/to/data.csv"] }
comment { "edit": "5678", "body": "Updated comment text" }

Use emails to find message IDs. Use thread to see comment IDs already posted on a conversation. Use team to list teams and their members.

action

Requires triage access.

Perform an action on one or more emails. Pass action_name plus a message_ids array; some actions need additional options (date, folder, team, user, assignee, comment).

Supported action_name values:

action { "action_name": "pin", "message_ids": ["12345"] }
action { "action_name": "archive", "message_ids": ["100", "200", "300"] }
action { "action_name": "markAsSeen", "message_ids": ["100", "200"] }
action { "action_name": "snooze", "message_ids": ["12345"], "date": "2026-04-10T09:00" }
action { "action_name": "snooze", "message_ids": ["12345"], "date": "2026-04-10" }
action { "action_name": "moveToFolder", "message_ids": ["12345"], "folder": "user@example.com:Archive" }
action { "action_name": "attachLabel", "message_ids": ["12345"], "folder": "user@gmail.com:MyLabel" }
action { "action_name": "detachLabel", "message_ids": ["12345"], "folder": "shared@company.com:SomeLabel" }
action { "action_name": "changeReminder", "message_ids": ["12345"], "date": "2026-04-15" }
action { "action_name": "shareInTeam", "message_ids": ["1234"], "team": "Engineering", "user": ["alice@co.com"] }
action { "action_name": "shareInTeam", "message_ids": ["1234"], "user": ["alice@co.com", "bob@co.com"] }
action { "action_name": "assign", "message_ids": ["1234"], "assignee": "bob@co.com" }
action { "action_name": "assign", "message_ids": ["1234"], "assignee": "bob@co.com", "date": "2026-04-15", "comment": "Please review" }
action { "action_name": "delegationComplete", "message_ids": ["1234"] }
action { "action_name": "delegationComplete", "message_ids": ["100", "200", "300"] }
action { "action_name": "delegationReopen", "message_ids": ["1234"] }

Use emails to find message IDs. Use folders to resolve qualified names for moveToFolder, attachLabel, and detachLabel. Use team to list teams and members for team actions.

contact-action

Requires triage access.

Perform an action on one or more contacts by email address.

Supported action_name values:

contact-action { "action_name": "blockContact", "emails": ["spammer@example.com"] }
contact-action { "action_name": "acceptContact", "emails": ["alice@co.com", "bob@co.com"] }
contact-action { "action_name": "changeCategoryPersonal", "emails": ["alice@co.com"] }
contact-action { "action_name": "markContactAsPrimary", "emails": ["ceo@company.com"] }
contact-action { "action_name": "enableAutosummaryForContact", "emails": ["newsletter@example.com"] }

Use contacts to look up email addresses.

Smart Categories

Spark automatically classifies incoming email into six categories. Use the category: filter operator with emails and search to view mail by category, and use action / contact-action to reclassify and tune (triage).

Browse by category (read-only):

emails { "folder": "Inbox", "filter": "category:priority is:unread" }
emails { "folder": "Inbox", "filter": "category:personal is:unread" }
emails { "folder": "Inbox", "filter": "category:invitation" }
emails { "folder": "Inbox", "filter": "category:notification is:unread" }
emails { "folder": "Inbox", "filter": "category:newsletter newer_than:7d" }

Reclassify a single message (triage):

action { "action_name": "changeCategoryPersonal", "message_ids": ["12345"] }
action { "action_name": "changeCategoryNotification", "message_ids": ["12345"] }
action { "action_name": "changeCategoryNewsletters", "message_ids": ["12345"] }

Tune per-contact category rules (triage) - changes apply to all future mail from the sender:

contact-action { "action_name": "changeCategoryPersonal", "emails": ["sender@example.com"] }
contact-action { "action_name": "changeCategoryNewsletters", "emails": ["sender@example.com"] }
contact-action { "action_name": "groupEmailsFromContact", "emails": ["sender@example.com"] }
contact-action { "action_name": "markContactAsImportant", "emails": ["vip@example.com"] }
contact-action { "action_name": "markContactAsPrimary", "emails": ["ceo@example.com"] }
contact-action { "action_name": "enableAutosummaryForContact", "emails": ["newsletter@example.com"] }

Category-first triage pattern: Process inbox in priority order - priority -> people -> invites -> notifications -> newsletters. This ensures the most important messages get attention first.

Typical Workflows

Answer a question about emails:

1. search { "query": "topic" } - find relevant emails with bodies.
2. Read the output and answer the user's question.

Find and read a specific email:

1. emails { "filter": "from:sender subject:keyword" } - locate the email.
2. thread { "message_id": "<ID>" } - read the full conversation.

Read an attachment (image, PDF, CSV):

1. thread { "message_id": "<ID>" } - look up the ID column in the Attachments: table.
2. attachment { "id": <attachment-id> } - receive the file contents directly (no need to read the local Path).

Draft a reply:

1. emails { "filter": "from:sender" } - find the email.
2. draft { "reply_to": "<ID>", "body": "Thanks for the update!" }.

Send an email from a saved template:

1. templates {} - list templates (or templates { "personal": true } / templates { "team": "<name>" }).
2. template { "ref": "<id|name>" } - inspect required manual placeholders.
3. draft { "template": "<id|name>", "to": ["alice@co.com"], "placeholder": ["<name>=<value>"] } - create the draft.

Check someone's schedule for a meeting:

1. availability { "tomorrow": true, "attendees": "alice@co.com,bob@co.com" }.
2. Suggest a time from the free slots.

Comment on a shared thread:

1. emails { "filter": "subject:keyword" } - find the email.
2. comment { "message_id": "<ID>", "body": "Looks good, approved!" }.

Get team workload overview:

1. team { "name": "Team Name" } - see members and assigned emails.

Look up a contact:

1. contacts { "query": "name or domain" } - find their email address.

Triage a thread (archive/pin/snooze):

1. emails { "filter": "from:sender" } - find the message.
2. action { "action_name": "archive", "message_ids": ["<ID>"] } - archive (or pin, snooze with date, etc.).

Bulk archive after review:

1. emails { "folder": "Inbox", "filter": "category:newsletter newer_than:7d" } - list candidates.
2. action { "action_name": "archive", "message_ids": ["<ID1>", "<ID2>", "<ID3>"] } - archive in one call.

Share an email with the team:

1. emails { "filter": "subject:keyword" } - find the email.
2. action { "action_name": "shareInTeam", "message_ids": ["<ID>"], "user": ["alice@co.com"] }.

Delegate an email to a teammate:

1. emails { "filter": "subject:keyword" } - find the email.
2. action { "action_name": "assign", "message_ids": ["<ID>"], "assignee": "bob@co.com", "date": "2026-04-15", "comment": "Please handle this" }.

Mark delegated emails as done:

1. emails { "filter": "subject:keyword" } - find the email(s).
2. action { "action_name": "delegationComplete", "message_ids": ["<ID1>", "<ID2>"] }.

Review assigned shared inbox items:

1. emails { "folder": "shared@co.com:Inbox", "filter": "assigned_to:unassigned" } - unassigned items.
2. action { "action_name": "assign", "message_ids": ["<ID>"], "assignee": "bob@co.com" } - assign to a teammate.
3. emails { "filter": "assigned_to:bob@co.com" } - items assigned to a teammate.
4. emails { "filter": "is:shared_inbox_open" } - all open shared inbox items.
5. emails { "filter": "is:shared_inbox_done" } - completed items.

Read meeting notes:

1. meetings { "filter": "newer_than:30d" } - find recent meetings.
2. meeting { "meeting_id": "<ID>", "transcript": true, "notes": true } - read summary, transcript, and notes.

Manage a contact (block/accept/categorize):

1. contacts { "query": "name or domain" } - find the contact email.
2. contact-action { "action_name": "blockContact", "emails": ["spammer@example.com"] } - block (or acceptContact, change category, etc.).

Tips

• Combine filter operators into a single filter string: "from:alice@co.com is:unread newer_than:7d" - do not split them across calls.
• Call folders to discover exact folder identifiers before passing them to emails or search's in parameter.
• Call accounts to discover calendar identifiers before passing them to events's in parameter, and to check each account's access level before attempting draft, comment, action, or contact-action.
• Use search for topic-based queries - it returns bodies. Use emails for browsing or slicing by metadata - it does not.
• Use thread after finding an interesting message ID with emails or search.
• Multi-word subjects and team names must be quoted inside the filter string: subject:"quarterly report".
• action and contact-action accept arrays of IDs/emails - batch related changes into a single call rather than one call per message.
• If a write tool returns an "access denied" error, surface it to the user and point them at Spark Desktop > Settings > AI Agents to raise the level. They can also perform the action directly in Spark Desktop.

Source: readdle/spark-claude-extension — distributed by TomeVault.