PSA/ee/docs/plans/2025-11-18-email-roundtrip-plan.md

# Email Roundtrip Implementation Plan (Holistic)
**Date:** November 18, 2025
**Status:** Planned

## Objective
Complete the email roundtrip feature by implementing outbound notification logic that ensures **channel consistency** and **correct threading**. When a ticket is created from an inbound email, any subsequent agent replies must be sent:
1.  From the **same email address** that received the original email.
2.  Via the **same provider** (Microsoft/Google) to ensure deliverability and header integrity.
3.  With correct **In-Reply-To** and **References** headers to maintain the conversation thread in the customer's email client.

## Architecture Analysis

### Current State
-   **Inbound:** `system-email-processing-workflow` creates tickets and stores `email_metadata` (including `providerId`, `messageId`, `references`).
-   **Inbound Adapters:** `MicrosoftGraphAdapter` and `GmailAdapter` currently only support reading emails.
-   **Outbound:** `TenantEmailService` uses `EmailProviderManager` to send emails, typically defaulting to a single configured outbound provider (SMTP/Resend).
-   **Subscriber:** `ticketEmailSubscriber` listens for events but doesn't currently support channel-specific routing or threading headers.

### The Gap
The current system treats inbound and outbound email as separate pipelines. There is no mechanism to "reply via the inbound channel." If `support@acme.com` (Microsoft) receives an email, the system currently replies via `noreply@platform.com` (Resend), breaking the "From" address and potentially the thread.

## Implementation Plan

### 1. Enhance Inbound Adapters (Bi-directional Capability)
Modify the existing inbound adapters to support sending emails. This allows us to reuse the existing authentication and connection logic.

*   **File:** `server/src/services/email/providers/MicrosoftGraphAdapter.ts`
    *   Implement `sendEmail(message: EmailMessage): Promise<EmailSendResult>`.
    *   Use the Graph API `/me/sendMail` or `/users/{id}/sendMail`.
    *   Map `In-Reply-To` and `References` from `message.headers` to the API payload.
*   **File:** `server/src/services/email/providers/GmailAdapter.ts`
    *   Implement `sendEmail(message: EmailMessage): Promise<EmailSendResult>`.
    *   Use the Gmail API `users.messages.send`.
    *   Construct a raw MIME message that includes the threading headers.

### 2. Upgrade EmailProviderManager (Channel Routing)
Enable the manager to route emails through specific providers based on ID, not just tenant defaults.

*   **File:** `server/src/services/email/EmailProviderManager.ts`
    *   Add method `sendEmailViaProvider(providerId: string, message: EmailMessage, tenantId: string)`.
    *   Logic:
        1.  Retrieve the provider configuration from the database using `providerId`.
        2.  Instantiate the appropriate adapter (`MicrosoftGraphAdapter` or `GmailAdapter`).
        3.  Call `adapter.sendEmail(message)`.

### 3. Update Service Layer (Context Propagation)
Pass the routing and threading information from the business logic down to the provider manager.

*   **File:** `server/src/types/email.types.ts` & `server/src/lib/email/BaseEmailService.ts`
    *   Update `EmailMessage` and `BaseEmailParams` to include:
        *   `headers?: Record<string, string>` (for threading).
        *   `providerId?: string` (for routing).
*   **File:** `server/src/lib/services/TenantEmailService.ts`
    *   Update `sendEmail` to handle `providerId`.
    *   If `providerId` is present, delegate to `providerManager.sendEmailViaProvider`.
    *   Otherwise, fall back to the default `providerManager.sendEmail`.
*   **File:** `server/src/lib/notifications/sendEventEmail.ts`
    *   Update `SendEmailParams` and `sendEventEmail` to accept and pass `providerId` and `headers`.

### 4. Wire Up the Subscriber (The Glue)
Connect the event system to the new logic.

*   **File:** `server/src/lib/eventBus/subscribers/ticketEmailSubscriber.ts`
    *   In `handleTicketCommentAdded`:
        1.  **Filter:** Ensure comment is public and from an agent/system.
        2.  **Context:** Retrieve `ticket.email_metadata`.
        3.  **Routing:** Extract `providerId` from `email_metadata`.
        4.  **Threading:** Construct `In-Reply-To` (from `messageId`) and `References`.
        5.  **Send:** Call `sendNotificationIfEnabled` passing `providerId` and `headers`.

## UX/Configuration Considerations
*   **Implicit Configuration:** By reusing the inbound provider for replies, we avoid complex "mapping" UI. If a user connects `support@acme.com` for inbound, replies automatically go out via `support@acme.com`.
*   **Setup Screens:** No immediate changes required to Setup UI, as the "connection" already exists. Future enhancements could allow configuring a specific "Signature" or "Display Name" for the inbound channel.

## Verification Strategy
1.  **Unit Tests:** Test `sendEmail` in adapters with mocks.
2.  **Integration:** Simulate a comment on a ticket created via email. Verify `EmailProviderManager` loads the specific provider and sends the email.
3.  **Roundtrip E2E:**
    *   Send email to `inbound@test.com` -> Ticket Created.
    *   Agent replies -> Email sent via `inbound@test.com` (verified via logs/headers).
    *   Customer replies -> Thread continues correctly.