Epic Goal

Enable shared email addresses for Organization notifications and ownership display by introducing a new Contact Email field that is decoupled from the unique internal "Account ID" email.

Why is this important?

Current Problem

Users tend to have a single email address but manage many organizations.  They currently cannot use the same email address for multiple organizations because:

• Database constraint: Organizations are stored in the User table with a unique constraint on the email field

• Confusing UX: When creating an org, users naturally enter their team lead's or manager's email, which often already exists in the system (causing a cryptic error)

• Poor error messaging: The UI says "must be different from your account's email" but doesn't explain it can't be ANY existing user/org email

• Unnecessary burden: Users must create and manage multiple email addresses (or aliases) if they wish to receive notifications from all their orgs

Customer Feedback

"When creating an org, it makes sense for them to put the logical owner's email in the organization email field - that is a natural thing to do. If the natural thing to do is the wrong thing to do, then the product is doing something wrong."

Scenarios

1. A user can create an organization without providing any email (system auto-generates internal ID)
2. A user can optionally provide a Contact Email during org creation
3. A user can create another organization using the same Contact Email as an existing org
4. An organization can be updated to use a Contact Email already registered to another organization
5. Organization recovery emails are sent to contact_email (if set)
6. Existing organizations continue to work (backward compatible)

Proposed Changes

1. Backend --> Goal: Ensure the database unique constraint is satisfied without user input

• Always auto-generate the auth_user.email field for Organizations (e.g., using a UUID) upon creation (regardless of FEATURE_MAILING or FEATURE_BILLING settings)

• Pass email_required=False when creating organizations (the existing code path already handles UUID generation)

2. Data model ("Contact Email" addition):

• Add a new column contact_email to the User table (which stores organizations)

• This field accepts duplicate values and is not constrained by auth_user.email uniqueness
  • [NEW] Can be the same as the creating user's email or any other user's email (addresses the collision issue)

3. UI/UX:

• Create Org modal: Remove the mandatory "Organization Email" field (since the backend now auto-generates it)

• Create Org modal: Add an optional "Contact Email" field that maps to contact_email
  • [NEW] Pre-populate with the creating user's email as the default value (user can change or clear it)
  • --> This way, users enter orgadmin1@acme.com, the system creates uuid@internal, and notifications flow to orgadmin1@acme.com

• Org Settings page: Show/allow editing of "Contact Email" field; hide the internal UUID email from users

4. Routing change:

• Update email sending functions to check contact_email first:
  • IF contact_email exists → send there
  • ELSE → [NEW] send to all org owners' email addresses (fallback to ensure notifications are never lost)

• Affected functions:
  • send_org_recovery_email() in util/useremails.py
  • Billing/invoice emails (if FEATURE_BILLING enabled)

What This Does NOT Change

• FEATURE_MAILING behavior remains unchanged (password recovery, email notifications still work)
• FEATURE_BILLING is unaffected
• Existing organizations continue to work (migration can optionally copy email → contact_email for existing orgs)
• Internal database uniqueness constraint remains intact (using auto-generated UUIDs)
• No breaking changes to existing API consumers

Acceptance Criteria

• Users can create organizations without providing an email address
• Users can optionally provide a Contact Email during org creation
• The same Contact Email can be used for multiple organizations
• Organization recovery emails are sent to Contact Email (when set)
• Existing organizations continue to function normally
• Organization settings UI allows viewing/editing Contact Email
• API documentation updated to reflect new contact_email field

• CI - MUST be running successfully with tests automated
• Release Technical Enablement - Provide necessary release enablement details and documents

Dependencies (internal and external)

1. ...

Previous Work (Optional):

1. ...

Open questions:

• 1) Are there any hard checks or assumptions in the code related to the uniqueness of an org email address?
  • Yes --> the User.email field has a unique constraint. The solution would auto-generate UUID for internal email, use separate contact_email for user-facing purposes.

• 2) Can we tie this to FEATURE_BILLING?
  • No --> on-prem deployments can have FEATURE_MAILING=true but FEATURE_BILLING=false and still need org recovery emails.  The solution needs to be independent of both feature flags.

• 3) What about existing orgs?
  • Backward compatible --> existing orgs work as-is.  Optional migration can copy email → contact_email for existing orgs that have real email addresses

Done Checklist

• CI - CI is running, tests are automated and merged.
• Release Enablement <link to Feature Enablement Presentation>
• DEV - Upstream code and tests merged: <link to meaningful PR or GitHub Issue>
• DEV - Upstream documentation merged: <link to meaningful PR or GitHub Issue>
• DEV - Downstream build attached to advisory: <link to errata>
• QE - Test plans in Polarion: <link or reference to Polarion>
• QE - Automated tests merged: <link or reference to automated tests>
• DOC - Downstream documentation merged: <link to meaningful PR>