PSA/ee/docs/plans/2026-03-15-multiple-email-addresses-per-contact/PRD.md

# PRD — Multiple Email Addresses Per Contact

- Slug: `2026-03-15-multiple-email-addresses-per-contact`
- Date: `2026-03-15`
- Status: `Draft`

## Summary

Allow contacts to keep a required primary email on `contacts.email`, add labeled additional email addresses in a child table, and let users promote an additional email to default by swapping it into `contacts.email`. The design preserves compatibility for the large set of existing application surfaces that already treat `contacts.email` as the canonical default email while still enabling inbound matching and search across multiple stored addresses.

## Problem

The current contact model allows only one email address, which is too restrictive for real customer records. A single contact may need work, personal, and billing addresses, but duplicating contacts to represent those variants causes inbound-email ambiguity and data quality issues.

At the same time, a full normalization of contact email would force contract changes across a large part of the product because many existing surfaces already read `contacts.email` as the default send/login/summary address. A safer design should add support for more addresses without breaking those default-email consumers.

## Goals

1. Let a contact store multiple labeled email addresses.
2. Keep `contacts.email` as the required authoritative default email.
3. Let users change the default by swapping an additional email into `contacts.email`.
4. Support canonical labels plus tenant-scoped custom labels using the same general model as contact phone labels.
5. Enforce tenant-wide uniqueness across both primary and additional contact emails.
6. Match inbound email and contact lookups by either the primary or an additional email address.
7. Preserve compatibility for existing outbound, portal, auth, and summary consumers that already use `contacts.email`.

## Non-goals

- Replacing `contacts.email` with a fully normalized email collection in this effort.
- Making `contacts.email` nullable.
- Allowing a contact to have no primary/default email.
- Treating additional emails as independent login aliases for portal or client-user auth.
- Rewriting every `contacts.email` consumer to a new default-email field when existing behavior can remain unchanged.
- Re-keying existing email-snapshot recipient records unless the surface explicitly re-resolves the contact from user input.

## Users and Primary Flows

**Primary users**
- Service desk agents managing contacts
- Operators handling inbound email and ticketing
- Staff sending notifications, invoices, surveys, and portal invitations
- Automation and integration flows that create or resolve contacts by email

### Flow A — Manage Contact Emails
1. User opens contact create or edit.
2. User edits the primary email row, including its label.
3. User adds, labels, reorders, or deletes additional email rows.
4. User promotes an additional email to default.
5. The system swaps the promoted row into `contacts.email` and moves the previous primary email into the additional-email table.

### Flow B — Match Inbound Email
1. An inbound message arrives from a sender address.
2. The system normalizes the sender address and searches both `contacts.email` and additional email rows.
3. The system resolves the owning contact uniquely.
4. Ticket/comment authorship preserves the matched sender address.
5. Any default outbound contact send still uses `contacts.email`.

### Flow C — Existing Default-Email Sends
1. A workflow or product surface needs to email a contact.
2. The surface reads `contacts.email`.
3. The send path continues to work without needing a new derived default-email field.
4. If the default was changed earlier, the promoted address is already present in `contacts.email`.

## UX / UI Notes

- Use a shared `ContactEmailAddressesEditor` modeled on the phone-number editor.
- The editor should render a pinned primary/default row plus a list of additional rows.
- Canonical labels: `work`, `personal`, `billing`, `other`.
- Custom labels must support freeform entry and tenant-scoped suggestions.
- Users cannot delete the primary email row directly.
- To change default, users promote an additional email, which swaps it with the current primary row.
- Detail views show the primary/default email distinctly, with additional emails listed underneath.
- List screens, pickers, and summary cards continue showing `contacts.email` as the default summary address.

## Functional Requirements

### Data Model and Validation

**FR-01**: `contacts.email` remains required and is the authoritative default contact email.

**FR-02**: The primary contact email stored on `contacts` gains label metadata.

**FR-03**: Non-default contact emails are stored as an ordered child collection separate from `contacts.email`.

**FR-04**: Canonical email labels are `work`, `personal`, `billing`, and `other`, and custom labels are tenant-scoped and reusable across primary and additional emails.

**FR-05**: Every normalized email address is unique per tenant across both `contacts.email` and additional email rows.

**FR-06**: Promoting an additional email to default swaps both the email value and its label metadata with the current `contacts.email` values.

**FR-07**: A contact can never lose its primary/default email; deleting the current default directly is disallowed.

**FR-08**: Existing contacts migrate without changing their current `contacts.email` values and gain safe initial primary-email label metadata.

### Contact CRUD and Discovery

**FR-09**: Contact create/edit screens support editing the primary email label plus adding, removing, reordering, and promoting additional email rows.

**FR-10**: Contact detail views display the primary/default email distinctly and list all additional emails with labels.

**FR-11**: Contact list, picker, and summary views continue to display `contacts.email` as the visible default email.

**FR-12**: Contact search, filter, import, and export by email must be able to match both primary and additional email addresses.

### Inbound Email and Workflow Lookups

**FR-13**: Inbound email sender matching resolves contacts by either the primary or an additional stored email address.

**FR-14**: Inbound and workflow contexts preserve the matched sender email separately when it differs from `contacts.email`.

**FR-15**: Shared contact lookup and create-or-find helpers search both storage locations while creating new contacts with the primary email stored in `contacts.email`.

**FR-16**: Workflow/domain-event/full-contact contracts expose primary-email label metadata and additional email rows where a full contact shape is needed, while summary email fields continue to use `contacts.email`.

### Compatibility and Integrations

**FR-17**: Existing outbound notifications, portal/auth flows, client-user linking, billing sends, and similar default-email consumers continue to use `contacts.email` without needing a new default-email field.

**FR-18**: Existing email-keyed watcher and recipient snapshot behavior remains compatible unless a surface explicitly re-resolves a contact from user-supplied email input.

**FR-19**: REST, n8n, CSV, and integration contracts add support for primary-email labels and additional email rows without removing scalar `email`.

**FR-20**: Automated coverage includes DB-backed uniqueness, swap, and lookup tests plus compatibility regressions for major `contacts.email` consumers.

## Non-functional Requirements

- Keep the email-label editor behavior aligned with the existing phone-number label model where practical.
- Favor compatibility by preserving `contacts.email` as the authoritative default field.
- Avoid ambiguous contact resolution by enforcing tenant-wide uniqueness across both storage locations.
- Keep the migration safe and reversible by preserving existing primary email values and layering additional-email support around them.

## Data / API / Integrations

### Proposed Shape

Primary/default email remains on `contacts`:

- `email`
- primary email label metadata fields

Additional emails live in a child table:

- `contact_additional_email_address_id`
- `email_address`
- `normalized_email_address`
- label metadata
- `display_order`

### API Direction

- Keep `email` in create/update/read contracts as the primary/default email.
- Add primary-email label fields to create/update/read contracts.
- Add `additional_email_addresses` to create/update/read contracts.
- Keep response summary email fields sourced from `contacts.email`.

### Workflow Direction

- `findContactByEmail` and related lookup helpers must search both `contacts.email` and additional email rows.
- Workflow contexts that care about inbound authorship should preserve:
  - matched sender email
  - primary/default contact email from `contacts.email`

## Risks and Migration Notes

- The main schema risk is cross-location uniqueness: the system must prevent duplicates between `contacts.email` and the additional-email table in both directions.
- Default-swap behavior must be transactional so the primary and additional rows cannot drift.
- CSV/import/export and API contracts still need real updates, even with the safer compatibility model.
- Some recipient stores, such as watcher-like email snapshots, may intentionally remain email-keyed rather than dynamically following future contact default swaps.
- Existing tests and fixtures that only know about scalar email will still need widespread updates to cover primary labels and additional emails.

## Acceptance Criteria / Definition Of Done

1. Contacts can keep a labeled primary/default email and add labeled additional emails.
2. Users can promote an additional email to default, and the system swaps it into `contacts.email`.
3. Tenant-wide uniqueness is enforced across both primary and additional contact emails.
4. Inbound email processing and lookup helpers can resolve a contact by any stored email address.
5. Existing default-email consumers continue to operate against `contacts.email`.
6. REST/API, CSV, n8n, and integration contracts support the hybrid model.
7. Automated coverage proves swap behavior, uniqueness, inbound lookup, and compatibility for key `contacts.email` consumers.