gmail-automation
Lightweight Gmail integration with standalone OAuth authentication. No MCP server required.
SKILL.md
Full skill instructions
Gmail
Lightweight Gmail integration with standalone OAuth authentication. No MCP server required.
⚠️ Requires Google Workspace account. Personal Gmail accounts are not supported.
First-Time Setup
Authenticate with Google (opens browser):
python scripts/auth.py login
Check authentication status:
python scripts/auth.py status
Logout when needed:
python scripts/auth.py logout
Commands
All operations via scripts/gmail.py. Auto-authenticates on first use if not logged in.
Search Emails
# Search with Gmail query syntax
python scripts/gmail.py search "from:[email protected] is:unread"
# Search recent emails (no query returns all)
python scripts/gmail.py search --limit 20
# Filter by label
python scripts/gmail.py search --label INBOX --limit 10
# Include spam and trash
python scripts/gmail.py search "subject:important" --include-spam-trash
Read Email Content
# Get full message content
python scripts/gmail.py get MESSAGE_ID
# Get just metadata (headers)
python scripts/gmail.py get MESSAGE_ID --format metadata
# Get minimal response (IDs only)
python scripts/gmail.py get MESSAGE_ID --format minimal
Send Emails
# Send a simple email
python scripts/gmail.py send --to "[email protected]" --subject "Hello" --body "Message body"
# Send with CC and BCC
python scripts/gmail.py send --to "[email protected]" --cc "[email protected]" --bcc "[email protected]" \
--subject "Team Update" --body "Update message"
# Send from an alias (must be configured in Gmail settings)
python scripts/gmail.py send --to "[email protected]" --subject "Hello" --body "Message" \
--from "Mile9 Accounts <[email protected]>"
# Send HTML email
python scripts/gmail.py send --to "[email protected]" --subject "HTML Email" \
--body "<h1>Hello</h1><p>HTML content</p>" --html
Draft Management
# Create a draft
python scripts/gmail.py create-draft --to "[email protected]" --subject "Draft Subject" \
--body "Draft content"
# Send an existing draft
python scripts/gmail.py send-draft DRAFT_ID
Modify Messages (Labels)
# Mark as read (remove UNREAD label)
python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD
# Mark as unread
python scripts/gmail.py modify MESSAGE_ID --add-label UNREAD
# Archive (remove from INBOX)
python scripts/gmail.py modify MESSAGE_ID --remove-label INBOX
# Star a message
python scripts/gmail.py modify MESSAGE_ID --add-label STARRED
# Unstar a message
python scripts/gmail.py modify MESSAGE_ID --remove-label STARRED
# Mark as important
python scripts/gmail.py modify MESSAGE_ID --add-label IMPORTANT
# Multiple label changes at once
python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD --add-label STARRED
List Labels
# List all Gmail labels (system and user-created)
python scripts/gmail.py list-labels
Gmail Query Syntax
Gmail supports powerful search operators:
| Query | Description |
|---|---|
from:[email protected] | Emails from a specific sender |
to:[email protected] | Emails to a specific recipient |
subject:meeting | Emails with "meeting" in subject |
is:unread | Unread emails |
is:starred | Starred emails |
is:important | Important emails |
has:attachment | Emails with attachments |
after:2024/01/01 | Emails after a date |
before:2024/12/31 | Emails before a date |
newer_than:7d | Emails from last 7 days |
older_than:1m | Emails older than 1 month |
label:work | Emails with a specific label |
in:inbox | Emails in inbox |
in:sent | Sent emails |
in:trash | Trashed emails |
Combine with AND (space), OR, or - (NOT):
python scripts/gmail.py search "from:[email protected] is:unread newer_than:1d"
python scripts/gmail.py search "subject:urgent OR subject:important"
python scripts/gmail.py search "from:[email protected] -is:starred"
Common Label IDs
| Label | ID |
|---|---|
| Inbox | INBOX |
| Sent | SENT |
| Drafts | DRAFT |
| Spam | SPAM |
| Trash | TRASH |
| Starred | STARRED |
| Important | IMPORTANT |
| Unread | UNREAD |
Token Management
Tokens stored securely using the system keyring:
- macOS: Keychain
- Windows: Windows Credential Locker
- Linux: Secret Service API (GNOME Keyring, KDE Wallet, etc.)
Service name: gmail-skill-oauth
Tokens automatically refresh when expired using Google's cloud function.
<!-- AGI-INTEGRATION-START -->
AGI Framework Integration
Adapted for @techwavedev/agi-agent-kit Original source: antigravity-awesome-skills
Memory-First Protocol
Retrieve prior agent configurations, team compositions, and orchestration patterns. Critical for multi-agent system consistency.
# Check for prior AI agent orchestration context before starting
python3 execution/memory_manager.py auto --query "agent patterns and orchestration strategies for Gmail Automation"
Storing Results
After completing work, store AI agent orchestration decisions for future sessions:
python3 execution/memory_manager.py store \
--content "Agent pattern: hierarchical orchestration with Control Tower dispatcher, 3 specialist sub-agents" \
--type decision --project <project> \
--tags gmail-automation ai-agents
Multi-Agent Collaboration
This skill is inherently multi-agent. Use cross-agent context to coordinate task distribution and avoid duplicate work.
python3 execution/cross_agent_context.py store \
--agent "<your-agent>" \
--action "Agent architecture designed — Control Tower + specialist agents with shared Qdrant memory" \
--project <project>
Control Tower Integration
Register agents and tasks with the Control Tower (execution/control_tower.py) for centralized orchestration across machines and LLM providers.
Blockchain Identity
Each agent has a cryptographic Ed25519 identity. All memory writes are signed — enabling trust verification in multi-agent systems.
<!-- AGI-INTEGRATION-END -->