EmailOS Plugin for OpenCode

Natural language email integration for OpenCode using the mailos CLI. Send, read, search, and manage emails through simple commands.

Prerequisites

Before using this plugin, you must have mailos installed and configured on your system.

Installing mailos

# Clone and install mailos
git clone https://github.com/yourusername/emailos.git
cd emailos
npm install
npm link

Configuring mailos

Run the setup wizard to configure your email account:

mailos setup

Or configure manually:

mailos configure --email [email protected] --provider gmail

For project-specific configuration:

mailos configure --local --email [email protected]

Supported providers: gmail, outlook, yahoo, icloud, proton, fastmail, custom

Setup

1. Install Dependencies

npm install

2. Verify mailos Installation

mailos info

This should display your configured email settings.

Using from Other Projects

To use this plugin from any other OpenCode project, add the absolute path to your opencode.json:

Available Tools

The plugin provides 10 comprehensive email management tools:

1. email-send

Send emails with full feature support including attachments, CC/BCC, markdown body, and preview mode.

Parameters:

• to (required): Recipient email address
• subject (required): Email subject
• body (required): Email content (supports Markdown)
• account (optional): Sender account to use
• cc (optional): CC recipients (comma-separated)
• bcc (optional): BCC recipients (comma-separated)
• attach (optional): Attachment file paths (comma-separated)
• plain (optional): Send as plain text
• preview (optional): Preview without sending

Examples:

opencode run "send email to [email protected] with subject 'Hello' and body 'Test message'"
opencode run "send email with attachment report.pdf to [email protected]"

2. email-search

Advanced email search with filters for sender, subject, date range, attachments, and more.

Parameters:

• query (optional): Search query with boolean operators (AND, OR, NOT)
• from (optional): Filter by sender
• to (optional): Filter by recipient
• subject (optional): Filter by subject
• days (optional): Search last N days
• alltime (optional): Search all emails
• limit (optional): Max results (default: 10)
• unread (optional): Only unread emails
• hasAttachments (optional): Only emails with attachments
• type (optional): inbox, sent, drafts, all
• last (optional): Get most recent email only
• first (optional): Get oldest email only

Examples:

opencode run "search emails from [email protected] in last 7 days"
opencode run "find unread emails with attachments"
opencode run "get the last email with subject invoice"

3. email-read

Read full email content by message-id or list recent emails with attachment support.

Parameters:

• messageId (optional): Specific message-id to read
• recent (optional): Show recent emails
• limit (optional): Number of emails (default: 10)
• from (optional): Filter by sender
• account (optional): Email account to use
• json (optional): Output as JSON
• showAttachments (optional): Display attachment previews
• saveAttachments (optional): Directory to save attachments

Examples:

opencode run "read recent emails, show last 5"
opencode run "read email with message-id '<[email protected]>' and save attachments"

4. email-reply

Reply to emails preserving thread context with support for reply-all.

Parameters:

• messageId (required): Message-id to reply to
• body (optional): Reply text
• all (optional): Reply to all recipients
• account (optional): Email account to use
• draft (optional): Save as draft
• file (optional): Read body from file

Examples:

opencode run "reply to email '<[email protected]>' with 'Thanks!'"
opencode run "reply all with 'Team, please review this'"

5. email-forward

Forward emails to one or more recipients with optional additional message.

Parameters:

• messageId (required): Message-id to forward
• to (required): Recipients (comma-separated)
• body (optional): Additional message
• cc (optional): CC recipients
• bcc (optional): BCC recipients
• account (optional): Email account to use
• draft (optional): Save as draft

Examples:

opencode run "forward email '<[email protected]>' to [email protected]"
opencode run "forward with message 'FYI' to [email protected]"

6. email-delete

Delete emails by various criteria including sender, subject, or date range.

Parameters:

• ids (optional): Comma-separated email IDs
• from (optional): Delete from sender
• subject (optional): Delete by subject
• days (optional): Delete older than N days
• before (optional): Delete before date (YYYY-MM-DD)
• after (optional): Delete after date (YYYY-MM-DD)
• account (optional): Email account to use
• confirm (optional): Confirm deletion

Examples:

opencode run "delete emails from [email protected] with confirmation"
opencode run "delete emails older than 90 days with confirmation"

7. email-save

Save emails and attachments to files in various formats (eml, txt, json).

Parameters:

• emailId (optional): Specific email ID to save
• from (optional): Save from sender
• to (optional): Save to recipient
• subject (optional): Save by subject
• days (optional): Save from last N days
• format (optional): eml, txt, json
• outputDir (optional): Output directory
• attachmentsOnly (optional): Save only attachments
• account (optional): Email account to use
• limit (optional): Max emails (default: 10)

Examples:

opencode run "save emails from [email protected] to ./backup"
opencode run "save attachments only from emails with subject Reports"

8. email-sync

Sync emails from IMAP server to local filesystem using mbsync.

Parameters:

• account (optional): Email account to use
• days (optional): Sync from last N days
• all (optional): Sync all emails
• limit (optional): Max per folder (default: 100)
• dir (optional): Base directory
• verbose (optional): Show detailed progress

Examples:

opencode run "sync emails from last 7 days"
opencode run "sync all emails with verbose output"

9. email-unsubscribe

Find and manage unsubscribe links in emails.

Parameters:

• from (optional): Find from sender
• subject (optional): Find by subject
• number (optional): Emails to check (default: 10)
• account (optional): Email account to use
• open (optional): Open first link in browser
• autoOpen (optional): Auto-open without prompt
• moveToFolder (optional): Move to IMAP folder

Examples:

opencode run "find unsubscribe links in last 20 emails"
opencode run "find and open unsubscribe link from [email protected]"

10. email-logs

View command execution logs for debugging and monitoring.

Parameters:

• limit (optional): Number of recent logs

Examples:

opencode run "show me the email operation logs"
opencode run "show last 10 email logs"

Email Features

Sending Emails

The plugin automatically formats emails with Markdown support:

# Simple thank you
opencode run "thank [email protected] for the recommendation"

# Multiple recipients
mailos send -t [email protected] -t [email protected] -s "Team Update" -m "Meeting at 3pm"

# With file attachment
mailos send -t [email protected] -s "Report" -f report.md

Reading Emails

# Read latest 10 emails
opencode run "read my latest emails"

# Read unread emails only
mailos read --unread

# Read from specific sender
mailos read --from [email protected]

# Read last 7 days
mailos read --days 7

Searching Emails

# Search by keyword
opencode run "search for emails about invoices"

# Search from sender
mailos search --from [email protected]

# Find newsletters
opencode run "find all unsubscribe emails"

Managing Emails

# Mark emails as read
mailos mark-read --ids 1,2,3

# View configuration
mailos info

# Reconfigure
mailos configure

Configuration Management

EmailOS supports both global and local configuration:

• Global: Stored in ~/.email/config.json, used by default
• Local: Stored in .email/config.json in current directory, overrides global

Create a local configuration for project-specific email accounts:

mailos configure --local --email [email protected]

Markdown Support

All email bodies support full Markdown formatting:

• Bold: **text**
• Italic: *text*
• Headers: # H1, ## H2, ### H3
• Links: [text](https://example.com)
• Code blocks: ```code```
• Lists: - item or * item

Requirements

• Node.js
• OpenCode CLI
• mailos CLI (installed and configured)
• Email account with app-specific password or OAuth

Security

• Credentials are stored locally in .email/ or ~/.email/
• Uses app-specific passwords, not main account passwords
• Configuration files have restricted permissions (600)
• Never commits credentials to git

Architecture

The plugin uses two main tools:

1. email-auto: Natural language detection system that identifies email commands from conversational input
2. email-send: Direct email sending with explicit parameters

Both tools execute mailos CLI commands in the background, leveraging the mailos configuration system for account management.

Troubleshooting

mailos command not found

Ensure mailos is installed and linked:

npm link mailos
# or add to PATH
export PATH=$PATH:/path/to/mailos/bin

Configuration not found

Run the setup wizard:

mailos setup

Authentication errors

Use app-specific passwords, not your main email password. Generate one from your email provider's security settings.

Check configuration

mailos info

Related Documentation

• EmailOS Command Reference - Full mailos CLI documentation
• Main Repository CLAUDE.md - Project-wide instructions