PSA/ee/docs/plans/2026-03-31-inbound-email-reopen-on-reply-design.md

Inbound Email Reopen On Reply Design

• Date: 2026-03-31
• Status: Approved

Summary

Improve inbound email threading against closed tickets by adding ConnectWise-style reopen behavior with per-board configuration, a configurable cutoff window, and optional AI suppression for simple client acknowledgements. Reopen-on-reply remains core behavior; AI suppression is an Enterprise Edition enhancement gated by the AI Assistant add-on.

Current State

Inbound replies are matched in shared/services/email/processInboundEmailInApp.ts via reply token or thread headers and then appended as comments. The matched-ticket reply path does not currently perform any inbound-specific reopen transition for closed tickets.

Ticket statuses are board-owned. Boards already have exactly one open default status, and existing ticket update paths already align status_id, is_closed, closed_at, and closed_by when moving between open and closed statuses.

The current inbound heuristic only filters token-only or effectively empty replies by stripping Alga reply markers and checking whether any text remains.

Product Decisions

• Reopen behavior is configured per board.
• Internal user replies always reopen closed tickets when threading matches and the cutoff window has not expired.
• Client/contact replies reopen closed tickets when threading matches and the cutoff window has not expired, unless AI suppression is enabled and classifies the reply as a simple acknowledgement.
• Boards may define an explicit reopen_status_id.
• If reopen_status_id is unset, reopening falls back to the board's default open status.
• Boards define a configurable cutoff window. Replies beyond that window do not revive the old ticket and instead enter the new-ticket path.
• AI acknowledgement suppression is a configurable board option so users can discover and opt out of it.

Board Configuration

Each board gains reopen-on-reply policy fields:

• reopen_on_inbound_reply_enabled
• reopen_cutoff_minutes or equivalent duration field
• reopen_status_id nullable
• ai_ack_suppression_enabled

These settings belong to boards rather than providers because reopen semantics and status ownership are board-scoped.

Runtime Decision Flow

When inbound email matches an existing ticket:

1. Load the matched ticket, board, and current status.
2. If the ticket is not closed, keep current behavior.
3. If the ticket is closed and the board policy disables reopen-on-reply, add the comment without reopening.
4. If the ticket is closed and the cutoff window is exceeded, do not attach to the old ticket; route into the existing new-ticket path.
5. If the sender is internal, reopen immediately.
6. If the sender is a client/contact:
   • Run the existing cheap heuristic first.
   • If AI suppression is disabled, or the tenant lacks AI Assistant, or the reply is clearly substantive, reopen normally.
   • If AI suppression is enabled and the reply is short and plausibly acknowledgement-like, call the standard LLM path with a tightly constrained prompt and require a tiny formatted response such as ACK or NOT_ACK.
   • ACK keeps the ticket closed and still records the comment.
   • NOT_ACK reopens normally.
7. Reopen by updating status_id, is_closed, closed_at, and closed_by using the same transition semantics used in existing ticket update paths.

AI Architecture

Reopen-on-reply is core behavior, but AI suppression is an EE enhancement and should follow the existing CE/EE split:

• Shared/server code depends on a small pluggable interface, for example InboundReplyAcknowledgementDecider.
• The default CE implementation performs no semantic suppression and always returns "not acknowledgement".
• In EE mode, shared/server code manually resolves an EE implementation from @ee/....
• The EE implementation may call the standard chat-completions provider already used elsewhere in the product.
• The EE implementation must still require the AI Assistant add-on and the board-level ai_ack_suppression_enabled flag before issuing any LLM call.
• If EE code is unavailable, entitlement fails, or the LLM call errors, the system falls back to normal reopen behavior.

This keeps AI-specific prompt and model behavior isolated in EE code while leaving the core reopen flow shared.

Failure Behavior

• If no valid reopen target can be resolved, attach the comment without reopening and log the configuration issue.
• If AI suppression cannot run for any reason, reopen normally rather than blocking email processing.
• Existing dedupe must continue to run before reopen/comment work so duplicate deliveries do not cause repeated reopen transitions.
• The system should record decision metadata sufficient to explain outcomes later, such as reopen reason, cutoff result, and AI suppression result.

Test Coverage

Prefer behavioral integration coverage around the inbound email flow:

• Closed ticket + internal reply reopens to explicit reopen status.
• Closed ticket + internal reply without explicit reopen status reopens to board default open status.
• Closed ticket + client reply with AI suppression disabled reopens.
• Closed ticket + client reply with AI suppression enabled and ACK stays closed while adding the comment.
• Closed ticket + client reply with AI suppression enabled and NOT_ACK reopens.
• Closed ticket + client reply with AI enabled but no AI Assistant add-on reopens without AI.
• Closed ticket + AI failure reopens without AI.
• Closed ticket + reply beyond cutoff creates a new ticket instead of attaching to the closed one.
• Open ticket replies preserve current behavior.
• Token-only replies remain skipped by the existing heuristic.