Gmail Manager
Full inbox management via Google Gmail API: read, summarize, draft, send, and search emails.
Prerequisites
- Google OAuth must be set up:
python3 ~/.claude/skills/_google-auth/scripts/setup.py
- Gmail API enabled in Google Cloud project
- Python packages:
google-auth-oauthlib, google-api-python-client
Command Routing
| User Says |
Action |
| "check email", "inbox", "read emails" |
Read & Summarize |
| "check email last 3 days" |
Read with timeframe |
| "send email to X", "email X" |
Draft → Review → Send |
| "search email about X" |
Search |
| No args / just "/gmail" |
Read today's unread |
Workflow: Read & Summarize Inbox
- Run the read script:
python3 ~/.claude/skills/gmail/scripts/read_emails.py --since today --unread
Options: --since "2 days ago", --since "2026-02-20", --max 20
Parse the JSON output (array of email objects with: from, subject, snippet, date, labels, unread, important)
Categorize each email:
- Urgent: Important flag, from known contacts, interview/offer keywords
- Needs Reply: Questions directed at user, action items
- FYI: Newsletters, notifications, automated emails
- Promotions: Marketing, sales emails
Present summary:
## Inbox Summary (Feb 25, 2026)
### Urgent (2)
- **Amazon Recruiter** - "Next steps for your application" - 10:30 AM
- **Professor Smith** - "Lab 5 deadline extended" - 9:15 AM
### Needs Reply (1)
- **GAUDON Client** - "Revised project timeline" - Yesterday
### FYI (3)
- GitHub notification - PR merged
- Canvas - Assignment 4 graded
- LinkedIn - 5 new connection requests
Workflow: Send Email (ALWAYS Draft-First)
CRITICAL: Never send without user confirmation.
MUST READ references/email-rules.md before composing any email.
Composition Rules
- New emails: Use time-appropriate greeting (Good morning / Good afternoon / Good evening) based on current time
- Replies/follow-ups: Use respectful acknowledgment ("Thank you for your response", "I appreciate you getting back to me")
- NEVER use dashes (--) or hyphens (-) as separators or bullet points in email body
- Keep emails concise and well structured. Short paragraphs, one idea per paragraph.
- Signature is auto-appended from
references/signature.html. Use --no-signature to skip.
Steps
- User provides: recipient, subject, body (or conversational intent)
- Read
references/email-rules.md for formatting rules
- Compose a professional email draft following the rules
- Show draft to user for confirmation
- Only after user confirms, run:
python3 ~/.claude/skills/gmail/scripts/send_email.py \
--to "recipient@email.com" \
--subject "Subject line" \
--body "Full email body here"
Optional: --cc, --bcc, --attach file1.pdf file2.pdf, --no-signature
- Report confirmation with message ID.
Workflow: Search Emails
python3 ~/.claude/skills/gmail/scripts/search_emails.py "search query" --max 10
Gmail search supports:
from:sender@email.comsubject:keywordhas:attachmentfilename:pdfafter:2026/02/01 before:2026/02/25- Free text search across all fields
Email Templates
See references/templates.md for pre-built templates:
- Interview follow-up / thank-you
- Recruiter response
- Cold outreach
- Professional inquiry
When composing, pick the appropriate template and personalize it.
Error Handling
| Error |
Solution |
| "OAuth credentials not found" |
Run setup: python3 ~/.claude/skills/_google-auth/scripts/setup.py |
| "Token expired" |
Script auto-refreshes; if fails, re-run setup |
| "Insufficient permissions" |
Re-run setup to re-authorize with Gmail scopes |
| Empty inbox result |
Widen the date range or check query syntax |
Safety Rules
- NEVER send email without showing draft and getting explicit user confirmation
- Never expose full email content of third parties without user request
- Truncate long email bodies in summaries (show snippet only)
- Don't auto-reply to any emails
1---2name: gmail3description: Full Gmail manager - read, summarize, draft, send, and search emails via Google Gmail API. Use when the user says "check email", "gmail", "inbox", "send email", "email this person", "compose email", "mail", "read emails", "draft email", "search email", or wants to manage their Gmail inbox.4---56# Gmail Manager78Full inbox management via Google Gmail API: read, summarize, draft, send, and search emails.910## Prerequisites11121. Google OAuth must be set up: `python3 ~/.claude/skills/_google-auth/scripts/setup.py`132. Gmail API enabled in Google Cloud project143. Python packages: `google-auth-oauthlib`, `google-api-python-client`1516## Command Routing1718| User Says | Action |19|-----------|--------|20| "check email", "inbox", "read emails" | Read & Summarize |21| "check email last 3 days" | Read with timeframe |22| "send email to X", "email X" | Draft → Review → Send |23| "search email about X" | Search |24| No args / just "/gmail" | Read today's unread |2526## Workflow: Read & Summarize Inbox27281. Run the read script:29```bash30python3 ~/.claude/skills/gmail/scripts/read_emails.py --since today --unread31```32Options: `--since "2 days ago"`, `--since "2026-02-20"`, `--max 20`33342. Parse the JSON output (array of email objects with: from, subject, snippet, date, labels, unread, important)35363. Categorize each email:37 - **Urgent**: Important flag, from known contacts, interview/offer keywords38 - **Needs Reply**: Questions directed at user, action items39 - **FYI**: Newsletters, notifications, automated emails40 - **Promotions**: Marketing, sales emails41424. Present summary:43```44## Inbox Summary (Feb 25, 2026)4546### Urgent (2)47- **Amazon Recruiter** - "Next steps for your application" - 10:30 AM48- **Professor Smith** - "Lab 5 deadline extended" - 9:15 AM4950### Needs Reply (1)51- **GAUDON Client** - "Revised project timeline" - Yesterday5253### FYI (3)54- GitHub notification - PR merged55- Canvas - Assignment 4 graded56- LinkedIn - 5 new connection requests57```5859## Workflow: Send Email (ALWAYS Draft-First)6061**CRITICAL: Never send without user confirmation.**6263**MUST READ `references/email-rules.md` before composing any email.**6465### Composition Rules66- **New emails**: Use time-appropriate greeting (Good morning / Good afternoon / Good evening) based on current time67- **Replies/follow-ups**: Use respectful acknowledgment ("Thank you for your response", "I appreciate you getting back to me")68- **NEVER** use dashes (--) or hyphens (-) as separators or bullet points in email body69- Keep emails concise and well structured. Short paragraphs, one idea per paragraph.70- Signature is auto-appended from `references/signature.html`. Use `--no-signature` to skip.7172### Steps731. User provides: recipient, subject, body (or conversational intent)742. Read `references/email-rules.md` for formatting rules753. Compose a professional email draft following the rules764. Show draft to user for confirmation775. Only after user confirms, run:78```bash79python3 ~/.claude/skills/gmail/scripts/send_email.py \80 --to "recipient@email.com" \81 --subject "Subject line" \82 --body "Full email body here"83```84Optional: `--cc`, `--bcc`, `--attach file1.pdf file2.pdf`, `--no-signature`85866. Report confirmation with message ID.8788## Workflow: Search Emails8990```bash91python3 ~/.claude/skills/gmail/scripts/search_emails.py "search query" --max 1092```9394Gmail search supports:95- `from:sender@email.com`96- `subject:keyword`97- `has:attachment`98- `filename:pdf`99- `after:2026/02/01 before:2026/02/25`100- Free text search across all fields101102## Email Templates103104See `references/templates.md` for pre-built templates:105- Interview follow-up / thank-you106- Recruiter response107- Cold outreach108- Professional inquiry109110When composing, pick the appropriate template and personalize it.111112## Error Handling113114| Error | Solution |115|-------|----------|116| "OAuth credentials not found" | Run setup: `python3 ~/.claude/skills/_google-auth/scripts/setup.py` |117| "Token expired" | Script auto-refreshes; if fails, re-run setup |118| "Insufficient permissions" | Re-run setup to re-authorize with Gmail scopes |119| Empty inbox result | Widen the date range or check query syntax |120121## Safety Rules122123- **NEVER send email without showing draft and getting explicit user confirmation**124- Never expose full email content of third parties without user request125- Truncate long email bodies in summaries (show snippet only)126- Don't auto-reply to any emails
theaayushstha1