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:

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

Quick Start

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

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

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:

Operator	Description	Example
`from:`	Sender email	`from:user@example.com`
`to:`	Recipient email	`to:user@example.com`
`subject:`	Subject contains	`subject:meeting`
`label:`	Has label	`label:important`
`has:attachment`	Has attachment	`has:attachment`
`is:unread`	Unread messages	`is:unread`
`is:starred`	Starred messages	`is:starred`
`after:`	After date	`after:2024/01/01`
`before:`	Before date	`before:2024/12/31`
`newer_than:`	Newer than period	`newer_than:7d`
`older_than:`	Older than period	`older_than:30d`

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.

gmail

Gmail

Installation

Setup Verification