Gmail

Interact with Gmail for email management, search, and organization.

Installation

Dependencies: pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml

Setup Verification

After installation, verify the skill is properly configured:

$SKILL_DIR/scripts/gmail.py check

This will check:

• Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client, keyring, pyyaml)
• Authentication configuration
• Connectivity to Gmail API

If anything is missing, the check command will provide setup instructions.

Authentication

Gmail uses OAuth 2.0 for authentication. For complete setup instructions, see:

1. GCP Project Setup Guide - Create project, enable Gmail API
2. Google OAuth Setup Guide - Configure credentials

Quick Start

1. Create ~/.config/agent-skills/google.yaml:

   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   

   Copy

2. Run $SKILL_DIR/scripts/gmail.py check to trigger OAuth flow and verify setup.

On scope or authentication errors, see the OAuth troubleshooting guide.

Commands

See permissions.md for read/write classification of each command.

check

Verify configuration and connectivity.

$SKILL_DIR/scripts/gmail.py check

This validates:

• Python dependencies are installed
• Authentication is configured
• Can connect to Gmail API
• Displays your email address and mailbox statistics

auth setup

Store OAuth 2.0 client credentials for custom OAuth flow.

$SKILL_DIR/scripts/gmail.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Credentials are saved to ~/.config/agent-skills/gmail.yaml.

auth reset

Clear stored OAuth token. The next command that needs authentication will trigger re-authentication automatically.

$SKILL_DIR/scripts/gmail.py auth reset

Use this when you encounter scope or authentication errors.

auth status

Show current OAuth token information without making API calls.

$SKILL_DIR/scripts/gmail.py auth status

Displays: whether a token is stored, granted scopes, refresh token presence, token expiry, and client ID.

messages list

List messages matching a query.

# List recent messages
$SKILL_DIR/scripts/gmail.py messages list

# Search for unread messages
$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"

# Search with max results
$SKILL_DIR/scripts/gmail.py messages list --query "from:user@example.com" --max-results 20

Arguments:

• --query: Gmail search query (optional)
• --max-results: Maximum number of results (default: 10)

Search Query Examples:

For complete Gmail search syntax, see gmail-queries.md.

Common queries:

• is:unread - Unread messages
• from:user@example.com - Messages from sender
• subject:meeting - Messages with subject keyword
• has:attachment - Messages with attachments
• after:2024/01/01 - Messages after date
• label:important - Messages with label

messages get

Get a message by ID.

# Get full message
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID

# Get minimal format
$SKILL_DIR/scripts/gmail.py messages get MESSAGE_ID --format minimal

Arguments:

• message_id: The message ID (required)
• --format: Message format (full, minimal, raw, metadata) - default: full

messages mark-read

Mark one or more messages as read by removing the UNREAD label.

# Mark a single message
$SKILL_DIR/scripts/gmail.py messages mark-read MESSAGE_ID

# Mark multiple messages
$SKILL_DIR/scripts/gmail.py messages mark-read MSG1 MSG2 MSG3

# Mark all unread messages from a sender
$SKILL_DIR/scripts/gmail.py messages mark-read --query "is:unread from:user@example.com"

# Combine IDs and query
$SKILL_DIR/scripts/gmail.py messages mark-read MSG1 --query "is:unread label:updates"

Arguments:

• message_ids: One or more message IDs (optional if --query is used)
• --query: Gmail search query to find messages to mark as read
• --max-results: Maximum messages to mark from --query (default: 100)

threads get

Get a full conversation thread with all messages displayed chronologically. For messages from Google Groups, includes shareable permalinks using the d/msgid URL format.

# Get full thread
$SKILL_DIR/scripts/gmail.py threads get THREAD_ID

Arguments:

• thread_id: The thread ID (required)

send

Send an email message.

# Send simple email
$SKILL_DIR/scripts/gmail.py send \
  --to recipient@example.com \
  --subject "Hello" \
  --body "This is the message body"

# Send with CC and BCC
$SKILL_DIR/scripts/gmail.py send \
  --to recipient@example.com \
  --subject "Team Update" \
  --body "Here's the update..." \
  --cc team@example.com \
  --bcc boss@example.com

# Send from a markdown file with frontmatter
$SKILL_DIR/scripts/gmail.py send --from-file update.md

# Send from file with CLI overrides
$SKILL_DIR/scripts/gmail.py send --from-file update.md --to override@example.com

# Reply to a message in-thread
$SKILL_DIR/scripts/gmail.py send --reply-to MESSAGE_ID --body "Thanks, got it."

Arguments:

• --to: Recipient email address (required unless in --from-file or --reply-to)
• --subject: Email subject (required unless in --from-file or --reply-to)
• --body: Email body text (required unless in --from-file)
• --from-file: Markdown file with YAML frontmatter (see format below)
• --cc: CC recipients (comma-separated)
• --bcc: BCC recipients (comma-separated)
• --reply-to: Message ID to reply to (sends in-thread, auto-fills to/subject)

CLI flags override frontmatter values. When using --from-file, the markdown body is converted to HTML and sent as multipart/alternative (HTML + plain text fallback).

Markdown file format:

---
to: recipient@example.com
cc: team@example.com
bcc: boss@example.com
subject: Weekly Update
---

# Status Update

Here's what happened this week:

- **Feature A** shipped to production
- Fixed the [login bug](https://jira.example.com/DEMO-123)

| Task | Status |
|------|--------|
| Deploy | Done |

drafts list

List draft messages.

# List drafts
$SKILL_DIR/scripts/gmail.py drafts list

# List with custom max results
$SKILL_DIR/scripts/gmail.py drafts list --max-results 20

Arguments:

• --max-results: Maximum number of results (default: 10)

drafts create

Create a draft email.

# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
  --to recipient@example.com \
  --subject "Draft Subject" \
  --body "This is a draft message"

# Create draft with CC
$SKILL_DIR/scripts/gmail.py drafts create \
  --to recipient@example.com \
  --subject "Meeting Notes" \
  --body "Notes from today's meeting..." \
  --cc team@example.com

# Create a reply draft in-thread
$SKILL_DIR/scripts/gmail.py drafts create --reply-to MESSAGE_ID --body "I'll look into this."

# Create draft from a markdown file
$SKILL_DIR/scripts/gmail.py drafts create --from-file update.md

Arguments:

• --to: Recipient email address (required unless in --from-file)
• --subject: Email subject (required unless in --from-file)
• --body: Email body text (required unless in --from-file)
• --from-file: Markdown file with YAML frontmatter (same format as send)
• --cc: CC recipients (comma-separated)
• --bcc: BCC recipients (comma-separated)

drafts send

Send a draft message.

# Send draft by ID
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

Arguments:

• draft_id: The draft ID to send (required)

labels list

List all Gmail labels.

# List labels
$SKILL_DIR/scripts/gmail.py labels list

labels create

Create a new label.

# Create label
$SKILL_DIR/scripts/gmail.py labels create "Project X"

Arguments:

• name: Label name (required)

Examples

Verify Setup

$SKILL_DIR/scripts/gmail.py check

Find unread emails

$SKILL_DIR/scripts/gmail.py messages list --query "is:unread"

Search for emails from a sender

$SKILL_DIR/scripts/gmail.py messages list --query "from:boss@example.com" --max-results 5

Send a quick email

$SKILL_DIR/scripts/gmail.py send \
  --to colleague@example.com \
  --subject "Quick Question" \
  --body "Do you have time for a meeting tomorrow?"

Create and send a draft

# Create draft
$SKILL_DIR/scripts/gmail.py drafts create \
  --to team@example.com \
  --subject "Weekly Update" \
  --body "Here's this week's update..."

# List drafts to get the ID
$SKILL_DIR/scripts/gmail.py drafts list

# Send the draft
$SKILL_DIR/scripts/gmail.py drafts send DRAFT_ID

Organize with labels

# Create a label
$SKILL_DIR/scripts/gmail.py labels create "Project Alpha"

# List all labels
$SKILL_DIR/scripts/gmail.py labels list

Advanced searches

# Find emails with attachments from last week
$SKILL_DIR/scripts/gmail.py messages list --query "has:attachment newer_than:7d"

# Find important emails from specific sender
$SKILL_DIR/scripts/gmail.py messages list --query "from:ceo@example.com is:important"

# Find emails in a conversation
$SKILL_DIR/scripts/gmail.py messages list --query "subject:project-alpha"

Gmail Search Query Syntax

Common search operators:

Combine operators with spaces (implicit AND) or OR:

# AND (implicit)
from:user@example.com subject:meeting

# OR
from:user@example.com OR from:other@example.com

# Grouping with parentheses
(from:user@example.com OR from:other@example.com) subject:meeting

For the complete reference, see gmail-queries.md.

Error Handling

Authentication and scope errors are not retryable. If a command fails with an authentication error, insufficient scope error, or permission denied error (exit code 1), stop and inform the user. Do not retry or attempt to fix the issue autonomously — these errors require user interaction (browser-based OAuth consent). Point the user to the OAuth troubleshooting guide.

Retryable errors: Rate limiting (HTTP 429) and temporary server errors (HTTP 5xx) may succeed on retry after a brief wait. All other errors should be reported to the user.

Model Guidance

This skill makes API calls requiring structured input/output. A standard-capability model is recommended.