mail-organizer/CLAUDE.md

Mail-Organizer

PowerShell-based automation that reads emails via Microsoft Graph API and files attachments/documents into SharePoint document libraries with metadata.

Architecture

• Runtime: PowerShell 5.1 (Windows PowerShell, not pwsh)
• Auth: Azure AD App Registration, Client Credentials Flow (OAuth2)
• API: Microsoft Graph v1.0

Project Structure

scripts/
  Process-MailRules.ps1      # Main entry point -- processes emails against rules
  Run-ServiceLoop.ps1        # Service wrapper -- infinite loop calling Process-MailRules
  Install-Service.ps1        # Registers Windows service via NSSM (run as Admin)
  Uninstall-Service.ps1      # Removes Windows service via NSSM (run as Admin)
  Test-SharePointUpload.ps1  # Manual test script for SharePoint upload
  Test-Connection.ps1        # Connection/auth test
  GraphHelper.psm1           # Graph API auth + mail operations
  SharePointHelper.psm1      # SharePoint site/library/upload/metadata operations
  Logger.psm1                # File + console logging
config/
  settings.json              # Credentials (TenantId, ClientId, ClientSecret, MailboxUser) — NEVER commit
  rules.json                 # Email processing rules
  sharepoint-targets.json    # SharePoint upload targets with field definitions

SharePoint Config

Target site: krahgruppe.sharepoint.com:/shared/it (Information Technology subsite) Library: Protokolle with fields: Thema (choice), Datum (date), Kommentar (text)

Known Pitfalls

• Encoding: All .ps1/.psm1 files MUST be ASCII-only or UTF-8 with BOM. PowerShell 5.1 reads files without BOM as Windows-1252. UTF-8 multi-byte chars (e.g. em dash — = E2 80 94) break parsing because 0x94 = " in Windows-1252.
• Unapproved verb warning: Upload-SharePointDocument uses non-standard verb Upload → harmless warning on Import-Module.
• SharePoint site URL format: Use hostname:/path syntax (e.g. krahgruppe.sharepoint.com:/shared/it), not full https URL.