zhongwei/gh-warrenzhu050413-warren-claude-code-plugin-marketplace-claude-context-orchestrator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:05:19 +08:00
commit 09fec2555b
96 changed files with 24269 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
skills/gmail-assistant/README.md Normal file
View File

@@ -0,0 +1,128 @@
# Gmail Assistant Skill
A comprehensive skill for managing email workflows using the gmaillm CLI tool.
## Skill Structure
```
gmail-assistant/
├── SKILL.md # Main skill instructions
├── references/
│ └── quick-reference.md # Concrete syntax examples and common patterns
└── assets/
└── style-template.md # Template for creating new email styles
```
## What This Skill Provides
### Core Workflows
1. **Email Composition** - Draft emails with context from past messages
2. **Search & Discovery** - Find similar emails, threads, and patterns
3. **Contact Finding** - Search web for email addresses before sending
4. **Group Management** - Create and manage distribution lists
5. **Style Management** - Work with email style templates
6. **Workflow Automation** - Set up and run email processing workflows
### Progressive Disclosure Design
The skill follows gmaillm's progressive disclosure pattern:
- **SKILL.md** provides high-level workflows and discovery patterns
- **quick-reference.md** loaded when concrete syntax examples needed
- **style-template.md** used when creating new email styles
### Safety First
The skill emphasizes **always testing first** to fuchengwarrenzhu@gmail.com before sending real emails.
## Usage Examples
### Compose Email with Context
Claude will:
1. Search for similar past emails
2. Review relevant threads
3. Check available styles
4. Draft based on context
5. TEST to fuchengwarrenzhu@gmail.com
6. Send after user confirms
### Find Contact and Send
Claude will:
1. Search web for contact information
2. Extract email address
3. Draft appropriate message
4. TEST first
5. Send after confirmation
### Manage Distribution Groups
Claude can:
- List existing groups
- Create new groups
- Add/remove members
- Send to groups
- Validate group emails
## Key Features
### Runtime Discovery
Instead of loading all documentation upfront, Claude uses discovery commands:
```bash
uv run gmail styles list # See what's available
uv run gmail styles show posts # Get specific details
uv run gmail styles examples # Learn patterns
```
### Context-Aware Email Drafting
Claude searches past emails to:
- Match tone with previous interactions
- Reference relevant context
- Follow established patterns
- Maintain consistency
### Multi-Channel Search
- Search email history (gmaillm)
- Search web for contacts (WebSearch/WebFetch)
- Combine information for informed communication
## Testing
A test email was sent during skill creation to verify the workflow:
```
To: fuchengwarrenzhu@gmail.com
Subject: [TEST] Gmail Assistant Skill - Testing Email Workflow
Status: ✅ Delivered (Message ID: 19a5a8dd9f5e3a21)
```
## Integration with gmaillm
This skill works with gmaillm CLI commands:
- `gmail send` - Send emails (with TEST-first workflow)
- `gmail search` - Find past emails
- `gmail read` - Read messages and threads
- `gmail groups` - Manage distribution lists
- `gmail styles` - Work with email templates
- `gmail workflows` - Automate email processing
All commands support `--output-format json` for programmatic parsing.
## Skill Metadata
- **Name**: gmail-assistant
- **Description**: Email workflow management using gmaillm CLI
- **Location**: `~/.claude/plugins/.../skills/gmail-assistant/`
- **Created**: 2025-11-06
- **Test Status**: ✅ Verified working
## Related Files
- **SKILL.md** - Main instructions (always loaded when skill triggers)
- **quick-reference.md** - Syntax examples (loaded on demand)
- **style-template.md** - Template for new styles (used when creating styles)

260
skills/gmail-assistant/SKILL.md Normal file
View File

@@ -0,0 +1,260 @@
---
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 fuchengwarrenzhu@gmail.com 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 fuchengwarrenzhu@gmail.com 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
```bash
gmail search "to:person@example.com" --max 10 # Emails to someone
gmail search "from:person@example.com" --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
```bash
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
```bash
# Send from file (preferred for composed emails)
gmail send --to user@example.com --subject "X" --body "$(cat /tmp/email/draft.txt)"
gmail send --to user@example.com --subject "X" --body "$(cat /tmp/email/draft.txt)" --attachment file.pdf
# Send inline (for quick replies only)
gmail send --to user@example.com --subject "X" --body "Y"
gmail reply <message_id> --body "Reply text"
gmail reply <message_id> --body "Reply" --reply-all
```
### Email Styles
```bash
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
```bash
gmail groups list # List all groups
gmail groups show team # Show group members
gmail groups add team person@example.com # Add member
gmail send --to @team --subject "X" --body "Y" # Use group
```
### Workflows
```bash
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 fuchengwarrenzhu@gmail.com first** using file: `gmail send --to fuchengwarrenzhu@gmail.com --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:**
```bash
# 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):**
```bash
# 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:
```python
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:**
```bash
# 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 "mksmith@hks.harvard.edu" --cc "Greg_Dorchak@hks.harvard.edu" --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:person@example.com OR from:person@example.com`
- 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 fuchengwarrenzhu@gmail.com 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

60
skills/gmail-assistant/assets/style-template.md Normal file
View File

@@ -0,0 +1,60 @@
---
name: "template-name"
description: "When to use: Clear context description (30-200 characters). Be specific about when this style should be used."
---
<examples>
First example email or situation
---
Second example email or situation
---
Third example (optional)
</examples>
<greeting>
- Option 1: "Hi [Name],"
- Option 2: "Hello [Name],"
- Option 3: "Dear [Name],"
- (no greeting) - if informal/broadcast style
</greeting>
<body>
- Guideline for body structure
- Tone characteristics (formal/casual/friendly/etc.)
- Length guidance (brief/detailed/etc.)
- Key elements to include
- Special formatting or structure
</body>
<closing>
- Option 1: "Best,"
- Option 2: "Thanks,"
- Option 3: "Sincerely,"
- (no closing) - if informal/broadcast style
</closing>
<do>
- Best practice 1
- Best practice 2
- Recommended approach 3
- Things that work well
</do>
<dont>
- Thing to avoid 1
- Thing to avoid 2
- Common mistake 3
- What doesn't fit this style
</dont>

659
skills/gmail-assistant/references/api-reference.md Normal file
View File

@@ -0,0 +1,659 @@
# gmaillm API Reference
Complete reference for gmaillm Python library and CLI.
## Table of Contents
- [Python Library API](#python-library-api)
- [CLI Commands](#cli-commands)
- [Models & Types](#models--types)
- [Gmail Search Syntax](#gmail-search-syntax)
---
## Python Library API
### GmailClient
```python
from gmaillm import GmailClient
client = GmailClient(
credentials_file="/Users/wz/.gmail-mcp/credentials.json", # optional
oauth_keys_file="/Users/wz/Desktop/OAuth2/gcp-oauth.keys.json" # optional
)
```
### Core Operations
#### verify_setup()
Verify authentication and basic functionality.
```python
result = client.verify_setup()
# Returns: {
# 'auth': bool,
# 'folders': int,
# 'inbox_accessible': bool,
# 'errors': List[str]
# }
```
#### list_emails()
List emails with pagination.
```python
result = client.list_emails(
folder='INBOX', # Gmail label/folder
max_results=10, # 1-50, default 10
page_token=None, # For pagination
query=None # Gmail search query
)
# Returns: SearchResult
```
**Example:**
```python
# First page
result = client.list_emails(folder='INBOX', max_results=10)
for email in result.emails:
print(email.to_markdown())
# Next page
if result.next_page_token:
next_result = client.list_emails(
folder='INBOX',
max_results=10,
page_token=result.next_page_token
)
```
#### read_email()
Read a specific email.
```python
email = client.read_email(
message_id, # Required: message ID
format="summary" # "summary" | "full"
)
# Returns: EmailSummary | EmailFull
```
**Formats:**
- `"summary"` (default): ID, from, to, subject, date, snippet, labels
- `"full"`: Everything + body (plain text & HTML), attachments
**Example:**
```python
# Get summary first (minimal context)
summary = client.read_email(msg_id, format="summary")
print(summary.to_markdown())
# Get full if body needed
full = client.read_email(msg_id, format="full")
print(full.body_plain)
```
#### search_emails()
Search emails using Gmail query syntax.
```python
result = client.search_emails(
query, # Gmail search query
folder='INBOX', # Optional: limit to folder
max_results=10 # 1-50, default 10
)
# Returns: SearchResult
```
**Example:**
```python
result = client.search_emails(
query="from:professor@university.edu has:attachment after:2024/10/01",
max_results=20
)
```
#### get_thread()
Get all emails in a conversation thread.
```python
messages = client.get_thread(message_id)
# Returns: List[EmailSummary] (chronologically sorted)
```
**Example:**
```python
thread = client.get_thread(msg_id)
print(f"Thread has {len(thread)} messages")
for i, msg in enumerate(thread, 1):
print(f"[{i}] {msg.from_.email} → {msg.to[0].email if msg.to else 'unknown'}")
print(f" {msg.subject}")
```
#### send_email()
Send a new email.
```python
from gmaillm import SendEmailRequest
request = SendEmailRequest(
to=["user@example.com"], # Required: list of recipients
subject="Subject", # Required: string
body="Email body", # Required: string
cc=["cc@example.com"], # Optional: list
attachments=["/path/to/file.pdf"] # Optional: list of file paths
)
response = client.send_email(request)
# Returns: SendEmailResponse
```
**Example:**
```python
request = SendEmailRequest(
to=["friend@gmail.com"],
subject="Quick Question",
body="Hey, are you free tomorrow?\n\nBest,\nWarren"
)
response = client.send_email(request)
if response.success:
print(f"Sent! Message ID: {response.message_id}")
```
#### reply_email()
Reply to an existing email.
```python
response = client.reply_email(
message_id, # Required: original message ID
body, # Required: reply body text
reply_all=False # Optional: reply to all recipients
)
# Returns: SendEmailResponse
```
**Example:**
```python
response = client.reply_email(
message_id="19abc123",
body="Thanks for the update!",
reply_all=False
)
```
#### get_folders()
List all Gmail labels/folders.
```python
folders = client.get_folders()
# Returns: List[Folder]
```
**Example:**
```python
folders = client.get_folders()
for folder in folders:
print(f"{folder.name}: {folder.unread_count} unread")
```
#### modify_labels()
Add or remove labels from an email.
```python
client.modify_labels(
message_id, # Required: message ID
add_labels=['STARRED'], # Optional: labels to add
remove_labels=['UNREAD'] # Optional: labels to remove
)
```
**Common operations:**
```python
# Mark as read
client.modify_labels(msg_id, remove_labels=['UNREAD'])
# Star email
client.modify_labels(msg_id, add_labels=['STARRED'])
# Archive (remove from inbox)
client.modify_labels(msg_id, remove_labels=['INBOX'])
# Move to trash
client.modify_labels(msg_id, add_labels=['TRASH'])
```
#### delete_email()
Delete a single email.
```python
success = client.delete_email(
message_id, # Required: message ID
permanent=False # Optional: True = permanent, False = trash
)
# Returns: bool
```
---
## CLI Commands
All commands use the `mail` entry point. For now, use:
```bash
python3 -m gmaillm.cli <command>
```
Or create an alias:
```bash
alias gmail='python3 -m gmaillm.cli'
```
### gmail verify
Check authentication and setup.
```bash
gmail verify
```
### gmail list
List emails from a folder.
```bash
gmail list # Default: INBOX, 10 results
gmail list --folder SENT # List from SENT folder
gmail list --max 20 # Get 20 results
gmail list --query "is:unread" # With search query
```
**Options:**
- `--folder FOLDER` - Folder/label to list from (default: INBOX)
- `--max N` - Maximum results (1-50, default: 10)
- `--query QUERY` - Gmail search query
### gmail read
Read a specific email.
```bash
gmail read <message_id> # Summary (default)
gmail read <message_id> --full # Full body
```
**Options:**
- `--full` - Show full email body (instead of summary)
### gmail thread
Show entire email conversation.
```bash
gmail thread <message_id>
```
### gmail search
Search emails.
```bash
gmail search "from:example@gmail.com"
gmail search "has:attachment" --max 20
gmail search "is:unread after:2024/10/01" --folder INBOX
```
**Options:**
- `--folder FOLDER` - Limit search to folder (default: INBOX)
- `--max N` - Maximum results (1-50, default: 10)
### gmail reply
Reply to an email.
```bash
gmail reply <message_id> --body "Thanks!"
gmail reply <message_id> --body "Sounds good" --reply-all
```
**Options:**
- `--body TEXT` - Required: reply body text
- `--reply-all` - Reply to all recipients (default: reply to sender only)
**Confirmation:** Always shows preview and asks "Send? (y/n/yolo)"
### gmail send
Send a new email.
```bash
gmail send \
--to user@example.com \
--subject "Subject" \
--body "Body text"
# With multiple recipients
gmail send \
--to user1@example.com user2@example.com \
--cc boss@example.com \
--subject "Report" \
--body "See attached" \
--attachments report.pdf data.xlsx
# Skip confirmation with YOLO mode
gmail send --to user@example.com --subject "Test" --body "Hi" --yolo
```
**Options:**
- `--to EMAIL [EMAIL...]` - Required: recipient email(s)
- `--subject TEXT` - Required: email subject
- `--body TEXT` - Required: email body
- `--cc EMAIL [EMAIL...]` - Optional: CC recipient(s)
- `--attachments FILE [FILE...]` - Optional: file path(s) to attach
- `--yolo` - Skip confirmation, send immediately
### gmail folders
List all available folders/labels.
```bash
gmail folders
```
---
## Models & Types
### EmailSummary
Brief email overview (minimal context).
**Fields:**
- `message_id: str` - Unique message ID
- `thread_id: str` - Thread/conversation ID
- `from_: EmailAddress` - Sender
- `to: List[EmailAddress]` - Recipients
- `subject: str` - Email subject
- `date: datetime` - Sent date/time
- `snippet: str` - Short preview (~100 chars)
- `labels: List[str]` - Gmail labels
- `has_attachments: bool` - Has files attached
- `is_unread: bool` - Unread status
**Methods:**
- `to_markdown() -> str` - Formatted output
### EmailFull
Complete email with body (use sparingly).
**Fields:** (All EmailSummary fields plus:)
- `body_plain: str` - Plain text body
- `body_html: str` - HTML body (if exists)
- `attachments: List[Attachment]` - Attached files
- `headers: Dict[str, str]` - All email headers
### EmailAddress
Email address with optional name.
**Fields:**
- `email: str` - Email address
- `name: Optional[str]` - Display name
### SearchResult
Paginated search results.
**Fields:**
- `emails: List[EmailSummary]` - Email summaries
- `total_count: int` - Total matching emails
- `query: str` - Search query used
- `next_page_token: Optional[str]` - Token for next page
**Methods:**
- `to_markdown() -> str` - Formatted output
### Folder
Gmail label/folder info.
**Fields:**
- `id: str` - Label ID
- `name: str` - Label name
- `type: str` - 'system' or 'user'
- `message_count: Optional[int]` - Total messages
- `unread_count: Optional[int]` - Unread messages
### SendEmailRequest
Email sending parameters.
**Fields:**
- `to: List[str]` - Required: recipient emails
- `subject: str` - Required: subject line
- `body: str` - Required: email body
- `cc: Optional[List[str]]` - CC recipients
- `attachments: Optional[List[str]]` - File paths
### SendEmailResponse
Email send result.
**Fields:**
- `success: bool` - Send succeeded
- `message_id: str` - Sent message ID
- `thread_id: str` - Thread ID
- `error: Optional[str]` - Error message if failed
---
## Gmail Search Syntax
### Basic Operators
**From/To:**
```
from:user@example.com # Emails from user
to:user@example.com # Emails to user
cc:user@example.com # CC'd to user
bcc:user@example.com # BCC'd to user
```
**Subject:**
```
subject:invoice # Subject contains "invoice"
subject:(invoice payment) # Subject contains both words
```
**Dates:**
```
after:2024/10/01 # After date
before:2024/10/31 # Before date
older_than:7d # Older than 7 days
newer_than:2d # Newer than 2 days
```
**Status:**
```
is:unread # Unread emails
is:read # Read emails
is:starred # Starred emails
is:important # Marked important
```
**Content:**
```
has:attachment # Has attachments
has:drive # Has Google Drive attachment
has:document # Has document attachment
has:spreadsheet # Has spreadsheet
has:presentation # Has presentation
```
**Size:**
```
size:1000000 # Larger than 1MB
larger:10M # Larger than 10MB
smaller:5M # Smaller than 5MB
```
**Labels:**
```
label:inbox # In INBOX
label:sent # In SENT
-label:inbox # NOT in inbox (archived)
```
### Boolean Operators
```
AND # Both conditions (implicit, can be omitted)
OR # Either condition
- # NOT (exclude)
() # Grouping
```
**Examples:**
```
from:professor@edu AND has:attachment
from:alice OR from:bob
subject:report -from:manager
(from:alice OR from:bob) has:attachment
```
### Advanced Examples
**Unread emails from specific person with attachments:**
```
from:john@example.com is:unread has:attachment
```
**Recent emails about project:**
```
subject:project after:2024/10/01 -label:trash
```
**Important emails not yet read:**
```
is:important is:unread -from:noreply
```
**Large emails with PDFs:**
```
has:attachment filename:pdf larger:5M
```
**Emails in thread:**
```
in:thread_id
```
---
## Quick Reference Card
### Python Library Cheat Sheet
```python
from gmaillm import GmailClient, SendEmailRequest
client = GmailClient()
# List
result = client.list_emails(folder='INBOX', max_results=10)
# Read
email = client.read_email(msg_id, format="summary")
email = client.read_email(msg_id, format="full")
# Search
result = client.search_emails("from:user@example.com has:attachment")
# Thread
thread = client.get_thread(msg_id)
# Send
request = SendEmailRequest(to=["user@example.com"], subject="Hi", body="Hello")
response = client.send_email(request)
# Reply
response = client.reply_email(msg_id, body="Thanks!", reply_all=False)
# Labels
client.modify_labels(msg_id, add_labels=['STARRED'], remove_labels=['UNREAD'])
```
### CLI Cheat Sheet
```bash
gmail verify # Check setup
gmail list --folder INBOX --max 10 # List emails
gmail read <id> --full # Read email
gmail thread <id> # View conversation
gmail search "is:unread" --max 20 # Search
gmail reply <id> --body "Thanks!" # Reply
gmail send --to user@example.com \ # Send
--subject "Test" --body "Hi"
gmail folders # List folders
```
---
## Authentication
Uses existing Gmail MCP OAuth2 credentials:
- **Credentials:** `/Users/wz/.gmail-mcp/credentials.json`
- **OAuth Keys:** `/Users/wz/Desktop/OAuth2/gcp-oauth.keys.json`
Tokens auto-refresh. If authentication fails:
1. Check credential files exist
2. Verify OAuth tokens not expired
3. Run `gmail verify` to diagnose
---
## Common Patterns
### Progressive Disclosure
```python
# Always start with summary
summaries = client.list_emails(max_results=10)
# Only get full content when needed
for summary in summaries.emails:
if "important keyword" in summary.subject.lower():
full = client.read_email(summary.message_id, format="full")
# Process full email
```
### Pagination
```python
all_emails = []
page_token = None
while True:
result = client.list_emails(max_results=50, page_token=page_token)
all_emails.extend(result.emails)
if not result.next_page_token:
break
page_token = result.next_page_token
```
### Error Handling
```python
try:
response = client.send_email(request)
if response.success:
print(f"Sent: {response.message_id}")
else:
print(f"Failed: {response.error}")
except RuntimeError as e:
print(f"Error: {e}")
```
---
## Style Guide System
Located at `references/email-styles/`:
- **STYLE.md** - Precise writing guidelines
- **CLEAR.md** - Brevity guidelines
- **learned/patterns.md** - User-specific patterns (grows over time)
When drafting emails, Claude:
1. Searches sent emails to recipient
2. Extracts patterns (greeting, tone, sign-off)
3. Applies STYLE + CLEAR + learned patterns
4. Shows preview for confirmation
---
## Additional Resources
- **SKILL.md** - Complete usage guide with workflows
- **README.md** - Quick start and installation
- **references/usage_examples.md** - 16 detailed examples
- **references/gmail_search_syntax.md** - Complete search reference

404
skills/gmail-assistant/references/email-styles.md Normal file
View File

@@ -0,0 +1,404 @@
# Email Styles Guide
Complete guide for creating and managing email styles in gmaillm.
## Overview
Email styles define different writing patterns for various contexts. Each style includes:
- **Metadata** - Name and usage guidance
- **Examples** - Real email templates
- **Guidelines** - Structured writing rules
- **Best practices** - Do's and don'ts
## Quick Start
### List Available Styles
```bash
gmail styles list
```
Shows all styles with "when to use" descriptions.
### View a Style
```bash
gmail styles show professional-formal
```
Displays the complete style template.
### Create a New Style
```bash
gmail styles create my-style
```
Creates from template and opens in your editor.
### Edit Existing Style
```bash
gmail styles edit casual-friend
```
### Validate Styles
```bash
# Validate single style
gmail styles validate my-style
# Auto-fix formatting issues
gmail styles validate my-style --fix
# Validate all styles
gmail styles validate-all --fix
```
## Style File Format
### Complete Structure
Each style file MUST follow this exact structure:
```markdown
---
name: "Style Name"
description: "When to use: Context description (30-200 chars)."
---
<examples>
Example email 1
---
Example email 2
</examples>
<greeting>
- Greeting option 1
- Greeting option 2
</greeting>
<body>
- Body guideline 1
- Body guideline 2
</body>
<closing>
- Closing option 1
- Closing option 2
</closing>
<do>
- Best practice 1
- Best practice 2
</do>
<dont>
- Avoid this 1
- Avoid this 2
</dont>
```
### Required Components
#### 1. YAML Frontmatter
**Required fields:**
- `name` - Style display name (3-50 characters)
- `description` - Usage context (30-200 characters, must start with "When to use:")
**Rules:**
- No extra fields allowed
- Must be at top of file
- Enclosed in `---` markers
**Example:**
```yaml
---
name: "Professional Formal"
description: "When to use: Executives, senior leadership, clients, legal/HR contacts, or first-time professional outreach."
---
```
#### 2. XML Sections
**Required sections (in strict order):**
1. `<examples>` - Example emails showing style in action
2. `<greeting>` - Greeting patterns and guidelines
3. `<body>` - Body content guidelines
4. `<closing>` - Closing patterns
5. `<do>` - Best practices
6. `<dont>` - Things to avoid
**Rules:**
- Must appear in exactly this order
- Each section must have opening and closing tags
- Sections must contain actual content
- Use bullet lists (`- ` followed by space) for guidelines
## Section Details
### Examples Section
**Purpose**: Show complete email examples demonstrating the style.
**Format**:
```markdown
<examples>
Subject: Meeting Follow-up
Hi [Name],
Thanks for meeting today. I'll send the proposal by Friday.
Best,
[Your Name]
---
Subject: Quick Question
Hi [Name],
Do you have 5 minutes to discuss the project timeline?
Thanks,
[Your Name]
</examples>
```
**Requirements:**
- 1-3 complete email examples
- Separate multiple examples with `---`
- Include realistic greetings, body, and closings
### Greeting Section
**Purpose**: Define greeting patterns.
**Format**:
```markdown
<greeting>
- "Dear [Title] [Last Name],"
- Use full name and title for first contact
- Avoid first names unless invited
</greeting>
```
### Body Section
**Purpose**: Define body content guidelines.
**Format**:
```markdown
<body>
- Write concise sentences
- One main point per paragraph
- Use bullet points for lists
- Professional tone throughout
</body>
```
### Closing Section
**Purpose**: Define closing patterns.
**Format**:
```markdown
<closing>
- "Best regards,"
- "Sincerely,"
- Sign with full name and title
</closing>
```
### Do Section
**Purpose**: Best practices to follow.
**Format**:
```markdown
<do>
- Proofread before sending
- Keep paragraphs short
- Use active voice
- Include clear call to action
</do>
```
**Requirements:**
- Minimum 2 items
- Actionable advice
- Clear and specific
### Dont Section
**Purpose**: Things to avoid.
**Format**:
```markdown
<dont>
- Use slang or casual language
- Write overly long paragraphs
- Forget to proofread
- Use all caps for emphasis
</dont>
```
**Requirements:**
- Minimum 2 items
- Clear antipatterns
- Specific examples
## Validation Rules
The `StyleLinter` enforces these rules:
### YAML Frontmatter
- ✓ Required fields: `name`, `description`
- ✓ Name length: 3-50 characters
- ✓ Description: 30-200 characters
- ✓ Description must start with "When to use:"
- ✓ No extra fields
### XML Sections
- ✓ All 6 sections present
- ✓ Correct order: examples → greeting → body → closing → do → dont
- ✓ Proper opening/closing tags
- ✓ Non-empty content
### Formatting
- ✓ No trailing whitespace
- ✓ List items: `- ` (dash + space)
- ✓ Minimum items: examples (1), do (2), dont (2)
### Auto-Fix Capabilities
The `--fix` flag can automatically correct:
- Trailing whitespace
- List item spacing (`-item` → `- item`)
- Extra blank lines
**Cannot auto-fix:**
- Missing sections
- Wrong section order
- Invalid frontmatter
- Empty sections
## Creating a New Style
### Step 1: Create Template
```bash
gmail styles create my-custom-style
```
This creates `~/.gmaillm/email-styles/my-custom-style.md` with template structure.
### Step 2: Edit in Your Editor
The command automatically opens the file in your default editor (determined by `$EDITOR` environment variable).
### Step 3: Fill In Content
Replace template placeholders with your content:
1. **Update frontmatter** - Set name and description
2. **Add examples** - Write 1-3 complete email examples
3. **Define greeting patterns** - Specify greeting guidelines
4. **Define body guidelines** - Specify writing rules
5. **Define closing patterns** - Specify closing guidelines
6. **List do's** - Best practices (minimum 2)
7. **List dont's** - Things to avoid (minimum 2)
### Step 4: Validate
```bash
gmail styles validate my-custom-style
```
Fix any errors shown.
### Step 5: Use
```bash
gmail styles show my-custom-style
```
## Common Validation Errors
### "Description must start with 'When to use:'"
**Problem**: Description doesn't have required prefix.
**Fix**:
```yaml
# Wrong
description: "For casual emails to friends"
# Correct
description: "When to use: Casual emails to friends and close colleagues."
```
### "Sections must appear in strict order"
**Problem**: Sections are out of order.
**Fix**: Reorder sections to match: examples → greeting → body → closing → do → dont
### "Missing required section"
**Problem**: One or more sections are missing.
**Fix**: Add all 6 required sections with proper tags.
### "List items must start with '- '"
**Problem**: List items have incorrect formatting.
**Fix**:
```markdown
# Wrong
<do>
-Item 1
* Item 2
</do>
# Correct
<do>
- Item 1
- Item 2
</do>
```
## Tips for Good Styles
1. **Be specific** - "Use first name only" not "Be casual"
2. **Show examples** - Real email examples are most helpful
3. **Keep it concise** - Shorter guidelines are easier to follow
4. **Test it** - Use the style for real emails and refine
5. **Version control** - Styles are just text files, commit them to git
## File Location
All styles are stored in:
```
~/.gmaillm/email-styles/
├── professional-formal.md
├── professional-friendly.md
├── academic.md
├── casual-friend.md
├── brief-update.md
└── my-custom-style.md
```
## Built-in Styles
gmaillm includes 5 professional styles:
1. **professional-formal** - Executives, legal, formal outreach
2. **professional-friendly** - Colleagues, known contacts
3. **academic** - Faculty, academic collaborators
4. **casual-friend** - Friends, informal communication
5. **brief-update** - Quick status updates
View any style: `gmail styles show <name>`

623
skills/gmail-assistant/references/gmail-search-syntax.md Normal file
View File

@@ -0,0 +1,623 @@
# Gmail Search Syntax Reference
Complete reference for Gmail search operators. Use these with the `gmail search` command.
## Quick Start
```bash
# Basic search
gmail search "from:user@example.com"
# Combined search
gmail search "from:user@example.com has:attachment after:2024/10/01"
# Complex search
gmail search "(from:alice OR from:bob) subject:report -is:read"
```
---
## Basic Operators
### From/To/CC/BCC
```
from:sender@example.com # Emails from sender
to:recipient@example.com # Emails to recipient
cc:person@example.com # CC'd to person
bcc:person@example.com # BCC'd to person (only sent emails)
```
**Examples:**
```bash
# All emails from professor
gmail search "from:professor@university.edu" --max 20
# All emails to colleague
gmail search "to:colleague@company.com" --max 10
# Emails CC'd to manager
gmail search "cc:manager@company.com" --max 5
```
### Subject
```
subject:keyword # Subject contains keyword
subject:"exact phrase" # Subject contains exact phrase
subject:(word1 word2) # Subject contains both words
```
**Examples:**
```bash
# Emails about meetings
gmail search "subject:meeting" --max 10
# Exact subject phrase
gmail search 'subject:"Weekly Report"' --max 5
# Subject with multiple keywords
gmail search "subject:(project deadline)" --max 10
```
### Body Content
```
keyword # Body or subject contains keyword
"exact phrase" # Body or subject has exact phrase
```
**Examples:**
```bash
# Emails mentioning budget
gmail search "budget" --max 10
# Exact phrase in email
gmail search '"quarterly results"' --max 5
```
---
## Date Operators
### Absolute Dates
```
after:YYYY/MM/DD # After specific date
before:YYYY/MM/DD # Before specific date
```
**Examples:**
```bash
# Emails after October 1, 2024
gmail search "after:2024/10/01" --max 20
# Emails before September 30, 2024
gmail search "before:2024/09/30" --max 10
# Emails in date range
gmail search "after:2024/10/01 before:2024/10/31" --max 20
```
### Relative Dates
```
newer_than:Nd # Newer than N days
older_than:Nd # Older than N days
newer_than:Nm # Newer than N months
older_than:Nm # Older than N months
newer_than:Ny # Newer than N years
older_than:Ny # Older than N years
```
**Examples:**
```bash
# Last 7 days
gmail search "newer_than:7d" --max 20
# Older than 30 days
gmail search "older_than:30d" --max 10
# Last 2 months
gmail search "newer_than:2m" --max 20
# Last year
gmail search "newer_than:1y" --max 50
```
---
## Status Operators
### Read/Unread
```
is:read # Read emails
is:unread # Unread emails
```
**Examples:**
```bash
# All unread emails
gmail search "is:unread" --max 20
# Unread emails from specific person
gmail search "from:boss@company.com is:unread" --max 10
```
### Starred/Important
```
is:starred # Starred emails
is:important # Marked important
-is:important # NOT important
```
**Examples:**
```bash
# Starred emails
gmail search "is:starred" --max 20
# Important emails from last week
gmail search "is:important newer_than:7d" --max 10
```
---
## Attachment Operators
### Has Attachment
```
has:attachment # Has any attachment
has:drive # Has Google Drive attachment
has:document # Has document
has:spreadsheet # Has spreadsheet
has:presentation # Has presentation
has:youtube # Has YouTube link
```
**Examples:**
```bash
# All emails with attachments
gmail search "has:attachment" --max 20
# Emails with PDFs
gmail search "filename:pdf" --max 10
# Emails with Google Drive files
gmail search "has:drive" --max 10
```
### Filename
```
filename:name # Attachment filename contains name
filename:pdf # Attachment is PDF
filename:xlsx # Attachment is Excel file
```
**Examples:**
```bash
# Emails with PDF attachments
gmail search "filename:pdf" --max 10
# Specific filename
gmail search 'filename:"report.pdf"' --max 5
# Invoices
gmail search "filename:invoice" --max 20
```
---
## Size Operators
```
size:N # Larger than N bytes
larger:N # Larger than N (use M/K for MB/KB)
smaller:N # Smaller than N
```
**Examples:**
```bash
# Larger than 1MB
gmail search "larger:1M" --max 10
# Larger than 10MB
gmail search "larger:10M" --max 5
# Smaller than 500KB
gmail search "smaller:500K" --max 10
# Large emails with attachments
gmail search "has:attachment larger:5M" --max 10
```
---
## Label Operators
```
label:name # Has specific label
-label:name # Does NOT have label
```
**System labels:**
- `INBOX` - In inbox
- `SENT` - Sent emails
- `DRAFT` - Drafts
- `TRASH` - Trash
- `SPAM` - Spam
- `STARRED` - Starred
- `IMPORTANT` - Important
- `UNREAD` - Unread
- `CATEGORY_PERSONAL` - Personal category
- `CATEGORY_SOCIAL` - Social category
- `CATEGORY_PROMOTIONS` - Promotions category
- `CATEGORY_UPDATES` - Updates category
- `CATEGORY_FORUMS` - Forums category
**Examples:**
```bash
# Emails in inbox
gmail search "label:inbox" --max 20
# Archived emails (not in inbox)
gmail search "-label:inbox" --max 20
# Sent emails
gmail search "label:sent" --max 10
# Custom label
gmail search "label:work" --max 20
```
---
## Boolean Operators
### AND (implicit)
```
keyword1 keyword2 # Both keywords (space = AND)
keyword1 AND keyword2 # Explicit AND
```
**Examples:**
```bash
# Both keywords
gmail search "project deadline" --max 10
# Explicit AND
gmail search "project AND deadline" --max 10
```
### OR
```
keyword1 OR keyword2 # Either keyword
```
**Examples:**
```bash
# Emails from either person
gmail search "from:alice@example.com OR from:bob@example.com" --max 10
# Multiple subjects
gmail search "subject:meeting OR subject:schedule" --max 10
```
### NOT (-)
```
-keyword # Does NOT contain keyword
-operator:value # Does NOT match operator
```
**Examples:**
```bash
# Exclude sender
gmail search "subject:report -from:manager@company.com" --max 10
# Not in inbox (archived)
gmail search "-label:inbox" --max 20
# Not read
gmail search "-is:read" --max 10
```
### Grouping ( )
```
(condition1 OR condition2) # Group conditions
```
**Examples:**
```bash
# Emails from alice OR bob with attachments
gmail search "(from:alice OR from:bob) has:attachment" --max 10
# Multiple subjects with specific date range
gmail search "(subject:meeting OR subject:schedule) after:2024/10/01" --max 20
```
---
## Thread Operators
```
in:thread_id # Emails in specific thread
```
**Example:**
```bash
# Get all emails in a thread (use thread_id from email details)
gmail search "in:19abc123def456" --max 20
```
---
## Wildcard Operator
```
* # Wildcard (limited use in Gmail)
```
**Note:** Gmail's wildcard support is limited. It works best with:
- Email addresses: `from:*@example.com`
- Not recommended for general text searches
---
## Common Search Patterns
### Workflow-Specific Searches
#### Before Composing to Someone
Find all correspondence (sent + received):
```bash
gmail search "to:person@example.com OR from:person@example.com" --max 10
```
#### Finding Unread Important Emails
```bash
gmail search "is:unread is:important" --max 20
```
#### Recent Emails About a Topic
```bash
gmail search "subject:project-name newer_than:30d" --max 10
```
#### Emails from Team with Attachments
```bash
gmail search "(from:alice@team.com OR from:bob@team.com) has:attachment" --max 10
```
#### Large Emails to Clean Up
```bash
gmail search "larger:10M older_than:1y" --max 20
```
#### Unanswered Emails
```bash
gmail search "is:unread from:important@person.com newer_than:7d" --max 10
```
---
## Advanced Search Patterns
### Finding Email Threads
Search for initial email and use thread view:
```bash
# Find thread starter
gmail search "subject:keyword from:person@example.com" --max 5
# Then use thread command
gmail thread <message_id>
```
### Combining Multiple Criteria
```bash
# Complex search: unread emails from professor with attachments in last 30 days
gmail search "from:professor@edu.edu is:unread has:attachment newer_than:30d" --max 10
# Emails from multiple people about specific topic
gmail search "(from:alice OR from:bob) subject:budget newer_than:7d" --max 10
```
### Excluding Common Patterns
```bash
# Important emails excluding automated notifications
gmail search "is:important -from:noreply -from:no-reply" --max 20
# Emails with attachments excluding newsletters
gmail search "has:attachment -label:promotions" --max 20
```
---
## Search Best Practices
### 1. Start Broad, Then Refine
```bash
# Start broad
gmail search "project" --max 20
# Refine
gmail search "project from:alice@example.com" --max 10
# Further refine
gmail search "project from:alice@example.com after:2024/10/01" --max 5
```
### 2. Use Date Ranges for Context
```bash
# Recent context (last 7 days)
gmail search "to:person@example.com newer_than:7d" --max 5
# Historical context (last 6 months)
gmail search "to:person@example.com newer_than:6m" --max 20
```
### 3. Combine Sender and Recipient
```bash
# All correspondence with someone
gmail search "to:person@example.com OR from:person@example.com" --max 10
```
### 4. Use Labels for Organization
```bash
# Search within labeled emails
gmail search "label:work subject:report" --max 10
# Exclude certain labels
gmail search "has:attachment -label:spam -label:trash" --max 20
```
---
## CLI-Specific Options
### Max Results
```bash
# Limit results (1-50)
gmail search "query" --max 10
gmail search "query" --max 20
gmail search "query" --max 50
```
### Folder Filtering
```bash
# Search within specific folder
gmail search "is:unread" --folder INBOX --max 10
gmail search "keyword" --folder SENT --max 20
```
---
## Common Mistakes
### 1. Not Quoting Phrases
**Wrong:**
```bash
gmail search "subject:meeting notes" # Searches for subject:meeting AND notes anywhere
```
**Right:**
```bash
gmail search 'subject:"meeting notes"' # Searches for exact phrase in subject
```
### 2. Forgetting OR is Uppercase
**Wrong:**
```bash
gmail search "from:alice or from:bob" # "or" treated as keyword
```
**Right:**
```bash
gmail search "from:alice OR from:bob" # OR is operator
```
### 3. Using Wildcards for General Text
**Wrong:**
```bash
gmail search "meet*" # Limited wildcard support
```
**Right:**
```bash
gmail search "meeting" # Use complete words
```
### 4. Not Using Parentheses for Complex Queries
**Wrong:**
```bash
gmail search "from:alice OR from:bob has:attachment" # Ambiguous
```
**Right:**
```bash
gmail search "(from:alice OR from:bob) has:attachment" # Clear grouping
```
---
## Quick Reference Table
| Operator | Description | Example |
|----------|-------------|---------|
| `from:` | From sender | `from:user@example.com` |
| `to:` | To recipient | `to:user@example.com` |
| `subject:` | Subject contains | `subject:meeting` |
| `after:` | After date | `after:2024/10/01` |
| `before:` | Before date | `before:2024/10/31` |
| `newer_than:` | Newer than N days/months/years | `newer_than:7d` |
| `older_than:` | Older than N days/months/years | `older_than:30d` |
| `is:unread` | Unread emails | `is:unread` |
| `is:starred` | Starred emails | `is:starred` |
| `has:attachment` | Has attachment | `has:attachment` |
| `filename:` | Attachment filename | `filename:pdf` |
| `larger:` | Larger than size | `larger:10M` |
| `smaller:` | Smaller than size | `smaller:500K` |
| `label:` | Has label | `label:inbox` |
| `-` | NOT operator | `-from:noreply` |
| `OR` | OR operator | `from:alice OR from:bob` |
| `( )` | Grouping | `(from:a OR from:b) subject:x` |
---
## Testing Searches
Always test searches with small result sets first:
```bash
# Test with --max 5 first
gmail search "complex query here" --max 5
# If results look good, increase
gmail search "complex query here" --max 20
```
---
## Pagination
For large result sets, use pagination:
```bash
# Get first page
gmail search "query" --max 50
# Use next_page_token from results for subsequent pages
# (Python API supports this; CLI shows truncated results)
```
---
## Additional Resources
- Gmail search operators: https://support.google.com/mail/answer/7190
- gmaillm API reference: `references/api-reference.md`

383
skills/gmail-assistant/references/quick-reference.md Normal file
View File

@@ -0,0 +1,383 @@
# Gmail Assistant Quick Reference
This file provides quick examples for common gmaillm operations. Load this when you need concrete syntax examples.
## Email Sending Examples
### Basic Send
```bash
gmail send \
--to "recipient@example.com" \
--subject "Subject line" \
--body "Email body content"
```
### Send with CC and BCC
```bash
gmail send \
--to "person1@example.com,person2@example.com" \
--cc "cc@example.com" \
--bcc "bcc@example.com" \
--subject "Subject" \
--body "Body"
```
### Send to Group
```bash
gmail send \
--to "#group-name" \
--subject "Broadcast message" \
--body "Message to entire group"
```
### Send with Attachments
```bash
gmail send \
--to "recipient@example.com" \
--subject "Files attached" \
--body "See attachments" \
--attachments "file1.pdf,file2.jpg"
```
## Search Examples
### Search by Subject
```bash
gmail search "subject:keyword" --max 10
```
### Search by Sender
```bash
gmail search "from:person@example.com" --max 5
```
### Search by Date Range
```bash
gmail search "after:2025/01/01 before:2025/12/31"
```
### Complex Search
```bash
gmail search "from:person subject:project has:attachment" --max 5
```
### Search Unread
```bash
gmail search "is:unread" --max 20
```
## Reading Emails
### Read Summary
```bash
gmail read <message_id>
```
### Read Full Content
```bash
gmail read <message_id> --full
```
### Read Entire Thread
```bash
gmail thread <message_id>
```
### JSON Output for Parsing
```bash
gmail read <message_id> --output-format json
```
## Group Management
### List Groups
```bash
gmail groups list
```
### Show Group Details
```bash
gmail groups show "#group-name"
```
### Create Group
```bash
gmail groups create \
--name "#new-group" \
--emails "person1@example.com,person2@example.com,person3@example.com"
```
### Add Member to Group
```bash
gmail groups add "#group-name" "newperson@example.com"
```
### Remove Member
```bash
gmail groups remove "#group-name" "person@example.com"
```
### Validate Group
```bash
gmail groups validate "#group-name"
```
## Style Management
### List All Styles
```bash
gmail styles list
```
### Show Style Content
```bash
gmail styles show <style-name>
```
### Create New Style
```bash
gmail styles create --name "my-style"
# Opens editor for you to define the style
```
### Edit Existing Style
```bash
gmail styles edit <style-name>
```
### Validate Style Format
```bash
gmail styles validate <style-name>
```
### Validate All Styles
```bash
gmail styles validate-all
```
## Workflow Management
### List Workflows
```bash
gmail workflows list
```
### Show Workflow Details
```bash
gmail workflows show <workflow-id>
```
### Create Workflow
```bash
gmail workflows create \
--id "daily-review" \
--name "Daily Email Review" \
--query "is:unread -label:spam" \
--auto-mark-read
```
### Run Workflow
```bash
gmail workflows run <workflow-id>
```
### Run Ad-hoc Query
```bash
gmail workflows run --query "is:unread from:important@person.com"
```
## Gmail Query Syntax
Common Gmail search operators:
| Operator | Example | Description |
|----------|---------|-------------|
| `from:` | `from:alice@example.com` | Emails from sender |
| `to:` | `to:bob@example.com` | Emails to recipient |
| `subject:` | `subject:meeting` | Subject contains word |
| `is:unread` | `is:unread` | Unread emails |
| `is:read` | `is:read` | Read emails |
| `has:attachment` | `has:attachment` | Has attachments |
| `label:` | `label:important` | Has label |
| `after:` | `after:2025/01/01` | After date (YYYY/MM/DD) |
| `before:` | `before:2025/12/31` | Before date |
| `newer_than:` | `newer_than:7d` | Last N days (d/m/y) |
| `older_than:` | `older_than:1m` | Older than N time |
| `OR` | `from:alice OR from:bob` | Either condition |
| `-` | `-label:spam` | Exclude (NOT) |
**Combine operators:**
```bash
gmail search "from:boss subject:urgent is:unread"
```
## Email Style Format
Email styles use YAML frontmatter + XML-like sections:
```markdown
---
name: "style-name"
description: "When to use: Context description (30-200 chars)."
---
<examples>
Example 1
---
Example 2
</examples>
<greeting>
- "Hi [Name],"
</greeting>
<body>
- Guideline 1
- Guideline 2
</body>
<closing>
- "Best,"
</closing>
<do>
- Best practice 1
</do>
<dont>
- What to avoid
</dont>
```
Required sections in strict order: examples → greeting → body → closing → do → dont
## Common Email Workflows
### 1. Research + Draft + Send
```bash
# Search for similar emails
gmail search "subject:similar topic" --max 3
# Read one for context
gmail read <message_id> --full
# Check style
gmail styles show professional-formal
# TEST first
gmail send --to fuchengwarrenzhu@gmail.com --subject "[TEST] ..." --body "..."
# Send for real
gmail send --to real@email.com --subject "..." --body "..." --yolo
```
### 2. Bulk Processing with Workflow
```bash
# Create workflow for common query
gmail workflows create \
--id "newsletter-cleanup" \
--name "Clean Up Newsletters" \
--query "label:newsletters is:read older_than:30d"
# Run workflow
gmail workflows run newsletter-cleanup
```
### 3. Group Broadcast
```bash
# Verify group
gmail groups show "#team"
# Check style
gmail styles show posts
# TEST
gmail send --to fuchengwarrenzhu@gmail.com --subject "[TEST] Update" --body "..."
# Broadcast
gmail send --to "#team" --subject "Update" --body "..." --yolo
```
## Status and Configuration
### Check Account Status
```bash
gmail status
```
### Verify Authentication
```bash
gmail verify
```
### Show Configuration
```bash
gmail config show
```
### List Labels
```bash
gmail labels list
```
## JSON Output for Automation
All commands support `--output-format json` for programmatic parsing:
```bash
# Get JSON for parsing
gmail search "is:unread" --output-format json | jq '.emails[] | {from: .from_.email, subject: .subject}'
# List groups in JSON
gmail groups list --output-format json
# Read email as JSON
gmail read <message_id> --output-format json
```
## Common Gotchas
1. **Email IDs**: Displayed short (12 chars) but use full ID in commands
2. **Group prefix**: Always use `#` prefix (e.g., `#team` not `team`)
3. **YOLO flag**: Skips confirmation, use after testing
4. **Date format**: Use YYYY/MM/DD for Gmail queries
5. **Test emails**: ALWAYS test to fuchengwarrenzhu@gmail.com first
6. **Style order**: Sections must be in exact order (examples, greeting, body, closing, do, dont)
7. **Attachment paths**: Use absolute or relative file paths, comma-separated