imap-idle-watcher

# 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) | Variable | Default | Description | |----------|---------|-------------| | `IMAP_ACCOUNT` | (required) | Email address | | `IMAP_PASSWORD` | (required) | App password | | `IMAP_HOST` | `imap.gmail.com` | IMAP server (auto-detected from email) | | `IMAP_PORT` | `993` | IMAP port | | `IMAP_FOLDER` | `INBOX` | Folder to watch | | `ON_NEW_MAIL_CMD` | (optional) | Shell command to run on new mail | | `FILTER_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` | `1200` | Seconds before IDLE renewal (max 1740) | | `DEBOUNCE_SECONDS` | `10` | Min 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: | Variable | Example | |----------|---------| | `MAIL_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](references/gmail.md) - Outlook: see [references/outlook.md](references/outlook.md) - Yahoo: see [references/yahoo.md](references/yahoo.md) ## Troubleshooting See [references/troubleshooting.md](references/troubleshooting.md) for common errors and fixes.