IMAP IDLE Watcher#

Real-time email watcher. Uses IMAP IDLE (server push) instead of polling. App passwords instead of OAuth — no token expiry, no re-auth.

Quick Start#

Interactive#

bash

bash scripts/setup_service.sh

Prompts for email, detects provider, gives app password link, tests connection, installs service.

Non-interactive#

bash

bash scripts/setup_service.sh \
  --account "user@gmail.com" \
  --password "xxxx xxxx xxxx xxxx" \
  --command "python3 /path/to/handler.py" \
  --service-name my-watcher

Test connection only#

bash

bash scripts/setup_service.sh --test --account "user@gmail.com" --password "xxxx"

Configuration (env vars)#

VariableDefaultDescriptionIMAP_ACCOUNT(required)Email addressIMAP_PASSWORD(required)App passwordIMAP_HOST``imap.gmail.comIMAP server (auto-detected from email)IMAP_PORT``993IMAP portIMAP_FOLDER``INBOXFolder to watchON_NEW_MAIL_CMD(optional)Shell command to run on new mailFILTER_FROM(optional)Only trigger for these senders (comma-separated, substring match)FILTER_SUBJECT(optional)Only trigger for these subjects (comma-separated, substring match)IDLE_TIMEOUT``1200Seconds before IDLE renewal (max 1740)DEBOUNCE_SECONDS``10Min seconds between command runs

Filtering#

Only process emails matching specific senders or subjects:

bash

FILTER_FROM=paypal.com,stripe.com      # from contains either (OR)
FILTER_SUBJECT=payment,invoice         # subject contains either (OR)

• Case-insensitive substring match
• Both FROM and SUBJECT must match if both set (AND)
• Within each filter, any value matches (OR)
• No filter set = process all emails

Writing a Handler#

The agent should write a handler script based on the user's intent. The daemon passes email metadata as env vars:

VariableExampleMAIL_FROM``John Doe <john@example.com>``MAIL_SUBJECT``Your order has shipped``MAIL_DATE``Mon, 17 Mar 2026 10:30:00 +0700``MAIL_UID``12345

Workflow#

1. User describes what they want (e.g. "watch my inbox, summarize new emails")
2. Agent writes a handler script (Python/Bash) that reads the env vars and does what the user asked
3. Agent saves it somewhere persistent (e.g. ~/email-handler.py)
4. Agent runs setup_service.sh with --command "python3 ~/email-handler.py"

Example: user says "notify me about new emails"#

Agent writes ~/email-handler.py:

python

#!/usr/bin/env python3
import os
print(f"New mail from {os.environ.get('MAIL_FROM', '?')}: {os.environ.get('MAIL_SUBJECT', '?')}")

Then wires it up:

bash

bash scripts/setup_service.sh --account "user@gmail.com" --password "xxxx" \
  --command "python3 ~/email-handler.py"

The handler is the agent's job — adapt it to whatever the user needs.

How It Works#

1. Connects to IMAP server with app password (SSL)
2. Enters IDLE mode — server holds connection open
3. Server pushes notification when new mail arrives (instant, no polling)
4. Daemon runs ON_NEW_MAIL_CMD with email metadata as env vars ( MAIL_FROM, MAIL_SUBJECT, MAIL_DATE, MAIL_UID)
5. Returns to IDLE. Renews every 20 min per RFC 2177.
6. Auto-reconnects on disconnect (backoff: 5s → 10s → 30s → 60s → 120s)

Service Management#

bash

systemctl status <service-name>
journalctl -u <service-name> -f
systemctl restart <service-name>
systemctl stop <service-name>

Uninstall#

bash

bash scripts/setup_service.sh --uninstall --service-name <service-name>

Provider Setup Guides#

• Gmail: see references/gmail.md
• Outlook: see references/outlook.md
• Yahoo: see references/yahoo.md

Troubleshooting#

See references/troubleshooting.md for common errors and fixes.