google-gmail-integration

Files (5)

• CHANGELOG.md
• LICENSE
• README.md
• SKILL.md
• authenticate.py · scripts/

SKILL.md (first lines)

# 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 "boss@company.com"

# 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:boss@company.com 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:alice@company.com OR from:bob@company.com) 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

From astoreyai/claude-skills, MIT.

More from astoreyai/claude-skills