AI-powered email automation and classification engine, part of the Appa8 AI Process Automation Hub.

MailFlow ingests emails from IMAP or Microsoft 365, classifies them using a hybrid rule + LLM approach, automatically routes them to the correct folders, and provides full supervision via a web dashboard. Designed for on-premise deployments where data privacy is critical.

Features

  • IMAP and Microsoft Graph / Outlook ingestion
  • RFC822 email parsing with attachment handling
  • Hybrid classification: rule-based matching + local LLM validation (Qwen 2.5)
  • Auto-move to classified folders
  • PDF export with customisable path templates
  • Invoice worker: PDF QR extraction and payment data parsing
  • Learning Mode: human review and approval before filing
  • Natural language search via Telegram (“send invoices from vendor X in January”)
  • Encrypted credential storage (Fernet)
  • Redis job queues with AOF persistence
  • PostgreSQL persistence (async SQLAlchemy 2.0)
  • Streamlit supervision dashboard
  • Docker-based deployment with Traefik reverse proxy
  • CI/CD via GitHub Actions + Portainer auto-deployment

Architecture

Email Inbox (IMAP / Microsoft 365)
              │
              ▼
        email-worker
    (poll, parse, route)
              │
              ▼
         Redis Queue
              │
       ┌──────┴───────┐
       ▼              ▼
   ai-worker    invoice-worker
 (LLM classify)  (QR + finance)
       │
  ┌────┴────────────────────┐
  ▼           ▼             ▼
folder    review-worker  query-worker
 move     (Learning Mode) (NL search)
              │
        telegram-bot
     (approvals + search)
WorkerDescription
email-workerPolls IMAP / M365, routes by worker type
ai-workerMain classification engine with Redis job processing
invoice-workerFinancial document extraction from PDF QR codes
review-workerLearning Mode human review cards
query-workerNatural language search processing
telegram-botUser interface for commands and approvals

Dashboard

The Streamlit interface provides multi-tab supervision:

  • Email statistics with confidence metrics
  • Account management
  • Learned rules editing
  • Dynamic folder creation
  • Company and seller tracking
  • Invoice analytics with monthly summaries
  • Full audit logging

Tech Stack

Backend:

  • Python 3.12
  • FastAPI / AsyncIO
  • SQLAlchemy 2.0 (asyncpg)
  • PostgreSQL
  • Redis (AOF persistence)
  • httpx

AI:

  • Local LLM support (Qwen 2.5)
  • OpenAI-compatible APIs

Frontend:

  • Streamlit (dashboard)

Infrastructure:

  • Docker / Docker Compose
  • Traefik (reverse proxy)
  • GitHub Actions (CI/CD)
  • Portainer (auto-deployment)

Author

Ricardo Grangeia
Senior Software Engineer
Portugal

Website
https://ricardo.grangeia.pt

Project Github
https://github.com/ricgrangeia/ai-process-automation-hub-mailflow

License

MIT License