Add Nextcloud integration tools

- CLI tools: nextcloud-client, nextcloud-contacts, nextcloud-calendar, nextcloud-mail - Build script with compile-time credentials - Skills for all four tools - Email tool supports IMAP/SMTP with attachment download
2026-02-20 17:24:13 +00:00
parent 8d932b1c15
commit 705f41a872
20 changed files with 5043 additions and 2 deletions
--- a/skills/nextcloud-mail/SKILL.md
+++ b/skills/nextcloud-mail/SKILL.md
@@ -0,0 +1,450 @@
+# 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*