Purpose
Automate Gmail operations including reading, sending, replying, forwarding, and managing emails. Useful for email automation, inbox management, and communication workflows.
Gmail
Read, send, and manage Gmail via OAuth authentication.
CRITICAL SAFETY RULES
These rules are MANDATORY and must NEVER be bypassed:
- NEVER Send Without Explicit Approval
-
ALWAYS show the user the complete email (to, subject, body) before sending
-
ALWAYS ask for explicit confirmation: "Do you want me to send this email? (yes/no)"
-
NEVER auto-send emails, even if user says "send an email to X"
-
NEVER send multiple emails in a loop without per-email confirmation
- Draft-First Workflow (DEFAULT BEHAVIOR)
-
ALL send/reply/forward operations create a draft FIRST
-
User sees the draft and chooses: yes (send now), no (delete draft), or keep-draft (review in Gmail)
-
This ensures user can ALWAYS review in Gmail UI before any email is sent
- Sensitive Operations Require Confirmation
Operation Requires Confirmation
Send email YES - ALWAYS
Reply to email YES - ALWAYS
Forward email YES - ALWAYS
Send draft YES - ALWAYS
Delete draft Yes
Trash email Yes
- Read Operations Are Safe
These do NOT require confirmation:
-
List emails, Search emails, Read email content
-
List labels, List drafts, Get attachment
Pre-Flight Check (ALWAYS RUN FIRST)
python3 00-system/skills/google/google-master/scripts/google_auth.py --check --service gmail
Exit codes:
-
0: Ready to use - proceed with user request
-
1: Need to login - run python3 00-system/skills/google/google-master/scripts/google_auth.py --login
-
2: Missing credentials or dependencies - see ../google-master/references/setup-guide.md
Quick Reference
List Emails
python3 00-system/skills/google/gmail/scripts/gmail_operations.py list --max 10
List Unread Emails
python3 00-system/skills/google/gmail/scripts/gmail_operations.py list --query "is:unread" --max 10
Search Emails
python3 00-system/skills/google/gmail/scripts/gmail_operations.py search "from:user@example.com subject:report"
Read Email
python3 00-system/skills/google/gmail/scripts/gmail_operations.py read <message_id>
Send Email
python3 00-system/skills/google/gmail/scripts/gmail_operations.py send --to "user@example.com" --subject "Hello" --body "Message body"
Reply to Email
python3 00-system/skills/google/gmail/scripts/gmail_operations.py reply <message_id> --body "Reply text"
Forward Email
python3 00-system/skills/google/gmail/scripts/gmail_operations.py forward <message_id> --to "user@example.com"
Create Draft
python3 00-system/skills/google/gmail/scripts/gmail_operations.py draft --to "user@example.com" --subject "Draft" --body "Content"
List Drafts
python3 00-system/skills/google/gmail/scripts/gmail_operations.py drafts
List Labels
python3 00-system/skills/google/gmail/scripts/gmail_operations.py labels
Trash/Archive/Mark Read
python3 00-system/skills/google/gmail/scripts/gmail_operations.py trash <message_id> python3 00-system/skills/google/gmail/scripts/gmail_operations.py archive <message_id> python3 00-system/skills/google/gmail/scripts/gmail_operations.py mark-read <message_id>
Gmail Search Syntax
Operator Example Description
from:
from:user@example.com
Emails from sender
to:
Emails to recipient
subject:
subject:meeting
Subject contains word
is:unread
is:unread
Unread emails
has:attachment
has:attachment
Has attachments
after:
after:2024/01/01
After date
before:
before:2024/12/31
Before date
label:
label:important
Has label
Error Handling
See ../google-master/references/error-handling.md for common errors and solutions.
Setup
First-time setup: ../google-master/references/setup-guide.md
Quick start:
-
pip install google-auth google-auth-oauthlib google-api-python-client
-
Create OAuth credentials in Google Cloud Console (enable Gmail API, choose "Desktop app")
-
Add to .env file at Nexus root: GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com GOOGLE_CLIENT_SECRET=your-client-secret GOOGLE_PROJECT_ID=your-project-id
-
Run python3 00-system/skills/google/google-master/scripts/google_auth.py --login