Awesome-openclaw-skills imap-email

Read and manage email via IMAP (ProtonMail Bridge, Gmail, etc.). Check for new/unread messages, fetch content, search mailboxes, and mark as read/unread. Works with any IMAP server including ProtonMail Bridge.

install

source · Clone the upstream repo

git clone https://github.com/sundial-org/awesome-openclaw-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/sundial-org/awesome-openclaw-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/imap-email" ~/.claude/skills/sundial-org-awesome-openclaw-skills-imap-email && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/sundial-org/awesome-openclaw-skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/imap-email" ~/.openclaw/skills/sundial-org-awesome-openclaw-skills-imap-email && rm -rf "$T"

manifest: skills/imap-email/SKILL.md

source content

IMAP Email Reader

Read, search, and manage email via IMAP protocol. Supports ProtonMail Bridge, Gmail IMAP, and any standard IMAP server.

Quick Start

Check for new emails:

node skills/imap-email/scripts/imap.js check

Fetch specific email:

node skills/imap-email/scripts/imap.js fetch <uid>

Mark as read:

node skills/imap-email/scripts/imap.js mark-read <uid>

Search mailbox:

node skills/imap-email/scripts/imap.js search --from "sender@example.com" --unseen

Configuration

Create

.env

in the skill folder or set environment variables:

IMAP_HOST=127.0.0.1          # Server hostname
IMAP_PORT=1143               # Server port
IMAP_USER=your@email.com
IMAP_PASS=your_password
IMAP_TLS=false               # Use TLS/SSL connection
IMAP_REJECT_UNAUTHORIZED=false  # Set to false for self-signed certs (optional)
IMAP_MAILBOX=INBOX           # Default mailbox

ProtonMail Bridge setup:

Install and run ProtonMail Bridge
Use
```
127.0.0.1:1143
```
for IMAP
Password is generated by Bridge (not your ProtonMail password)
TLS: Use
```
false
```
(Bridge uses STARTTLS)
```
REJECT_UNAUTHORIZED
```
: Set to
```
false
```
(Bridge uses self-signed cert)

Gmail IMAP setup:

Host:
```
imap.gmail.com
```
Port:
```
993
```
TLS:
```
true
```
Enable "Less secure app access" or use App Password
```
REJECT_UNAUTHORIZED
```
: Omit or set to
```
true
```
(default)

Commands

check

Check for unread/new emails in mailbox.

node scripts/imap.js check [--limit 10] [--mailbox INBOX] [--recent 2h]

Options:

```
--limit <n>
```
: Max results (default: 10)
```
--mailbox <name>
```
: Mailbox to check (default: INBOX)
```
--recent <time>
```
: Only show emails from last X time (e.g., 30m, 2h, 7d)

Returns JSON array of messages with:

uid, from, subject, date, snippet, flags

fetch

Fetch full email content by UID.

node scripts/imap.js fetch <uid> [--mailbox INBOX]

Returns JSON with full body (text + HTML).

search

Search emails with filters.

node scripts/imap.js search [options]

Options:
  --unseen           Only unread messages
  --seen             Only read messages
  --from <email>     From address contains
  --subject <text>   Subject contains
  --recent <time>    From last X time (e.g., 30m, 2h, 7d)
  --since <date>     After date (YYYY-MM-DD)
  --before <date>    Before date (YYYY-MM-DD)
  --limit <n>        Max results (default: 20)
  --mailbox <name>   Mailbox to search (default: INBOX)

Time format examples:

```
30m
```
= last 30 minutes
```
2h
```
= last 2 hours
```
7d
```
= last 7 days

mark-read / mark-unread

Mark message(s) as read or unread.

node scripts/imap.js mark-read <uid> [uid2 uid3...]
node scripts/imap.js mark-unread <uid> [uid2 uid3...]

list-mailboxes

List all available mailboxes/folders.

node scripts/imap.js list-mailboxes

Cron Integration

Set up periodic email checking with Clawdbot cron:

# Check email every 15 minutes, deliver to iMessage
clawdbot cron add \
  --name "email-check" \
  --cron "*/15 * * * *" \
  --session isolated \
  --message "Check for new ProtonMail emails and summarize them" \
  --deliver \
  --channel imessage \
  --to "+15085600825"

Inside the isolated session, the agent can run:

node /Users/mike/clawd/skills/imap-email/scripts/imap.js check --limit 5

Workflow Examples

Morning email digest:

Run
```
check --limit 10 --recent 12h
```
Summarize unread emails from overnight
Deliver summary to preferred channel

Check recent emails from specific sender:

Run

search --from "important@company.com" --recent 24h

Fetch full content if needed
Mark as read after processing

Hourly urgent email check:

Run
```
search --recent 1h --unseen
```
Filter for important keywords
Extract action items
Deliver notification if urgent

Weekly digest:

Run
```
search --recent 7d --limit 20
```
Summarize activity
Generate weekly report

Dependencies

Install in skill folder:

cd skills/imap-email
npm install imap-simple dotenv

Or install globally:

npm install -g imap-simple dotenv

Security Notes

Store credentials in
```
.env
```
(add to
```
.gitignore
```
)
ProtonMail Bridge password is NOT your account password
Bridge must be running for ProtonMail IMAP access
Consider using app-specific passwords for Gmail

Troubleshooting

Connection timeout:

Verify IMAP server is running and accessible
Check host/port configuration
Test with:
```
telnet <host> <port>
```

Authentication failed:

Verify username (usually full email address)
Check password is correct
For ProtonMail Bridge: use Bridge-generated password, not account password
For Gmail: use App Password if 2FA is enabled

TLS/SSL errors:

Match
```
IMAP_TLS
```
setting to server requirements (true for SSL, false for STARTTLS)
For self-signed certs (e.g., ProtonMail Bridge): set
```
IMAP_REJECT_UNAUTHORIZED=false
```
Check port matches TLS setting (993 for SSL, 143 for STARTTLS)

Empty results:

Verify mailbox name (case-sensitive)
Check search criteria
List mailboxes with
```
list-mailboxes
```