PSA/ee/docs/plans/2026-02-25-inbound-email-sender-routing-to-boards/PRD.md

PRD — Inbound Email Sender Routing to Boards

• Slug: inbound-email-sender-routing-to-boards
• Date: 2026-02-25
• Status: Draft

Summary

Revise routing ownership to live on clients and contacts instead of provider-level sender-rule tables.

The system should resolve an effective inbound destination from:

• contact override (exact sender match),
• then client default destination (exact contact client or domain-matched client),
• then provider default inbound settings.

Destination should resolve to an Inbound Ticket Defaults profile (not just board_id) so board/status/priority/category/client/location remain coherent.

Problem

Today, new inbound-email tickets always use one provider-level defaults profile and one board.

Current sender matching logic only influences client_id/contact_id:

• exact contact email match,
• explicit client domain mapping (client_inbound_email_domains).

Because board/defaults are not resolved from client/contact ownership, tickets from known client domains still land on a generic board and require manual rerouting.

Goals

1. Let each client define a default inbound destination profile.
2. Let each contact optionally define a destination override that takes precedence over client default.
3. Reuse existing client domain mapping so unknown contacts from a known client domain route to that client's destination.
4. Preserve deterministic precedence and safe fallback to provider defaults.
5. Keep existing reply-thread behavior unchanged.

Non-goals

1. Provider-level sender-rule table UI in this phase.
2. Wildcard/regex sender matching.
3. Routing existing ticket replies to other boards.
4. Auto-provisioning client/contact routing from historical mail.

Users and Primary Flows

Personas

• Admin/dispatcher configuring client and contact behavior.
• Helpdesk operators expecting inbound tickets to land on the correct board.

Flow A — Exact contact with contact override

1. New email arrives from invoices@customer.com.
2. Sender matches a contact by exact email.
3. Contact has inbound_ticket_defaults_id override.
4. Ticket uses contact override defaults profile.

Flow B — Exact contact without override

1. New email arrives from tech@customer.com.
2. Sender matches a contact by exact email.
3. Contact has no override; contact's client has default destination.
4. Ticket uses client default destination profile.

Flow C — Domain-matched client (unknown contact)

1. New email sender is not an exact contact.
2. Domain matches explicit client_inbound_email_domains record.
3. Matched client has default destination.
4. Ticket uses client default destination profile.

Flow D — No contact/domain client routing match

1. New email arrives from unconfigured sender/domain.
2. Ticket uses provider default inbound settings.

Flow E — Existing ticket reply

1. Email is matched by reply token/thread headers.
2. System appends comment to existing ticket.
3. No client/contact routing for board/defaults is evaluated.

UX / UI Notes

Client screen (ClientDetails)

• Keep existing Inbound email domains management.
• Add Inbound ticket destination picker for Inbound Ticket Defaults.
• Helper text: "Used for inbound senders that map to this client and have no contact override."

Contact screen

• Add optional Inbound ticket destination override picker.
• Helper text: "If set, this overrides the client destination for this exact sender contact."

Resolution help text

• Display precedence in both screens:
  • Contact override -> Client destination -> Provider default.

Requirements

Functional Requirements

1. Add client-level inbound destination setting:
   • clients.inbound_ticket_defaults_id (nullable UUID), or equivalent persisted client property.
2. Add contact-level destination override:
   • contacts.inbound_ticket_defaults_id (nullable UUID), or equivalent persisted contact property.
3. Resolution for new-ticket creation must use this precedence:
   • exact contact sender + contact override,
   • else exact contact sender + contact's client destination,
   • else domain-matched client destination,
   • else provider default inbound settings.
4. Existing ticket reply/comment paths remain unchanged and do not re-evaluate destination.
5. Existing exact-contact and domain-to-client matching behavior remains intact.
6. Validate resolved destination belongs to tenant and is active; otherwise fallback to provider default.
7. Add server actions/API updates to read/write client/contact destination settings with existing permissions.
8. Update client and contact UI surfaces to set/clear these values.
9. When no client/contact destination is configured, behavior remains identical to current provider-default flow.

Non-functional Requirements

1. No degradation of inbound processing throughput.
2. No cross-tenant routing leakage.
3. No dedupe/idempotency regression.

Data / API / Integrations

Approach Options

1. Provider-level sender rule table (previous draft).
2. Client/contact-owned destination config (recommended).
3. Board-only fields on client/contact.

Recommendation rationale:

• Client and contact screens are the natural ownership point.
• Existing domain mapping already maps senders to client identity.
• Using inbound defaults profile IDs avoids board-only mismatches.

Proposed Data Model

• Reuse: client_inbound_email_domains (already present).
• Add:
  • clients.inbound_ticket_defaults_id nullable.
  • contacts.inbound_ticket_defaults_id nullable.
• Add indexes for read path:
  • (tenant, inbound_ticket_defaults_id) on clients.
  • (tenant, inbound_ticket_defaults_id) on contacts.

Resolution Integration Points

• shared/services/email/processInboundEmailInApp.ts
  • resolve effective defaults before ticket creation.
• shared/workflow/runtime/actions/registerEmailWorkflowActions.ts
  • extend resolve_inbound_ticket_context to return effective defaults using same precedence.
• shared/workflow/actions/emailWorkflowActions.ts
  • add shared resolver helper(s) used by both paths.
• UI/actions:
  • packages/clients/src/components/clients/ClientDetails.tsx
  • contact edit/create surfaces in packages/clients/src/components/contacts/*
  • related actions in packages/clients/src/actions/*

Security / Permissions

1. Client destination updates require existing client update permission.
2. Contact override updates require existing contact update permission.
3. Resolver validates destination defaults are in the same tenant.

Observability

1. Add structured debug logs for destination resolution source:
   • contact_override, client_default_from_contact, client_default_from_domain, provider_default.
2. Warn when configured client/contact destination is invalid or inactive and fallback is applied.

Rollout / Migration

1. Add migration(s) for client/contact destination fields (or equivalent persisted schema).
2. No backfill required.
3. Tenants without new config continue on provider defaults unchanged.

Open Questions

1. Should client/contact destination be global, or optionally provider-specific when a tenant has multiple inbound mailboxes?
2. Should we block saving client/contact destination when target defaults are inactive, or allow and fallback at runtime?
3. Should contact override be shown only for contacts with valid email addresses?

Acceptance Criteria (Definition of Done)

1. Exact-sender contact with contact override creates new ticket using contact destination defaults.
2. Exact-sender contact without override uses client destination defaults.
3. Unknown sender with domain-matched client uses client destination defaults.
4. Unmatched sender uses provider default inbound settings.
5. Existing-ticket reply flows are unchanged.
6. In-app inbound and workflow-runtime paths produce identical destination resolution for the same sender/provider input.