Gmail Inbox Agent

A small local agent that monitors a Gmail inbox and sends a short Telegram summary about emails waiting for a reply.

What it does

• Reads Gmail inbox (read-only)
• Detects threads waiting for your reply
• Stores state locally (SQLite)
• Sends a short, privacy-safe Telegram summary
• Runs on a schedule (cron)

No email bodies or sensitive content are sent outside Gmail.

Tech stack

• Node.js
• Gmail API (OAuth, read-only)
• SQLite
• Telegram Bot API
• Cron

Setup

1. Install dependencies

npm install
2. Environment variables
Create a .env file:
MY_EMAIL=your.email@company.com
TELEGRAM_BOT_TOKEN=xxxx
TELEGRAM_CHAT_ID=xxxx
3. Gmail API
•	Create a Google Cloud project
•	Enable Gmail API
•	Create OAuth credentials (Desktop app)
•	Download credentials JSON
•	Place it in:
credentials/gmail.json
First run will open a browser for OAuth consent.
4. Run manually
npm run dev
5. Run automatically
Use cron to run twice per day, for example:
•	08:00 CET
•	16:00 CET
## Scheduled execution (cron)
The agent is designed to run automatically on the local machine using cron.
Current setup:
- Runs twice per day
- 08:00 CET
- 16:00 CET
- Executed via macOS cron
- Sends a Telegram summary only (no inbox actions)
Example cron entries:
```cron0 8 ***cd /Users/46elks/gmail-inbox-agent && /usr/bin/env node src/index.js0 16 ***cd /Users/46elks/gmail-inbox-agent && /usr/bin/env node src/index.jsNotes	•	Designed to run locally	•	Personal inbox use	•	Easy to extend but intentionally simple