feat(email-api): Implement email document creation via SuperOffice API (no SMTP)

connector-superoffice/README.md

@@ -253,32 +253,27 @@ Das System unterstützt mehrere Outreach-Varianten über das Feld **`MA_Campaign
 2.  **Spezifisch:** Wird ein Wert gewählt (z.B. "Messe 2026"), sucht der Connector gezielt nach Matrix-Einträgen mit diesem Tag.
 3.  **Fallback:** Existiert für die gewählte Kampagne kein spezifischer Text für das Vertical/Persona, wird automatisch auf "standard" zurückgegriffen.
 
-### 15. Advanced Implementation Details (v1.8)
+### 16. Email Sending Implementation (Feb 28, 2026)
 
-Mit der Version 1.8 des Workers wurden kritische Optimierungen für den produktiven Betrieb (online3) implementiert, um API-Stabilität und Datenintegrität zu gewährleisten.
+A dedicated script `create_email_test.py` has been implemented to create "Email Documents" directly in SuperOffice via the API. This bypasses the need for an external SMTP server by utilizing SuperOffice's internal document system.
 
-#### A. Atomic PATCH Strategy
-Um "Race Conditions" und unnötigen API-Traffic zu vermeiden, bündelt der Worker alle Änderungen an einem Kontakt-Objekt in einem einzigen **Atomic PATCH**. 
-*   **Betroffene Felder:** `Address` (Postal & Street), `OrgNr` (VAT), `Urls` (Website) und alle `UserDefinedFields`.
-*   **Vorteil:** Entweder alle Daten werden konsistent übernommen, oder der Call schlägt kontrolliert fehl. Dies verhindert, dass Teil-Updates (z.B. nur die Adresse) von nachfolgenden UDF-Updates überschrieben werden.
+**Features:**
+*   **Document Creation:** Creates a document of type "Ausg. E-Mail" (Template ID 157).
+*   **Activity Tracking:** Automatically creates a linked "Appointment" (Task ID 6 - Document Out) to ensure the email appears in the contact's activity timeline.
+*   **Direct Link:** Outputs a direct URL to open the created document in SuperOffice Online.
 
-#### B. REST Website-Sync (The `Urls` Array)
-SuperOffice REST akzeptiert kein direktes Update auf `UrlAddress` via PATCH. Stattdessen muss das `Urls` Array manipuliert werden.
-*   **Logik:** Der Worker prüft, ob die KI-entdeckte Website bereits im Array vorhanden ist. Wenn nicht, wird sie als neues Objekt mit der Beschreibung `"AI Discovered"` an den Anfang der Liste gestellt.
-*   **Format:** `"Urls": [{"Value": "https://...", "Description": "AI Discovered"}]`.
+**Usage:**
+```bash
+python3 connector-superoffice/create_email_test.py <PersonID>
+# Example:
+python3 connector-superoffice/create_email_test.py 193036
+```
 
-#### C. Kampagnen-Auflösung via `:DisplayText`
-Um den Klarnamen einer Kampagne (z.B. "Messe 2026") statt der internen ID (z.B. `[I:123]`) zu erhalten, nutzt der Worker eine OData-Optimierung.
-*   **Technik:** Im `$select` Parameter wird das Feld `SuperOffice:23:DisplayText` angefordert. 
-*   **Ergebnis:** Der Worker erhält direkt den sauberen String, der zur Steuerung der Textvarianten im Company Explorer dient. Zusätzliche API-Abfragen zur Listenauflösung entfallen.
-
-#### D. Feldlängen & Truncation
-Standard-UDF-Textfelder in SuperOffice sind oft auf **254 Zeichen** begrenzt. Da das AI-Dossier (Summary) deutlich länger sein kann, kürzt der Worker den Text hart auf **132 Zeichen** (+ "..."). Dies stellt sicher, dass der gesamte `PATCH` Request nicht aufgrund eines "Field Overflow" von der SuperOffice-Validierung abgelehnt wird.
+**Key API Endpoints Used:**
+*   `POST /Document`: Creates the email body and metadata.
+*   `POST /Appointment`: Creates the activity record linked to the document.
 
 ---
-
-
-## Appendix: The "First Sentence" Prompt
 This is the core logic used to generate the company-specific opener.
 
 **Goal:** Prove understanding of the business model + imply the pain (positive observation).