Add exportmessages action to IMAP, POP3, and MS Graph protocols

[ziembor]

Summary

This PR adds a new exportmessages action across three email protocols (IMAP, POP3, and MS Graph) that allows users to search for messages by Internet Message-ID and/or subject substring, then export matching messages as raw RFC822 .eml files.

Key Changes

New Features

• IMAP: Added exportmessages command that uses SEARCH to find messages by Message-ID/Subject headers and exports them via FETCH
• POP3: Added exportmessages command that uses TOP to fetch headers for matching criteria and RETR to export full messages
• MS Graph: Added exportmessages command that uses OData filters to search by internetMessageId and subject, then downloads raw MIME content

Shared Infrastructure

• Created new internal/common/export package with:
  • CreateExportDir(): Generates dated export directories (<baseDir>/export/YYYY-MM-DD/)
  • SanitizeFilename(): Sanitizes filenames for filesystem safety
• Refactored MS Graph's existing createExportDir() and sanitizeFilename() functions to use the shared package

Protocol-Specific Implementations

• IMAP (internal/protocols/imap/):

  • Added SelectMailbox(), SearchMessages(), and FetchRFC822() client methods
  • New exportmessages.go with search/export logic and CSV logging
  • Updated config to support messageid, subject, mailbox, count, and exportdir parameters

• POP3 (internal/protocols/pop3/):

  • Added Top() and Retr() client methods for header/body retrieval
  • New exportmessages.go with header matching and export logic
  • Updated config to support messageid, subject, count, and exportdir parameters

• MS Graph (internal/protocols/msgraph/):

  • Added exportMessages() and exportMessageToEML() handlers
  • New JMAP protocol helpers: NewEmailGetRequest(), ParseEmailGetResponse(), and BuildEmailSearchFilter()
  • Updated config to support exportdir parameter
  • Added validateSearchSubject() utility for OData filter validation

Documentation

• Updated docs/protocols/imap.md, docs/protocols/pop3.md, and docs/protocols/msgraph.md with usage examples and flag documentation for the new exportmessages action

Implementation Details

• Search Criteria: All implementations support searching by Message-ID (exact match) and/or Subject (substring match). At least one criterion must be provided.
• Export Format: Messages are exported as raw RFC822 .eml files with sanitized filenames based on Message-ID or message number/UID
• CSV Logging: Each protocol logs export results to CSV with action status, server details, and error information
• Rate Limiting: IMAP and POP3 implementations respect configured rate limits during API calls
• OData Security: MS Graph implementation escapes single quotes in search filters for defense-in-depth protection

https://claude.ai/code/session_01XqmZvaRnk6rQ2whp5DaBb5