google-gmail-integration

What this skill does

# Gmail Integration

Comprehensive Gmail integration enabling email search, message management, sending, label organization, attachment handling, and workflow automation through the Gmail API v1.

## Quick Start

When asked to work with Gmail:

1. **Authenticate**: Set up OAuth2 credentials (one-time setup)
2. **Search emails**: Find messages by sender, subject, date, or content
3. **Read messages**: Get email content and attachments
4. **Send emails**: Compose and send messages
5. **Organize**: Create labels, apply filters, archive messages
6. **Automate**: Process emails based on rules

## Prerequisites

### One-Time Setup

**1. Enable Gmail API:**
```bash
# Visit Google Cloud Console
# https://console.cloud.google.com/

# Enable Gmail API for your project
# APIs & Services > Enable APIs and Services > Gmail API
```

**2. Create OAuth2 Credentials:**
```bash
# In Google Cloud Console:
# APIs & Services > Credentials > Create Credentials > OAuth client ID
# Application type: Desktop app
# Download credentials as credentials.json
```

**3. Install Dependencies:**
```bash
pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client --break-system-packages
```

**4. Initial Authentication:**
```bash
python scripts/authenticate.py
# Opens browser for Google sign-in
# Saves token.json for future use
```

See [reference/setup-guide.md](reference/setup-guide.md) for detailed setup instructions.

## Core Operations

### Search Emails

**Basic search:**
```bash
# Search by keyword
python scripts/search_emails.py --query "project update"

# Search by sender
python scripts/search_emails.py --from "[email protected]"

# Search by subject
python scripts/search_emails.py --subject "Weekly Report"

# Search unread
python scripts/search_emails.py --unread

# Search with label
python scripts/search_emails.py --label "Important"
```

**Advanced search queries:**
```python
# Combination search
query = "from:[email protected] subject:urgent is:unread"

# Date ranges
query = "after:2025/01/01 before:2025/01/31"

# Has attachment
query = "has:attachment filename:pdf"

# Size filters
query = "larger:10M"

# Categories
query = "category:primary"
query = "category:social"
query = "category:promotions"

# Boolean operators
query = "(from:[email protected] OR from:[email protected]) subject:meeting"
```

See [reference/search-syntax.md](reference/search-syntax.md) for complete search reference.

### Read Messages

**Get message content:**
```bash
# Read email
python scripts/read_email.py --message-id MESSAGE_ID

# Get specific format
python scripts/read_email.py --message-id MESSAGE_ID --format full
python scripts/read_email.py --message-id MESSAGE_ID --format minimal
python scripts/read_email.py --message-id MESSAGE_ID --format raw
```

**Extract information:**
```bash
# Get headers
python scripts/get_headers.py --message-id MESSAGE_ID

# Get body text
python scripts/get_body.py --message-id MESSAGE_ID --format text
python scripts/get_body.py --message-id MESSAGE_ID --format html

# List attachments
python scripts/list_attachments.py --message-id MESSAGE_ID
```

**Download attachments:**
```bash
# Download all attachments
python scripts/download_attachments.py --message-id MESSAGE_ID --output ./downloads/

# Download specific attachment
python scripts/download_attachments.py --message-id MESSAGE_ID --filename "report.pdf"
```

### Send Emails

**Simple send:**
```bash
# Send plain text
python scripts/send_email.py \
  --to "[email protected]" \
  --subject "Hello" \
  --body "Email content here"

# Send to multiple recipients
python scripts/send_email.py \
  --to "[email protected],[email protected]" \
  --cc "[email protected]" \
  --subject "Team Update" \
  --body "Content here"
```

**Send with attachments:**
```bash
python scripts/send_email.py \
  --to "[email protected]" \
  --subject "Report" \
  --body "Please see attached" \
  --attachments "./report.pdf,./data.xlsx"
```

**Send HTML email:**
```bash
python scripts/send_email.py \
  --to "[email protected]" \
  --subject "Newsletter" \
  --html-body "./newsletter.html"
```

**Reply to message:**
```bash
python scripts/reply_email.py \
  --message-id MESSAGE_ID \
  --body "Thanks for your email..."
```

**Forward message:**
```bash
python scripts/forward_email.py \
  --message-id MESSAGE_ID \
  --to "[email protected]" \
  --body "FYI"
```

### Label Management

**Create labels:**
```bash
# Create label
python scripts/create_label.py --name "Project Alpha"

# Create nested label
python scripts/create_label.py --name "Projects/Alpha"

# Create with settings
python scripts/create_label.py \
  --name "Important" \
  --label-list-visibility show \
  --message-list-visibility show
```

**Apply labels:**
```bash
# Add label to message
python scripts/add_label.py --message-id MESSAGE_ID --label "Important"

# Add multiple labels
python scripts/add_label.py --message-id MESSAGE_ID --labels "Work,Urgent"

# Remove label
python scripts/remove_label.py --message-id MESSAGE_ID --label "Inbox"
```

**List labels:**
```bash
# Get all labels
python scripts/list_labels.py

# Get label ID
python scripts/get_label_id.py --name "Project Alpha"
```

### Message Management

**Mark as read/unread:**
```bash
# Mark as read
python scripts/mark_read.py --message-id MESSAGE_ID

# Mark as unread
python scripts/mark_unread.py --message-id MESSAGE_ID
```

**Archive/Trash:**
```bash
# Archive message (remove from Inbox)
python scripts/archive_email.py --message-id MESSAGE_ID

# Move to trash
python scripts/trash_email.py --message-id MESSAGE_ID

# Delete permanently
python scripts/delete_email.py --message-id MESSAGE_ID
```

**Batch operations:**
```bash
# Archive all read emails older than 30 days
python scripts/batch_archive.py --days 30 --read-only

# Delete all emails from sender
python scripts/batch_delete.py --from "[email protected]"

# Mark all as read
python scripts/batch_mark_read.py --label "Inbox"
```

## Common Workflows

### Workflow 1: Process Unread Emails

**Scenario:** Read unread emails and categorize

```bash
# Get unread emails
python scripts/process_unread.py \
  --label-rules rules.json \
  --mark-read

# rules.json example:
{
  "rules": [
    {
      "condition": "from:[email protected]",
      "action": "add_label",
      "label": "Important"
    },
    {
      "condition": "subject:invoice",
      "action": "add_label",
      "label": "Finance"
    }
  ]
}
```

### Workflow 2: Email to Task Conversion

**Scenario:** Convert emails into task format

```bash
# Extract tasks from emails
python scripts/email_to_tasks.py \
  --query "label:To-Do" \
  --output tasks.json \
  --mark-done
```

### Workflow 3: Automated Responses

**Scenario:** Send auto-replies based on conditions

```bash
# Auto-respond to specific emails
python scripts/auto_respond.py \
  --query "from:[email protected] subject:urgent" \
  --template response_template.txt \
  --label "Auto-Responded"
```

### Workflow 4: Email Backup

**Scenario:** Download emails for backup

```bash
# Backup all emails
python scripts/backup_emails.py \
  --output ./email_backup/ \
  --format mbox

# Backup specific label
python scripts/backup_emails.py \
  --label "Important" \
  --output ./important_backup/ \
  --include-attachments
```

### Workflow 5: Email Analytics

**Scenario:** Analyze email patterns

```bash
# Generate email statistics
python scripts/email_stats.py \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --output stats.json

# Top senders
python scripts/top_senders.py --limit 10

# Email volume by day
python scripts/email_volume.py --days 30
```

## Search Query Syntax

### Operators

```python
# Sender/Recipient
"from:[email protected]"
"to:[email protected]"
"cc:[email protected]"
"bcc:[email protected]"

# Subject
"subject:meeting"
"subject:(status report)"

# Date
"after:2025/01/01"
"before:2025/12/31"
"older_than:2d"  # days
"newer_than:7d"

# Status
"is:unread"
"is:read"
"is:starred"
"is:imp