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:

```cron
0 8 * * * cd /Users/46elks/gmail-inbox-agent && /usr/bin/env node src/index.js
0 16 * * * cd /Users/46elks/gmail-inbox-agent && /usr/bin/env node src/index.js

Notes
	•	Designed to run locally
	•	Personal inbox use
	•	Easy to extend but intentionally simple