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…
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: First, show them the complete email details: From (which account) To CC/BCC (if any) Subject Full body text Ask: "Do you want me to send this email?" ONLY run the send command AFTER the user explicitly confirms (e.g., "yes", "send it", "go ahead") 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: Go to Google Cloud Console Create a project (or select existing) Enable Gmail API and People API (APIs & Services → Library) 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 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 EMAIL] List Recent Emails python3 ~/.claude/skills/gmail-skill/gmail_skill.py list [--max-results N] [--label LABEL] [--account EMAIL] Send Email (Requires Confirmation) 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: python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \ --to "recipient@example.com" \ --subject "Meeting Tomorrow" \ --body "Hi, just confirming our meeting at 2pm tomorrow." \ --account work@company.com Mark as Read python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read EMAIL_ID [--account EMAIL] Mark as Unread 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): python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-read "id1,id2,id3" --account user@gmail.com Mark Done (Archive) Archives email(s) by removing from inbox. Equivalent to Gmail's 'e' keyboard shortcut. python3 ~/.claude/skills/gmail-skill/gmail_skill.py mark-done EMAIL_ID [--account EMAIL] Unarchive Moves email(s) back to inbox (undo archive). python3 ~/.claude/skills/gmail-skill/gmail_skill.py unarchive EMAIL_ID [--account EMAIL] Star / Unstar 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): python3 ~/.claude/skills/gmail-skill/gmail_skill.py star "id1,id2,id3" --account user@gmail.com 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. 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): python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \ --to "recipient@example.com" \ --subject "Draft for Review" \ --body "Here's my draft message." Example (reply to existing email): python3 ~/.claude/skills/gmail-skill/gmail_skill.py draft \ --to "sender@example.com" \ --subject "Re: Original Subject" \ --body "Thanks for your email..." \ --reply-to-id 19b99b3127793843 \ --account work@company.com List Labels python3 ~/.claude/skills/gmail-skill/gmail_skill.py labels [--account EMAIL] List Contacts python3 ~/.claude/skills/gmail-skill/gmail_skill.py contacts [--max-results N] [--account EMAIL] Search Contacts python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "query" [--account EMAIL] Manage Accounts # 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 user@gmail.com Multi-Account Support Add accounts by using --account with a new email - browser opens for that account: # 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 work@company.com # Add personal account python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account personal@gmail.com # Use specific account python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "from:boss" --account work@company.com Tokens are stored per-account in ~/.claude/skills/gmail-skill/tokens/ Examples Find unread emails from this week python3 ~/.claude/skills/gmail-skill/gmail_skill.py search "is:unread after:2026/01/01" Read a specific email python3 ~/.claude/skills/gmail-skill/gmail_skill.py read 18d5a3b2c1f4e5d6 Send a quick email python3 ~/.claude/skills/gmail-skill/gmail_skill.py send \ --to "friend@example.com" \ --subject "Hello!" \ --body "Just wanted to say hi." Find someone's contact info python3 ~/.claude/skills/gmail-skill/gmail_skill.py search-contacts "John Smith" Check work email from personal machine python3 ~/.claude/skills/gmail-skill/gmail_skill.py list --account work@company.com --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) 1d:[
don't have the plugin yet? install it then click "run inline in claude" again.