Bee Push Email

Monitors email in real-time via IMAP IDLE and triggers the OpenClaw agent to notify users through active channels like Telegram or Discord.

Email Push — IMAP IDLE → OpenClaw Agent → User Notification

Real-time email monitoring: IMAP IDLE detects new emails, triggers OpenClaw agent to process and notify the user via their active channel.

Security & Permissions

The agent MUST explicitly inform the user of all actions below and obtain approval before starting installation. Do not proceed without confirmed user consent.

What this skill installs (requires root)

Action	Path / Target	Notes
System user	imap-watcher (useradd -r)	Service runs as this non-root user
Python venv	/opt/imap-watcher/	Isolated env, not system-wide
pip package	imapclient (inside venv only)	Not installed system-wide
Watcher script	/opt/imap-watcher/imap_watcher.py	Copied from skill directory
systemd unit	/etc/systemd/system/imap-watcher.service	Enabled + started, restarts on boot
Config file	/opt/imap-watcher/watcher.conf	chmod 600, owner imap-watcher only
Log file	/var/log/imap-watcher.log	chmod 640, owner imap-watcher

External downloads (requires user awareness)

What	From	Condition
himalaya binary	github.com/pimalaya/himalaya/releases/latest/	Only if not already installed
Method	curl | tar into /usr/local/bin/	Writes a system binary

Credentials accessed

Credential	Source	Usage
IMAP email password	Provided by user at install time	IMAP IDLE connection
Telegram botToken	Read from ~/.openclaw/openclaw.json	Registers /beemail* commands via Telegram API (setMyCommands)

The bot token is never stored by this skill.

Auto-reply behaviour

By 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:

Value	Behaviour
false (default)	Agent notifies you via Telegram only. Never replies to senders.
ask	Agent asks you for explicit approval via Telegram before replying.
true	Agent may reply to senders if it deems appropriate (least safe).

Configured interactively during install. Change anytime with --reconfigure + systemctl restart imap-watcher.

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.

Persistence

This 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.

Uninstall removes everything: service, systemd unit, /opt/imap-watcher/, log file, system user, and Telegram bot commands.

Install Flow (4 stages)

Stage 1: Dependencies (--deps)

python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --deps

Stage 2: Test Connection (--test)

echo '{"host":"...","port":993,"ssl":true,"email":"...","password":"..."}' | python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --test

Stage 3: Install (only if Stage 1+2 passed)

echo '{"host":"...","port":993,"ssl":true,"email":"...","password":"..."}' | python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py

Stage 4: Verify (automatic)

Other Modes

Register Bot Commands (after update)

python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --register-commands

Reconfigure (after update)

After running clawhub update bee-push-email, new config fields may be available. Run:

python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --reconfigure

This 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.

Force Reinstall

echo '{...}' | python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --force

Show Config / Uninstall

python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --show
bash /root/.openclaw/workspace/skills/bee-push-email/scripts/uninstall.sh --yes

Telegram Bot Commands

<details> <summary>Click to expand command details</summary>

/beemail_status

1. systemctl is-active imap-watcher + systemctl status imap-watcher --no-pager -l
2. Last 10 log lines: journalctl -u imap-watcher -n 10 --no-pager
3. UID state: cat /opt/imap-watcher/last_seen_uids.json
4. Report: status, uptime, last email, IMAP state

/beemail_start

1. systemctl start imap-watcher → wait 3s → verify active → show last 5 log lines

/beemail_stop

1. systemctl stop imap-watcher → verify inactive → report

/beemail_test

1. Check service active → read target email from config → tell user to send test email
2. Optionally run: setup.py --test

/beemail

Quick summary: service active? + last email processed + one-liner health

/beemail_reply

Show current auto-reply mode:

1. Run python3 <skill_dir>/scripts/setup.py --reply-status
2. Report current mode with label: DISABLED / ASK / ENABLED

/beemail_reply_off

Disable auto-reply immediately:

1. Run python3 <skill_dir>/scripts/setup.py --reply-off
2. Service restarts automatically
3. Confirm: "🔒 Auto-reply DISABLED"

/beemail_reply_ask

Set approval-required mode:

1. Run python3 <skill_dir>/scripts/setup.py --reply-ask
2. Service restarts automatically
3. Confirm: "❓ Auto-reply set to ASK"

/beemail_reply_on

Enable auto-reply — warn the user first:

1. Inform user: "⚠️ Enabling auto-reply exposes system activity to all senders including spam/phishing. Confirm?"
2. Only proceed if user confirms
3. Run python3 <skill_dir>/scripts/setup.py --reply-on
4. Service restarts automatically
5. Confirm: "⚠️ Auto-reply ENABLED"

</details>

Telegram Bot Commands Troubleshooting

If /beemail* commands don't appear in the Telegram menu after install:

1. Verify registration:

   python3 /root/.openclaw/workspace/skills/bee-push-email/scripts/setup.py --register-commands
   

2. Manual registration via BotFather:

   • Open @BotFather in Telegram
   • Send /setcommands
   • Select your bot
   • Add each command:
     • beemail — Email push status & recent emails
     • beemail_start — Start IMAP email watcher
     • beemail_stop — Stop IMAP email watcher
     • beemail_status — Detailed watcher service status
     • beemail_test — Send test email to verify push

3. If bot token not found: The setup reads botToken from ~/.openclaw/openclaw.json. Check that the Telegram channel is configured.

4. Commands registered but agent doesn't respond: The agent needs this skill installed to handle the commands. Verify with clawhub list.

Troubleshooting

• Logs: journalctl -u imap-watcher -f
• Status: systemctl status imap-watcher
• Restart: systemctl restart imap-watcher
• Config: /opt/imap-watcher/watcher.conf (JSON, chmod 600)
• State: /opt/imap-watcher/last_seen_uids.json

Architecture

1. imap_watcher.py maintains persistent IMAP IDLE connection
2. On new email, resolves active OpenClaw session (with 60s cache)
3. Triggers openclaw agent --deliver to process and notify user
4. Uses Himalaya for email operations (read, move, reply)
5. Runs as systemd service as dedicated imap-watcher user with auto-reconnect, exponential backoff, and health checks