Gmail

This skill provides Gmail-specific operations beyond the shared messaging skill. For cross-platform messaging (send, read, search, reply), use the messaging skill. Gmail operations depend on the messaging skill's provider infrastructure - load messaging first if Gmail is not yet connected.

Script Reference

All operations use CLI scripts that return JSON:

• Success: { "ok": true, "data": ... }
• Failure: { "ok": false, "error": "..." }

Email Operations

# Draft an email
bun run scripts/gmail-email.ts draft --to "user@example.com" --subject "Hello" --body "Message body"

# Draft a reply in a thread
bun run scripts/gmail-email.ts draft --to "user@example.com" --subject "Re: Hello" --body "Reply body" --thread-id "18f..." --in-reply-to "18f..."

# Send an existing draft (REQUIRES user confirmation before execution)
bun run scripts/gmail-email.ts send-draft --draft-id "r123..."

# Forward a message
bun run scripts/gmail-email.ts forward --message-id "18f..." --to "recipient@example.com" --text "FYI"

# Trash a message
bun run scripts/gmail-email.ts trash --message-id "18f..."

Management Operations

# Label - add a label to a message
bun run scripts/gmail-manage.ts label --message-id "18f..." --add-labels "Work,Important"

# Follow-up - track a message for follow-up
bun run scripts/gmail-manage.ts follow-up --action track --message-id "18f..."

# Attachments - list attachments on a message
bun run scripts/gmail-manage.ts attachments --action list --message-id "18f..."

# Attachments - download a specific attachment
bun run scripts/gmail-manage.ts attachments --action download --message-id "18f..." --attachment-id "ANGj..." --filename "report.pdf"

# Filters - create a Gmail filter
bun run scripts/gmail-manage.ts filters --action create --from "newsletter@example.com" --remove-labels "INBOX"

# Vacation - enable auto-responder
bun run scripts/gmail-manage.ts vacation --action enable --message "I'm out of office until Monday"

# Unsubscribe from a mailing list (REQUIRES user confirmation before execution)
bun run scripts/gmail-manage.ts unsubscribe --message-id "18f..."

Scan Operations

# Sender digest - scan inbox grouped by sender
bun run scripts/gmail-scan.ts sender-digest [--query "in:inbox category:promotions newer_than:90d"]

# Outreach scan - identify cold outreach senders
bun run scripts/gmail-scan.ts outreach-scan [--time-range "90d"]

Scan scripts store message IDs in the assistant's cache and return a lightweight summary with a cache_key. This keeps thousands of message IDs out of the conversation context. To retrieve cached message IDs for a specific sender:

assistant cache get <cache_key> --json
# Returns: { "ok": true, "data": { "sender@example.com": ["msgId1", "msgId2", ...], ... } }

Archive Operations

# Archive using cache_key + sender emails (preferred for declutter workflows)
bun run scripts/gmail-archive.ts archive --cache-key "scan:abc123" --sender-emails "news@example.com,promo@example.com"

# Archive specific message IDs
bun run scripts/gmail-archive.ts archive --message-ids "18f1...,18f2...,18f3..."

# Archive a single message
bun run scripts/gmail-archive.ts archive --message-id "18f..."

# Archive by query
bun run scripts/gmail-archive.ts archive --query "from:newsletter@example.com in:inbox"

Operation Runs

All destructive archive operations are logged to a JSONL operation log for resumability and auditing. Each batch of archives is tracked as a "run" with a unique ID.

# List recent runs with status summaries
bun run scripts/gmail-runs.ts list [--limit 20]

# Show detailed log entries for a specific run
bun run scripts/gmail-runs.ts inspect --run-id "run_20260420_a1b2c3d4"

# Delete logs older than 30 days
bun run scripts/gmail-runs.ts prune

Dry-Run Mode

Dry-run mode runs the full pipeline (scanning, collecting message IDs) but skips all destructive API calls. Staged entries are written to the op log for review.

# Preview what would be archived
bun run scripts/gmail-archive.ts archive --query "..." --dry-run

# Review the staged operations
bun run scripts/gmail-runs.ts inspect --run-id "<run-id>"

# Commit the staged operations (executes the archive)
bun run scripts/gmail-commit.ts commit --run-id "<run-id>"

# Cancel (delete the log, nothing executed)
bun run scripts/gmail-commit.ts cancel --run-id "<run-id>"

Label and filter operations also support --dry-run:

bun run scripts/gmail-manage.ts label --message-ids "..." --add-labels "..." --dry-run
bun run scripts/gmail-manage.ts filters --action create --from "..." --remove-labels "INBOX" --dry-run

Archive operations now return a run_id in their output. Use this to resume interrupted runs:

# Resume an interrupted run (e.g. after daily quota hit)
bun run scripts/gmail-archive.ts archive --resume "run_20260420_a1b2c3d4"

# Pass --run-id to group multiple archive calls under one run
bun run scripts/gmail-archive.ts archive --query "..." --run-id "run_20260420_a1b2c3d4" --phase "noise_archive"

When a run is interrupted (e.g. Gmail daily quota exceeded), the operation log records the interruption with a resume hint. The assistant should detect interrupted runs and offer to resume them rather than starting fresh.

Reversing a Run

If a committed run archived messages incorrectly, reverse it:

# Reverse all committed operations in a run (requires confirmation)
bun run scripts/gmail-reverse.ts --run-id "run_20260420_a1b2c3d4"

# Reverse a specific message within a run (no confirmation needed)
bun run scripts/gmail-reverse.ts --run-id "run_20260420_a1b2c3d4" --thread "18f..."

Reversal semantics:

• archive → adds INBOX label back (un-archives)
• label_add → removes the labels that were added
• label_remove → adds back the labels that were removed
• trash → removes TRASH label and adds INBOX (un-trashes, within Gmail's 30-day window)
• filter_create → not auto-reversible; delete manually via gmail-manage.ts filters --action delete

Reversals are themselves logged as runs (auditable, resumable). The reversal only touches labels/state that the original run modified — it does not touch user-applied labels.

Preferences Operations

# List all preferences
bun run scripts/gmail-prefs.ts --action list

# Add senders to blocklist
bun run scripts/gmail-prefs.ts --action add-blocklist --emails "spam@example.com,junk@example.com"

# Add senders to safelist
bun run scripts/gmail-prefs.ts --action add-safelist --emails "important@example.com"

# Remove from blocklist
bun run scripts/gmail-prefs.ts --action remove-blocklist --emails "spam@example.com"

# Remove from safelist
bun run scripts/gmail-prefs.ts --action remove-safelist --emails "important@example.com"

Email Routing Priority

When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - always default to the user's own email (Gmail) unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail, not the assistant's @vellum.me address.

Do not offer the assistant's own email as an option unless the user specifically asks. If Gmail is not connected, guide them through Gmail setup.

Connection Setup

Gmail

1. Check connection health first. Run assistant oauth status google. This checks whether the user's Google account is connected and the token is valid.
2. If no connection is found or the status check fails: Load the vellum-oauth-integrations skill. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.

Error Recovery

When a Gmail script fails with a token or authorization error:

1. Try to reconnect silently. Run assistant oauth ping google. This often resolves expired tokens automatically.
2. If reconnection fails, go straight to setup. Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected - let me set that up") and immediately load the vellum-oauth-integrations skill. The user came to you to get something done, not to troubleshoot - make it seamless.
3. Never try alternative approaches. Don't use curl, browser automation, or any workaround. If the scripts can't do it, the reconnection flow is the answer.
4. Never expose error details. The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.

Safety: Send-Draft and Unsubscribe

Two operations are high-risk and require explicit user confirmation before execution:

• send-draft: Always show the user what will be sent (recipients, subject, body summary) and wait for explicit confirmation ("yes", "send it", etc.) before running the send-draft script. The script gates on assistant ui confirm — it will present a confirmation dialog to the user and only proceed if approved. Never auto-send.
• unsubscribe: Always tell the user which mailing list will be unsubscribed from and wait for explicit confirmation before running the unsubscribe script. The script gates on assistant ui confirm. Unsubscribe actions cannot be undone.

If the user has not explicitly confirmed, do not execute these operations. A general instruction like "clean up my inbox" is not confirmation to unsubscribe - it means scan and present options.

Drafting vs Sending (Gmail)

Gmail uses a draft-first workflow. All compose and reply operations create Gmail drafts automatically:

• bun run scripts/gmail-email.ts draft creates a draft in Gmail Drafts
• bun run scripts/gmail-email.ts draft with --thread-id and --in-reply-to creates a threaded reply draft
• bun run scripts/gmail-email.ts forward creates a forward draft, preserving attachments
• The messaging skill's send operation with Gmail also creates a draft

To actually send: Use bun run scripts/gmail-email.ts send-draft with the draft ID after the user has reviewed it. Only run send-draft when the user explicitly says "send it" or equivalent.

Email Threading (Gmail)

When replying to or continuing an email thread:

• Preferred: Use the messaging skill's send with the thread's thread_id — it automatically handles threading, reply-all recipients, and subject lines.
• Manual drafting: Use bun run scripts/gmail-email.ts draft with both --thread-id and --in-reply-to for full control. The thread_id places the draft in the correct Gmail thread; in_reply_to sets the RFC 822 threading headers.
• Getting the Message-ID: Search and read results include rfc822MessageId in message metadata (looks like <CABx...@mail.gmail.com>). This is the value to pass as --in-reply-to. You can also pass a Gmail message ID directly — the draft script auto-resolves it to the RFC 822 header.

Gmail Search Syntax

When searching Gmail, the query uses Gmail's search operators:

Email Decluttering

When a user asks to declutter, clean up, or organize their email - start scanning immediately. Don't ask what kind of cleanup they want or request permission to read their inbox. Go straight to scanning - but once results are ready, always present them and let the user choose actions before archiving or unsubscribing.

CRITICAL: Never archive, unsubscribe, or take similar bulk actions unless the user has explicitly confirmed for that specific batch. Each batch of results requires its own explicit user confirmation. If the user says "keep going" or "keep decluttering," that means scan and present new results - NOT auto-archive. Previous batch approvals do not carry forward, but deselections DO carry forward: when the user deselects senders from a cleanup batch, run bun run scripts/gmail-prefs.ts --action add-safelist with those sender emails. Before building the next cleanup table, run bun run scripts/gmail-prefs.ts --action list and exclude safelisted senders from the table — the user already indicated they want to keep those.

Inbox Recon (run before cleanup passes)

Before starting category-specific cleanup, understand the inbox.

Never run more than one gmail-scan.ts command in the same turn. Each scan already fans out authenticated Gmail requests. Parallel bash calls multiply that. Run the broad scan, then promotions, then the general-noise scan, one after another.

1. Broad scan: Run bun run scripts/gmail-scan.ts sender-digest --query "in:inbox" with --max-senders 75. This surfaces the top senders across ALL categories, not just promotions.
2. Identify cleanup buckets: Group the results mentally:
   • Newsletters/promotions (hasUnsubscribe: true) → handle in promotions pass
   • Mailing lists / automated forwards (group addresses like devops@, alerts@, noreply@) → handle in general noise pass
   • Reminder chains (DocuSign, GCP, Auth0 — same sender, many messages) → handle in general noise pass
   • Automated receipts (Brex, Stripe, OpenAI credits) → handle in general noise pass
   • Cold outreach (unfamiliar senders, no unsubscribe) → handle in outreach pass
   • Real correspondence → skip
3. Design passes: Use the recon results to decide which passes to run and in what order. If 80% of the inbox is promotions, start there. If the biggest bucket is mailing-list forwards, start with a targeted query for that address.
4. General noise pass: After promotions and before outreach, run bun run scripts/gmail-scan.ts sender-digest --query "in:inbox -category:promotions -category:personal" to catch mailing lists, reminder chains, and automated notifications that aren't categorized as promotions. Present as a table following the same pattern as the promotions pass. Pre-select automated/noise senders, deselect anything that looks like real correspondence.

Workflow

1. Scan: Run bun run scripts/gmail-scan.ts sender-digest. Default query targets promotions currently in the inbox from the last 90 days (in:inbox category:promotions newer_than:90d). The script returns a cache_key plus a lightweight sender summary (counts, unsubscribe availability, sample subjects). Message IDs are stored in the assistant's cache — do NOT ask for them unless needed for archiving. Counts shown in the table reflect only what is currently in the inbox — these are the emails that will be archived.
2. Present: Show results as a table with selectionMode: "multiple":
   • Columns (exactly 3): Sender, Emails Found, Unsub?
     • Unsub? cell values: Use rich cell format: { "text": "Yes", "icon": "checkmark.circle.fill", "iconColor": "success" } when hasUnsubscribe is true, { "text": "No", "icon": "minus.circle", "iconColor": "muted" } when false.
   • Pre-select all rows (selected: true) - users deselect what they want to keep
   • Caption: Include two parts separated by a newline: (1) data scope, e.g. "Newsletters, notifications, and outreach from last 90 days. Deselect anything you want to keep." (adjusted to match the query used), and (2) the Unsub? column legend: "Unsub? - "Yes" means these emails contain an unsubscribe link, so I can opt you out automatically. "No" means no unsubscribe link was found - these will be archived but you may continue receiving them."
   • Action buttons (exactly 2): "Archive & Unsubscribe" (primary), "Archive Only" (secondary). NEVER offer Delete, Trash, or any destructive action.
3. Embed cache_key in button data: When constructing the action buttons, include the cache_key from the scan result in each button's data field. This ensures cache_key is forwarded automatically when the user clicks — the LLM does not need to recall it from earlier context:

   {
     "id": "archive_unsubscribe",
     "label": "Archive & Unsubscribe",
     "style": "primary",
     "data": { "cache_key": "<cache_key value here>" }
   }

4. Wait for user action: Stop and wait. Do NOT proceed to archiving or unsubscribing until the user explicitly confirms which senders to clean up and which action to take. When the user clicks an action button you will receive an action message containing action data: { cache_key, selectedIds }:
   • selectedIds are sender IDs (base64-encoded email addresses) — NOT Gmail message IDs. Always use them as sender emails with cache_key, never as message_ids.
   • Show progress with steps for each phase (e.g., "Archiving 89 senders (2,400 emails)", "Unsubscribing from 72 senders"). Update each step as each phase finishes.
5. Act on selection - batch, don't loop:
   • Archive all at once: Run bun run scripts/gmail-archive.ts archive --skip-confirm once with --cache-key (from action data) + --sender-emails set to all selected sender emails. The script resolves message IDs from the cache and batches the Gmail API calls internally - never loop sender-by-sender. Use --skip-confirm because the user already confirmed via the UI table.
   • Unsubscribe in bulk: If the action is "Archive & Unsubscribe", run bun run scripts/gmail-manage.ts unsubscribe for each sender that has hasUnsubscribe: true — but emit all unsubscribe calls in a single assistant response (parallel tool use) rather than one-at-a-time across separate turns.
6. Accurate summary: The scan counts are exact - the messageCount shown in the table matches the number of messages archived. Format: "Cleaned up [total_archived] emails from [sender_count] senders. Unsubscribed from [unsub_count]."
7. Ongoing protection offer: After reporting results, offer auto-archive filters:
   • "Want me to set up auto-archive filters so future emails from these senders skip your inbox?"
   • If yes, run bun run scripts/gmail-manage.ts filters --action create for each sender with --from set to the sender's email and --remove-labels "INBOX".
   • Then offer a recurring declutter schedule: "Want me to scan for new clutter monthly?"