luffyDTaro/Gmail_Notifications

🚀 GMAIL Alert Bot

Smart Gmail → Telegram notification system for GMAIL alerts.

Monitors your Gmail for GMAIL -related emails and sends real-time notifications to your Telegram — 100% FREE. Includes a premium web dashboard for live configuration.

✨ Features

• —� Web Dashboard: Configure everything from a beautiful dark-theme UI
• —�🎛 Two Alert Modes: all (every email) or filtered (smart filtering)
• —✅ Whitelist: Only alert for specific senders or keywords
• —🚫 Blacklist: Auto-skip spam, promos, irrelevant emails (overrides whitelist)
• —🏷 Safe Processing: Uses PROCESSED_BY_BOT label — no emails lost, no mark-as-read
• —🔄 Retry Logic: Exponential backoff if Telegram fails
• —💾 Hot-Reload: Change settings from dashboard — no restart needed
• —📊 Live Stats: Track checks, alerts, skipped emails in real-time
• —☁ Free Deployment: Ready for Hugging Face Spaces

📋 Setup Guide (Step-by-Step)

Step 1: Install Dependencies

cd GMAIL -alert-bot
npm install

Step 2: Create Telegram Bot & Get Chat ID

2a. Create the Bot

1. 1.Open Telegram → search for @BotFather
2. 2.Send /start then /newbot
3. 3.Choose a name and username
4. 4.Copy the Bot Token (looks like 123456:ABC-DEF...)

2b. Get Your Chat ID

1. 1.Open Telegram → send any message (like "hi") to your new bot
2. 2.Open this URL in browser (replace <TOKEN> with your bot token):

   https://api.telegram.org/bot<TOKEN>/getUpdates

1. 1.Look for "chat": { "id": 123456789 } — that number is your Chat ID

Step 3: Configure Environment

1. 1.Copy the example env file:

   copy .env.example .env

1. 1.Edit .env — you only need to fill in two values to get started:

   TELEGRAM_BOT_TOKEN=your_actual_bot_token
   TELEGRAM_CHAT_ID=your_actual_chat_id

1. 1.Everything else (alert mode, whitelist, blacklist, etc.) can be configured later from the web dashboard.

Step 4: Set Up Gmail API (Free)

4a. Create Google Cloud Project

1. 1.Go to Google Cloud Console
2. 2.Click "Select a project" → "New Project"
3. 3.Name it (e.g., "GMAIL Alert Bot") → Create

4b. Enable Gmail API

1. 1.Go to APIs & Services → Library
2. 2.Search for "Gmail API"
3. 3.Click it → Enable

4c. Configure OAuth Consent Screen

1. 1.Go to APIs & Services → OAuth consent screen
2. 2.Select External → Create
3. 3.Fill in:
4. 4.App name: GMAIL Alert Bot
5. 5.User support email: your email
6. 6.Developer email: your email
7. 7.Click Save and Continue through all steps
8. 8.Go to Test users → Add Users → add your Gmail address

4d. Create OAuth Credentials

1. 1.Go to APIs & Services → Credentials
2. 2.Click Create Credentials → OAuth client ID
3. 3.Application type: Desktop app
4. 4.Name: anything (e.g., "Alert Bot")
5. 5.Click Create
6. 6.Click Download JSON
7. 7.Rename the downloaded file to credentials.json
8. 8.Place it in the project root (same folder as package.json)

Step 5: Create Gmail Filter (Optional but Recommended)

In Gmail:

1. 1.Click the search bar → Click the filter icon → Create filter
2. 2.Set rules like:
3. 3.From: GMAIL OR hr
4. 4.Subject: interview OR test OR assignment
5. 5.Click Create filter → Check Apply label → Create label GMAIL _ALERT
6. 6.Also check Also apply to matching conversations

Step 6: Run Setup Wizard

npm run setup

This will:

• —✅ Verify your .env configuration
• —✅ Test Telegram bot connection
• —✅ Guide you through Gmail OAuth (opens browser)
• —✅ Save your auth token

Step 7: Start the Bot

npm start

You'll see:

🚀 GMAIL  Alert Bot — Starting...
✅ Gmail authenticated!
📋 PROCESSED_BY_BOT label ready
📱 Startup notification sent to Telegram!
📊 Dashboard: http://localhost:7860
🟢 Bot is running.

Open http://localhost:7860 in your browser to access the configuration dashboard!

🌐 Web Dashboard

The dashboard lets you configure everything from your browser — no need to edit .env manually:

Changes are saved to .env and applied instantly — no restart needed.

🎛 Configuration Reference

Filtering Logic

1. Fetch unread emails (not yet processed by bot)
2. For each email:
   → If sender in BLACKLIST → SKIP
   → If subject has BLACKLIST keyword → SKIP
   → If ALERT_MODE = "all" → SEND
   → If ALERT_MODE = "filtered":
       → If sender in WHITELIST → SEND
       → If subject has WHITELIST keyword → SEND
       → Otherwise → SKIP
3. On successful Telegram send → Add PROCESSED_BY_BOT label
4. Failed sends → email stays unprocessed, retried next cycle

☁ Deploy on Hugging Face Spaces (Free, 24/7)

What Goes Where

Since the dashboard handles most configuration, you only need 3 things as Hugging Face Space Secrets:

⚠️ Note: Dashboard changes are saved to .env in the container, but are lost on container restart. For persistent settings, set them as Hugging Face Space Secrets.

Deployment Steps

1. 1.Create a new Space at huggingface.co/spaces
2. 2.Select Docker as the SDK
3. 3.Upload all project files (except .env, credentials.json, token.json)
4. 4.Add required secrets in Space Settings → Secrets:
5. 5.TELEGRAM_BOT_TOKEN = your bot token
6. 6.TELEGRAM_CHAT_ID = your chat ID
7. 7.Encode `credentials.json` and `token.json` as base64:

On your PC, run these commands to get the base64 strings:

   # PowerShell
   [Convert]::ToBase64String([IO.File]::ReadAllBytes("credentials.json"))
   [Convert]::ToBase64String([IO.File]::ReadAllBytes("token.json"))

Add these as Space Secrets:

• —GOOGLE_CREDENTIALS = base64 output of credentials.json
• —GOOGLE_TOKEN = base64 output of token.json

1. 1.Update `Dockerfile` entry point to decode secrets at startup (see below)
2. 2.Space builds and deploys automatically — your bot runs 24/7!

Updated Dockerfile (for base64 secrets)

The included Dockerfile already handles this. On startup, if GOOGLE_CREDENTIALS and GOOGLE_TOKEN environment variables exist, the app will decode them into files.

📁 Project Structure

GMAIL -alert-bot/
├── package.json
├── .env.example            # Environment template
├── .env                    # Your actual config (git-ignored)
├── .gitignore
├── credentials.json        # Gmail OAuth creds (git-ignored)
├── token.json              # Saved auth token (git-ignored)
├── setup.js                # Interactive setup wizard
├── Dockerfile              # For Hugging Face deployment
├── README.md
├── public/
│   └── dashboard.html      # Web dashboard UI
└── src/
    ├── index.js             # Main entry point + scheduler
    ├── config.js            # Config loader + validator
    ├── auth.js              # Gmail OAuth2 authentication
    ├── gmail.js             # Email fetching + filtering
    ├── telegram.js          # Telegram notifications
    └── dashboard.js         # Dashboard API routes

🎯 Resume-Worthy Description

Smart GMAIL Alert System Built a real-time email monitoring system using Node.js, Gmail API (OAuth2), and Telegram Bot API. Features a premium web dashboard for live configuration, dual alert modes with whitelist/blacklist filtering, safe-processing with custom Gmail labels, retry logic with exponential backoff, and containerized cloud deployment on Hugging Face Spaces.

🛠 Troubleshooting