DEV Community

Jehadur Rahman (Emran)
Jehadur Rahman (Emran)

Posted on • Originally published at openclaw-apple-mail.jehadurre.me

Building an Apple Mail Channel Plugin for OpenClaw

#automation #ai #macos #typescript

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}`;
Enter fullscreen mode Exit fullscreen mode

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
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

2. GitHub

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

3. ClawHub 

openclaw plugins install @jehadurre/openclaw-apple-mail
Enter fullscreen mode Exit fullscreen mode

4. OpenClaw Skill

Created a comprehensive setup skill:

clawhub install apple-mail-setup
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Step 2: Configure

Add to openclaw.json:

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

Step 3: Start 

openclaw start
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

🔐 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

🤝 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!

Top comments (0)