Building an Apple Mail Channel Plugin for OpenClaw

I recently built and published a plugin that integrates Apple Mail with OpenClaw (an AI automation platform), allowing AI agents to monitor and respond to emails with per-thread session isolation.

🎯 The Problem

OpenClaw and Hermes are powerful AI automation platforms, but they lacked native Apple Mail integration on macOS. Users wanted to:

• Monitor multiple email accounts
• Have AI agents automatically respond to emails
• Maintain conversation context across email threads
• Keep different email conversations isolated

💡 The Solution

I built @jehadurre/openclaw-apple-mail - a channel plugin that:

• Connects to Apple Mail via AppleScript
• Creates isolated sessions per email thread
• Processes HTML emails intelligently
• Supports multi-account configuration
• Includes security features like sender allowlists

🛠️ Technical Stack

• TypeScript - Type-safe development
• AppleScript - Native macOS Mail.app integration
• HTML Processing - DOMPurify, jsdom, sanitize-html, marked
• Schema Validation - Zod for configuration validation

📦 Key Features

1. Per-Thread Session Isolation

Each email conversation gets its own isolated session, preventing context mixing:

// Each thread gets unique session ID
const sessionId = `apple-mail:${threadId}`;

2. Multi-Account Support

Configure multiple email accounts with independent settings:

{
  "channels": {
    "apple-mail": {
      "accounts": {
        "work": {
          "email": "work@company.com",
          "pollIntervalMs": 15000,
          "archiveOnReply": true
        },
        "personal": {
          "email": "personal@gmail.com",
          "pollIntervalMs": 60000
        }
      }
    }
  }
}

3. Security Features

• Sender allowlist per account
• HTML sanitization
• AppleScript sandboxing

4. Smart HTML Processing

Automatically converts HTML emails to clean markdown:

• Table extraction and conversion
• Removes tracking pixels
• Sanitizes malicious content
• Preserves formatting for AI agents

📚 Publishing Journey

I published this plugin to multiple platforms:

1. npm Registry

npm install @jehadurre/openclaw-apple-mail

2. GitHub

• Full source code
• Issue tracking
• Contribution guidelines
• MIT License

3. ClawHub

openclaw plugins install @jehadurre/openclaw-apple-mail

4. OpenClaw Skill

Created a comprehensive setup skill:

clawhub install apple-mail-setup

The skill includes:

• Installation guide
• 5 configuration templates
• Troubleshooting solutions
• Best practices

🎓 Lessons Learned

1. Compiled Output Matters

ClawHub requires compiled JavaScript, not just TypeScript source. I had to:

• Get compiled output from production deployment
• Include index.js in the package
• Update package.json to reference the compiled file

2. Skills Enhance Adoption

Creating a separate "skill" package that teaches users how to set up and use the plugin significantly improves the user experience.

3. Multi-Platform Publishing

Publishing to npm, GitHub, ClawHub, and creating documentation on GitHub Pages maximizes discoverability.

🚀 Usage Example

Here's how users set it up:

Step 1: Install

openclaw plugins install @jehadurre/openclaw-apple-mail
clawhub install apple-mail-setup

Step 2: Configure

Add to openclaw.json:

{
  "channels": {
    "apple-mail": {
      "enabled": true,
      "accounts": {
        "personal": {
          "email": "user@example.com",
          "mailboxAccount": "iCloud",
          "allowFrom": ["*"]
        }
      }
    }
  }
}

Step 3: Start

openclaw start

That's it! OpenClaw now monitors your email and can respond automatically.

📊 Architecture

User Email → Apple Mail.app
              ↓ (AppleScript)
           Plugin Monitor
              ↓
        Session Manager (per-thread isolation)
              ↓
         HTML Processor
              ↓
        OpenClaw/Hermes AI Agent
              ↓
          Response
              ↓ (AppleScript)
        Apple Mail.app → Send Reply

🔐 Security Considerations

1. Sender Allowlist: Only process emails from trusted senders
2. HTML Sanitization: Remove malicious content from HTML emails
3. AppleScript Sandboxing: Limited access to Mail.app APIs
4. No Credential Storage: Uses existing Apple Mail accounts

🌟 Future Enhancements

Planned features:

• [ ] Smart reply suggestions
• [ ] Attachment handling
• [ ] Email categorization
• [ ] Custom email templates
• [ ] Integration with other channels

📖 Resources

• GitHub: https://github.com/JehadurRE/openclaw-apple-mail
• npm: https://www.npmjs.com/package/@jehadurre/openclaw-apple-mail
• Documentation: https://openclaw-apple-mail.jehadurre.me
• Skill: clawhub install apple-mail-setup

🤝 Contributing

Contributions welcome! Check out the Contributing Guide.

💬 Feedback

Have you used AI automation with email? What features would you like to see? Let me know in the comments!

About Me: I'm Md. Jehadur Rahman (Emran), a developer passionate about AI automation and productivity tools. Find me on GitHub and my website.

License: MIT - Free to use, modify, and redistribute!