Gmail Telegram Agent

A fully customizable AI-powered Email Agent in Java that reads your Gmail inbox, classifies incoming emails by priority using an LLM, and delivers formatted summaries to your Telegram account at scheduled intervals.

Features

• OAuth2 Authentication: Securely connects to Gmail without needing app passwords.
• AI Classification: Uses OpenAI-compatible APIs to categorize emails and determine priority (HIGH, MEDIUM, LOW).
• Rich Telegram Summaries: Delivers clean, emoji-rich markdown messages.
• Configurable Scheduler: Runs automatically every few hours (default: 3).
• Extensible: Easy to customize categories, rules, and AI models.

---

Setup Instructions

Step 1 - Create Telegram Bot

1. Open Telegram, search for @BotFather.
2. Send /newbot and follow prompts to get a bot token.
3. Send any message to your new bot.
4. Visit https://api.telegram.org/bot{YOUR_TOKEN}/getUpdates in a browser.
5. Find "chat":{"id": 123456789} and save that number as your TELEGRAM_CHAT_ID.

Step 2 - Enable Gmail API

1. Go to console.cloud.google.com and create a new project.
2. Enable the Gmail API under APIs & Services > Library.
3. Configure the OAuth consent screen (External, add your email as a test user, add the gmail.readonly scope).
4. Create credentials: OAuth client ID > Desktop app > Download JSON.
5. Rename the downloaded file to credentials.json and place it in the root of this project.

Step 3 - Configure .env

1. Run: cp .env.example .env
2. Fill in TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, and OPENAI_API_KEY.

Step 4 - First Run (OAuth Authorization)

1. Run: mvn clean package
2. Run: ./run.sh --once
3. A browser window will open — log in to Google and grant Gmail read access.
4. A tokens/ folder is created; you will not need to authorize again.

Step 5 - Start the Scheduled Agent

Run: ./run.sh The agent will process emails immediately and then every 3 hours automatically.

---

Run Modes

• Scheduled (Default): ./run.sh
• Single Run: ./run.sh --once
• Connection Test: ./run.sh --test

---

Customization Plan

CUSTOMIZATION 1 - Email Categories

In EmailClassifier.java, modify the SYSTEM_PROMPT to add or rename categories based on personal needs. For example, add a FREELANCE category for Upwork/Fiverr/client emails, or a GOVERNMENT category for official notices. Update the getCategoryEmoji() method in TelegramService.java to add matching emojis for new categories.

CUSTOMIZATION 2 - Summary Frequency

In the .env file, change SCHEDULER_INTERVAL_HOURS to any value (e.g., 1 for hourly, 6 for twice a day, 24 for daily digest). The fetchRecentEmails() method automatically adjusts the lookback window to match this interval.

CUSTOMIZATION 3 - AI Model Selection

In the .env file, change AI_MODEL to any OpenAI-compatible model:

• gpt-4.1-nano for cheapest/fastest classification
• gpt-4.1-mini for balanced cost and accuracy (recommended default)
• gpt-4o for highest accuracy on complex emails

To use a different provider (e.g., Groq, Mistral, local Ollama), change AI_API_BASE_URL to the provider's base URL and set AI_MODEL to the appropriate model name.

CUSTOMIZATION 4 - Priority Rules

In the SYSTEM_PROMPT inside EmailClassifier.java, edit the "Priority rules" section to match your personal priorities. For example, if you are a freelancer, add "Freelance project inquiries = HIGH priority". If you want all bank emails as HIGH, add that rule explicitly.

CUSTOMIZATION 5 - Summary Format

In TelegramService.java, modify the formatSummary() method to change the message layout. For example, list ALL emails including LOW priority, add clickable email links, include the time each email was received, or change the emoji set.

CUSTOMIZATION 6 - Gmail Filter

In GmailService.java, modify the query string in fetchRecentEmails() to pre-filter emails before AI classification. For example:

• "is:unread after:{timestamp} label:inbox" to exclude spam/promotions
• "is:unread after:{timestamp} from:(@company.com)" to only process emails from a specific domain
• "is:unread after:{timestamp} -category:promotions" to skip Gmail's promotions tab

CUSTOMIZATION 7 - Multiple Telegram Recipients

In TelegramService.java, change TELEGRAM_CHAT_ID to a comma-separated list and loop through each chat ID when calling sendMessage(). Update AppConfig.java to parse the value as a List<String>. (Note: This is already implemented in the base code!)

CUSTOMIZATION 8 - Deployment as a Background Service

To run 24/7 on a Linux server or Raspberry Pi, create a systemd service file at /etc/systemd/system/email-agent.service with the working directory, ExecStart pointing to the run.sh script, and Restart=always. Enable it with: sudo systemctl enable email-agent && sudo systemctl start email-agent.