Check Gmail for unread inbox emails, filtered by priority. Use when asked to check emails, check inbox, email digest, email summary, or "any new mail". Outputs a brief list sorted by priority (HIGH/MEDIUM/LOW). Skips marketing, promotions, social, and update categories. Configurable via gmail-config.json.
Fetch unread Gmail messages, filter out noise, deliver a prioritized digest.
Your inbox is full of automated emails, promotions, and updates. This skill surfaces what actually matters — security alerts, personal messages, and anything you've flagged as important.
First-time users need Google OAuth credentials. If the script exits with a "missing file" error, read references/setup.md and walk the user through the setup flow.
pip install google-api-python-client google-auth-oauthlib
python3 scripts/check_gmail.py [hours] # default: last 24h
python3 scripts/check_gmail.py --json [hours] # structured JSON output
Config: Copy config.example.json to <DATA_DIR>/gmail-config.json and customize. The script prints the resolved <DATA_DIR> path if credentials are missing.
Credentials and config resolve to:
1. $SKILL_DATA_DIR (set by agent platform)
2. ~/.config/gmail-checker/ (default fallback)
Any platform can set $SKILL_DATA_DIR to their preferred credential store. If unset, ~/.config/gmail-checker/ is used automatically. Works with OpenClaw, Claude Code, Codex, and any agent that can run Python scripts.
🔴 HIGH → Sender domain or subject matches your config
🟡 MEDIUM → Gmail-labeled personal messages
🟢 LOW → Everything else (still inbox, still unread)
Filtered out entirely:
• CATEGORY_PROMOTIONS
• CATEGORY_UPDATES
• CATEGORY_FORUMS
• CATEGORY_SOCIAL
Customize priorities in gmail-config.json:
high_priority_domains: ["stripe.com", "github.com"]
high_priority_keywords: ["security", "urgent", "billing"]
Unread Inbox (last 24h)
🔴 HIGH
Security alert: new sign-in from unknown device
from: Google <[email protected]>
🟡 MED
Re: dinner friday?
from: Sarah <[email protected]>
🟢 LOW
Your weekly GitHub digest
from: GitHub <[email protected]>
3 unread emails
Adapt formatting for the current channel (bold, bullets, etc.).