📄 2026-04-28-imap-proxy.md 2,254 bytes Apr 28, 2026 📋 Raw

2026-04-28 Evening — IMAP Proxy Live, Dashboard Updated

IMAP Proxy — Phase 6.2 Foundation (20:05 UTC)

Status: ✅ Infrastructure wired and dashboard live
Credentials: Pending Matt's iCloud app-specific password

What was built

  • imap_proxy/ module in hoffdesk-api:
  • proxy.py — IMAPProxy class with IDLE support, provider presets (iCloud/Gmail/Outlook/Yahoo), app-specific password auth
  • dashboard_router.py — /imap/status, /imap/metrics, /imap/dashboard endpoints
  • Auto-start on server startup if IMAP_USER + IMAP_PASSWORD env vars set
  • Dashboard updated:
  • IMAP Proxy card added to main dashboard (auto-refreshes every 10s)
  • System health card now includes IMAP proxy status
  • CSS for IMAP-specific styling
  • Auth bypass for /imap/ prefix (health/metrics, no sensitive data)

Endpoints

  • GET /imap/status — JSON proxy status (provider, connection, emails processed)
  • GET /imap/metrics — Recent email processing metrics
  • GET /imap/dashboard — HTMX fragment for dashboard embed
  • Dashboard at family.hoffdesk.com now includes IMAP card

To activate iCloud Mail

  1. Generate app-specific password at appleid.apple.com
  2. Add to hoffdesk-api .env:
    IMAP_PROVIDER=icloud IMAP_USER=your_email@icloud.com IMAP_PASSWORD=xxxx-xxxx-xxxx-xxxx
  3. Restart server → proxy auto-connects via IMAP IDLE

Architecture

  • Outbound-only (appliance-initiated, no inbound tunnels)
  • IMAP IDLE for real-time push notification
  • Fallback poll every 30s if IDLE unsupported
  • Auth circuit breaker: 3 consecutive failures → alert Matt, silence
  • Zero-config ingress: iCloud App Password → IMAP IDLE → Document Pipeline

Files Modified/Created

  • NEW: hoffdesk-api/imap_proxy/__init__.py
  • NEW: hoffdesk-api/imap_proxy/proxy.py
  • NEW: hoffdesk-api/imap_proxy/dashboard_router.py
  • MODIFIED: hoffdesk-api/main_v2.py (added IMAP router + startup/shutdown hooks)
  • MODIFIED: hoffdesk-api/dashboard/router.py (IMAP health check)
  • MODIFIED: hoffdesk-api/shared/session_auth.py (IMAP auth bypass)
  • MODIFIED: shared/project-docs/dashboard/templates/index.html (IMAP card)
  • MODIFIED: shared/project-docs/dashboard/static/style.css (IMAP styles)
← Back