An intelligent email monitoring agent that reads your Gmail in real time, analyzes every incoming message using AI, and instantly delivers categorized, actionable summaries to your Telegram — so you never miss what matters.
- Real-time Gmail Monitoring — Checks for new emails every 60 seconds, automatically skipping existing ones on startup.
- AI-Powered Analysis — Every email is analyzed by GPT-4o-mini: category, importance score, summary, and action required.
- Smart Filtering — Ads, newsletters, and promotional emails are silently ignored. Only what matters reaches you.
- Instant Telegram Notifications — Get structured, readable summaries delivered directly to your Telegram bot.
- 7 Smart Categories — Job applications, personal messages, invoices, meeting invites, important alerts, and more.
- Zero Noise — Importance scoring (1–10) ensures low-value emails never interrupt you.
| Tool | Purpose |
|---|---|
| Python | Core programming language |
| Gmail API | Email access via OAuth 2.0 |
| OpenAI GPT-4o-mini | Email analysis & categorization |
| Telegram Bot API | Real-time push notifications |
| python-dotenv | Secure environment variable management |
mail-tracker/
├── main.py # Entry point — monitoring loop
├── gmail_client.py # Gmail OAuth connection & email fetching
├── ai_analyzer.py # OpenAI-powered email analysis
├── telegram_client.py # Telegram notification delivery
├── requirements.txt # Python dependencies
├── .env.example # Environment variable template
└── credentials.json # Gmail OAuth credentials (not committed)
1. Clone the repository
git clone https://github.com/ozeg8/mail-tracker.git
cd mail-tracker2. Install dependencies
pip install -r requirements.txt3. Set up Gmail API
- Go to Google Cloud Console
- Create a project and enable the Gmail API
- Create OAuth 2.0 credentials (Desktop App)
- Download
credentials.jsonand place it in the project root
4. Create a Telegram Bot
- Message @BotFather on Telegram
- Create a new bot and copy the token
- Get your chat ID via
https://api.telegram.org/bot<TOKEN>/getUpdates
5. Configure environment variables
Create a .env file in the project root:
OPENAI_API_KEY=your_openai_api_key
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_telegram_chat_id6. Run
python main.pyOn first run, a browser window will open for Gmail authorization. After that, token.json is created and authorization is automatic.
💰 Fatura/Ödeme
👤 Gönderen: John Doe <john@example.com>
📋 Konu: Invoice #1042
📝 Özet: Monthly subscription invoice for April 2026.
⚡ Aksiyon: Evet
🕐 Sat, 11 Apr 2026 12:05:59 +0300