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:

{
  "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):

Personalisierung: Verknüpfung des API-Users mit einer Personalkarte im SuperOffice (damit Associate/Me funktioniert).
Rollen: Zuweisung der Rolle "Mailing Administrator" (oder vergleichbar), um Shipments zu erstellen.
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:

Die KI generiert den E-Mail-Text.
Anstatt die Mail zu senden, erstellen wir einen Termin (Appointment) in der Vergangenheit.
Der E-Mail-Text wird in die Beschreibung des Termins geschrieben.
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)

Trigger: Ein Mitarbeiter setzt in SuperOffice den Status einer Person auf MA-Status: Init.
Enrichment: Die Gemini GTM-Engine (Company Explorer) erkennt den Trigger via Webhook, analysiert das Unternehmen und generiert hyper-personalisierte Texte in den UDFs.
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.
Status-Update: Nach erfolgreichem Versand wird der Status auf Sent 1st E-Mail gesetzt.

B. Multi-Step Follow-up (Drip Campaign)

Wartezeit: Das System prüft nach 7 Tagen (via Queue/Cron) erneut den Status der Person.
Bedingung: Ist der Status unverändert (Sent 1st E-Mail), wird automatisch die 2. E-Mail (Nurture) versendet.
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)

Trigger: Ein Angebot (Sale) ist seit 14 Tagen im Status "Offen" und es gab keine dokumentierte Aktivität.
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

5.1 KiB Raw Blame History