# Outreach-System -- Deployment & Bedienungsanleitung

**Zweck:** Personalisierte B2B-Kaltakquise-Emails fuer LP (Lueftungsprofi) und AG (Agent Solutions / Mario's Portier-Projekt).

---

## Setup (einmalig)

```bash
cd K:\projekte-AG\email_agent
pip install -r requirements.txt
```

**Umgebungsvariablen** (in `.env` Datei):
```
ANTHROPIC_API_KEY=sk-ant-...
SENDGRID_API_KEY=SG....
OUTREACH_FROM_EMAIL_AG=karlo@agentsolutions.tech
OUTREACH_FROM_EMAIL_LP=karlo@mallorcaairservices.com
```

---

## Workflow (Schritt fuer Schritt)

### Schritt 1 -- Excel importieren

Mario liefert Excel-Datei. Datei in den Projektordner legen, dann:

```bash
# AG-Kontakte (KI-Automatisierung)
python excel_importer.py --file leads_mario.xlsx --campaign "Mario Leads April 2026" --icp AG

# LP-Kontakte (Lueftung Mallorca)
python excel_importer.py --file hotels_mallorca.xlsx --campaign "Hotels Mallorca Q2" --icp LP
```

**Output:** "47 Kontakte importiert, 3 Duplikate, 2 ohne Email"

---

### Schritt 2 -- Kontakte anreichern (Website-Scraping + Claude)

```bash
# Kampagne komplett anreichern
python contact_enricher.py --campaign 1

# Oder: Erste 50 rohe Kontakte
python contact_enricher.py --batch 50
```

**Was passiert:**
- Website aus Email-Domain abgeleitet
- Website gescrapt (Titel, Text)
- Claude bestimmt: Branche, Firmenbeschreibung, Schmerzpunkt

Wenn Kontakte nicht automatisch angereichert werden koennen:
```bash
python contact_enricher.py --manual
# Interaktiver Modus: Branche + Problem manuell eingeben
```

---

### Schritt 3 -- ICP-Klassifikation

```bash
# Alle enriched Kontakte klassifizieren
python icp_classifier.py --campaign 1
```

**Output:**
- LP-Kontakte: Lueftungsanlage anbieten
- AG-Kontakte: Email/Telefon Agent oder Portier anbieten
- Beide: Kontakt bekommt erstmal das Produkt mit hoeherem Fit

---

### Schritt 3.5 -- Excel-Export (optional aber empfohlen)

Nach jedem Schritt kannst du die Daten zu Excel exportieren fuer Kontrolle/Reporting:

```bash
# Export nach Enrichment/Klassifikation
python excel_exporter.py --campaign 1

# Mit eigenem Dateinamen
python excel_exporter.py --campaign 1 --output "portier_status_2026-04-24.xlsx"
```

**Was wird exportiert:**
- Sheet 1: Kampagnen-Info (Kontakt-Zahlen, Status)
- Sheets 2-6: Kontakte nach Status (raw, enriched, active, replied, converted)
- Sheets 7+: Sequenzen nach Status (pending, sent, failed)

Die Excel-Datei oeffnet sich direkt mit Spalten-Filterung und ist einfach sortierbar.

---

### Schritt 4 -- Emails generieren

```bash
# Step-1 Emails generieren (erste Kontaktaufnahme)
python outreach_generator.py --step 1 --campaign 1
```

**Was Claude generiert:**
- Personalisierter Betreff
- Email-Text (80-120 Woerter, bezieht sich konkret auf die Firma)
- Personalisierungs-Score (muss >= 0.6 sein)
- Emails mit niedrigem Score werden automatisch verworfen oder regeneriert

---

### Schritt 5 -- Review (PFLICHT vor Versand)

```bash
python review_cli.py --campaign 1
```

**Tasten:**
- `g` -- Genehmigen (Email wird versendet)
- `e` -- Editieren (Editor oeffnet sich)
- `s` -- Ueberspringen (Email wird nicht gesendet)
- `r` -- Regenerieren (neue Version generieren lassen)
- `q` -- Review beenden

**WICHTIG:** Keine Email wird ohne deine Genehmigung versendet.

---

### Schritt 6 -- Emails versenden

```bash
# Test-Modus (nichts wird wirklich gesendet)
python outreach_orchestrator.py --send-approved --dry-run

# Wirklich senden
python outreach_orchestrator.py --send-approved
```

**Anti-Spam:**
- Max 50 Emails/Tag
- Nur Mo-Fr, 9:00-17:00 Uhr
- 30 Sekunden Pause zwischen Emails

---

### Schritt 7 -- Follow-Up Emails (Tag 4 und 8)

Am Tag 4 nach dem Erstversand:
```bash
# Pruefen ob Step-2 Emails faellig sind
python outreach_orchestrator.py --check-due

# Dann Review + Versand wie in Schritt 5-6
python review_cli.py
python outreach_orchestrator.py --send-approved
```

---

### Schritt 8 -- Reply-Detection (automatisch)

Wenn `agent.py` laeuft (Inbound-Loop), wird automatisch erkannt wenn jemand antwortet.
- Kontakt-Status wird auf "replied" gesetzt
- Alle weiteren Sequenz-Emails werden gestoppt
- Log-Eintrag: "OUTREACH-ANTWORT von xyz@firma.de"

---

## Statistiken

```bash
# Alle Kampagnen
python outreach_orchestrator.py --stats

# Einzelne Kampagne
python outreach_orchestrator.py --stats --campaign 1
```

---

## Dateien & Module

```
email_agent/
├── excel_importer.py       -- Excel/CSV -> cold_contacts (NEU)
├── contact_enricher.py     -- Website-Scraping + Claude-Analyse (NEU)
├── icp_classifier.py       -- LP/AG/beide Zuordnung (NEU)
├── knowledge_retriever.py  -- RAG-Zugriff auf YouTube Research DB (NEU)
├── outreach_generator.py   -- Personalisierte Email-Generierung via Claude (NEU)
├── review_cli.py           -- Interaktiver Review vor Versand (NEU)
├── outreach_orchestrator.py -- Workflow-Steuerung + Versand (NEU)
├── excel_exporter.py       -- Exportiert Daten zu Excel fuer Kontrolle (NEU)
├── cold_outreach_db.py     -- Datenbank (ERWEITERT)
├── agent.py                -- Inbound-Loop + Reply-Detection (ERWEITERT)
├── OUTREACH.md             -- Diese Datei
└── OUTREACH_AGENT_KONZEPT.md -- Vollstaendiges Konzept-Dokument
```

---

## Datenbank-Schema

```
cold_contacts               -- Kontakte (mit Enrichment-Feldern)
cold_sequences              -- 3-Step Email-Sequenzen pro Kontakt
outreach_campaigns          -- Kampagnen-Verwaltung
enrichment_cache            -- Website-Scraping Cache (kein Doppel-Scraping)
```

Neue Felder in cold_contacts:
- `website` -- Unternehmens-Website
- `phone` -- Telefonnummer
- `company_description` -- Was macht die Firma (1 Satz, von Claude)
- `enrichment_source` -- auto_website / auto_email_domain / manual
- `icp_confidence` -- Wie sicher ist die ICP-Zuordnung (0-1)
- `icp_recommended_product` -- lueftung / email_agent / telefon_agent / portier
- `language` -- de / es / en

Status-Werte fuer cold_contacts:
- `raw` -- Frisch importiert
- `enriched` -- Angereichert, bereit fuer Generierung
- `needs_manual` -- Muss manuell gepflegt werden
- `active` -- Sequenz laeuft
- `replied` -- Hat geantwortet (Sequenz gestoppt)
- `converted` -- Wurde Kunde
- `bounced` -- Email ungueltig
- `unsubscribed` -- Abgemeldet

---

## YouTube Research Knowledge Base

Der `knowledge_retriever.py` greift auf die YouTube Research Datenbank zu:
- `K:/projekte-AG/YouTube_Research/dist/knowledge.db`
- 468 Videos ueber Claude Code, KI-Automatisierung, AI Voice Agents
- FTS5-Suche nach branchenrelevanten Inhalten
- Wird als Wissens-Snippet in Step-2 AG-Emails eingebettet

LP-Emails nutzen stattdessen eine statische Faktenbasis (Schimmelstatistiken,
Energiekosten, spanische Baunormen CTE/RITE).

---

## Kosten

| Service | Verwendung | Kosten/Monat |
|---------|------------|--------------|
| Claude API (Haiku) | Enrichment + ICP | ~2-5 EUR |
| Claude API (Sonnet) | Email-Generierung | ~5-10 EUR |
| SendGrid | 50 Emails/Tag | 0-15 EUR |
| **Gesamt** | | **~7-30 EUR** |

---

*Erstellt: 2026-04-24*
*Status: Produktionsbereit*