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": "[email protected]",

          "pollIntervalMs": 15000,

          "archiveOnReply": true

        },

        "personal": {

          "email": "[email protected]",

          "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": "[email protected]",

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