Inbox Poller

Poll a POP3 mailbox, download new messages (body + attachments ≤ 25 MB), archive them by date, and log a summary. Duplicate-safe via UID tracking.

Quick Start

# Dry-run — see what would be downloaded, change nothing
python3 scripts/poll_inbox.py --dry-run

# Live poll — download and archive new mail
python3 scripts/poll_inbox.py

# Cron (every 30 min)
# */30 * * * * python3 /home/nickwaye/.openclaw/workspace/skills/inbox-poller/scripts/poll_inbox.py >> /tmp/inbox-poller.log 2>&1

Configuration

Credentials are read from ~/.openclaw/workspace/email_config.json. The skill uses the pop3_* keys (added alongside the existing SMTP keys):

{
  "smtp_server": "smtp.dreamhost.com",
  "smtp_port": 465,
  "sender_email": "...",
  "sender_password": "...",
  "use_ssl": true,

  "pop3_server": "pop.dreamhost.com",
  "pop3_port": 995,
  "pop3_user": "nickolis79@relativeprogress.com",
  "pop3_password": "same-or-different-password",
  "pop3_ssl": true
}

Env-var overrides: POP3_SERVER, POP3_PORT, POP3_USER, POP3_PASS.

UID Tracking

references/processed_uids.json stores every Message-ID already handled. On each poll, only messages with unseen UIDs are processed.

Archive Layout

inbox-archive/
└── 2026-03-01/
    ├── 001_from-alice_subject-hello.txt      (plain-text body)
    ├── 001_from-alice_subject-hello.html     (HTML body, if present)
    ├── 001_report.pdf                        (attachment)
    └── 002_from-bob_subject-invoice.txt

Inbox Log

Each poll appends to inbox-log.md:

## 2026-03-01 13:30 MST — 2 new messages
- **From:** alice@example.com **Subject:** Hello **Attachments:** report.pdf (140 KB)
- **From:** bob@example.com **Subject:** Invoice **Attachments:** (none)

Dry-Run

Pass --dry-run to simulate the full poll:

• Connects to POP3 server
• Lists new (untracked) messages
• Prints what would be downloaded and where it would be saved
• Downloads nothing. Writes nothing. Updates no UIDs.

Attachment Policy

Same as send-email skill:

• Allowed types: .pdf, .txt, .odf, .png, .jpg, .jpeg, .gif, .mp3
• Max size: 25 MB per file
• Oversized or disallowed attachments are logged but skipped (message body is still archived).

Extensibility

The script is designed to be hooked into downstream triggers:

• "If subject contains X, run skill Y"
• "If from matches Z, forward to Telegram"

These hooks can be added later via a references/rules.json file.

Error Handling

• POP3 connection failure → logged, non-zero exit
• Auth failure → logged with hint to check pop3_user / pop3_password
• Attachment skip (wrong type / too large) → warning logged, message still archived
• Duplicate UID → silently skipped