{"skill":{"slug":"bee-push-email-skill","displayName":"Bee Push Email","summary":"Monitors email in real-time via IMAP IDLE and triggers the OpenClaw agent to notify users through active channels like Telegram or Discord.","description":"---\nname: bee-push-email\ndescription: Push email notifications via IMAP IDLE + Himalaya + OpenClaw agent. Detects new emails in real-time and triggers the agent to process and notify the user. Use when: setting up email push notifications, configuring IMAP watcher, installing bee-push-email system, testing email connectivity, checking system dependencies, viewing email-push config, troubleshooting IMAP IDLE watcher, or managing the imap-watcher systemd service. Also handles uninstall/cleanup of the bee-push-email system. Trigger on beemail commands: /beemail, /beemail_start, /beemail_stop, /beemail_status, /beemail_test, /beemail_reply, /beemail_reply_off, /beemail_reply_ask, /beemail_reply_on. Also: start watcher, stop watcher, watcher status, email push status, registrar comandos, comandos no aparecen, beemail no funciona en telegram.\nemoji: 📧\nrequirements:\n  bins:\n    - python3\n    - systemctl\n    - openclaw\n---\n\n# Email Push — IMAP IDLE → OpenClaw Agent → User Notification\n\nReal-time email monitoring: IMAP IDLE detects new emails, triggers OpenClaw agent to process and notify the user via their active channel.\n\n## Security & Permissions\n\n**The agent MUST explicitly inform the user of all actions below and obtain approval before starting installation. Do not proceed without confirmed user consent.**\n\n### What this skill installs (requires root)\n\n| Action | Path / Target | Notes |\n|---|---|---|\n| **System user** | `imap-watcher` (useradd -r) | Service runs as this non-root user |\n| **Python venv** | `/opt/imap-watcher/` | Isolated env, not system-wide |\n| **pip package** | `imapclient` (inside venv only) | Not installed system-wide |\n| **Watcher script** | `/opt/imap-watcher/imap_watcher.py` | Copied from skill directory |\n| **systemd unit** | `/etc/systemd/system/imap-watcher.service` | Enabled + started, restarts on boot |\n| **Config file** | `/opt/imap-watcher/watcher.conf` | chmod 600, owner imap-watcher only |\n| **Log file** | `/var/log/imap-watcher.log` | chmod 640, owner imap-watcher |\n\n### External downloads (requires user awareness)\n\n| What | From | Condition |\n|---|---|---|\n| `himalaya` binary | `github.com/pimalaya/himalaya/releases/latest/` | Only if not already installed |\n| Method | `curl \\| tar` into `/usr/local/bin/` | Writes a system binary |\n\n### Credentials accessed\n\n| Credential | Source | Usage |\n|---|---|---|\n| IMAP email password | Provided by user at install time | IMAP IDLE connection |\n| Telegram `botToken` | Read from `~/.openclaw/openclaw.json` | Registers `/beemail*` commands via Telegram API (`setMyCommands`) |\n\nThe bot token is **never stored** by this skill.\n\n### Auto-reply behaviour\n\nBy default, the agent is instructed **not to reply to email senders**. This prevents exposing that the system is active and avoids phishing/spam risks. The `allow_auto_reply` field in `watcher.conf` controls this:\n\n| Value | Behaviour |\n|---|---|\n| `false` (default) | Agent notifies you via Telegram only. **Never** replies to senders. |\n| `ask` | Agent asks you for **explicit approval** via Telegram before replying. |\n| `true` | Agent may reply to senders if it deems appropriate (least safe). |\n\nConfigured interactively during install. Change anytime with `--reconfigure` + `systemctl restart imap-watcher`.\n\n**If `auto_reply_mode` is missing from an existing install**, the watcher logs `[SECURITY] WARNING` on startup and notifies the agent to alert you. The safe default `false` is applied until you run `--reconfigure`. It is read once per operation and used only to call `api.telegram.org`. The agent must inform the user that their bot token will be used to modify the bot's command menu.\n\n### Persistence\n\nThis skill installs a **persistent background service** (`Restart=always`, starts on boot). It maintains a continuous IMAP connection. The service runs as the dedicated `imap-watcher` user, not as root.\n\n**Uninstall** removes everything: service, systemd unit, `/opt/imap-watcher/`, log file, system user, and Telegram bot commands.\n\n## Install Flow (4 stages)\n\n### Stage 1: Dependencies (`--deps`)\n```bash\npython3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --deps\n```\n\n### Stage 2: Test Connection (`--test`)\n```bash\necho '{\"host\":\"...\",\"port\":993,\"ssl\":true,\"email\":\"...\",\"password\":\"...\"}' | python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --test\n```\n\n### Stage 3: Install (only if Stage 1+2 passed)\n```bash\necho '{\"host\":\"...\",\"port\":993,\"ssl\":true,\"email\":\"...\",\"password\":\"...\"}' | python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py\n```\n\n### Stage 4: Verify (automatic)\n\n## Other Modes\n\n### Register Bot Commands (after update)\n```bash\npython3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --register-commands\n```\n\n### Reconfigure (after update)\n\nAfter running `clawhub update bee-push-email`, new config fields may be available. Run:\n\n```bash\npython3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --reconfigure\n```\n\nThis detects fields missing from your existing `/opt/imap-watcher/watcher.conf` and asks about each one interactively — without touching your existing values. Restart the service after: `systemctl restart imap-watcher`.\n\n### Force Reinstall\n```bash\necho '{...}' | python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --force\n```\n\n### Show Config / Uninstall\n```bash\npython3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --show\nbash /root/.openclaw/workspace/skills/bee-push-email/scripts/uninstall.sh --yes\n```\n\n## Telegram Bot Commands\n\n<details>\n<summary>Click to expand command details</summary>\n\n### `/beemail_status`\n1. `systemctl is-active imap-watcher` + `systemctl status imap-watcher --no-pager -l`\n2. Last 10 log lines: `journalctl -u imap-watcher -n 10 --no-pager`\n3. UID state: `cat /opt/imap-watcher/last_seen_uids.json`\n4. Report: status, uptime, last email, IMAP state\n\n### `/beemail_start`\n1. `systemctl start imap-watcher` → wait 3s → verify active → show last 5 log lines\n\n### `/beemail_stop`\n1. `systemctl stop imap-watcher` → verify inactive → report\n\n### `/beemail_test`\n1. Check service active → read target email from config → tell user to send test email\n2. Optionally run: `setup.py --test`\n\n### `/beemail`\nQuick summary: service active? + last email processed + one-liner health\n\n### `/beemail_reply`\nShow current auto-reply mode:\n1. Run `python3 <skill_dir>/scripts/setup.py --reply-status`\n2. Report current mode with label: DISABLED / ASK / ENABLED\n\n### `/beemail_reply_off`\nDisable auto-reply immediately:\n1. Run `python3 <skill_dir>/scripts/setup.py --reply-off`\n2. Service restarts automatically\n3. Confirm: \"🔒 Auto-reply DISABLED\"\n\n### `/beemail_reply_ask`\nSet approval-required mode:\n1. Run `python3 <skill_dir>/scripts/setup.py --reply-ask`\n2. Service restarts automatically\n3. Confirm: \"❓ Auto-reply set to ASK\"\n\n### `/beemail_reply_on`\nEnable auto-reply — **warn the user first**:\n1. Inform user: \"⚠️ Enabling auto-reply exposes system activity to all senders including spam/phishing. Confirm?\"\n2. Only proceed if user confirms\n3. Run `python3 <skill_dir>/scripts/setup.py --reply-on`\n4. Service restarts automatically\n5. Confirm: \"⚠️ Auto-reply ENABLED\"\n\n</details>\n\n## Telegram Bot Commands Troubleshooting\n\nIf `/beemail*` commands don't appear in the Telegram menu after install:\n\n1. **Verify registration:**\n   ```bash\n   python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --register-commands\n   ```\n\n2. **Manual registration via BotFather:**\n   - Open @BotFather in Telegram\n   - Send `/setcommands`\n   - Select your bot\n   - Add each command:\n     - `beemail` — Email push status & recent emails\n     - `beemail_start` — Start IMAP email watcher\n     - `beemail_stop` — Stop IMAP email watcher\n     - `beemail_status` — Detailed watcher service status\n     - `beemail_test` — Send test email to verify push\n\n3. **If bot token not found:** The setup reads `botToken` from `~/.openclaw/openclaw.json`. Check that the Telegram channel is configured.\n\n4. **Commands registered but agent doesn't respond:** The agent needs this skill installed to handle the commands. Verify with `clawhub list`.\n\n## Troubleshooting\n\n- **Logs:** `journalctl -u imap-watcher -f`\n- **Status:** `systemctl status imap-watcher`\n- **Restart:** `systemctl restart imap-watcher`\n- **Config:** `/opt/imap-watcher/watcher.conf` (JSON, chmod 600)\n- **State:** `/opt/imap-watcher/last_seen_uids.json`\n\n## Architecture\n\n1. `imap_watcher.py` maintains persistent IMAP IDLE connection\n2. On new email, resolves active OpenClaw session (with 60s cache)\n3. Triggers `openclaw agent --deliver` to process and notify user\n4. Uses Himalaya for email operations (read, move, reply)\n5. Runs as systemd service as dedicated `imap-watcher` user with auto-reconnect, exponential backoff, and health checks\n","topics":["Email","Telegram"],"tags":{"latest":"1.5.3"},"stats":{"comments":0,"downloads":643,"installsAllTime":24,"installsCurrent":0,"stars":2,"versions":12},"createdAt":1774197357112,"updatedAt":1778492115715},"latestVersion":{"version":"1.5.3","createdAt":1774342869217,"changelog":"**bee-push-email 1.5.3 Changelog**\n\n- Added new Telegram bot commands: `/beemail_reply`, `/beemail_reply_off`, `/beemail_reply_ask`, and `/beemail_reply_on` for managing email auto-reply behavior directly from Telegram.\n- Updated command usage instructions and documentation to reflect new auto-reply control options.\n- Improved skill descriptor with emoji and simplified requirements section.\n- No code or logic changes (documentation and trigger/command list updates only).","license":"MIT-0"},"metadata":null,"owner":{"handle":"canihojr","userId":"s17a9x6bmr0wxhxm6qev5y1yv583fgv3","displayName":"canihojr","image":"https://avatars.githubusercontent.com/u/25158827?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090068550}}