gmail-skill

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
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

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

Query examples:

• from:john@example.com - 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

python3 ~/.claude/skills/gmail-skill/gmail_skill.py read EMAIL_ID [--account 

List Recent Emails

Send Email (Requires Confirmation)

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:

Mark as Read

Mark as Unread

Both mark-read and mark-unread support multiple IDs (comma-separated):

Mark Done (Archive)

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

Unarchive

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

Star / Unstar

All label commands support multiple IDs (comma-separated):

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.

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):

Example (reply to existing email):

List Labels

List Contacts

Search Contacts

Manage Accounts

Multi-Account Support

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

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

Examples

Find unread emails from this week

Read a specific email

Send a quick email

Find someone's contact info

Check work email from personal machine

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)