home / skills / idanbeck / claude-skills / gmail-skill

gmail-skill skill

safe

This skill helps you read, search, and manage Gmail emails and contacts across multiple accounts with safe sending confirmations.

npx playbooks add skill idanbeck/claude-skills --skill gmail-skill

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

8.2 KB

---
name: gmail-skill
description: Read, search, send, and draft Gmail emails and Google contacts. Use when the user asks to check email, find emails, search messages, send emails, create drafts, look up contacts, or find someone's email/phone. Supports multiple accounts.
allowed-tools: Bash, Read
---

# Gmail Skill - Email & Contacts Access

Read, search, and send Gmail emails. Access Google contacts.

## CRITICAL: Email Sending Confirmation Required

**Before sending ANY email, you MUST get explicit user confirmation.**

When the user asks to send an email:
1. First, show them the complete email details:
   - From (which account)
   - To
   - CC/BCC (if any)
   - Subject
   - Full body text
2. Ask: "Do you want me to send this email?"
3. ONLY run the send command AFTER the user explicitly confirms (e.g., "yes", "send it", "go ahead")
4. NEVER send an email without this confirmation, even if the user asked you to send it initially

This applies even when:
- The user says "send an email to X"
- You are in "dangerously skip permissions" mode
- The user seems to be in a hurry

Always confirm first. No exceptions.

## First-Time Setup (One-Time, ~2 minutes)

On first run, the script will guide you through setup. You need to create a Google Cloud OAuth client once:

1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Create a project (or select existing)
3. Enable **Gmail API** and **People API** (APIs & Services → Library)
4. Configure OAuth consent screen:
   - User Type: External
   - App name: Gmail Skill
   - Add yourself as test user
   - Add scopes: `gmail.readonly`, `gmail.send`, `gmail.modify`, `contacts.readonly`
5. Create OAuth client ID:
   - Application type: **Desktop app**
   - Download JSON → save as `~/.claude/skills/gmail-skill/credentials.json`

Then just run any command - browser opens, you approve, done. Works for all your accounts.

**Note:** If you previously used gmail-reader, you'll need to re-authenticate to grant the new `gmail.send` scope.

## Commands

### Search Emails

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "query" [--max-results N] [--account EMAIL]
```

**Query examples:**
- `from:[email protected]` - from specific sender
- `subject:meeting after:2026/01/01` - subject + date
- `has:attachment filename:pdf` - with PDF attachments
- `is:unread` - unread emails
- `"exact phrase"` - exact match

### Read Email

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py read EMAIL_ID [--account EMAIL]
```

### List Recent Emails

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list [--max-results N] [--label LABEL] [--account EMAIL]
```

### Send Email (Requires Confirmation)

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py send --to EMAIL --subject "Subject" --body "Body text" [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]
```

**Required arguments:**
- `--to` / `-t` - Recipient email address
- `--subject` / `-s` - Email subject line
- `--body` / `-b` - Email body text

**Optional arguments:**
- `--cc` - CC recipients (comma-separated)
- `--bcc` - BCC recipients (comma-separated)
- `--account` / `-a` - Send from specific account

**Example:**
```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "[email protected]" \
  --subject "Meeting Tomorrow" \
  --body "Hi, just confirming our meeting at 2pm tomorrow." \
  --account [email protected]
```

### Mark as Read

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read EMAIL_ID [--account EMAIL]
```

### Mark as Unread

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-unread EMAIL_ID [--account EMAIL]
```

Both mark-read and mark-unread support multiple IDs (comma-separated):
```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read "id1,id2,id3" --account [email protected]
```

### Mark Done (Archive)

Archives email(s) by removing from inbox. Equivalent to Gmail's 'e' keyboard shortcut.

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-done EMAIL_ID [--account EMAIL]
```

### Unarchive

Moves email(s) back to inbox (undo archive).

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py unarchive EMAIL_ID [--account EMAIL]
```

### Star / Unstar

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py star EMAIL_ID [--account EMAIL]
python3 ~/.claude/skills/gmail-skill/gmail_skill.py unstar EMAIL_ID [--account EMAIL]
```

All label commands support multiple IDs (comma-separated):
```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py star "id1,id2,id3" --account [email protected]
```

### Create Draft

Creates a draft email. Use `--reply-to-id` when replying to an existing email to ensure proper threading in email clients like Superhuman.

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft --to EMAIL --subject "Subject" --body "Body text" [--reply-to-id EMAIL_ID] [--cc EMAIL] [--bcc EMAIL] [--account EMAIL]
```

**Required arguments:**
- `--to` / `-t` - Recipient email address
- `--subject` / `-s` - Email subject line
- `--body` / `-b` - Email body text

**Optional arguments:**
- `--reply-to-id` / `-r` - Message ID to reply to (adds proper In-Reply-To and References headers for threading)
- `--cc` - CC recipients (comma-separated)
- `--bcc` - BCC recipients (comma-separated)
- `--account` / `-a` - Create draft in specific account

**Example (new email):**
```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "[email protected]" \
  --subject "Draft for Review" \
  --body "Here's my draft message."
```

**Example (reply to existing email):**
```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \
  --to "[email protected]" \
  --subject "Re: Original Subject" \
  --body "Thanks for your email..." \
  --reply-to-id 19b99b3127793843 \
  --account [email protected]
```

### List Labels

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py labels [--account EMAIL]
```

### List Contacts

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py contacts [--max-results N] [--account EMAIL]
```

### Search Contacts

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "query" [--account EMAIL]
```

### Manage Accounts

```bash
# List all authenticated accounts
python3 ~/.claude/skills/gmail-skill/gmail_skill.py accounts

# Remove an account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py logout --account [email protected]
```

## Multi-Account Support

Add accounts by using `--account` with a new email - browser opens for that account:

```bash
# First account (auto-authenticates)
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list

# Add work account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account [email protected]

# Add personal account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account [email protected]

# Use specific account
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "from:boss" --account [email protected]
```

Tokens are stored per-account in `~/.claude/skills/gmail-skill/tokens/`

## Examples

### Find unread emails from this week

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "is:unread after:2026/01/01"
```

### Read a specific email

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py read 18d5a3b2c1f4e5d6
```

### Send a quick email

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \
  --to "[email protected]" \
  --subject "Hello!" \
  --body "Just wanted to say hi."
```

### Find someone's contact info

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "John Smith"
```

### Check work email from personal machine

```bash
python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account [email protected] --max-results 5
```

## Output

All commands output JSON for easy parsing.

## Requirements

- Python 3.9+
- `pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client requests`

## Security Notes

- **Send confirmation required** - Claude must always confirm with the user before sending emails
- Tokens stored locally in `~/.claude/skills/gmail-skill/tokens/`
- Revoke access anytime: https://myaccount.google.com/permissions
- Apps in "testing" mode may require re-auth every 7 days (publish app to avoid)

Overview

This skill provides read, search, draft, send and contact lookup capabilities for Gmail accounts. It supports multiple authenticated accounts and outputs machine-friendly JSON for integration. Explicit user confirmation is always required before any email is actually sent.

How this skill works

The skill uses Google OAuth to access Gmail and People APIs; a one-time OAuth client setup is required. Commands let you search messages with advanced Gmail query syntax, read or list messages, create drafts, send messages (after confirmation), manage labels, and search or list contacts. Tokens are stored locally per account so you can switch between accounts using an --account flag.

When to use it

Check inboxes or list recent messages across multiple accounts
Search for messages with advanced Gmail queries (from:, subject:, has:attachment, is:unread, date filters)
Read a specific email or mark messages read/unread, starred, archived, or unarchived
Create drafts or send emails (send requires explicit confirmation)
Lookup or search Google Contacts to find email addresses and phone numbers

Best practices

Complete the one-time OAuth setup to enable read and send scopes before first use
Always review the full email preview (from, to, cc/bcc, subject, body) when asked to send and confirm explicitly
Use Gmail query syntax for precise searches (e.g., from:alice subject:report after:2026/01/01)
Prefer creating drafts with --reply-to-id when replying to preserve threading
Limit --max-results for list/search to keep outputs small when integrating with scripts

Example use cases

Find unread messages from this week: search 'is:unread after:2026/01/01'
Read a specific message by its ID to display full content for follow-up
Create a draft reply referencing an existing message ID to maintain threading
Send a quick email after reviewing the preview and confirming 'yes'
Search contacts for 'Jane Doe' to get email and phone for outreach

FAQ

Do I need to confirm before sending every email?

Yes. The skill always shows the full composed email (from, to, cc/bcc, subject, body) and asks 'Do you want me to send this email?' It will only send after explicit user confirmation.

How do I add multiple accounts?

Run any command with --account EMAIL for a new address. The browser-based OAuth flow will open and authenticate that account; tokens are stored per-account locally.