Email Monitor

Set up periodic email monitoring for any IMAP mailbox (Gmail, Outlook, QQ, etc.). Guides users through mailbox configuration, tests the connection, then creates a scheduled cron task to check for new emails at user-defined intervals and deliver summaries in a custom format. Use when a user wants to automatically monitor an inbox for new messages, set up periodic email fetching or summarization, or configure email alerts and digests on a schedule.

Email Monitor Skill

This skill guides the user through a 6-step onboarding to set up automated email monitoring.

Onboarding Flow

Work through these steps in order, one step per conversation turn. Do not skip ahead.

Step 1 — Ask which mailbox to monitor

Ask the user:

"请告诉我你想监控的邮箱地址是什么？（例如 [e-mail]）"

Step 2 — Provide provider-specific setup guidance

Based on the email domain, read references/imap-setup.md and show the user the relevant setup instructions:

• @gmail.com → Gmail IMAP + App Password guide
• @outlook.com / @hotmail.com → Outlook section
• @qq.com → QQ Mail section
• Others → Generic IMAP section

Ask the user to provide:

• Their email address
• Their app password (or account password for non-Gmail)

Store these in a local config file: ~/.openclaw/email-monitor/<sanitized-email>/config.json

Config template:

{
  "email": "<email>",
  "password": "<password>",
  "imap_host": "<host>",
  "imap_port": 993,
  "mailbox": "INBOX",
  "state_file": "~/.openclaw/email-monitor/<sanitized-email>/state.json",
  "max_emails": 20,
  "fetch_attachments": false,
  "attachment_dir": "~/Downloads/email-attachments"
}

Step 3 — Test connection

Run the fetch script once to verify credentials and connectivity:

python3 <skill_dir>/scripts/fetch_emails.py --config ~/.openclaw/email-monitor/<sanitized-email>/config.json

• Success: Show the user a sample of fetched emails (first 3), confirm "连接成功！"
• Failure: Show the error message, help the user troubleshoot (wrong password, IMAP not enabled, etc.)

Only proceed to Step 4 after a successful test.

Step 4 — Ask for polling interval

Ask:

"连接成功！你希望每隔多久检查一次新邮件？（例如：每1小时、每2小时、每天早上8点）"

Parse the user's answer into a valid cron expression. Examples:

• "每小时" → 0 * * * *
• "每2小时" → 0 */2 * * *
• "每天早上8点" → 0 8 * * *
• "每4小时" → 0 */4 * * *

Step 5 — Ask for notification format and attachment handling

Ask two questions in one message:

消息格式：新邮件通知时，你希望看到哪些信息？

• A) 简洁版：发件人 + 主题 + 日期
• B) 标准版：发件人 + 主题 + 日期 + 摘要（前200字）
• C) 自定义（请描述）

附件：是否需要下载附件？如果需要，保存到哪个目录？

Update config.json with fetch_attachments and attachment_dir based on the response.

Store the notification format preference as notify_format in config.json:

• "brief" for A
• "standard" for B
• "<custom template string>" for C

Step 6 — Summarize and create cron job

Show a confirmation summary:

📧 邮件监控配置确认

邮箱：<email>
检查频率：每 X 小时（cron: <expr>）
通知格式：<format>
下载附件：<yes/no>（保存至：<dir>）

确认后将创建定时任务。确认吗？（是/否）

After user confirms, create the cron job using openclaw:

openclaw cron add "<cron-expr>" "检查邮件 <email>" --run "python3 <skill_dir>/scripts/fetch_emails.py --config ~/.openclaw/email-monitor/<email>/config.json"

Then confirm to the user that the cron task is active.

---

Running Manually

At any time the user can say "现在检查一下邮件" or similar — run the fetch script and display results using the configured format.

Format Templates

brief:

📩 [<date>] <from> — <subject>

standard:

📩 <subject>
👤 <from>
📅 <date>
---
<snippet>

Config File Location

Always store per-account config at: ~/.openclaw/email-monitor/<sanitized-email>/config.json

Where <sanitized-email> = email address with @ replaced by _at_ and . replaced by _. Example: qiusuo9809_at_gmail_com

State File

The state file tracks the last fetched UID to avoid re-sending old emails. It is auto-managed by scripts/fetch_emails.py. If the user wants to re-fetch all emails, delete the state file.