Email Manager Skill

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

📋 Configuration

Edit config.json in the skill directory:

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

📨 Available Operations

List folders

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

python3 scripts/imap_utils.py list --folder INBOX --limit 10
python3 scripts/imap_utils.py list --flagged-only --output json

Read email

python3 scripts/imap_utils.py read --message-id 1234
python3 scripts/imap_utils.py read --message-id 1234 --output json

Save draft

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

List drafts

python3 scripts/imap_utils.py list-drafts
python3 scripts/imap_utils.py list-drafts --output json

Update draft

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

Send email

python3 scripts/smtp_utils.py send \
  --to "user@example.com" \
  --subject "Test" \
  --body "Hello"

Send draft

python3 scripts/smtp_utils.py send-draft --draft-id 1234

Flag/star email

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

python3 scripts/imap_utils.py move \
  --message-id 1234 \
  --from-folder INBOX \
  --to-folder Projects

Create folder

python3 scripts/imap_utils.py create-folder --name "NewFolder"

Delete email

python3 scripts/imap_utils.py delete --message-id 1234

Empty trash

python3 scripts/imap_utils.py empty-trash

Search emails

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

Spam operations

# 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:

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

Example JSON output:

[
  {
    "name": "Drafts",
    "delimiter": "/",
    "flags": ["\\HasNoChildren", "\\Drafts"]
  }
]

🤖 AI Usage Examples

Always use --output json when parsing results:

# 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:

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

# 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:

{
    "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