Telegram - Gmail Assistant
An event-driven Gmail assistant that classifies incoming messages and brings decisions into Telegram, with human approval before sending replies or creating calendar events.
View on GitHubProblem & context
Email triage involves repeated decisions: what matters, what needs a reply, and what should become a calendar event.
My contribution
I mapped the triage workflow, designed the routing and approval states, and built the system end to end in Python — from the Gmail event intake through LangGraph orchestration to the Telegram decision interface and deployment.
Workflow
Gmail notification
Google Pub/Sub push
Receive & persist event
PostgreSQL, idempotent
Classify
OpenAI via LangGraph
Route by required action
- No action
- Label
- Draft reply
- Calendar event
Decision in Telegram
Human approval
Approved action
Send reply / create event
Persist processed state
Technology
- Python
- FastAPI
- Google Pub/Sub
- LangGraph
- OpenAI
- Telegram Bot API (webhooks)
- Gmail API
- Google Calendar API
- PostgreSQL
- Docker
- Oracle VPS + HTTPS reverse proxy
Key design decisions
Not every email needs an action
The router has explicit no-action and labelling paths. Most messages should be quietly sorted, not surfaced — the assistant only interrupts when a decision is genuinely needed.
Drafts, not sends
Replies are drafted by the model and presented in Telegram. Nothing is sent until I approve it. Calendar events follow the same rule: the assistant proposes, I confirm, then it creates the event.
Why human-in-the-loop
Email carries commitments. An automated reply or a wrongly-booked meeting has real consequences, so the system is designed to reduce effort on each decision rather than remove the decision itself.
Persisted state and idempotency
Push notifications can arrive more than once or out of order. Each event is persisted on receipt and processed idempotently, so a retried notification never produces a duplicate reply or event, and the workflow can resume after a restart.
Capabilities & limitations
Implemented
- Event-driven intake of new Gmail messages
- Classification, summaries, and reply drafting
- Telegram-based approval for replies and calendar events
- Persisted, idempotent event processing
Limitations
- Built and operated as a personal system for a single mailbox
- Runs on a single VPS rather than a highly available platform
Future improvements
Not yet implemented.
- Exploring improved classification and learning from approval feedback — exploratory, not implemented
Have a workflow worth automating?
I'm interested in AI-focused roles and conversations about building useful, practical agentic AI systems.