# Vorbereitung für SuperOffice Meeting: API E-Mail-Versand (Shipment)
**Datum:** 05.03.2026  
**Teilnehmer:** Christian Godelmann (RoboPlanet), Frau Grilnberger / Herr Eberhard (SuperOffice)  
**Thema:** Fehlende Berechtigung für automatisierten E-Mail-Versand via API

---

## 1. Ausgangslage & Ziel
Wir haben die **GTM-Engine** (KI-basierte Anreicherung) erfolgreich an SuperOffice (Tenant `Cust26720`) angebunden.
*   ✅ **Lese-Zugriff:** Funktioniert (Webhooks, Person/Contact lesen).
*   ✅ **Schreib-Zugriff (Daten):** Funktioniert (UDFs schreiben, Sales erstellen).
*   ❌ **E-Mail-Versand (Shipment):** Schlägt fehl (500 Internal Server Error).

**Ziel:** Der API-User (Client ID `0fd8...`) soll automatisierte Erstkontakt-E-Mails ("Shipments") im Namen des zugewiesenen Vertriebsmitarbeiters versenden können.

---

## 2. Diagnose-Ergebnisse (Live-Test vom 05.03.2026)

Wir haben eine Tiefenanalyse mit Admin-Rechten durchgeführt. Hier sind die harten Fakten:

### A. Identitätsproblem (Ursache)
Der API-User hat keine verknüpfte "Person" im System.
*   **Request:** `GET /api/v1/Associate/Me`
*   **Response:** `500 Internal Server Error`
*   **Bedeutung:** Das System weiß nicht, "wer" der API-User ist. Ohne Identität können keine personalisierten Aktionen (wie E-Mail-Versand) ausgeführt werden.

### B. E-Mail-Versand (Blockade)
Trotz aktiver Marketing-Lizenz (ShipmentTypes sind abrufbar) scheitert der Versand.
*   **Test:** Erstellung eines `Shipment` Objekts (Type: Email).
*   **Response:** `500 Internal Server Error`
*   **Log-Auszug:**
    ```json
    {
      "Error": true,
      "ErrorType": "NullReferenceException",
      "Message": "Object reference not set to an instance of an object.",
      "Source": "SoDataBase"
    }
    ```
    *(Hinweis: Der Fehler deutet darauf hin, dass interne E-Mail-Einstellungen (SMTP/Exchange) für den user `null` sind.)*

### C. Schreibrechte (Erfolgreich)
Zum Vergleich haben wir andere Objekte erstellt, um generelle API-Probleme auszuschließen.
*   **Sale (Verkauf):** ✅ Erfolgreich erstellt (ID 342539).
*   **Appointment (Termin):** ✅ Erfolgreich erstellt (ID 993350).

---

## 3. Unsere Bitte an SuperOffice (Lösungsvorschlag)

Um das Problem zu lösen, benötigen wir folgende Anpassungen für den API-User (oder einen dedizierten System-User):

1.  **Personalisierung:** Verknüpfung des API-Users mit einer **Personalkarte** im SuperOffice (damit `Associate/Me` funktioniert).
2.  **Rollen:** Zuweisung der Rolle **"Mailing Administrator"** (oder vergleichbar), um Shipments zu erstellen.
3.  **E-Mail-Konfiguration:** Hinterlegung der **E-Mail-Einstellungen** (idealerweise "Send As" Recht für die Account-Manager, damit die Mails im Namen von Herrn Godelmann/Herrn X rausgehen).

---

## 4. Aktueller Workaround (Plan B)

Bis zur Lösung nutzen wir folgenden Workaround:
1.  Die KI generiert den E-Mail-Text.
2.  Anstatt die Mail zu senden, erstellen wir einen **Termin** (`Appointment`) in der Vergangenheit.
3.  Der E-Mail-Text wird in die **Beschreibung** des Termins geschrieben.
4.  Der Vertriebler muss den Text manuell kopieren und versenden.

*Dies ist funktionstüchtig (getestet), aber keine Dauerlösung.*

---

## 5. Technische Details (für Support)

*   **Tenant:** `Cust26720` (Online3)
*   **Client ID:** `0fd8...` (Name: "Gemini Connector Production")
*   **Authentication:** System User Flow (Refresh Token)
*   **Endpoint:** `/api/v1/Shipment`

---

## 6. Ziel-Prozess & Automatisierungs-Logik (Roadmap)

Um den SuperOffice-Experten den Kontext unserer Anforderungen zu verdeutlichen, hier das geplante Ziel-Szenario:

### A. Neukunden-Akquise (Prospecting)
1.  **Trigger:** Ein Mitarbeiter setzt in SuperOffice den Status einer Person auf `MA-Status: Init`.
2.  **Enrichment:** Die Gemini GTM-Engine (Company Explorer) erkennt den Trigger via Webhook, analysiert das Unternehmen und generiert hyper-personalisierte Texte in den UDFs.
3.  **Versand (Der "Send As" Case):** Die Engine stößt über die API den Versand der 1. E-Mail an.
    *   **Wichtig:** Der Versand erfolgt im **"Send As"** Modus (nicht "Im Auftrag von").
    *   **Absender:** Der in SuperOffice hinterlegte `Account Manager` / `Associate`.
    *   **Signatur:** Die E-Mail muss die **persönliche Signatur** des jeweiligen Absenders enthalten.
4.  **Status-Update:** Nach erfolgreichem Versand wird der Status auf `Sent 1st E-Mail` gesetzt.

### B. Multi-Step Follow-up (Drip Campaign)
1.  **Wartezeit:** Das System prüft nach 7 Tagen (via Queue/Cron) erneut den Status der Person.
2.  **Bedingung:** Ist der Status unverändert (`Sent 1st E-Mail`), wird automatisch die 2. E-Mail (Nurture) versendet.
3.  **Abbruch:** Reagiert der Kontakt (Statusänderung durch Sales) oder ist die 3. Mail ohne Erfolg rausgegangen, stoppt die Sequenz.

### C. Sales Follow-up (Angebot-Nachfassen)
1.  **Trigger:** Ein Angebot (`Sale`) ist seit 14 Tagen im Status "Offen" und es gab keine dokumentierte Aktivität.
2.  **Aktion:** Die Engine generiert ein personalisiertes Follow-up für den Account Manager und versendet dieses (ebenfalls via "Send As"), um den Sales-Prozess zu beschleunigen.

---
*Ende des Protokolls*