nextcloud-integration/skills/nextcloud-mail/SKILL.md

# Nextcloud Mail Skill

**Purpose:** Full-featured email client for Nextcloud with IMAP and SMTP support. Includes server-side search, attachment handling, and folder management.

**Location:** `~/bin/nextcloud-mail`

**Server:** https://teamworkapps.com (Nextcloud 25.0.13)

---

## Bootstrap Process (Automatic)

The skill will guide you through setting up email credentials:

**What you need to provide:**
- Nextcloud username
- Nextcloud password (or app token)
- IMAP server (default: teamworkapps.com)
- SMTP server (default: teamworkapps.com)
- IMAP port (default: 993 for SSL, 143 for STARTTLS)
- SMTP port (default: 465 for SSL, 587 for STARTTLS)
- Use SSL (default: true)
- Ignore certificate validity (default: false)

**The skill will:**
1. Ask for your email credentials
2. Build the nextcloud-mail tool with compile-time credentials
3. Immediately forget all credentials (never stored)
4. Provide instructions for using the tool

**Why this approach:**
- Credentials embedded at compile time (secure, local-only)
- No environment variables needed at runtime
- Simple command invocation

---

## Available Operations

### 1. List Folders
List all IMAP folders/mailboxes.

```bash
nextcloud-mail --op list-folders
```

**Example output:**
```
IMAP Folders:
  INBOX
  Sent
  Drafts
  Trash
  Archive
```

---

### 2. List Messages
List messages in a folder with pagination.

```bash
nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 25
```

**Parameters:**
- `--folder`: IMAP folder name (default: INBOX)
- `--page`: Page number (1-indexed, default: 1)
- `--page-size`: Messages per page (default: 25)

**Example output:**
```
Messages in INBOX (Page 1 of 3, showing 1-25 of 72):

UID: 1234
  From: John Doe <john@example.com>
  To: me@example.com
  Subject: Project Update
  Date: Fri, 20 Feb 2026 17:00:00 +0000
```

---

### 3. Get Message
Retrieve message content and handle attachments.

```bash
# Get message body
nextcloud-mail --op get-message --folder INBOX --uids 1234

# List attachments
nextcloud-mail --op get-message --folder INBOX --uids 1234 --list-attachments

# Save attachments to a directory
nextcloud-mail --op get-message --folder INBOX --uids 1234 --save-attachments --save-dir ./attachments
```

**Parameters:**
- `--folder`: IMAP folder
- `--uids`: Message UIDs (comma-separated)
- `--list-attachments`: List attachments only
- `--save-attachments`: Save attachments to disk
- `--save-dir`: Directory for saving attachments (default: .)

**Example output (list attachments):**
```
UID: 1234
  From: John Doe <john@example.com>
  Subject: Project Update
  Attachments (2):
    1. report.pdf (application/pdf) - Part: 1.2
    2. image.png (image/png) - Part: 1.3
```

**Example output (save attachments):**
```
UID: 1234
  From: John Doe <john@example.com>
  Subject: Project Update
  Saving attachments to ./attachments:
    Saved: report.pdf (1024576 bytes)
    Saved: image.png (45678 bytes)
```

---

### 4. Send Email
Send email with attachments.

```bash
# Simple email
nextcloud-mail --op send-email \
  --from me@example.com \
  --to recipient@example.com \
  --subject "Test Email" \
  --body "This is a test email"

# Email with attachments
nextcloud-mail --op send-email \
  --from me@example.com \
  --to recipient@example.com,recipient2@example.com \
  --subject "Report" \
  --body "Please find attached the report" \
  --attachments "./report.pdf,./image.png"
```

**Parameters:**
- `--from`: Sender email address (required)
- `--to`: Recipient email addresses (comma-separated, required)
- `--subject`: Email subject
- `--body`: Email body text
- `--attachments`: Attachment file paths (comma-separated)

---

### 5. Delete Messages
Delete messages by UID.

```bash
# Delete single message
nextcloud-mail --op delete-messages --folder INBOX --uids 1234

# Delete multiple messages
nextcloud-mail --op delete-messages --folder INBOX --uids 1234,1235,1236
```

**Parameters:**
- `--folder`: IMAP folder
- `--uids`: Message UIDs (comma-separated, required)

**Note:** Messages are permanently deleted (no undo).

---

### 6. Move Messages
Move messages between folders.

```bash
# Move single message
nextcloud-mail --op move-messages --folder INBOX --uids 1234 --dest-folder Archive

# Move multiple messages
nextcloud-mail --op move-messages --folder INBOX --uids 1234,1235 --dest-folder Archive
```

**Parameters:**
- `--folder`: Source folder
- `--uids`: Message UIDs (comma-separated, required)
- `--dest-folder`: Destination folder (required)

---

### 7. Search
Perform server-side search.

```bash
nextcloud-mail --op search --folder INBOX --query "project update"
```

**Parameters:**
- `--folder`: IMAP folder to search
- `--query`: Search query (searches message text)

**Example output:**
```
Found 3 messages matching 'project update' in INBOX:

UID: 1234
  From: John Doe <john@example.com>
  Subject: Project Update
  Date: Fri, 20 Feb 2026 17:00:00 +0000
```

---

## Security and Configuration

### Credential Priority

The tool supports multiple configuration methods (in priority order):

1. **Build-time ldflags** (highest priority)
   - Embedded at compile time
   - Most secure
   - No runtime configuration needed

2. **Environment variables** (fallback)
   ```bash
   export NEXTCLOUD_MAIL_IMAP_SERVER="teamworkapps.com"
   export NEXTCLOUD_MAIL_IMAP_PORT="993"
   export NEXTCLOUD_MAIL_IMAP_USER="username"
   export NEXTCLOUD_MAIL_IMAP_PASSWORD="password"
   export NEXTCLOUD_MAIL_SMTP_SERVER="teamworkapps.com"
   export NEXTCLOUD_MAIL_SMTP_PORT="465"
   export NEXTCLOUD_MAIL_SMTP_USER="username"
   export NEXTCLOUD_MAIL_SMTP_PASSWORD="password"
   ```

3. **Command-line flags** (lowest priority)
   ```bash
   nextcloud-mail --imap-server teamworkapps.com --imap-user username ...
   ```

### SSL/TLS and Certificate Validation

By default, the tool uses SSL/TLS with certificate validation:

```bash
# Use SSL/TLS with certificate validation (default)
nextcloud-mail --ssl=true --ignore-certs=false

# Use SSL/TLS but ignore certificate warnings (for self-signed certs)
nextcloud-mail --ssl=true --ignore-certs=true

# Use STARTTLS (non-SSL port)
nextcloud-mail --ssl=false
```

**Security Note:** Setting `--ignore-certs=true` is useful for self-signed certificates but reduces security. Use with caution.

---

## Use Cases and Workflows

### Workflow 1: Check for Important Emails

```bash
# List recent messages in INBOX
nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 10

# Get full message
nextcloud-mail --op get-message --folder INBOX --uids 1234
```

### Workflow 2: Download Attachments

```bash
# List attachments first
nextcloud-mail --op get-message --folder INBOX --uids 1234 --list-attachments

# Create directory and save attachments
mkdir -p ~/downloads/attachments
nextcloud-mail --op get-message --folder INBOX --uids 1234 --save-attachments --save-dir ~/downloads/attachments
```

### Workflow 3: Send Report with Attachments

```bash
# Compile report and send
nextcloud-mail --op send-email \
  --from me@example.com \
  --to client@example.com \
  --subject "Monthly Report - $(date +%Y-%m)" \
  --body "Please find the monthly report attached." \
  --attachments "./report.pdf,./summary.xlsx"
```

### Workflow 4: Clean Up Inbox

```bash
# Search for old emails
nextcloud-mail --op search --folder INBOX --query "old newsletter"

# Move to archive
nextcloud-mail --op move-messages --folder INBOX --uids 1234,1235,1236 --dest-folder Archive

# Delete spam
nextcloud-mail --op delete-messages --folder INBOX --uids 7890,7891
```

### Workflow 5: Monitor Specific Folder

```bash
# Check drafts folder
nextcloud-mail --op list-messages --folder Drafts --page 1

# Check sent items
nextcloud-mail --op list-messages --folder Sent --page 1 --page-size 50
```

---

## Error Handling

### Common Errors

**"failed to connect to IMAP server"**
- Check server address and port
- Verify SSL settings (`--ssl` flag)
- Try `--ignore-certs=true` for self-signed certificates

**"IMAP login failed"**
- Verify username and password
- Check if account is locked
- Ensure IMAP is enabled for the account

**"failed to select folder"**
- Verify folder name (case-sensitive)
- List folders first: `--op list-folders`
- Check if folder exists

**"folder is read-only"**
- Some folders (like shared folders) may not allow modifications
- Check folder permissions

**"failed to send email"**
- Verify SMTP server settings
- Check sender address
- Ensure SMTP authentication credentials are correct
- Verify recipient email addresses

---

## Best Practices

1. **Pagination** - Always use pagination for large folders
   ```bash
   nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 25
   ```

2. **Search Before Delete** - Verify messages before deletion
   ```bash
   nextcloud-mail --op search --folder INBOX --query "newsletter"
   nextcloud-mail --op delete-messages --folder INBOX --uids 1234,1235
   ```

3. **Attachment Management** - List attachments before saving
   ```bash
   nextcloud-mail --op get-message --folder INBOX --uids 1234 --list-attachments
   nextcloud-mail --op get-message --folder INBOX --uids 1234 --save-attachments --save-dir ./attachments
   ```

4. **Move Instead of Delete** - Use archive folder for safekeeping
   ```bash
   nextcloud-mail --op move-messages --folder INBOX --uids 1234 --dest-folder Archive
   ```

5. **Use Descriptive Subjects** - Makes searching easier
   ```bash
   nextcloud-mail --op send-email \
     --from me@example.com \
     --to recipient@example.com \
     --subject "[PROJECT] Meeting Notes - 2026-02-20" \
     --body "Meeting notes attached."
   ```

---

## Advanced Features

### Multiple Recipients

```bash
nextcloud-mail --op send-email \
  --from me@example.com \
  --to "alice@example.com,bob@example.com,charlie@example.com" \
  --subject "Team Update" \
  --body "Team update for the week."
```

### Custom IMAP/SMTP Servers

```bash
# Override build-time credentials
nextcloud-mail \
  --imap-server mail.example.com \
  --imap-port 993 \
  --smtp-server smtp.example.com \
  --smtp-port 465 \
  --op list-folders
```

### Batch Operations

```bash
# Delete multiple emails found by search
# First search to get UIDs
nextcloud-mail --op search --folder INBOX --query "spam"

# Then delete the UIDs you want
nextcloud-mail --op delete-messages --folder INBOX --uids 1234,1235,1236
```

---

## Testing

Test your email setup:

```bash
# 1. List folders (basic connectivity)
nextcloud-mail --op list-folders

# 2. List messages (IMAP working)
nextcloud-mail --op list-messages --folder INBOX --page 1

# 3. Send test email (SMTP working)
nextcloud-mail --op send-email \
  --from me@example.com \
  --to me@example.com \
  --subject "Email Test" \
  --body "This is a test email from nextcloud-mail"

# 4. Search (server-side search working)
nextcloud-mail --op search --folder INBOX --query "test"
```

---

*Nextcloud Mail Skill - Full email integration with IMAP and SMTP*