🐝 bee-push-email v2.5.0 — OpenClaw Plugin

Real-time IMAP IDLE email push notifications for OpenClaw with a flexible rule engine.

---

What can bee-push-email do?

Q: How quickly does it notify me when a new email arrives? Using IMAP IDLE, the plugin detects new emails within ~1 second of arrival. It runs as a background service inside the OpenClaw Gateway — no polling, no subprocess, no delay.

Q: Do I need to leave something open for it to work? No. The plugin runs as part of the OpenClaw Gateway daemon, which stays running on your machine at all times. As long as the Gateway is running, email monitoring is active.

Q: Can I silence specific types of emails without being notified? Yes. Create a rule with the silence action. For example: mark all GitHub notification emails as read and move them to a folder silently — but still catch emails from GitHub where the subject contains "security alert" and notify those immediately.

Q: Can it reply to emails automatically? Yes, with three modes: false (never reply — default), ask (asks your approval before each reply), or true (agent composes and sends replies based on your rules). Toggle at any time with /beemail_reply_off, /beemail_reply_ask, or /beemail_reply_on.

Q: Can I define rules that trigger custom agent actions? Yes. The agent_command action lets you write a natural language instruction that runs whenever a matching email arrives. For example: "When an invoice arrives from any supplier, extract the amount and due date and save them to my expenses tracker."

Q: How do I create rules? Do I need to edit JSON manually? Use /beemail_rule_add from Telegram — the agent guides you through creating a rule interactively. You can also edit bee-push-email-rules.json directly in your workspace if you prefer.

Q: Can I filter by sender, domain, subject, or email body? Yes. Rules match on from, from_domain, to, subject, folder, and body_preview. Conditions combine with AND, OR, and NOT logic.

Q: What happens if my internet connection drops? The plugin reconnects automatically with exponential backoff (10s → 20s → 40s → up to 5 min). On reconnect it fetches any emails missed while disconnected before re-entering IDLE.

Q: Will it flood me with notifications on first install? No. On first install the plugin initializes to the current mailbox position and only notifies about emails that arrive after installation.

Q: Is my email password stored securely? The password lives in openclaw.json. Use an app-specific password (not your main password) and chmod 600 ~/.openclaw/openclaw.json. App password setup for Gmail, Outlook, and Yahoo is covered in the guided wizard.

Q: Can I test a rule before activating it? Yes. /beemail_rule_test <rule_id> tests any rule against the last email received in the current session and shows whether it would match and which actions would run.

---

Architecture

Native OpenClaw Plugin (TypeScript, runs in-process with the Gateway):

• registerService — persistent IMAP IDLE connection inside the Gateway process
• enqueueSystemEvent — true push (~1s latency, wakes the agent immediately)
• registerCommand — direct Telegram commands, no LLM overhead for status queries
• Bundled SKILL.md — agent instructions shipped with the plugin

Guided setup

After installing, tell your agent:

"Set up bee-push-email" or "install email push notifications"

The agent walks you through each setting with descriptions, examples, and safe defaults, then asks for confirmation before writing to openclaw.json.

To reconfigure later: /beemail_reconfigure

Installation

openclaw plugins install clawhub:bee-push-email

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "bee-push-email": {
        "enabled": true,
        "config": {
          "host": "imap.gmail.com",
          "port": 993,
          "ssl": true,
          "email": "you@gmail.com",
          "password": "your-app-password",
          "folder": "INBOX",
          "rules_file": "bee-push-email-rules.json",
          "auto_reply_mode": "false"
        }
      }
    }
  }
}

Then: openclaw gateway restart

Rules

Copy bee-push-email-rules.example.json to your workspace as bee-push-email-rules.json and customize, or use /beemail_rule_add. Full schema reference in skills/bee-push-email/SKILL.md.

Telegram commands

Command	Description
/beemail	Status: connection + rule count
/beemail_rules	List all rules
/beemail_rule_add	Add a rule (agent-guided)
/beemail_rule_toggle <id>	Enable or disable a rule
/beemail_rule_delete <id>	Delete a rule
/beemail_rule_test <id>	Test rule against last email
/beemail_reconfigure	Re-run guided setup
/beemail_reply_off	Disable auto-reply (default)
/beemail_reply_ask	Require approval before replying
/beemail_reply_on	Enable auto-reply

Migration from v1.x (Python watcher)

1. Stop the old watcher: bash uninstall.sh --yes
2. Tell your agent "set up bee-push-email" for guided config, or add config to openclaw.json manually
3. Copy or recreate your rules in bee-push-email-rules.json
4. openclaw gateway restart

The gateway token missing issue from v1.x is resolved — the plugin runs in-process with the Gateway.

Development

pnpm install
pnpm typecheck
pnpm build
pnpm dev

Changelog

See CHANGELOG.md