ClawHub

Apple Mail Channel Setup

Other

Assist with installing, configuring, and using the Apple Mail channel plugin for OpenClaw/Hermes on macOS to monitor and respond to emails.

Install

openclaw skills install @jehadurre/apple-mail-setup

Apple Mail Channel Setup & Configuration Skill

Overview

This skill helps you install, configure, and use the Apple Mail channel plugin for OpenClaw and Hermes on macOS.

Prerequisites

  • macOS system (required for Apple Mail and AppleScript)
  • Apple Mail.app configured with at least one email account
  • Node.js >= 18.0.0
  • OpenClaw >= 2026.1.0 or Hermes

Installation

Step 1: Install the Plugin

# Via ClawHub (Recommended)
openclaw plugins install @jehadurre/openclaw-apple-mail

# Or via npm
npm install @jehadurre/openclaw-apple-mail

Step 2: Verify Installation

openclaw plugins list
# Should show: @jehadurre/openclaw-apple-mail@1.0.1

Configuration

Basic Configuration

Add to your openclaw.json or Hermes config:

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

Configuration Options

enabled (boolean)

  • Default: true
  • Description: Enable or disable the Apple Mail channel globally

accounts (object)

Define one or more email accounts to monitor.

Per-Account Settings:

email (string, required)

  • Your email address as configured in Apple Mail

mailboxAccount (string)

  • Default: "iCloud"
  • The account name in Apple Mail (e.g., "iCloud", "Gmail", "Work")

allowFrom (array of strings)

  • Default: []
  • Sender allowlist for security
  • Use ["*"] to allow all senders
  • Use ["boss@company.com", "client@domain.com"] for specific senders

pollIntervalMs (number)

  • Default: 30000 (30 seconds)
  • How often to check for new emails (in milliseconds)

archiveOnReply (boolean)

  • Default: false
  • Automatically archive email thread after sending reply

Multi-Account Configuration Example

{
  "channels": {
    "apple-mail": {
      "enabled": true,
      "accounts": {
        "work": {
          "email": "john@company.com",
          "mailboxAccount": "Exchange",
          "allowFrom": ["*"],
          "pollIntervalMs": 15000,
          "archiveOnReply": true
        },
        "personal": {
          "email": "john@gmail.com",
          "mailboxAccount": "Gmail",
          "allowFrom": ["family@domain.com", "friend@email.com"],
          "pollIntervalMs": 60000,
          "archiveOnReply": false
        }
      }
    }
  }
}

Usage

Starting the Channel

# Start OpenClaw/Hermes with Apple Mail channel
openclaw start

# Or for Hermes
hermes start

The plugin will:

  1. Connect to Apple Mail via AppleScript
  2. Monitor configured mailboxes
  3. Create isolated sessions per email thread
  4. Allow AI agents to read and respond to emails

Testing the Setup

Send a test email to one of your configured accounts. OpenClaw/Hermes should:

  • Detect the new email
  • Create a session for the thread
  • Process according to your agent configuration

Monitoring

# Check OpenClaw logs
openclaw logs

# Check active sessions
openclaw sessions list

Features

Per-Thread Session Isolation

Each email thread gets its own isolated session, preventing context mixing between conversations.

HTML Processing

  • Automatically extracts and cleans HTML email content
  • Converts tables to markdown
  • Sanitizes potentially malicious content
  • Preserves formatting for AI agents

Smart Threading

  • Maintains conversation context across replies
  • Groups related emails together
  • Handles Re: and Fwd: prefixes correctly

Security

  • Sender allowlist per account
  • HTML sanitization
  • AppleScript sandboxing

Troubleshooting

Issue: Plugin not found

# Reinstall
npm install -g @jehadurre/openclaw-apple-mail
openclaw plugins install @jehadurre/openclaw-apple-mail

Issue: AppleScript permissions denied

  1. Open System Preferences → Security & Privacy → Privacy
  2. Select Automation
  3. Enable access for Terminal/OpenClaw to control Mail.app

Issue: Emails not detected

  • Verify email matches exactly as configured in Mail.app
  • Check mailboxAccount name matches the account in Mail.app
  • Ensure Mail.app is running
  • Check allowFrom settings

Issue: Cannot send replies

  • Verify account has send permissions in Mail.app
  • Check Mail.app can send emails manually
  • Review OpenClaw logs for errors

Advanced Configuration

Custom Polling Intervals per Account

For high-priority work email:

{
  "work": {
    "email": "urgent@company.com",
    "pollIntervalMs": 5000  // Check every 5 seconds
  }
}

For low-priority personal email:

{
  "personal": {
    "email": "casual@gmail.com",
    "pollIntervalMs": 300000  // Check every 5 minutes
  }
}

Strict Sender Filtering

Only allow specific clients and your boss:

{
  "work": {
    "email": "sales@company.com",
    "allowFrom": [
      "boss@company.com",
      "client1@bigcorp.com",
      "client2@enterprise.com"
    ]
  }
}

Auto-Archive for Customer Support

Automatically archive threads after replying:

{
  "support": {
    "email": "support@company.com",
    "archiveOnReply": true,
    "pollIntervalMs": 10000
  }
}

API Reference

Channel ID

apple-mail

Configuration Schema

See openclaw.plugin.json for full JSON schema.

Events

  • email:received - New email detected
  • email:sent - Reply sent successfully
  • session:created - New thread session created
  • session:archived - Thread archived

Links

Support

For issues, questions, or contributions:

  1. Check the GitHub Issues
  2. Read the Contributing Guide
  3. Contact the author via Dev.to @jehadurre

License

MIT License - See LICENSE

Version: 1.0.1
Author: Md. Jehadur Rahman (Emran)
Last Updated: June 2026