📢 Placement Notifier (Telegram Bot)

An automated Node.js service that checks your Gmail inbox for placement emails (from your college’s placement cell), scans them for your name/registration number, and instantly notifies you on Telegram whether you are ✅ Shortlisted or ❌ Not Shortlisted.

---

✨ Features

• 🔍 Monitors unread emails from a specific placement cell email ID.

• 📑 Supports both:

  • Names in the email body
  • Names/roll numbers inside Excel attachments (.xls, .xlsx).

• 🤖 Sends instant Telegram alerts with:

  • Email subject
  • Shortlist status (✅ / ❌).

• ♻️ Runs automatically every 5 minutes (configurable).

• ⚡ Lightweight Express server included for health checks.

---

📂 Project Structure

placement-notifier/
│── index.js          # Main app logic
│── package.json      # Dependencies & scripts
│── .env              # Environment variables (not committed)
│── README.md         # Project documentation

---

🔧 Installation & Setup

1️⃣ Clone repo

git clone https://github.com/yourusername/placement-notifier.git
cd placement-notifier

2️⃣ Install dependencies

npm install

3️⃣ Configure .env

Create a .env file in the project root:

# Gmail
EMAIL_USER=yourgmail@gmail.com
EMAIL_PASS=your-16-digit-app-password
WATCH_EMAIL=placement@college.edu

# Student Info
YOUR_NAME=Deep Chakraborty
YOUR_REG_NO=123456

# Telegram Bot
TELEGRAM_TOKEN=1234567890:AAHkjsfh23ksdf...
TELEGRAM_CHAT_ID=987654321

⚠️ Use a Google App Password instead of your normal Gmail password.

4️⃣ Run locally

npm run start

5️⃣ Deploy (optional)

Deploy to cloud platforms like Render, Railway, Heroku, or DigitalOcean. Make sure to add all .env values in the platform’s environment variables section.

---

📲 Telegram Setup

1. Open @BotFather in Telegram.

2. Run /newbot → get your bot token.

3. Add the bot to your Telegram account or group.

4. Get your chat ID using:

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

   Send a message to your bot, then check the response JSON for "chat":{"id": ...}.

---

⚙️ Configurations

• Mail check interval: default = 5 minutes → change in code:

  setInterval(checkMails, 5 * 60 * 1000); // 5 mins

• Health check: visit http://localhost:3000/ → returns 📢 Placement Notifier (Telegram) is running!

---

📦 Libraries Used

• express → lightweight web server
• imap-simple → IMAP client for Gmail
• mailparser → parses email content
• xlsx → reads Excel attachments
• node-fetch → sends messages to Telegram API
• dotenv → loads .env configs

---

🚀 Example Notification

📢 Placement Alert

📌 Subject: Shortlist for TCS Digital

✅ You are shortlisted!

or

📢 Placement Alert

📌 Subject: Infosys Final Round Results

❌ You are NOT shortlisted.

---

👨‍💻 Author

Deep Chakraborty 📫 [Your Email] 💼 [LinkedIn/GitHub Profile]

---

🛡️ License

This project is licensed under the MIT License.

---