Channels
Apple Mail
By Apple Mail channel plugin for OpenClaw and Hermes - AppleScript integration with per-thread session isolation for macOS Mail.app
Install
npm install
#README
# ?? openclaw-apple-mail
[](https://opensource.org/licenses/MIT)
[](https://github.com/openclaw/openclaw)
[](https://www.apple.com/macos/)
Apple Mail channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) and [Hermes](https://github.com/hermesai/hermes). Uses AppleScript to integrate with Mail.app on macOS, providing **isolated sessions per email thread**.
## ? Key Features
### ?? Per-Thread Session Isolation
Each email thread gets its own OpenClaw/Hermes session via the session key:
\\\
agent:main:apple-mail:{email}:{threadId}
\\\
This ensures:
- ? Each email thread has isolated conversation history
- ? No mixing of conversations between different emails
- ? Follow-ups automatically go to the correct thread
- ? Works with OpenClaw's built-in session management
### ??? Security Features
- **Allowlist enforcement**: Only process emails from approved senders
- **Self-reply prevention**: Avoids infinite loops
- **Outbound restrictions**: Control who can receive replies
- **Thread reply policies**: Flexible access control
### ?? HTML Table Support
- Extract and process HTML tables from emails
- Preserve table structure and formatting
- Sanitize HTML content for security
## ?? Quick Start
### Prerequisites
- macOS with Mail.app configured
- OpenClaw >= 2026.1.0 or Hermes >= 2026.1.0
- Node.js >= 18.0.0
### Installation
#### For OpenClaw:
\\\ash
openclaw plugins install --link /path/to/openclaw-apple-mail
\\\
#### For Hermes:
\\\ash
hermes plugins install --link /path/to/openclaw-apple-mail
\\\
## ?? Configuration
### For OpenClaw
Add to your \~/.openclaw/openclaw.json\:
\\\json
{
"channels": {
"apple-mail": {
"enabled": true,
"accounts": {
"[email protected]": {
"email": "[email protected]",
"mailboxAccount": "iCloud",
"allowFrom": [
"[email protected]",
"[email protected]"
],
"pollIntervalMs": 30000,
"archiveOnReply": false
}
}
}
}
}
\\\
### For Hermes
Add to your \~/.hermes/hermes.json\:
\\\json
{
"channels": {
"apple-mail": {
"enabled": true,
"accounts": {
"[email protected]": {
"email": "[email protected]",
"mailboxAccount": "iCloud",
"allowFrom": [
"[email protected]"
],
"pollIntervalMs": 30000
}
}
}
}
}
\\\
## ?? Configuration Options
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| \email\ | string | � | Email address (required) |
| \mailboxAccount\ | string | \"iCloud"\ | Apple Mail account name |
| \llowFrom\ | string[] | \[]\ | Sender allowlist. \["*"]\ allows all |
| \pollIntervalMs\ | number | \30000\ | Polling interval in ms |
| \rchiveOnReply\ | boolean | \ alse\ | Archive thread after reply |
| \includeQuotedReplies\ | boolean | \ rue\ | Include thread history in replies |
| \includeThreadContext\ | boolean | \ alse\ | Include context from non-allowed senders |
## ??? How It Works
\\\
Mail.app INBOX
? (AppleScript polling)
AppleMailClient
? (parse inbound)
OpenClaw/Hermes Gateway
? (SessionKey: agent:main:apple-mail:email:threadId)
Agent (isolated session per thread)
? (reply)
AppleMailClient.replyToMessage
? (AppleScript)
Mail.app ? Sent
\\\
### Thread Detection
Generates stable thread IDs using:
\\\ ypescript
threadId = md5(cleanSubject + ":" + senderEmail)
\\\
This ensures:
- Same subject + sender = same thread
- "Re:", "Fwd:" prefixes are normalized
- Consistent thread tracking across conversations
## ?? Security Best Practices
1. **Use Allowlists**: Always configure \llowFrom\ in production
2. **Dedicated Accounts**: Use separate email accounts for agent communication
3. **Monitor Logs**: Regularly review session logs for suspicious activity
4. **Update Regularly**: Keep the plugin updated for security patches
5. **File Permissions**: Protect your configuration files (\chmod 600\)
## ??? Development
\\\ash
# Clone the repository
git clone https://github.com/JehadurRE/openclaw-apple-mail.git
cd openclaw-apple-mail
# Install dependencies
npm install
# Build
npm run build
# Link for local testing with OpenClaw
openclaw plugins install --link .
# Or with Hermes
hermes plugins install --link .
\\\
## ?? Architecture
- **\src/channel.ts\** - Main channel implementation
- **\src/applescript-client.ts\** - AppleScript interface
- **\src/inbound.ts\** - Inbound message processing
- **\src/outbound.ts\** - Outbound reply handling
- **\src/monitor.ts\** - Email polling and monitoring
- **\src/threading.ts\** - Thread ID generation
- **\src/html-processor.ts\** - HTML table extraction
- **\src/session-watcher.ts\** - Session state management
## ?? Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## ?? License
MIT License - see [LICENSE](LICENSE) file for details.
Copyright (c) 2026 Md. Jehadur Rahman (Emran)
## ?? Author
**Md. Jehadur Rahman (Emran)**
- GitHub: [@JehadurRE](https://github.com/JehadurRE)
- Website: [jehadurre.me](https://jehadurre.me)
- Dev.to: [@jehadurre](https://dev.to/jehadurre)
## ?? Acknowledgments
- OpenClaw team for the extensible plugin architecture
- Hermes team for AI agent framework
- Apple Mail.app for AppleScript support
## ?? Related Projects
- [OpenClaw](https://github.com/openclaw/openclaw) - AI Agent Framework
- [Hermes](https://github.com/hermesai/hermes) - AI Agent Platform
## ?? Support
- ?? [Report Bugs](https://github.com/JehadurRE/openclaw-apple-mail/issues)
- ?? [Request Features](https://github.com/JehadurRE/openclaw-apple-mail/issues)
- ?? [Documentation](https://github.com/JehadurRE/openclaw-apple-mail/wiki)
---
**Made with ?? by Md. Jehadur Rahman (Emran)**
channels
Comments
Sign in to leave a comment