PSA/ee/docs/plans/2026-02-13-inbound-email-domain-matching-default-contact/SCRATCHPAD.md

Scratchpad — Inbound Email Domain Matching + Client Default Contact

• Plan slug: inbound-email-domain-matching-default-contact
• Created: 2026-02-13

What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while implementing this plan.

Prefer short bullets. Append new entries as you learn things, and also update earlier notes when a decision changes or an open question is resolved.

Decisions

• (2026-02-13) Store the “client default contact” using existing clients.properties.primary_contact_id (and optional primary_contact_name) to avoid a DB migration for this phase.
• (2026-02-13) Superseded: Domain-to-client matching derived from scanning contacts.email domains.
• (2026-02-13) New requirement: Admin must explicitly configure inbound email domains per client; enforce uniqueness per tenant; do not attempt domain matching unless the domain is configured.

Discoveries / Constraints

• (2026-02-13) In-app inbound email new-ticket creation happens in shared/services/email/processInboundEmailInApp.ts and:
  • Finds a contact strictly by exact normalized email (findContactByEmail).
  • If no exact contact match, only attempts domain matching via explicit domain mappings (client_inbound_email_domains).
  • If no explicit mapping exists for the sender domain, falls back to inbound ticket defaults client_id and leaves contact_id null.
• (2026-02-13) Updated in-app inbound email new-ticket creation (shared/services/email/processInboundEmailInApp.ts) to:
  • Prefer exact contact match (existing behavior).
  • Else attempt unique client match by sender domain, and apply the client's validated properties.primary_contact_id as ticket contact when available.
  • Keep comment author attribution as system unless there is an exact sender email contact match (avoids implying the default contact authored the email).
  • When the resolved client differs from the inbound defaults client, do not apply defaults.location_id to avoid cross-client location mismatch.
• (2026-02-13) Client "default contact" storage is already supported end-to-end via client properties:
  • Types: packages/types/src/interfaces/client.interfaces.ts includes properties.primary_contact_id and properties.primary_contact_name.
  • Client-side validation: packages/clients/src/schemas/client.schema.ts includes primary_contact_id and primary_contact_name.
  • Server API schema: server/src/lib/api/schemas/client.ts allows properties.primary_contact_id (uuid) + primary_contact_name.
  • Client update persistence merges properties into clients.properties: packages/clients/src/actions/clientActions.ts.
• (2026-02-13) Added shared helper extractEmailDomain() in shared/lib/email/addressUtils.ts which normalizes via normalizeEmailAddress() then returns substring after @ (lowercased).
• (2026-02-13) Superseded implementation: contact-derived domain matching (findUniqueClientIdByContactEmailDomain) was removed in favor of explicit domain mappings.
• (2026-02-13) Implemented findClientIdByInboundEmailDomain(domain, tenant) in shared/workflow/actions/emailWorkflowActions.ts:
  • Looks up client_inbound_email_domains by lower(domain) in the tenant.
  • Returns a client_id only when a mapping exists; otherwise returns null.
• (2026-02-13) Added migration creating client_inbound_email_domains with unique (tenant, lower(domain)): server/migrations/20260213180500_create_client_inbound_email_domains.cjs.
• (2026-02-13) Added server actions for managing inbound email domains:
  • packages/clients/src/actions/clientInboundEmailDomainActions.ts
• (2026-02-13) Implemented findValidClientPrimaryContactId(clientId, tenant) in shared/workflow/actions/emailWorkflowActions.ts to safely apply clients.properties.primary_contact_id only when it references an active contact belonging to the client.
• (2026-02-13) The workflow runtime action resolve_inbound_ticket_context in shared/workflow/runtime/actions/registerEmailWorkflowActions.ts contains similar “find contact by email, else defaults” logic and should be kept in parity if workflows still invoke it.
• (2026-02-13) Updated shared/workflow/runtime/actions/registerEmailWorkflowActions.ts (resolve_inbound_ticket_context) to match in-app resolution using explicit domain mappings:
  • Exact contact match first.
  • Else configured domain-to-client match and optional validated client default contact.
  • targetLocationId is null when resolved client differs from defaults client.
• (2026-02-13) Added inbound-email integration coverage for domain fallback in server/src/test/integration/inboundEmailInApp.webhooks.integration.test.ts:
  • Configured domain match sets ticket client_id.
  • Default contact applied when configured on client properties.
  • No explicit mapping => no domain match (falls back to defaults), even if contacts exist with that domain.
  • Location_id cleared when resolved client differs from defaults.
• (2026-02-13) There is existing “billing contact” (clients.billing_contact_id) UI in packages/clients/src/components/clients/BillingConfigForm.tsx, but it is billing-specific and not suitable as the inbound-email default contact.
• (2026-02-13) Added "Default contact" picker to the client details screen: packages/clients/src/components/clients/ClientDetails.tsx persists properties.primary_contact_id and properties.primary_contact_name.
• (2026-02-13) Client default contact picker supports clearing by selecting "None" (empties both primary_contact_id and primary_contact_name).
• (2026-02-13) Added Playwright coverage for default contact persistence: ee/server/src/__tests__/integration/client-default-contact.playwright.test.ts.
• (2026-02-13) Added Playwright coverage for clearing the default contact: ee/server/src/__tests__/integration/client-default-contact.playwright.test.ts.

Commands / Runbooks

• (2026-02-13) Code search:
  • rg -n "resolve_inbound_ticket_context|processInboundEmailInApp|findContactByEmail" -S
• (2026-02-13) Unit tests:
  • shared/lib/email/addressUtils.test.ts covers extractEmailDomain() normalization + domain extraction cases.
  • shared/workflow/actions/emailWorkflowActions.inboundDomainLookup.test.ts covers findClientIdByInboundEmailDomain() lookup + normalization behavior.

Links / References

• shared/services/email/processInboundEmailInApp.ts (new-ticket path)
• shared/workflow/actions/emailWorkflowActions.ts (findContactByEmail)
• shared/workflow/runtime/actions/registerEmailWorkflowActions.ts (resolve_inbound_ticket_context)
• packages/clients/src/components/clients/ClientDetails.tsx (client screen)
• packages/types/src/interfaces/client.interfaces.ts (IClient.properties.primary_contact_id)
• server/src/test/integration/inboundEmailInApp.webhooks.integration.test.ts (inbound email integration coverage)
• server/src/test/integration/resolveInboundTicketContext.domainFallback.integration.test.ts (workflow action parity coverage)

Open Questions

• Exact-only domain matching vs subdomain handling (it.acme.com vs acme.com).
• Should comment author attribution change when ticket contact is set via default contact (domain fallback)?
• Do we want an admin helper that suggests domains based on contacts, while still requiring explicit confirmation?