IMAP IDLE Watcher

Real-time email monitoring using IMAP IDLE — no OAuth, no token expiration. Sets up a persistent connection to any IMAP server (Gmail, Outlook, Yahoo, etc.)...

Security Scan

The skill's code and instructions match the claimed purpose (an IMAP IDLE watcher that runs user commands), but there are several mismatches and operational risks you should understand before installing (missing metadata declarations, systemd/root installation, plaintext credential handling, and running arbitrary shell commands).

Purpose & Capability

The name/description (IMAP IDLE watcher) aligns with the included daemon and setup script: the package needs an IMAP account and app password and installs a systemd service to run a handler. However the registry metadata declares no required env vars or config paths while the daemon and SKILL.md clearly require IMAP_ACCOUNT and IMAP_PASSWORD and the setup script writes /etc/<service>.env — this mismatch is unexpected and should have been declared.

Instruction Scope

SKILL.md and setup_service.sh instruct the agent/user to install a systemd service, store credentials in /etc/<service>.env, and provide an arbitrary ON_NEW_MAIL_CMD which will be executed via shell. The daemon fetches email metadata and passes it as environment variables to the command. This is coherent for the feature but grants the skill the ability to (a) store and use plaintext credentials, (b) execute arbitrary shell commands (shell=True), and (c) cause email metadata to be sent anywhere the handler chooses (e.g., webhooks). The instructions also show non-interactive usage that places the password on the command line (process args/history), which is a sensitive and risky practice.

Install Mechanism

No external downloads or package installs are performed — the skill is instruction + included scripts. That reduces supply-chain risk. However the install requires writing files to /etc and enabling a systemd service, which requires root privileges; the SKILL metadata did not signal this requirement.

Credentials

The daemon legitimately needs IMAP_ACCOUNT and IMAP_PASSWORD (app password) to operate, but the registry metadata does not declare these required env vars or the /etc env file path. The setup script writes credentials to /etc/<service>.env (mode 600) and the systemd unit runs the daemon (by default as root). The non-interactive examples accept --password on the CLI (exposes secrets in process lists and shell history). No other unrelated credentials are requested.

Persistence & Privilege

The skill instructs creating a systemd service and writing persistent config into /etc — this is normal for a daemon but it requires root privileges and creates long-lived access to email credentials. The skill does not set a less-privileged User in the provided unit file, so the service will run as root unless the operator modifies it. always:false is appropriate, but the persistence and need for elevated install privileges are important operational considerations.

What to consider before installing

What to consider before installing: - Metadata mismatch: The registry claims 'no required env vars' but the daemon requires IMAP_ACCOUNT and IMAP_PASSWORD and the setup writes /etc/<service>.env. Demand corrected metadata before trusting automated installers. - Root/systemd install: Installing the service writes files under /etc and enables a systemd unit (requires root). If you proceed, prefer creating a dedicated unprivileged service user and add 'User=...' to the unit file so the daemon doesn't run as root. - Secret handling: The setup script stores the app password in /etc/<service>.env (mode 600) which is reasonable, but avoid using the non-interactive --password CLI form (it exposes the password in process arguments and shell history). Use interactive entry or securely provision the env file yourself. - Arbitrary command execution: The daemon executes ON_NEW_MAIL_CMD via the shell (subprocess.run with shell=True). That is necessary to support arbitrary handlers but is high-risk if the command string is constructed from untrusted inputs. Ensure the handler/command is safe and that the agent does not interpolate untrusted values into the command line. - Data exfiltration risk: Handlers can send email metadata (MAIL_FROM, MAIL_SUBJECT, MAIL_DATE, MAIL_UID) anywhere (webhook, remote server). If your handler posts data externally, review what metadata will be transmitted and how it is authenticated. - Hardening recommendations: (1) Run the service under a dedicated low-privilege user, (2) restrict access to /etc/<service>.env (mode 600 is good), (3) avoid passing secrets on CLI, (4) review and vet any handler script the agent writes, (5) consider use of short-lived tokens or more controlled webhook endpoints rather than storing long-lived credentials if possible. If you want higher confidence, ask the publisher to: declare required env vars and the need for root/systemd in registry metadata, provide a unit file that sets a non-root User, and document secure non-interactive deployment options (e.g., reading password from a protected file or secret manager rather than CLI args).

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 scripts/setup_service.sh

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

Non-interactive

bash scripts/setup_service.sh \
  --account "[e-mail]" \
  --password "xxxx xxxx xxxx xxxx" \
  --command "python3 /path/to/handler.py" \
  --service-name my-watcher

Test connection only

bash scripts/setup_service.sh --test --account "[e-mail]" --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:

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 <[e-mail]>
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:

#!/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 scripts/setup_service.sh --account "[e-mail]" --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

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

Uninstall

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.