Gmail Skill - Detailed Usage Guide

Token-efficient Gmail management through CLI scripts for Claude Code.

Quick Start

All scripts are in the scripts/ directory and output JSON.

gmail-send.js - Send Emails

Send emails with support for HTML, CC/BCC, and custom headers.

Basic Usage

node gmail-send.js --to "user@example.com" --subject "Hello" --body "Message body"

Advanced Options

node gmail-send.js \
  --to "user@example.com" \
  --cc "cc@example.com" \
  --bcc "bcc@example.com" \
  --subject "Project Update" \
  --body "The project is complete." \
  --reply-to "reply@example.com"

HTML Email

node gmail-send.js \
  --to "user@example.com" \
  --subject "Newsletter" \
  --html "<h1>Welcome</h1><p>This is HTML content</p>"

Output

{
  "success": true,
  "messageId": "18d1234567890",
  "threadId": "18d1234567890",
  "to": "user@example.com",
  "subject": "Hello"
}

gmail-search.js - Search Emails

Search emails using Gmail's powerful query syntax.

Basic Search

node gmail-search.js --query "is:unread" --limit 10

Search Operators

# From specific sender
node gmail-search.js --query "from:boss@company.com"

# Emails with attachments
node gmail-search.js --query "has:attachment"

# Date range
node gmail-search.js --query "after:2024/01/01 before:2024/12/31"

# Subject search
node gmail-search.js --query "subject:invoice"

# Combine operators
node gmail-search.js --query "from:client@example.com has:attachment is:unread"

# Complex search
node gmail-search.js --query "is:important OR is:starred" --limit 20

Output

{
  "success": true,
  "count": 3,
  "total": 150,
  "query": "is:unread",
  "messages": [
    {
      "id": "18d1234567890",
      "threadId": "18d1234567890",
      "from": "sender@example.com",
      "to": "you@gmail.com",
      "subject": "Project Update",
      "date": "Mon, 15 Jan 2024 10:30:00 -0800",
      "snippet": "The project is progressing well...",
      "labels": ["INBOX", "UNREAD"]
    }
  ]
}

gmail-read.js - Read Messages

Read full message content and thread details.

Read Single Message

node gmail-read.js --id "18d1234567890"

Read Message with Thread Context

node gmail-read.js --id "18d1234567890" --thread

Output

{
  "success": true,
  "id": "18d1234567890",
  "threadId": "18d1234567890",
  "from": "sender@example.com",
  "to": "you@gmail.com",
  "subject": "Project Update",
  "date": "Mon, 15 Jan 2024 10:30:00 -0800",
  "labels": ["INBOX", "UNREAD"],
  "snippet": "The project is progressing well...",
  "body": "Full email body content here..."
}

gmail-labels.js - Manage Labels

List, create, add, and remove labels.

List All Labels

node gmail-labels.js --action list

Create New Label

node gmail-labels.js --action create --name "Project Alpha"

Add Label to Message

# Using label name
node gmail-labels.js --action add --id "18d1234567890" --label "Important"

# Using label ID
node gmail-labels.js --action add --id "18d1234567890" --label "Label_123"

Remove Label from Message

node gmail-labels.js --action remove --id "18d1234567890" --label "Important"

Output (list)

{
  "success": true,
  "action": "list",
  "count": 15,
  "labels": [
    {
      "id": "INBOX",
      "name": "INBOX",
      "type": "system"
    },
    {
      "id": "Label_123",
      "name": "Project Alpha",
      "type": "user"
    }
  ]
}

gmail-drafts.js - Manage Drafts

Create, update, send, and delete draft emails.

List Drafts

node gmail-drafts.js --action list --limit 10

Create Draft

node gmail-drafts.js \
  --action create \
  --to "user@example.com" \
  --subject "Draft Subject" \
  --body "Draft body text"

Update Draft

node gmail-drafts.js \
  --action update \
  --id "r-1234567890" \
  --to "user@example.com" \
  --subject "Updated Subject" \
  --body "Updated body text"

Send Draft

node gmail-drafts.js --action send --id "r-1234567890"

Delete Draft

node gmail-drafts.js --action delete --id "r-1234567890"

Output (create)

{
  "success": true,
  "action": "create",
  "draftId": "r-1234567890",
  "to": "user@example.com",
  "subject": "Draft Subject"
}

Common Workflows

1. Find and Reply to Unread Emails

# Search for unread emails
node gmail-search.js --query "is:unread" --limit 5 > /tmp/unread.json

# Read first message
MESSAGE_ID=$(cat /tmp/unread.json | jq -r '.messages[0].id')
node gmail-read.js --id "$MESSAGE_ID" > /tmp/message.json

# Send reply
SENDER=$(cat /tmp/message.json | jq -r '.from')
SUBJECT=$(cat /tmp/message.json | jq -r '.subject')
node gmail-send.js --to "$SENDER" --subject "Re: $SUBJECT" --body "Thanks for your message!"

2. Organize Emails by Label

# Search for project-related emails
node gmail-search.js --query "subject:project alpha" > /tmp/results.json

# Create label
node gmail-labels.js --action create --name "Project Alpha"

# Add label to each message
cat /tmp/results.json | jq -r '.messages[].id' | while read id; do
  node gmail-labels.js --action add --id "$id" --label "Project Alpha"
done

3. Draft Review Workflow

# Create draft
node gmail-drafts.js --action create \
  --to "client@example.com" \
  --subject "Proposal" \
  --body "Initial draft text" > /tmp/draft.json

DRAFT_ID=$(cat /tmp/draft.json | jq -r '.draftId')

# Update after review
node gmail-drafts.js --action update \
  --id "$DRAFT_ID" \
  --to "client@example.com" \
  --subject "Proposal - Final" \
  --body "Revised draft text"

# Send when ready
node gmail-drafts.js --action send --id "$DRAFT_ID"

Gmail Search Operators Reference

Operator	Example	Description
from:	from:user@example.com	Emails from sender
to:	to:user@example.com	Emails to recipient
subject:	subject:invoice	Subject contains word
has:attachment	has:attachment	Has any attachment
filename:	filename:pdf	Attachment filename
is:unread	is:unread	Unread emails
is:read	is:read	Read emails
is:starred	is:starred	Starred emails
is:important	is:important	Important emails
label:	label:work	Has specific label
after:	after:2024/01/01	After date
before:	before:2024/12/31	Before date
older_than:	older_than:7d	Older than (d/m/y)
newer_than:	newer_than:2d	Newer than (d/m/y)

Error Handling

All scripts return JSON error objects:

{
  "success": false,
  "error": "Token not found. Run: npm run setup"
}

Common errors:

• Token not found: Run npm run setup to authenticate
• Invalid credentials: Check scripts/auth/credentials.json
• Permission denied: Ensure Gmail API scope is granted
• Message not found: Invalid message/draft ID

Tips for Claude

1. Parse JSON efficiently: Use jq for extracting specific fields
2. Chain operations: Save intermediate results to /tmp/ files
3. Validate IDs: Check that message/draft IDs exist before operations
4. User-friendly output: Convert JSON to readable summaries for users
5. Error handling: Check success field and handle errors gracefully