PluginBench
Skill
Review
Audit score 70

gmail-skill

idanbeck/claude-skills

Read, search, send, and draft Gmail emails and manage Google contacts with multi-account support.

SourceView on skills.sh

What is gmail-skill?

Access and manage Gmail emails and Google contacts directly from your agent. Search emails by sender, subject, date, and attachments; read full messages; send emails with confirmation; create drafts; and look up contact information. Supports multiple Gmail accounts.

  • Search emails by sender, subject, date, attachments, and read status
  • Read full email content and list recent messages by label
  • Send emails and create drafts with optional CC/BCC
  • Mark emails as read, unread, starred, or archived
  • Manage Google contacts and search contact information
  • Support multiple Gmail accounts with per-account authentication

How to install gmail-skill

npx skills add https://github.com/idanbeck/claude-skills --skill gmail-skill
Prerequisites
  • Python 3.9 or higher
  • Google Cloud OAuth credentials (one-time setup via Google Cloud Console)
  • Gmail API and People API enabled in Google Cloud project
  • Desktop OAuth application type configured
Claude Code
Cursor
Windsurf
Cline

How to use gmail-skill

  1. 1.Set up Google Cloud OAuth credentials by creating a project, enabling Gmail and People APIs, and downloading credentials.json to ~/.claude/skills/gmail-skill/
  2. 2.Run any command to trigger browser authentication on first use
  3. 3.Use search command with queries like 'from:sender@example.com' or 'is:unread' to find emails
  4. 4.Read specific emails using the read command with an email ID
  5. 5.To send an email, prepare the message and wait for explicit user confirmation before executing the send command
  6. 6.Add additional accounts by using --account flag with a new email address; browser will open for authentication
  7. 7.Use --account flag on any command to specify which account to use for multi-account workflows

Use cases

Good for
  • Check unread emails and search for messages from specific senders
  • Send emails on behalf of the user after explicit confirmation
  • Look up contact information and phone numbers for people
  • Create draft emails for review before sending
  • Organize emails by archiving, starring, or marking as read
Who it's for
  • Users managing multiple email accounts
  • Teams needing automated email workflows with safety checks
  • Anyone wanting to integrate Gmail access into agent workflows
  • Professionals organizing and searching large email volumes

gmail-skill FAQ

Do I need to confirm before sending emails?

Yes, the skill requires explicit user confirmation before sending any email. It will show you the complete email details (from, to, cc/bcc, subject, body) and ask for approval before executing the send command.

Can I use this with multiple Gmail accounts?

Yes, the skill supports multiple accounts. Authenticate additional accounts by using the --account flag with a new email address. Tokens are stored separately per account.

What email search queries are supported?

The skill supports Gmail search syntax including from:sender, subject:text, after:date, has:attachment, filename:type, is:unread, and exact phrase matching with quotes.

How do I create a draft instead of sending immediately?

Use the draft command instead of send. Drafts are created in your Gmail account and can be reviewed before sending manually or through the agent later.

What happens if I already used gmail-reader?

You'll need to re-authenticate to grant the new gmail.send scope required by this skill. Run any command and approve the new permissions in the browser.

Full instructions (SKILL.md)

Source of truth, from idanbeck/claude-skills.

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

Related skills

More from idanbeck/claude-skills and the wider catalog.

OPopen-computer-use logo

open-computer-use

ifuryst/open-codex-computer-use

Platform-neutral CLI and MCP server for GUI automation across macOS, Linux, and Windows.

1.4k installs
POpowerpoint logo

powerpoint

igorwarzocha/opencode-workflows

Create, design, and analyze PowerPoint presentations with precise layout control and design principles.

6.0k installs
WOword logo

word

igorwarzocha/opencode-workflows

|-

658 installsAudited
II

iii-architecture-patterns

iii-hq/iii

Agent skill from iii-hq/iii.

2.8k installs
II

iii-core-primitives

iii-hq/iii

Agent skill from iii-hq/iii.

2.8k installs
II

iii-engine-config

iii-hq/iii

Configure iii engine workers, adapters, queues, ports, and environment variables via YAML.

3.1k installs