Building an Apple Mail Channel Plugin for OpenClaw

Jehadur Rahman (Emran) — Mon, 22 Jun 2026 03:12:42 +0000

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

Sender Allowlist: Only process emails from trusted senders
HTML Sanitization: Remove malicious content from HTML emails
AppleScript Sandboxing: Limited access to Mail.app APIs
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!

I Built a Native Apple Mail Plugin for OpenClaw

Jehadur Rahman (Emran) — Mon, 22 Jun 2026 02:45:58 +0000

If you are running an OpenClaw agent on a Mac, you probably already know the headache of trying to get your agent to read your Apple Mail inbox.

Because Apple intentionally makes iCloud Mail access difficult for third-party clients, the standard advice is usually a messy workaround: set up auto-forwarding to a Gmail account, and then use the Gmail webhook integrations to let OpenClaw read it.

I got tired of the webhook bridge, so today I built and published a native solution.

Introducing the OpenClaw Apple Mail Plugin

Instead of routing your personal emails through third-party servers, this plugin runs strictly local. It gives your OpenClaw agent the ability to directly read from your local Apple Mail database right on your Mac.

You can find the official plugin on the Clawhub registry here:
🔗 openclaw-apple-mail Plugin on Clawhub

How to get it running

Because this interacts directly with Apple's local ecosystem, there are a few permissions you need to grant macOS first (specifically Automation and full disk access for the Mail directory).

I wrote up a quick step-by-step guide to get past Apple's security prompts without pulling your hair out:
📖 Apple Mail Setup Guide

If you are running OpenClaw locally and want your agent to finally clear out your Apple Mail inbox without relying on external webhooks, give it a try. Let me know if you hit any weird edge cases with specific Mail configurations!

sample2

Jehadur Rahman (Emran) — Sat, 16 Oct 2021 00:35:00 +0000

test 2 data

sample

Jehadur Rahman (Emran) — Sat, 16 Oct 2021 00:28:12 +0000

test one

DEV Community: Jehadur Rahman (Emran)

Building an Apple Mail Channel Plugin for OpenClaw

Building an Apple Mail Channel Plugin for OpenClaw

🎯 The Problem

💡 The Solution

🛠️ Technical Stack

📦 Key Features

1. Per-Thread Session Isolation

2. Multi-Account Support

3. Security Features

4. Smart HTML Processing

📚 Publishing Journey

1. npm Registry

2. GitHub

3. ClawHub

4. OpenClaw Skill

🎓 Lessons Learned

1. Compiled Output Matters

2. Skills Enhance Adoption

3. Multi-Platform Publishing

🚀 Usage Example

Step 1: Install

Step 2: Configure

Step 3: Start

📊 Architecture

🔐 Security Considerations

🌟 Future Enhancements

📖 Resources

🤝 Contributing

💬 Feedback

I Built a Native Apple Mail Plugin for OpenClaw

Introducing the OpenClaw Apple Mail Plugin

How to get it running

sample2

sample