Monitor a Gmail inbox for new emails matching keywords and send real-time Telegram alerts while starring important messages in Gmail.
# Gmail Lead Monitor
Monitor any Gmail inbox and get instant Telegram alerts for important emails. Configure keywords to filter for leads, orders, or support inquiries. Zero dependencies beyond Python stdlib — no pip required.
## What It Does
- Connects to Gmail via IMAP (no OAuth, just app password)
- Checks for new emails every N minutes (configurable)
- Sends Telegram alert with sender, subject, and snippet
- Detects important emails by keyword matching
- Marks important emails with Gmail STAR flag
- Tracks seen emails to avoid duplicate alerts
## Setup
### 1. Enable Gmail App Password
1. Go to [myaccount.google.com/security](https://myaccount.google.com/security)
2. Enable 2-Step Verification
3. Go to App passwords → Generate new app password
4. Select "Mail" and your device → Copy the 16-char password
### 2. Create Config File
```bash
mkdir -p ~/.config/gmail_monitor
cat > ~/.config/gmail_monitor/config.json << 'EOF'
{
"email": "you@gmail.com",
"app_password": "xxxx xxxx xxxx xxxx",
"telegram_token": "your_bot_token",
"telegram_chat_id": "your_chat_id",
"keywords": ["order", "purchase", "setup", "interested", "question", "invoice"],
"check_interval_minutes": 5,
"max_emails_per_check": 20
}
EOF
```
### 3. Get Telegram Bot Token
1. Message [@BotFather](https://t.me/BotFather) on Telegram
2. `/newbot` → follow prompts
3. Copy the bot token
4. Get your chat ID from [@userinfobot](https://t.me/userinfobot)
## Usage
```bash
# Run once (check now)
python3 gmail_monitor.py --once
# Run in daemon mode (default interval from config)
python3 gmail_monitor.py
# Custom interval
python3 gmail_monitor.py --interval 10
# Run via cron every 5 minutes
*/5 * * * * python3 /path/to/gmail_monitor.py --once >> /tmp/gmail_monitor.log 2>&1
```
## Alert Example (Telegram)
```
📧 New Lead — Gmail
From: john@company.com
Subject: Question about your service
Time: 2025-03-15 14:22 PST
"Hi, I'm interested in your product and had a question about..."
⭐ Marked as important (keyword: question)
```
## Keyword Matching
Keywords match against: subject line + sender name + first 200 chars of body.
Case-insensitive. Add your own in config:
```json
"keywords": ["order", "purchase", "invoice", "urgent", "setup", "question", "interested", "trial"]
```
## Requirements
- Python 3.6+
- Gmail account with App Password enabled
- Telegram bot (free)
- Zero pip dependencies
don't have the plugin yet? install it then click "run inline in claude" again.