105 lines
5.1 KiB
Markdown
105 lines
5.1 KiB
Markdown
# 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*
|