npm package: @openpets/email
Description: EmailOS (mailos) integration for OpenCode - send, read, search, and manage emails from natural language
Author: OpenPets
Latest version: 1.0.7

# 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

```bash
# 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:

```bash
mailos setup
```

Or configure manually:

```bash
mailos configure --email your@email.com --provider gmail
```

For project-specific configuration:

```bash
mailos configure --local --email project@email.com
```

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

## Setup

### 1. Install Dependencies

```bash
npm install
```

### 2. Verify mailos Installation

```bash
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:**
```bash
opencode run "send email to user@example.com with subject 'Hello' and body 'Test message'"
opencode run "send email with attachment report.pdf to client@company.com"
```

### 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:**
```bash
opencode run "search emails from boss@company.com 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:**
```bash
opencode run "read recent emails, show last 5"
opencode run "read email with message-id '<abc@example.com>' 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:**
```bash
opencode run "reply to email '<msg-id@example.com>' 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:**
```bash
opencode run "forward email '<msg-id@example.com>' to team@company.com"
opencode run "forward with message 'FYI' to colleague@company.com"
```

### 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:**
```bash
opencode run "delete emails from spam@marketing.com 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:**
```bash
opencode run "save emails from client@company.com 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:**
```bash
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:**
```bash
opencode run "find unsubscribe links in last 20 emails"
opencode run "find and open unsubscribe link from newsletter@marketing.com"
```

### 10. email-logs
View command execution logs for debugging and monitoring.

**Parameters:**
- `limit` (optional): Number of recent logs

**Examples:**
```bash
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:

```bash
# Simple thank you
opencode run "thank john@example.com for the recommendation"

# Multiple recipients
mailos send -t alice@example.com -t bob@example.com -s "Team Update" -m "Meeting at 3pm"

# With file attachment
mailos send -t recipient@example.com -s "Report" -f report.md
```

### Reading Emails

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

# Read unread emails only
mailos read --unread

# Read from specific sender
mailos read --from sender@example.com

# Read last 7 days
mailos read --days 7
```

### Searching Emails

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

# Search from sender
mailos search --from john@example.com

# Find newsletters
opencode run "find all unsubscribe emails"
```

### Managing Emails

```bash
# 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:

```bash
mailos configure --local --email project@company.com
```

## 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:
```bash
npm link mailos
# or add to PATH
export PATH=$PATH:/path/to/mailos/bin
```

### Configuration not found

Run the setup wizard:
```bash
mailos setup
```

### Authentication errors

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

### Check configuration

```bash
mailos info
```

## Related Documentation

- [EmailOS Command Reference](/EMAILOS.md) - Full mailos CLI documentation
- [Main Repository CLAUDE.md](/CLAUDE.md) - Project-wide instructions