# Email Strategy & Domain Reputation - Implementation Doc

## 📋 PROBLEMA RISOLTO

Il sistema permetteva di **cambiare mittente per ogni campagna**, distruggendo la reputazione del dominio:
- ❌ Campo `fromEmail` editabile per campagna
- ❌ Campo `fromName` editabile per campagna
- ❌ Nessun rate limiting
- ❌ Nessun monitoraggio bounce rate

**Conseguenze**: Email sempre in spam, impossibile fare domain warmup, reputazione dominio ZERO.

---

## ✅ SOLUZIONE IMPLEMENTATA

### 1. **Mittente Fisso (OBBLIGATORIO)**

**Backend (`email.service.js`)**:
- SEMPRE usa `FROM_EMAIL` da `.env` (marketing@gixmkt.cloud)
- SEMPRE usa `FROM_NAME` da `.env` (GIX Marketing)
- SEMPRE usa `REPLY_TO` da `.env` (giovanni@gix.management)
- Ignora completamente valori da Campaign model (anche se presenti nel DB)

**Frontend (`CampaignBuilderView.vue`)**:
- Campi `fromEmail` e `fromName` **RIMOSSI** dall'interfaccia
- Alert informativo: "Mittente fisso per costruire reputazione dominio"
- Form data non include più questi campi

**Database**:
- Campi `from_email`, `from_name`, `reply_to` in `campaigns` **MANTENUTI** per backward compatibility
- Valori salvati sempre con defaults da `.env`
- **IGNORATI** durante l'invio

---

### 2. **Domain Warmup Service**

**File**: `/backend/src/services/warmup.service.js`

**Strategia Graduata**:
```
Fase 1 (Settimana 1-2):   50 email/giorno   ← ATTUALE
Fase 2 (Settimana 3-4):  100 email/giorno
Fase 3 (Settimana 5-6):  250 email/giorno
Fase 4 (Settimana 7-8):  500 email/giorno
Fase 5 (Dopo 2 mesi):    UNLIMITED
```

**Funzionalità**:
- `canSendEmail()`: Verifica se possiamo inviare oggi
- `validateBatch(size)`: Valida dimensione batch prima dell'invio
- `calculateOptimalDelay(total)`: Calcola delay tra invii (distribuisce su 8h lavorative)
- `getWarmupStats()`: Statistiche complete fase corrente

**Configurazione** (`.env`):
```bash
WARMUP_START_DATE=2026-02-12  # Data inizio warmup
```

**Logica di Blocco**:
- ❌ Blocca invio se limite giornaliero raggiunto
- ⚠️ Warning se batch > 30% del limite giornaliero
- ✅ Approva batch entro limiti con delay raccomandato

---

### 3. **Bounce Monitoring Service**

**File**: `/backend/src/services/bounce.service.js`

**Soglie di Sicurezza**:
```javascript
bounceRate:
  warning:  5%   ⚠️
  critical: 10%  🚨 BLOCCO INVII

spamRate:
  warning:  0.1%  ⚠️
  critical: 0.5%  🚨 BLOCCO INVII

openRate:
  low: < 10%     ⚠️ Contenuto sospetto
  good: > 15%    ✅
  excellent: > 25% 🎯
```

**Funzionalità**:
- `getQualityMetrics(days)`: Metriche ultimi N giorni (bounce, open, click rate)
- `isSafeToSend()`: Verifica sicurezza invio (ritorna blocco se bounce critico)
- `identifyProblematicContacts()`: Trova email con bounce ripetuti
- `generateReport()`: Report completo con raccomandazioni

**Health Status**:
- `excellent`: Bounce < 2%, Open > 25%
- `good`: Bounce < 5%, Open > 15%
- `warning`: Bounce 5-10% o Open < 10%
- `critical`: Bounce > 10% → **BLOCCO INVII**

---

### 4. **Monitoring API Routes**

**File**: `/backend/src/routes/monitoring.routes.js`

**Endpoints** (autenticati):

```bash
GET /api/monitoring/warmup
# Ritorna stato warmup: fase corrente, limite giornaliero, invii oggi

GET /api/monitoring/bounce
# Ritorna report qualità: bounce rate, open rate, contatti problematici

GET /api/monitoring/health
# Ritorna stato globale: warmup + quality + blockers

POST /api/monitoring/validate-batch
# Body: { "batchSize": 100 }
# Ritorna: approved/rejected + delay raccomandato
```

**Esempio Response Health**:
```json
{
  "success": true,
  "data": {
    "canSend": true,
    "status": "healthy",
    "warmup": {
      "phase": "Fase 1 - Avvio",
      "dailyLimit": 50,
      "sent": 0,
      "remaining": 50
    },
    "quality": {
      "bounceRate": 0.02,
      "openRate": 0.18,
      "status": "good"
    },
    "blockers": []
  }
}
```

---

### 5. **Integrazione in Campaign Service**

**File**: `/backend/src/services/campaigns.service.js`

**Modifiche a `scheduleCampaign()`**:

```javascript
// PRIMA: Inviava senza controlli
await campaign.update({ status: 'sending' });

// DOPO: Valida warmup + quality
const warmupValidation = await warmupService.validateBatch(contacts.length);
if (!warmupValidation.approved) {
  throw new Error(`Warmup failed: ${warmupValidation.reason}`);
}

const safetyCheck = await bounceService.isSafeToSend();
if (!safetyCheck.safe) {
  throw new Error(`Safety check failed: ${safetyCheck.reason}`);
}

// Poi procede con invio
```

**Risultato**:
- ❌ Blocca campagne che superano limite giornaliero
- ❌ Blocca campagne se bounce rate critico
- ⚠️ Warning se batch troppo grande per fase corrente
- ✅ Log delay raccomandato per ottimizzare distribuzione

---

## 🎯 UTILIZZO

### Scenario 1: Inviare Prima Campagna

```bash
1. Check warmup status:
GET /api/monitoring/warmup
→ Fase 1: 50 email/giorno disponibili

2. Validate batch:
POST /api/monitoring/validate-batch
{ "batchSize": 30 }
→ ✅ Approved, delay: 960000ms (16min tra invii)

3. Schedule campaign:
POST /api/campaigns/:id/schedule
{ "sendNow": true }
→ ✅ Campagna accodata, 30 email distribuite su 8h
```

### Scenario 2: Batch Troppo Grande

```bash
POST /api/monitoring/validate-batch
{ "batchSize": 100 }
→ ❌ REJECTED
{
  "approved": false,
  "reason": "Batch troppo grande per oggi (100 > 50)",
  "maxAllowed": 50,
  "suggestion": "Riduci a 50 email o distribuisci su più giorni"
}
```

### Scenario 3: Bounce Rate Critico

```bash
GET /api/monitoring/bounce
→ {
  "bounceRate": 0.12,  // 12% !!!
  "status": "critical",
  "alert": {
    "level": "critical",
    "message": "Bounce rate critico: 12.00%. SOSPENDI invii",
    "action": "suspend_sending"
  }
}

POST /api/campaigns/:id/schedule
→ ❌ ERROR: "Safety check failed: Bounce rate critico..."
```

---

## 📊 DASHBOARD METRICS

**Da Implementare nel Frontend**:

1. **Warmup Progress Card**:
   - Barra progresso fase corrente
   - Email inviate oggi / limite
   - Giorni rimanenti alla fase successiva

2. **Quality Metrics Card**:
   - Bounce rate ultimi 7 giorni
   - Open rate trend
   - Status indicator (🟢 good / 🟡 warning / 🔴 critical)

3. **Daily Send Capacity**:
   - Gauge circolare: email disponibili oggi
   - Countdown reset giornaliero (00:00)

---

## 🔧 CONFIGURAZIONE

**Variabili `.env` Critiche**:

```bash
# Email Provider (FISSO)
EMAIL_PROVIDER=sendgrid
SENDGRID_API_KEY=SG.xxx...
FROM_EMAIL=marketing@gixmkt.cloud      # ⚠️ NON CAMBIARE MAI
FROM_NAME=GIX Marketing                # ⚠️ NON CAMBIARE MAI
REPLY_TO=giovanni@gix.management

# Warmup
WARMUP_START_DATE=2026-02-12

# Rate Limiting
EMAIL_RATE_LIMIT_MS=100  # Delay minimo tra invii (warmup calcola il giusto)
```

---

## 🚀 PROSSIMI PASSI

### Immediate (Questa Settimana):
1. ✅ Segnare email test come "Non spam" su Gmail
2. ✅ Aggiungere marketing@gixmkt.cloud ai contatti
3. 🔄 Inviare 20-30 email/giorno a contatti **HOT** (lead_quality='hot')
4. 🔄 Monitorare bounce rate ogni giorno

### Settimana 2-4:
1. Gradualmente aumentare a 50 email/giorno
2. Implementare **email verification** prima dell'invio (zerobounce.net o similari)
3. Dashboard frontend con metriche warmup + quality

### Mese 2:
1. Aumentare a 100-250 email/giorno (se bounce < 2%)
2. Implementare A/B testing su oggetti
3. Automatizzare pulizia contatti problematici

---

## 🛡️ SICUREZZE IMPLEMENTATE

1. **Impossibile cambiare mittente** (codificato in email.service.js)
2. **Validazione pre-invio** (warmup + bounce check)
3. **Blocco automatico** se bounce critico
4. **Rate limiting intelligente** (delay calcolato dinamicamente)
5. **Backward compatibility** (campi DB mantenuti ma ignorati)
6. **Monitoring completo** (API per dashboard real-time)

---

## 📝 NOTE TECNICHE

**Perché Approccio Conservativo?**
- Campi `from_email`/`from_name` mantenuti nel DB → no breaking changes
- Valori sempre salvati da `.env` → consistenza
- Valori **ignorati** nell'email.service → comportamento corretto
- Possibilità futura di rimuovere campi dal DB senza impatto

**Performance**:
- Warmup service: O(1) (contatori in memoria)
- Bounce service: Query aggregate efficienti
- No overhead significativo su invii

**Scalabilità**:
- Ready per Bull queue integration (TODO in campaigns.service.js)
- Rate limiting gestibile con Redis (attualmente in-memory)
- Monitoring API già pronta per dashboard frontend

---

## 🎓 BEST PRACTICES EMAIL MARKETING

1. **Domain Warmup**: SEMPRE necessario per domini nuovi
2. **Bounce Rate**: Mantieni sempre < 2% per reputazione ottimale
3. **List Quality**: Meglio 100 email verificate che 1000 dubbie
4. **Timing**: Invia 9-11 o 14-16 (orari B2B migliori)
5. **Content**: Oggetto chiaro, preview text curato, CTA evidente
6. **Unsubscribe**: SEMPRE presente (legge + reputazione)
7. **Monitoring**: Controlla bounce rate OGNI giorno primo mese

---

**Data Implementazione**: 12 Febbraio 2026
**Versione Sistema**: 1.0.0
**Status**: ✅ Implementato e Testato