# Gmail

> Search and read Gmail for research or information retrieval.

- Skill: `tylerprogramming/gmail` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tylerprogramming/gmail`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tylerprogramming/gmail/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: tylerprogramming (https://skillmd.com/u/tylerprogramming)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tylerprogramming/gmail

---


Search and read Gmail for research or information retrieval.

## Setup Check

Before running, verify credentials exist:
```
ls ~/.claude/gmail/credentials.json
```

If missing, tell the user:
> "You need to set up Gmail API credentials first. See the setup instructions below."
>
> **Setup (one-time):**
> 1. Go to [console.cloud.google.com](https://console.cloud.google.com)
> 2. Create a project → Enable **Gmail API**
> 3. Go to **APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID**
> 4. Application type: **Desktop app**
> 5. Download the JSON → save as `~/.claude/gmail/credentials.json`
> 6. Run `/gmail` again — it will open your browser to authorize (one-time)

## Parsing Arguments

Parse `$ARGUMENTS` for the user's intent:

- **Natural language queries** like "emails from stripe last month" → convert to Gmail search syntax
- **Explicit queries** with Gmail operators (from:, subject:, after:, etc.) → use as-is
- **`--limit N`** → max results, default 10
- **`--body`** → include full body in search results (slower, use only when user wants content)
- **`--thread`** → fetch full thread instead of individual message

### Gmail Search Query Conversion

Convert natural language to Gmail search syntax:
- "from stripe last week" → `from:stripe after:2026/03/14`
- "unread newsletters" → `is:unread label:newsletters`
- "emails about invoice" → `subject:invoice OR invoice`
- "attachments from john" → `from:john has:attachment`
- "today's emails" → `after:2026/03/21`

Today's date: 2026-03-21

## Flow

### Step 1: Search

```bash
python3 ~/.claude/skills/gmail/gmail_client.py search "<query>" --limit <N> [--body]
```

On first run, this opens the browser for OAuth authorization. Tell the user to complete that step, then re-run.

### Step 2: Present Results

Show a clean table of results:

| # | From | Subject | Date | Snippet |
|---|------|---------|------|---------|
| 1 | sender@example.com | Subject line | Mar 20 | Preview... |

### Step 3: Read Full Email (if user wants details)

When user wants to read a specific email:
```bash
python3 ~/.claude/skills/gmail/gmail_client.py read <message_id>
```

Or fetch the full thread:
```bash
python3 ~/.claude/skills/gmail/gmail_client.py thread <thread_id>
```

### Step 4: Analyze / Summarize

After reading emails, synthesize the content for the user's research goal. Focus on:
- Key information, decisions, or action items
- Chronological summaries for threads
- Patterns across multiple emails (e.g., "All 5 emails from Stripe are receipts for X")

## Rules

- Never store or log email content to disk unless the user explicitly asks
- If a query returns 0 results, suggest alternative search terms
- Respect the `--limit` — don't fetch more than requested
- For research tasks, use `--body` only when the snippet isn't enough
- When summarizing threads, preserve chronological order
- If the user asks to "find all emails from X", default limit to 20 and ask if they want more