gmail-automation

name	gmail-automation
description	Lightweight Gmail integration with standalone OAuth authentication. No MCP server required.
license	Apache-2.0
risk	critical
source	community
metadata	{"author":"sanjay3290","version":"1.0"}

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:[e-mail] 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 "[e-mail]" --subject "Hello" --body "Message body"

# Send with CC and BCC
python scripts/gmail.py send --to "[e-mail]" --cc "[e-mail]" --bcc "[e-mail]" \
  --subject "Team Update" --body "Update message"

# Send from an alias (must be configured in Gmail settings)
python scripts/gmail.py send --to "[e-mail]" --subject "Hello" --body "Message" \
  --from "Mile9 Accounts <[e-mail]>"

# Send HTML email
python scripts/gmail.py send --to "[e-mail]" --subject "HTML Email" \
  --body "<h1>Hello</h1><p>HTML content</p>" --html

Draft Management

# Create a draft
python scripts/gmail.py create-draft --to "[e-mail]" --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:[e-mail]	Emails from a specific sender
to:[e-mail]	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:[e-mail] is:unread newer_than:1d"
python scripts/gmail.py search "subject:urgent OR subject:important"
python scripts/gmail.py search "from:[e-mail] -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 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.