gmail-assistant

name	gmail-assistant
description	Use when composing, sending, searching, or managing Warren's emails via gmail CLI. Covers drafting with styles, finding similar emails for context, managing groups, discovering contacts online, and email workflows. Always test to [e-mail] before real sends.

Gmail Assistant

Use this skill when working with email through the gmail CLI tool.

Quick Commands

• /gmail - Quick reference for common gmail CLI commands
• /gmail::setup - Set up Gmail CLI authentication

Core Principles

ALWAYS before composing:

1. Search past emails to recipient(s) → extract patterns (greeting, tone, sign-off)
2. Check available email styles → match context
3. Test to [e-mail] FIRST
4. Review preview → then send to real recipient

Progressive disclosure:

• Start with summaries (gmail list, gmail search)
• Read full content only when needed (--full)
• Get thread context only if required (gmail thread)

---

Essential Commands

Search & Discovery

gmail search "to:[e-mail]" --max 10        # Emails to someone
gmail search "from:[e-mail]" --max 10      # Emails from someone
gmail search "subject:keyword after:2024/10/01"      # By subject + date
gmail search "has:attachment filename:pdf"           # With attachments
gmail list --folder INBOX --max 10                   # List inbox
gmail folders                                        # List all folders/labels

Read & View

gmail read <message_id>                              # Summary view
gmail read <message_id> --full                       # Full content
gmail read <message_id> --full-thread                # Full content with thread context
gmail thread <message_id>                            # View entire thread
gmail thread <message_id> --strip-quotes             # View thread without quoted content

Send & Reply

# Send from file (preferred for composed emails)
gmail send --to [e-mail] --subject "X" --body "$(cat /tmp/email/draft.txt)"
gmail send --to [e-mail] --subject "X" --body "$(cat /tmp/email/draft.txt)" --attachment file.pdf

# Send inline (for quick replies only)
gmail send --to [e-mail] --subject "X" --body "Y"
gmail reply <message_id> --body "Reply text"
gmail reply <message_id> --body "Reply" --reply-all

Email Styles

gmail styles list                                    # List all styles
gmail styles show professional-formal                # View specific style
gmail styles validate style-name                     # Validate format

Common styles: professional-formal, professional-friendly, casual-friend, brief-reply

Email Groups

gmail groups list                                    # List all groups
gmail groups show team                               # Show group members
gmail groups add team [e-mail]             # Add member
gmail send --to @team --subject "X" --body "Y"       # Use group

Workflows

gmail workflows list                                 # List workflows
gmail workflows run clear                            # Run interactively
gmail workflows start clear                          # Start programmatic (JSON)
gmail workflows continue <token> archive             # Continue with action

---

Important Workflow Guidelines

Composing Emails

1. Search past emails to recipient → extract greeting/tone/sign-off patterns
2. Check relevant email styles (gmail styles list)
3. Draft combining past patterns + style + current context
4. Write draft to /tmp/email/{descriptive_name}.txt
5. Open file for user review/editing (use open command on macOS)
6. Test to [e-mail] first using file: gmail send --to [e-mail] --subject "..." --body "$(cat /tmp/email/{name}.txt)" --yolo
7. After user confirms, send to real recipient using same file

Extracting Email Style from Past Emails

1. Search relevant past emails: gmail search "to:@harvard.edu" --folder SENT --max 10
2. Read full content: gmail read <message_id> --full
3. Note patterns:
   • Greeting: Formal (Dear Professor) vs. casual (Hi)
   • Tone: Professional, friendly, concise
   • Structure: Sections (Why/Preparation/Commitment), bullet points, paragraphs
   • Sign-off: Best regards, Thanks, etc.
   • Signature: Contact info format
4. Match these patterns in new draft for consistency

Replying to Emails

1. Read original email (gmail read <id> --full)
2. Check thread if needed (gmail thread <id>)
3. Search past emails from sender to match their style
4. Draft appropriate reply → review preview → send

Finding Contacts

1. Search inbox: gmail search "from:[name]"
2. Search sent: gmail search "to:[name]"
3. Check groups: gmail groups list
4. If not found → search web (LinkedIn, org directories)
5. Confirm with user before using new emails

---

Extracting Email Context

Getting Full Thread Conversation

Recommended approach:

# Use gmail thread to view entire conversation
gmail thread <message_id>                  # Show full thread
gmail thread <message_id> --strip-quotes   # Remove quoted content for clarity
gmail thread <message_id> --output-format json  # Get JSON format

Alternative (manual assembly):

# 1. Find thread
gmail list --folder ALL --query "keyword"

# 2. Get all message IDs in thread
# Note thread_id from results

# 3. Read each message with full body
gmail read <id> --full

# 4. Piece together conversation manually

Finding CC'd Recipients

If gmail read output doesn't show CC/BCC recipients (current limitation), use Python workaround:

from gmaillm.gmail_client import GmailClient

client = GmailClient()
msg = client.service.users().messages().get(
    userId='me',
    id='<message_id>',
    format='full'
).execute()

headers = msg['payload']['headers']

# Extract CC recipients
cc = [h['value'] for h in headers if h['name'].lower() == 'cc']
to = [h['value'] for h in headers if h['name'].lower() == 'to']
from_ = [h['value'] for h in headers if h['name'].lower() == 'from']

print(f"From: {from_}")
print(f"To: {to}")
print(f"CC: {cc}")

Common Pattern: Draft Reply Based on Thread

Complete workflow:

1. Search for thread: gmail list --folder ALL --query "subject:keywords"
2. Note message IDs and thread_id from results
3. Read each message for context: gmail read <id> (or --full for body)
4. Extract who's involved:
   • If CC not visible, use Python workaround above
   • Note all participants from From/To/CC fields
5. Draft reply matching tone and context
6. Include appropriate recipients (reply vs reply-all)
7. Send with --yolo to skip confirmation

Example:

# Find thread
gmail list --folder ALL --query "MLD courses" --output-format json

# Read messages
gmail read 19a5a90f97be8df8

# Extract CC (if needed)
# Use Python script above

# Send reply with CC
gmail send --to "[e-mail]" --cc "[e-mail]" --subject "Reply" --body "..." --yolo

---

Gmail Search Operators

People: from:, to:, cc:, bcc: Date: after:YYYY/MM/DD, before:YYYY/MM/DD, newer_than:7d, older_than:30d Status: is:unread, is:starred, is:important, is:read Content: subject:keyword, has:attachment, has:drive, filename:pdf Size: larger:10M, smaller:5M Boolean: OR, - (NOT), () (grouping)

Examples:

• All correspondence: to:[e-mail] OR from:[e-mail]
• Recent thread: subject:project after:2024/10/01
• Unread important: is:unread is:important
• With PDF: has:attachment filename:pdf

---

Key Things to Know

Email Styles:

• Located in ~/.gmaillm/email-styles/
• Common: professional-formal, professional-friendly, casual-friend, brief-reply
• View with gmail styles show <name>
• Use for guidance on tone, greetings, closings

Configuration:

• All settings in ~/.gmaillm/
• First time: gmail setup-auth
• Verify: gmail verify

Best Practices:

• Search past emails before composing → extract patterns
• Use progressive disclosure → summaries first, full content only when needed
• Test to [e-mail] before real sends
• Leverage email groups for recurring distributions
• Match recipient's formality level

Common Mistakes to Avoid:

• Sending without searching first
• Wrong formality level (too casual or too formal)
• Skipping test emails
• Not using groups for recurring sends
• Getting full email when summary sufficient

---

References

For detailed information when needed:

• references/email-styles.md - Complete styles guide
• references/gmail-search-syntax.md - Full search syntax
• references/api-reference.md - Complete API docs