mcpField
G
gmail

gmail

github.com/team-attentionProductivity82838 installsUpdated 27w ago
Repository

About gmail

gmail is a skill for managing email through the Gmail API across multiple Google accounts. Its sending workflow gathers context, collects feedback on a draft, and requires confirmation of a test email before the actual send.

Key features

  1. 01Manage multiple Google accounts
  2. 02Read and search email
  3. 03Send email and manage labels
  4. 04Test sends and request confirmation
  5. 05Automatically refresh expired tokens

Use cases

  1. 01Find unread email or past conversations
  2. 02Draft email using relevant background
  3. 03Send to a recipient after testing and confirmation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/team-attention/plugins-for-claude-natives --skill gmail

After installing, type/gmailin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

.gitignore
accounts.yaml.example
pyproject.toml
assets/
accounts.default.yaml
email-templates.md
signatures.md
references/
cli-usage.md
search-queries.md
setup-guide.md
scripts/
gmail_client.py
list_messages.py
manage_labels.py
read_message.py
send_message.py
setup_auth.py
scripts/core/
__init__.py
batch_processor.py
cache_manager.py
quota_manager.py
retry_handler.py

Details

From the project README

Gmail Skill

Manage emails through Gmail API - read, search, send, and organize across multiple Google accounts.

Account Setup

Before running any command, read accounts.yaml to check registered accounts.

If accounts.yaml is missing or empty → Read references/setup-guide.md for initial setup

# accounts.yaml example
accounts:
  personal:
    email: [email protected]
    description: Personal Gmail
  work:
    email: [email protected]
    description: Work account

Email Sending Workflow (5 Steps)

When sending emails, create 5 Tasks with TaskCreate and execute sequentially:

StepTaskKey Action
1Gather contextRun Explore SubAgents in parallel: recipient info, related projects, background context
2Check previous conversationsSearch --query "to:recipient OR from:recipient newer_than:90d" → AskUserQuestion for thread selection
3Draft emailCompose draft → AskUserQuestion for feedback
4Test sendSend [TEST] email to user's own address → Open in Gmail web → Request confirmation
5Actual sendSend to recipient → Report completion

Signature: Append ---\nSent with Claude Code to all outgoing emails

Workflow Example: "Send a meeting email to John"
1. Create 5 Tasks
2. Step 1: Run parallel Explore SubAgents
   - Search recipient (John) info (partners/, projects/, context.md, etc.)
   - Search meeting context (calendar, recent meeting notes, etc.)
3. Step 2: Search "to:[email protected] OR from:[email protected]"
   → If previous conversation exists, AskUserQuestion (reply/new email)
4. Step 3: Draft email → AskUserQuestion (proceed/revise)
5. Step 4: Test send to my email → Open in Gmail web (`open "https://mail.google.com/mail/u/0/#inbox/{message_id}"`) → Request confirmation
6. Step 5: Actual send → Done

CLI Quick Reference

# List messages
uv run python scripts/list_messages.py --account work --query "is:unread" --max 10

# Send email
uv run python scripts/send_message.py --account work --to "[email protected]" --subject "Subject" --body "Content"

# Check profile
uv run python scripts/manage_labels.py --account work profile

Detailed CLI usage: references/cli-usage.md Search query reference: references/search-queries.md

View Email in Web

After sending, use the returned Message ID to view directly in Gmail web:

# URL format
https://mail.google.com/mail/u/0/#inbox/{message_id}

# Example: Open in browser after test send
open "https://mail.google.com/mail/u/0/#inbox/19c145bbd47ddd01"

Note: u/0 is the first logged-in account, u/1 is the second account

File Structure

skills/gmail/
├── SKILL.md
├── accounts.yaml           # Account metadata
├── scripts/                # CLI scripts
├── references/
│   ├── setup-guide.md      # Initial setup guide
│   ├── cli-usage.md        # Detailed CLI usage
│   ├── search-queries.md   # Search query reference
│   └── credentials.json    # OAuth Client ID (gitignore)
├── assets/
│   ├── accounts.default.yaml  # Account config template
│   ├── email-templates.md     # Email body templates
│   └── signatures.md          # Signature templates (Plain/HTML)
└── accounts/               # Per-account tokens (gitignore)

Error Handling

SituationResolution
accounts.yaml missingRead references/setup-guide.md for initial setup
Token missingGuide user to run setup_auth.py --account <name>
Token expiredAuto-refresh; if failed, guide re-authentication

Comments

Markdown supported