gmail

What this skill does

# Gmail

Interact with Gmail for email management, search, and organization.

## Installation

**Dependencies**: `pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml`

## Setup Verification

After installation, verify the skill is properly configured:

```bash
$SKILL_DIR/scripts/gmail.py check
```

This will check:
- Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
- Authentication configuration
- Connectivity to Gmail API

If anything is missing, the check command will provide setup instructions.

## Authentication

Gmail uses OAuth 2.0 for authentication. For complete setup instructions, see:

1. [GCP Project Setup Guide](https://github.com/odyssey4me/agent-skills/blob/main/docs/gcp-project-setup.md) - Create project, enable Gmail API
2. [Google OAuth Setup Guide](https://github.com/odyssey4me/agent-skills/blob/main/docs/google-oauth-setup.md) - Configure credentials

### Quick Start

1. Create `~/.config/agent-skills/google.yaml`:
   ```yaml
   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   ```

2. Run `$SKILL_DIR/scripts/gmail.py check` to trigger OAuth flow and verify setup.

On scope or authentication errors, see the [OAuth troubleshooting guide](https://github.com/odyssey4me/agent-skills/blob/main/docs/google-oauth-setup.md#troubleshooting).

## Commands

See [permissions.md](references/permissions.md) for read/write classification of each command.

### check

Verify configuration and connectivity.

```bash
$SKILL_DIR/scripts/gmail.py check
```

This validates:
- Python dependencies are installed
- Authentication is configured
- Can connect to Gmail API
- Displays your email address and mailbox statistics

### auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.

```bash
$SKILL_DIR/scripts/gmail.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET
```

Credentials are saved to `~/.config/agent-skills/gmail.yaml`.

### auth reset

Clear stored OAuth token. The next command that needs authentication will trigger re-authentication automatically.

```bash
$SKILL_DIR/scripts/gmail.py auth reset
```

Use this when you encounter scope or authentication errors.

### auth status

Show current OAuth token information without making API calls.

```bash
$SKILL_DIR/scripts/gmail.py auth status
```

Displays: whether a token is stored, granted scopes, refresh token presence, token expiry, and client ID.

### messages list

List messages matching a query.

```bash
# List recent messages
$SKILL_DIR/scripts/gmail.py messages list

# Search for unread messages
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"

# Search with max results
$SKILL_DIR/scripts/gmail.py messages list --query "from:[email protected]" --max-results 20
```

**Arguments:**
- `--query`: Gmail search query (optional)
- `--max-results`: Maximum number of results (default: 10)

**Search Query Examples:**

For complete Gmail search syntax, see [gmail-queries.md](references/gmail-queries.md).

Common queries:
- `is:unread` - Unread messages
- `from:[email protected]` - Messages from sender
- `subject:meeting` - Messages with subject keyword
- `has:attachment` - Messages with attachments
- `after:2024/01/01` - Messages after date
- `label:important` - Messages with label

### messages get

Get a message by ID.

```bash
# Get full message
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID

# Get minimal format
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID --format minimal
```

**Arguments:**
- `message_id`: The message ID (required)
- `--format`: Message format (full, minimal, raw, metadata) - default: full

### messages mark-read

Mark one or more messages as read by removing the UNREAD label.

```bash
# Mark a single message
$SKILL_DIR/scripts/gmail.py messages mark-read MESSAGE_ID

# Mark multiple messages
$SKILL_DIR/scripts/gmail.py messages mark-read MSG1 MSG2 MSG3

# Mark all unread messages from a sender
$SKILL_DIR/scripts/gmail.py messages mark-read --query "is:unread from:[email protected]"

# Combine IDs and query
$SKILL_DIR/scripts/gmail.py messages mark-read MSG1 --query "is:unread label:updates"
```

**Arguments:**
- `message_ids`: One or more message IDs (optional if `--query` is used)
- `--query`: Gmail search query to find messages to mark as read
- `--max-results`: Maximum messages to mark from `--query` (default: 100)

### threads get

Get a full conversation thread with all messages displayed chronologically. For messages from Google Groups, includes shareable permalinks using the `d/msgid` URL format.

```bash
# Get full thread
$SKILL_DIR/scripts/gmail.py threads get THREAD_ID
```

**Arguments:**
- `thread_id`: The thread ID (required)

### send

Send an email message.

```bash
# Send simple email
$SKILL_DIR/scripts/gmail.py send \
  --to [email protected] \
  --subject "Hello" \
  --body "This is the message body"

# Send with CC and BCC
$SKILL_DIR/scripts/gmail.py send \
  --to [email protected] \
  --subject "Team Update" \
  --body "Here's the update..." \
  --cc [email protected] \
  --bcc [email protected]
```

```bash
# Send from a markdown file with frontmatter
$SKILL_DIR/scripts/gmail.py send --from-file update.md

# Send from file with CLI overrides
$SKILL_DIR/scripts/gmail.py send --from-file update.md --to [email protected]

# Reply to a message in-thread
$SKILL_DIR/scripts/gmail.py send --reply-to MESSAGE_ID --body "Thanks, got it."
```

**Arguments:**
- `--to`: Recipient email address (required unless in `--from-file` or `--reply-to`)
- `--subject`: Email subject (required unless in `--from-file` or `--reply-to`)
- `--body`: Email body text (required unless in `--from-file`)
- `--from-file`: Markdown file with YAML frontmatter (see format below)
- `--cc`: CC recipients (comma-separated)
- `--bcc`: BCC recipients (comma-separated)
- `--reply-to`: Message ID to reply to (sends in-thread, auto-fills to/subject)

CLI flags override frontmatter values. When using `--from-file`, the markdown
body is converted to HTML and sent as multipart/alternative (HTML + plain text
fallback).

**Markdown file format:**

```markdown
---
to: [email protected]
cc: [email protected]
bcc: [email protected]
subject: Weekly Update
---

# Status Update

Here's what happened this week:

- **Feature A** shipped to production
- Fixed the [login bug](https://jira.example.com/DEMO-123)

| Task | Status |
|------|--------|
| Deploy | Done |
```

### drafts list

List draft messages.

```bash
# List drafts
$SKILL_DIR/scripts/gmail.py drafts list

# List with custom max results
$SKILL_DIR/scripts/gmail.py drafts list --max-results 20
```

**Arguments:**
- `--max-results`: Maximum number of results (default: 10)

### drafts create

Create a draft email.

```bash
# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
  --to [email protected] \
  --subject "Draft Subject" \
  --body "This is a draft message"

# Create draft with CC
$SKILL_DIR/scripts/gmail.py drafts create \
  --to [email protected] \
  --subject "Meeting Notes" \
  --body "Notes from today's meeting..." \
  --cc [email protected]

# Create a reply draft in-thread
$SKILL_DIR/scripts/gmail.py drafts create --reply-to MESSAGE_ID --body "I'll look into this."
```

```bash
# Create draft from a markdown file
$SKILL_DIR/scripts/gmail.py drafts create --from-file update.md
```

**Arguments:**
- `--to`: Recipient email address (required unless in `--from-file`)
- `--subject`: Email subject (required unless in `--from-file`)
- `--body`: Email body text (required unless in `--from-file`)
- `--from-file`: Markdown file with YAML frontmatter (same format as `send`)
- `--cc`: CC recipients (comma-separated)
- `--bcc`: BCC recipients (comma-separated)

### drafts send

Send a draft message.

```bash
# Send draft by ID
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID
```

**Arguments:**
- `draft_id`: The d