Email IMAP Fetch

Core Goal

• Wait for new mail with IMAP IDLE.
• Fetch unread messages after each wake-up.
• Support multiple mailbox accounts configured with env.
• Control IDLE support strictly with env mode (idle or poll) without runtime probing.
• Forward each fetched email to OpenClaw webhooks.
• Emit machine-readable JSON lines for downstream steps.
• Keep this skill strictly in stage-1 routing mode: send snippet + structured refs only, never send full raw message body, and never send attachment binary/content.

Workflow

1. Configure account env variables and OpenClaw webhook env variables (see references/env.md and assets/config.example.env).
2. Validate configuration:

python3 scripts/imap_idle_fetch.py check-config

1. Run one IDLE cycle per account (smoke test):

python3 scripts/imap_idle_fetch.py listen --cycles 1 --idle-seconds 120 --max-messages 10

1. Run continuously (default resident mode):

python3 scripts/imap_idle_fetch.py listen

Runtime Model

• Skill files are installed locally, but the listener is not auto-started.
• In idle mode, IMAP IDLE receives push events only while listener process and IMAP connection are alive.
• In poll mode, listener sleeps for poll interval and then fetches unread messages.
• If the process exits, push events are missed; next run can still fetch existing unread emails with UNSEEN.
• Default runtime is resident mode (IMAP_CYCLES=0 by default).
• Default IDLE mode is poll (safe for servers without IDLE support).
• In production, always-on deployment must run under systemd, launchd, supervisor, or an equivalent daemon manager.
• Do not run the listener as a foreground process bound to an interactive exec session; once that session exits, the listener will stop.

Output Contract

• Output format is JSONL (one JSON object per line).
• type=status for lifecycle events.
• type=message for fetched emails with:

- account, mailbox, seq, uid - subject, from, to, date - messageidraw, messageidnorm (and compatibility field messageid) - snippet (plain-text preview only) - attachmentcount, attachmentmanifest (summary only, no attachment content) - mailref machine-readable object (account, mailbox, uid, messageidraw, messageidnorm, date)

• Webhook message includes two fixed machine-readable blocks for deterministic dispatch extraction:

- <<<MAILREFJSON>>> ... <<<ENDMAILREFJSON>>> - <<<ATTACHMENTMANIFESTJSON>>> ... <<<ENDATTACHMENTMANIFESTJSON>>>

• wait_mode is idle or poll in cycle status output.
• wait_events records the active wait strategy details.
• event=webhook_delivered status events when OpenClaw webhook POST succeeds.
• type=error for account-level failures.
• event=webhook_failed error events when OpenClaw webhook POST fails.

Parameters

• --cycles: IDLE cycles per account (0 means forever).
• --idle-seconds: max wait time for each IDLE call.
• --poll-seconds: interval used when polling mode is active.
• --idle-mode: idle or poll.
• --max-messages: max unread emails fetched each cycle.
• --mark-seen / --no-mark-seen: control unread state updates.
• --snippet-chars: preview length limit.
• --connect-timeout: connection timeout seconds.
• --retry-seconds: retry delay after failure.

Environment defaults:

• IMAP_CYCLES
• IMAPIDLEMODE
• IMAPIDLESECONDS
• IMAPPOLLSECONDS
• IMAPMAXMESSAGES
• IMAPMARKSEEN
• IMAPSNIPPETCHARS
• IMAPCONNECTTIMEOUT
• IMAPRETRYSECONDS

OpenClaw webhooks forwarding:

• OPENCLAWWEBHOOKSENABLED
• OPENCLAWWEBHOOKSTOKEN
• OPENCLAWWEBHOOKSBASE_URL
• OPENCLAWWEBHOOKSMODE (agent or wake)
• OPENCLAWWEBHOOKSENDPOINT (optional endpoint override)
• OPENCLAWWEBHOOKSPATH
• OPENCLAWWEBHOOKSWAKE_MODE
• OPENCLAWWEBHOOKSDELIVER
• OPENCLAWWEBHOOKSTIMEOUT
• OPENCLAWWEBHOOKSNAME
• OPENCLAWWEBHOOKSAGENT_ID
• OPENCLAWWEBHOOKSCHANNEL
• OPENCLAWWEBHOOKSTO
• OPENCLAWWEBHOOKSMODEL
• OPENCLAWWEBHOOKSTHINKING
• OPENCLAWWEBHOOKSAGENTTIMEOUTSECONDS
• OPENCLAWWEBHOOKSSESSIONKEYPREFIX

Error Handling

• Invalid env configuration exits with code 2.
• In idle mode, unsupported IDLE returns explicit error and suggests IMAPIDLEMODE=poll.
• Runtime failures are emitted as type=error.
• Command exits non-zero when account processing errors occur.

References

• references/env.md

Assets

• assets/config.example.env

Scripts

• scripts/imapidlefetch.py