emailToChat/README.md

EmailToChat

Gestore email desktop multi-canale con AI integrata. Riceve email via IMAP, le inoltra automaticamente su SMTP, Telegram e WhatsApp secondo regole personalizzabili, e permette di analizzarle con Claude (Anthropic), OpenAI o Ollama locale.

Funzionalità

• Multi-account: configura più caselle IMAP/SMTP, più bot Telegram, più sessioni WhatsApp in parallelo.
• Ricezione IMAP con polling configurabile per casella, parsing completo (mailparser) di body HTML/testo e allegati.
• Invio SMTP via nodemailer, con allegati e from-name personalizzabile.
• Bot Telegram via telegraf (Telegram Bot API). Supporta lunghi messaggi con auto-chunk, foto e documenti.
• WhatsApp via whatsapp-web.js. Login QR-code, sessione persistente locale, invio testo e media.
• Motore di forwarding con regole basate su: from/to/oggetto/corpo/allegati e categoria AI. Template messaggi con placeholder.
• AI multi-provider: Anthropic Claude, OpenAI, Ollama. Funzioni:
  • Classificazione (automatica al ricevimento o on-demand)
  • Riassunto (on-demand)
  • Estrazione informazioni strutturate in JSON (date, importi, action items…)
  • Bozza di risposta suggerita
• Rubrica contatti condivisa tra i canali.
• DB SQLite locale (better-sqlite3), salvato nella userData di Electron.
• Toast notifications per nuovi messaggi ed errori in tempo reale.

Stack tecnico

• Electron + electron-vite
• TypeScript
• React 18 + Tailwind CSS
• better-sqlite3, imapflow, mailparser, nodemailer, telegraf, whatsapp-web.js
• @anthropic-ai/sdk, openai (SDK)

Setup

Prerequisiti

• Node.js 20+ e npm
• macOS, Windows o Linux
• (Per WhatsApp) connessione internet stabile + sufficienti risorse per Puppeteer headless

Installazione

npm install

postinstall esegue electron-builder install-app-deps che ricompila i moduli nativi (better-sqlite3) per la versione di Electron usata.

Avvio in sviluppo

npm run dev

Apre l'app in modalità dev con hot-reload del renderer.

Build di produzione

npm run build
npm run dist:mac     # oppure dist:win / dist:linux

L'output finisce in release/.

Primo utilizzo

1. Configurare un account Email (IMAP+SMTP)

Pagina Email Account → + Nuovo account.

Esempio Gmail (richiede una "App Password" se hai 2FA attiva):

Campo	Valore
IMAP host	imap.gmail.com
IMAP porta	993
IMAP secure	sì
SMTP host	smtp.gmail.com
SMTP porta	465
SMTP secure	sì
User / Password	la tua email + app password

Clicca Test per verificare la connessione. Se l'account è attivo, il polling parte automaticamente.

2. Configurare un bot Telegram

1. Apri Telegram → scrivi a @BotFather → /newbot → segui le istruzioni.
2. Copia il token e incollalo in Telegram → + Nuovo bot.
3. Per ottenere il tuo chat_id: scrivi al bot, poi apri nel browser: https://api.telegram.org/bot<TOKEN>/getUpdates → cerca "chat":{"id":...}.

3. Configurare una sessione WhatsApp

1. Vai su WhatsApp → + Nuova sessione → dai un nome.
2. Clicca Avvia: comparirà un QR code.
3. Apri WhatsApp sul telefono → Impostazioni → Dispositivi collegati → Collega un dispositivo → scansiona il QR.
4. Quando lo stato passa a ready, la sessione è pronta. Resta autenticata anche dopo il riavvio dell'app (sessione salvata in userData/whatsapp-sessions/).

4. Configurare l'AI

Pagina AI → + Nuovo provider.

• Anthropic: ottieni una API key da console.anthropic.com, modello consigliato claude-haiku-4-5-20251001 per velocità o claude-sonnet-4-6 per qualità.
• OpenAI: API key da platform.openai.com, modello consigliato gpt-4o-mini.
• Ollama: avvia Ollama localmente (ollama serve) e indica http://localhost:11434 come Base URL. Esempio modello: llama3.2.

Imposta un provider come predefinito (per azioni on-demand) e attiva Classificazione automatica su uno solo dei provider per categorizzare ogni email all'arrivo.

5. Creare una regola di inoltro

Esempio: "Inoltra su Telegram tutte le email categorizzate come fattura".

Pagina Regole Forward → + Nuova regola:

• Filtro: Categoria AI = fattura
• Destinazione: canale telegram, identifier 1:123456789 (bot id 1, chat 123456789)
• Includi corpo: sì
• Includi allegati: sì

Per inoltrare su WhatsApp invece, l'identifier ha formato sessionId|numero (es. 1|393331234567). Se vuoi usare il destinatario predefinito della sessione, scrivi solo 1|.

6. Comporre e inviare un messaggio

Pagina Componi: scegli canale (SMTP/Telegram/WhatsApp), account/bot/sessione, destinatario, messaggio. I contatti in rubrica appaiono come suggerimenti.

Struttura del progetto

EmailToChat/
├── electron.vite.config.ts      # Configurazione electron-vite
├── package.json
├── src/
│   ├── main/                    # Electron main process
│   │   ├── index.ts             # Bootstrap finestra + servizi
│   │   ├── ipc.ts               # IPC handlers
│   │   ├── db/
│   │   │   ├── database.ts      # SQLite + migrations
│   │   │   └── repositories.ts  # Repository pattern
│   │   └── services/
│   │       ├── imap.ts          # Polling IMAP
│   │       ├── smtp.ts          # Invio SMTP
│   │       ├── telegram.ts      # Bot Telegram
│   │       ├── whatsapp.ts      # whatsapp-web.js
│   │       ├── ai.ts            # Anthropic/OpenAI/Ollama
│   │       └── forwarder.ts     # Motore regole
│   ├── preload/
│   │   ├── index.ts             # contextBridge IPC
│   │   └── index.d.ts           # Tipi window.api
│   ├── renderer/
│   │   ├── index.html
│   │   └── src/
│   │       ├── App.tsx
│   │       ├── main.tsx
│   │       ├── styles.css
│   │       ├── components/      # Sidebar, Modal, Toaster, PageHeader
│   │       └── views/           # 8 pagine UI
│   └── shared/
│       ├── types.ts             # DTO condivisi main/renderer
│       └── ipc-channels.ts      # Costanti canali IPC

Dati e privacy

• Tutti i dati sono memorizzati localmente in:
  • macOS: ~/Library/Application Support/EmailToChat/
  • Windows: %APPDATA%/EmailToChat/
  • Linux: ~/.config/EmailToChat/
• DB: data/emailtochat.db
• Allegati: attachments/<accountId>/<messageId>/
• Sessioni WhatsApp: whatsapp-sessions/wa-<id>/
• Le API key dei provider AI sono salvate in chiaro nel DB. Per maggiore sicurezza puoi cifrare il filesystem.

Note operative

• Gmail App Passwords: se hai 2FA, devi generare una password app-specifica da https://myaccount.google.com/apppasswords.
• whatsapp-web.js dipende da Chromium scaricato da Puppeteer (~150 MB al primo npm install).
• Telegram Bot vs Channel: per inviare a un canale, il bot deve esserne admin e il chat_id ha la forma -100xxxxxxxxx.
• Limite messaggi Telegram: 4096 caratteri, l'app fa auto-chunk.
• Polling IMAP minimo: 15 secondi per evitare ban dai provider email.

Sviluppi futuri suggeriti

• Cifratura del DB (sqlcipher) per le credenziali
• IMAP IDLE invece di polling per ricezione push
• Search globale su messaggi
• Allegati Telegram/WhatsApp anche per messaggi outbound dalla compose UI
• Support webhook per Telegram in alternativa al long-polling
• Pannello "AI Chat" per fare domande sull'intera casella

Licenza

MIT