OpenClaw Email Manager for Postfic and Dovecot

SKILL.md

---
name: email-manager
description: Complete email management for Postfix/Dovecot
version: 1.0.0
author: Mattias Söderholm
triggers:
  - email
  - mail
  - draft
  - inbox
  - send email
  - folder
  - flag
  - star
  - important
  - spam
  - junk
  - trash
  - delete
  - move
  - search
  - read
  - compose
  - reply
  - archive
  - mark as spam
  - not spam
  - empty trash
  - empty spam
requires:
  bins:
    - python3
---

# Email Manager Skill

This skill provides complete email management using your Postfix/Dovecot infrastructure.

## 📋 Configuration

Edit `config.json` in the skill directory:

```json
{
  "email_address": "your-email@domain.com",
  "email_password": "your-password",
  "imap_server": "mail.yourdomain.com",
  "smtp_server": "mail.yourdomain.com"
}
```

## 📨 Available Operations

### List folders
```bash
python3 scripts/imap_utils.py list-folders
python3 scripts/imap_utils.py list-folders --output json
```

**Example output:**
```
📁 Available folders:
  • Drafts 📝 DRAFTS
  • Sent 📤 SENT
  • Trash 🗑️ TRASH
  • Junk 📧 SPAM
  • INBOX 📥 INBOX
  • Archive
  • Projects/ClientA
```

### List emails
```bash
python3 scripts/imap_utils.py list --folder INBOX --limit 10
python3 scripts/imap_utils.py list --flagged-only --output json
```

### Read email
```bash
python3 scripts/imap_utils.py read --message-id 1234
python3 scripts/imap_utils.py read --message-id 1234 --output json
```

### Save draft
```bash
python3 scripts/imap_utils.py save-draft \
  --to "user@example.com" \
  --subject "Draft subject" \
  --body "Draft content"
```

### List drafts
```bash
python3 scripts/imap_utils.py list-drafts
python3 scripts/imap_utils.py list-drafts --output json
```

### Update draft
```bash
python3 scripts/imap_utils.py update-draft \
  --draft-id 1234 \
  --subject "Updated subject" \
  --body "Updated content"
```

### Send email
```bash
python3 scripts/smtp_utils.py send \
  --to "user@example.com" \
  --subject "Test" \
  --body "Hello"
```

### Send draft
```bash
python3 scripts/smtp_utils.py send-draft --draft-id 1234
```

### Flag/star email
```bash
python3 scripts/imap_utils.py flag --message-id 1234 --add
python3 scripts/imap_utils.py flag --message-id 1234 --remove
python3 scripts/imap_utils.py list --flagged-only
```

### Move email
```bash
python3 scripts/imap_utils.py move \
  --message-id 1234 \
  --from-folder INBOX \
  --to-folder Projects
```

### Create folder
```bash
python3 scripts/imap_utils.py create-folder --name "NewFolder"
```

### Delete email
```bash
python3 scripts/imap_utils.py delete --message-id 1234
```

### Empty trash
```bash
python3 scripts/imap_utils.py empty-trash
```

### Search emails
```bash
python3 scripts/imap_utils.py search --query "FROM user@example.com"
python3 scripts/imap_utils.py search --query "subject:meeting" --output json
```

### Spam operations
```bash
# List spam
python3 scripts/imap_utils.py list-spam
python3 scripts/imap_utils.py list-spam --output json

# Mark as spam
python3 scripts/imap_utils.py mark-spam --message-id 1234
python3 scripts/imap_utils.py mark-spam --message-id 1234 --from-folder INBOX

# Mark as not spam
python3 scripts/imap_utils.py mark-ham --message-id 1234
python3 scripts/imap_utils.py mark-ham --message-id 1234 --from-folder Junk

# Empty spam folder
python3 scripts/imap_utils.py empty-spam
```

## 🔍 Folder Auto-Detection

The skill automatically detects folder names for:
- **Inbox:** INBOX, Inbox
- **Drafts:** Drafts, INBOX.Drafts, Draft
- **Sent:** Sent, Sent Messages, INBOX.Sent
- **Trash:** Trash, Deleted, INBOX.Trash
- **Junk/Spam:** Junk, Spam, INBOX.Junk, INBOX.Spam, Bulk
- **Archive:** Archive, Archives, INBOX.Archive

## 📁 Folder Name Handling

The skill cleans up folder names for display by removing IMAP flags like `\HasNoChildren` and quotes. For raw folder data with flags:

```bash
python3 scripts/imap_utils.py list-folders --output json
```

**Example JSON output:**
```json
[
  {
    "name": "Drafts",
    "delimiter": "/",
    "flags": ["\\HasNoChildren", "\\Drafts"]
  }
]
```

## 🤖 AI Usage Examples

Always use `--output json` when parsing results:

```bash
# List drafts and find specific one
drafts=$(python3 scripts/imap_utils.py list-drafts --output json)
# Parse JSON to find draft by subject

# Send the draft
python3 scripts/smtp_utils.py send-draft --draft-id $ID

# Check spam count
spam=$(python3 scripts/imap_utils.py list-spam --output json)

# Get folder metadata
folders=$(python3 scripts/imap_utils.py list-folders --output json)
```

## ✅ Testing

Test your configuration:

```bash
python3 scripts/imap_utils.py list-folders
python3 scripts/imap_utils.py list --limit 5
python3 scripts/imap_utils.py list-spam
```

All operations are non-interactive and suitable for automation.

## 🚀 Setup Instructions

```bash
# 1. Create skill directory
mkdir -p ~/OpenClaw-Workspace/skills/email-manager/scripts
cd ~/OpenClaw-Workspace/skills/email-manager

# 2. Create config.json
cat > config.json << 'EOF'
{
    "email_address": "your-email@yourdomain.com",
    "email_password": "your-password",
    "imap_server": "mail.yourdomain.com",
    "imap_port": 993,
    "smtp_server": "mail.yourdomain.com",
    "smtp_port": 465,
    "folders": {
        "drafts": "Drafts",
        "sent": "Sent",
        "trash": "Trash",
        "junk": "Junk"
    }
}
EOF

# 3. Make scripts executable
chmod +x scripts/*.py

# 4. Test it!
python3 scripts/imap_utils.py list-folders
```

## 📝 Common Spam Folder Names

Different Dovecot configurations use different spam folder names:
- Junk (most common)
- Spam
- INBOX.Junk
- INBOX.Spam
- Bulk
- Junk E-mail

Set it explicitly in `config.json` if auto-detection doesn't work:

```json
{
    "folders": {
        "junk": "INBOX.Junk"
    }
}
```

## 🎯 Key Benefits

- ✅ Zero dependencies - Uses only Python standard library
- ✅ No virtualenv needed - Works with system Python
- ✅ JSON config - Easy to edit, no parsing libraries needed
- ✅ Non-interactive - Perfect for AI automation
- ✅ Full feature set - Drafts, send, folders, flags, move, delete, spam
- ✅ Debian/Ubuntu compatible - No "externally-managed-environment" errors