An intelligent email-to-Telegram urgency filter that watches your inbox, judges each message for genuine urgency using AI, and proactively alerts you via Telegram only when something actually warrants an interruption.
Built for people drowning in email who need their attention protected, not just their notifications filtered.
Most notification systems are binary: all or nothing. Email filters and rules are static — they can't understand context, urgency, or whether "the third follow-up today from this person" means something different than the first.
worth-a-ping solves this by:
- Watching a noisy channel (email) where anyone can reach you
- Judging each message contextually using Gemini, which considers:
- Message content and tone
- Sender identity
- Recent conversation history (is this the 3rd follow-up today?)
- Time-sensitive signals (production down, hard deadlines)
- Alerting on a clean channel (Telegram) that you actually check, only when something genuinely needs you right now
This isn't message routing — it's intelligent triage. The agent learns from your conversation patterns, defaults to silence, and only interrupts when precision is high.
- caspian-sdk — Email monitoring with automatic message routing
- python-telegram-bot — Direct Telegram Bot API integration for proactive alerts
- Gemini API (gemini-3.5-flash-lite) — Low-latency, cost-effective urgency classification
- SQLite — Conversation history for context-aware judgments
- Python 3.11+ — Single long-running backend process
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txtGemini API:
- Visit Google AI Studio
- Create a free API key
Caspian API:
- Install the CLI:
pip install caspian-cli - Run
caspian initto generate your API key automatically - This will create your Caspian identity and write credentials to
.env
- Open Telegram and search for @BotFather
- Send
/newbotand follow the prompts - Give it a name (e.g., "Worth A Ping Alert Bot")
- Give it a username ending in "bot" (e.g., "worthaping_bot")
- Copy the bot token (format:
123456789:ABCdef...)
- Open Telegram and search for @userinfobot
- Send it any message
- Copy your numeric user ID (e.g.,
123456789)
cp .env.example .envEdit .env and fill in:
CASPIAN_API_KEY=<auto-generated by caspian init>
CASPIAN_BASE_URL=https://api.trycaspianai.com
GEMINI_API_KEY=<your_gemini_api_key>
TELEGRAM_BOT_TOKEN=<bot_token_from_botfather>
TELEGRAM_CHAT_ID=<your_numeric_chat_id>caspian connect emailThis will give you an email address like:
agt-xxxxxxxx@agents.trycaspianai.com
Save this address — all emails sent to it will be monitored by the agent.
Before the agent can send you alerts:
- Open Telegram and search for your bot's username
- Start a chat and send
/start
source venv/bin/activate
python main.pyYou should see:
🔌 Initializing worth-a-ping agent...
✅ Agent ready. Listening for messages...
Test 1: Urgent Message
Send an email to your agent's email address with urgent content:
To: agt-xxxxxxxx@agents.trycaspianai.com
Subject: Production Emergency
Body:
URGENT: The production database is completely offline.
Users cannot login and we're losing customers.
Need immediate assistance!
Expected result:
- Terminal:
[inbound] "URGENT: The production database..." → ALERT → Telegram sent - Telegram: You receive an alert from your bot with the message + AI reasoning
Test 2: Non-Urgent Message
Send a casual email:
Body:
Hey! Are we still on for lunch tomorrow?
Let me know what time works for you.
Expected result:
- Terminal:
[inbound] "Hey! Are we still on for lunch..." → SKIP (casual social message...) - Telegram: No alert (proving the precision bias works)
Every inbound email is evaluated by Gemini using a carefully designed prompt that:
- Defaults to NOT urgent — Precision over recall. False alarms defeat the purpose.
- Considers conversation context — If this is the 3rd message today from someone, that matters.
- Looks for genuine urgency signals:
- Production outages, system failures, security incidents
- Time-sensitive opportunities with hard deadlines (today/tonight)
- Critical personal emergencies
- Explicit "need you now" from VIPs
- Filters out noise:
- Newsletters, marketing, automated notifications
- Meeting invites for future dates
- FYI updates without time pressure
- Routine follow-ups
- Social messages that can wait
The model returns structured JSON with a boolean urgency flag and a one-line reason. The reason is logged to the database and included in Telegram alerts so you can see why the agent thought something was urgent.
The system is intentionally biased toward not interrupting you. A false negative (missing an urgent message) is recoverable — you'll see it eventually when you check email. A false positive (getting pinged for non-urgent stuff) trains you to ignore the alerts, which defeats the entire purpose.
This is reflected in the prompt design, the default-to-skip logic, and the fallback behavior (if the AI fails to parse, assume not urgent).
worth-a-ping/
├── main.py # Entrypoint: client setup, message handler, event loop
├── triage.py # Gemini judgment logic (isolated for easy tuning)
├── db.py # SQLite helpers: logging, context retrieval, alert tracking
├── requirements.txt # Python dependencies
├── .env.example # Template for configuration
├── .gitignore # Excludes .env and *.db
└── README.md # This file
[Link to demo video will be added here]
If you're getting too many or too few alerts, edit the SYSTEM_PROMPT in triage.py to adjust the criteria. The model is instruction-following, so clear natural language changes (e.g., "Be more conservative about what counts as urgent") will directly affect behavior.
You can also test the judgment in isolation:
python triage.pyThis runs a few hardcoded test cases and prints the model's verdicts.
MIT