gmail-automation
Lightweight Gmail integration with standalone OAuth authentication. No MCP server required.
- License 许可
- Apache-2.0
- 所属仓库
- ASoudy/AGS
- 最近更新
- 2026-05-23
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- gmail-automation
- risk
- critical
- source
- community
- license
- Apache-2.0
- metadata
- { "author": "sanjay3290", "version": "1.0" }
- description
- Lightweight Gmail integration with standalone OAuth authentication. No MCP server required.
03 SKILL.md 正文
Gmail
Lightweight Gmail integration with standalone OAuth authentication. No MCP server required.
⚠️ Requires Google Workspace account. Personal Gmail accounts are not supported.
When to Use
- You need to search, read, or send Gmail messages from the command line without an MCP server.
- You are automating inbox workflows for a Google Workspace account.
- You want a lightweight Gmail integration backed by standalone OAuth scripts.
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:someone@example.com 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 "user@example.com" --subject "Hello" --body "Message body"
# Send with CC and BCC
python scripts/gmail.py send --to "user@example.com" --cc "cc@example.com" --bcc "bcc@example.com" \
--subject "Team Update" --body "Update message"
# Send from an alias (must be configured in Gmail settings)
python scripts/gmail.py send --to "user@example.com" --subject "Hello" --body "Message" \
--from "Mile9 Accounts <accounts@mile9.io>"
# Send HTML email
python scripts/gmail.py send --to "user@example.com" --subject "HTML Email" \
--body "<h1>Hello</h1><p>HTML content</p>" --html
Draft Management
# Create a draft
python scripts/gmail.py create-draft --to "user@example.com" --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:user@example.com |
Emails from a specific sender |
to:user@example.com |
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:boss@company.com is:unread newer_than:1d"
python scripts/gmail.py search "subject:urgent OR subject:important"
python scripts/gmail.py search "from:newsletter@example.com -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.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
04 同仓库更多 Skills
web-typography
Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", or "typographic scale". Also trigger when choosing between system fonts and web fonts, optimizing font loading performance, or designing readable long-form content layouts. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.
ux-heuristics
Evaluate and improve interface usability using heuristic analysis. Use when the user mentions "usability audit", "UX review", "users are confused", "heuristic evaluation", "form usability", "navigation problems", "Nielsen heuristics", "cognitive walkthrough", or "usability testing". Also trigger when reviewing a design for usability issues, improving form completion rates, or evaluating information architecture and navigation. Covers Nielsens 10 heuristics, severity ratings, and information architecture. For visual design fixes, see refactoring-ui. For conversion-focused audits, see cro-methodology.
traction-eos
Implement the Entrepreneurial Operating System (EOS) to align vision and execution across a company. Use when the user mentions "EOS", "V/TO", "quarterly rocks", "Level 10 meetings", "accountability chart", "IDS process", "Entrepreneurial Operating System", or "business operating system". Also trigger when a growing company needs meeting structure, goal-setting frameworks, or a systematic approach to solving recurring organizational issues. Covers the six EOS components: Vision, People, Data, Issues, Process, Traction. For team motivation design, see drive-motivation. For lean experimentation, see lean-startup.
top-design
Create award-winning, immersive web experiences at the level of Awwwards-featured agencies. Use when the user mentions "premium website", "portfolio site", "scroll animations", "Awwwards quality", "brand experience", "cinematic web design", "parallax storytelling", or "agency-quality site". Also trigger when building landing pages that need to impress, designing creative portfolios, or elevating a standard website to a memorable digital experience. Covers dramatic typography, purposeful motion, scroll-based composition, and performance-optimized animation. For foundational UI, see refactoring-ui. For type selection, see web-typography.
system-design
Design scalable distributed systems using structured approaches for load balancing, caching, database scaling, and message queues. Use when the user mentions "system design", "scale this", "high availability", "rate limiter", "design a URL shortener", "system design interview", "capacity planning", or "distributed architecture". Also trigger when estimating infrastructure requirements, choosing between microservices and monoliths, or designing for millions of concurrent users. Covers common system designs and back-of-the-envelope estimation. For data fundamentals, see ddia-systems. For resilience, see release-it.
storybrand-messaging
Clarify brand messaging using narrative structure that positions the customer as hero. Use when the user mentions "brand message", "website copy", "elevator pitch", "one-liner", "messaging isnt resonating", "brand script", "StoryBrand framework", or "customer as hero". Also trigger when rewriting homepage copy, crafting email nurture sequences, or creating consistent messaging across sales collateral and marketing materials. Covers landing page copy, marketing collateral, and consistent communication. For memorable messaging, see made-to-stick. For product positioning, see obviously-awesome.