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.

nextcloud-mail --op list-folders

Example output:

IMAP Folders:
  INBOX
  Sent
  Drafts
  Trash
  Archive

---

2. List Messages

List messages in a folder with pagination.

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.

# 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.

# 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.

# 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.

# 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.

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)

   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)

   nextcloud-mail --imap-server teamworkapps.com --imap-user username ...
   

SSL/TLS and Certificate Validation

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

# 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

# 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

# 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

# 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

# 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

# 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

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

2. Search Before Delete - Verify messages before deletion

   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

   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

   nextcloud-mail --op move-messages --folder INBOX --uids 1234 --dest-folder Archive
   

5. Use Descriptive Subjects - Makes searching easier

   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

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

# 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

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

# 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