diff --git a/connector-superoffice/SENDING_STRATEGY_ANALYSIS.md b/connector-superoffice/SENDING_STRATEGY_ANALYSIS.md new file mode 100644 index 00000000..1bcd867c --- /dev/null +++ b/connector-superoffice/SENDING_STRATEGY_ANALYSIS.md @@ -0,0 +1,37 @@ +# SuperOffice Email Sending Strategy Analysis (Feb 28, 2026) + +## Executive Summary +Automated email sending "on behalf of" sales representatives directly via the SuperOffice API is currently **technically blocked** due to missing permissions and license restrictions on the configured System User (Client ID `0fd8...`). + +We have exhausted all standard API paths (Agents, REST, Archive, CRMScript). A strategic reconfiguration by the SuperOffice administrator is required. + +## Technical Findings + +| Feature | Status | Error Code | Root Cause Analysis | +| :--- | :--- | :--- | :--- | +| **Document Creation** | ✅ Working | 200 OK | We can create `.somail` files in the archive. | +| **Native Sending** (`/Shipment`) | ❌ Failed | 500 Internal | The System User lacks a valid `Associate` context or "Mailing" license. | +| **Agent Sending** (`/Agents/EMail`) | ❌ Failed | 401 Unauth | The standard OAuth token is rejected for this Agent; likely requires "interactive" user context or specific scope. | +| **CRMScripting** | ❌ Failed | 403 Forbidden | Access to the Scripting Engine is blocked for this API user. | +| **User Context** (`/Associate/Me`) | ❌ Failed | 500 Internal | **Critical:** The System User does not know "who it is". This breaks all "Send As" logic. | + +## Required Actions (IT / Admin) + +To enable automated sending, one of the following two paths must be implemented: + +### Option A: Enable Native SuperOffice Sending (Preferred) +1. **Fix System User:** The API User must be linked to a valid "Person" card in SuperOffice Admin with **Service / Marketing Administrator** rights. +2. **Enable Mailings:** The tenant `Cust26720` must have the "Marketing" license active and assigned to the API User. +3. **Approve "Send As":** The API User needs explicit permission to set the `SenderEmailAddress` field in Shipments. + +### Option B: External Sending Engine (Recommended Fallback) +If Option A is too complex or costly (licensing), we switch the architecture: +1. **SMTP Relay:** Provision a dedicated SMTP account (e.g., Office365 Service Account or SendGrid) for the "RoboPlanet GTM Engine". +2. **Logic Shift:** The Python Connector sends the email via SMTP (Python `smtplib`). +3. **Archiving:** The Connector saves the *sent* email as a `.eml` document in SuperOffice (which already works!). + +## Immediate Workaround +Until a decision is made, the system uses the **"Activity Handoff"** method: +1. System generates the text. +2. System creates a Task (Appointment) in SuperOffice. +3. User clicks a link, copies the text, and sends via their own Outlook/Gmail.