Email Domain Mappings

Email domain mappings allow Cortex to treat two equivalent email domains as the same fan identity for selected authentication flows.

The common use case is Gmail and Googlemail. Some fans may have registered with [email protected], while others may have registered with the equivalent [email protected]. When a mapping is enabled, Cortex can resolve the mapped domain to the canonical domain so fans do not accidentally create separate accounts for what is effectively the same inbox.

Mappings are configured per Cortex client.

Example: Gmail and Googlemail

In the Gmail/Googlemail example:

Term	Example	Meaning
Mapped domain	`googlemail.com`	The domain a fan might type or that might already exist on a legacy account.
Canonical domain	`gmail.com`	The domain Cortex uses for new accounts when the mapping is enabled.
Mapping	`googlemail.com -> gmail.com`	`[email protected]` is treated as equivalent to `[email protected]` in supported flows.

If a new fan registers with [email protected] after the mapping is enabled, the account is created and displayed as [email protected].

What Changes When Mapping Is Enabled

When a mapping is enabled, Cortex applies it in two ways:

Behavior	What happens
New account writes	New registrations using the mapped domain are stored with the canonical domain. For example, `[email protected]` is stored as `[email protected]`.
Identity lookups	Login, registration checks, and social-login checks can resolve equivalent Gmail and Googlemail addresses to the same existing account.
Password reset	Password-reset requests continue to avoid account enumeration. Cortex accepts the request even when no reset email can be sent for the supplied address.
Duplicate mappings	A client cannot have multiple mapped domains pointing to the same canonical domain, because that would make reverse matching ambiguous.

This feature maps equivalent account identities. It does not automatically move entitlements, tickets, memberships, preferences, juniors, account links, or other user data between duplicate legacy accounts.

Existing Accounts Before Mapping Is Enabled

Existing account state matters. A clean account state has only one version of the fan account. A duplicate-account state has both a Gmail and Googlemail account for the same local part.

Existing account state	After mapping is enabled	Data impact
Only `[email protected]` exists	The fan continues to use `[email protected]`. They can also type `[email protected]` for login, but they are signed into the Gmail account.	Gmail account data remains attached to the same account.
Only `[email protected]` exists	The fan can continue using `[email protected]`. Email SSO login and social login can also resolve `[email protected]` to this legacy Googlemail account.	Googlemail account data remains attached to the same account.
Both `[email protected]` and `[email protected]` exist	The Gmail account becomes the account used by mapped login and social flows. The Googlemail account remains in the system but is not the account the fan reaches through normal mapped login flows.	Gmail data remains. Data attached only to the Googlemail account must be migrated if it should remain available to the fan.

Registration With Email SSO

Email SSO registration prevents new duplicate accounts after the mapping is enabled.

Existing account state	Fan registers with `[email protected]`	Fan registers with `[email protected]`
No matching account exists	New account created as `[email protected]`.	New account created as `[email protected]`.
Only `[email protected]` exists	Already registered.	Already registered.
Only `[email protected]` exists	Already registered, because the mapped lookup treats the Gmail and Googlemail forms as the same identity for registration.	Already registered.
Both accounts exist	Already registered.	Already registered.

The main user-facing nuance is that a fan who typed [email protected] during registration sees the new account stored and displayed as [email protected].

Login With Email SSO

Email SSO login resolves the equivalent address forms to the account that should be used.

Existing account state	Fan logs in with `[email protected]`	Fan logs in with `[email protected]`
Only `[email protected]` exists	Logs into the Gmail account with the Gmail password.	Logs into the Gmail account with the Gmail password.
Only `[email protected]` exists	Logs into the Googlemail account with the Googlemail password.	Logs into the Googlemail account with the Googlemail password.
Both accounts exist	Logs into the Gmail account with the Gmail password.	Logs into the Gmail account if the Gmail password is used. The old Googlemail password does not unlock the Googlemail account through the mapped flow.

Social Login

Social login handles registration and login together. The email returned by the social provider is resolved through the same mapping rules.

Existing account state	Social provider returns `[email protected]`	Social provider returns `[email protected]`
No matching account exists	New account created as `[email protected]`.	New account created as `[email protected]`.
Only `[email protected]` exists	Logs into the Gmail account.	Logs into the Gmail account.
Only `[email protected]` exists	Logs into the Googlemail account.	Logs into the Googlemail account.
Both accounts exist	Logs into the Gmail account.	Logs into the Gmail account.

If the provider returns [email protected] for a brand new fan, Cortex creates the account as [email protected].

Password Reset and Email Verification

Password reset remains non-enumerating. A password-reset request is accepted even when Cortex cannot send a reset email for the supplied address, so the response does not reveal whether the account exists.

Scenario	Behavior
New fan registers with `[email protected]`	The account is stored as `[email protected]`; verification email follows the stored canonical email. Gmail and Googlemail route to the same inbox for this use case.
Only `[email protected]` exists and reset is requested with either address	The request is accepted and the reset flow targets the Gmail account.
Only `[email protected]` exists and reset is requested with `[email protected]`	The request is accepted and the reset flow targets the Googlemail account.
Only `[email protected]` exists and reset is requested with `[email protected]`	The request is accepted so the system does not reveal whether an account exists. The fan should use the Googlemail address to receive the reset email.
Both accounts exist and reset is requested with either address	The request is accepted; the mapped Googlemail form resolves to the Gmail account.

In practice, Gmail and Googlemail usually route to the same inbox, but there are possible mappings in which this is not the case. The important distinction is which Cortex account owns the password and verification state.

Changing Email Addresses

Fan self-service email changes apply the mapping before deciding whether the new email is available.

Flow	Behavior
Gmail account changes to equivalent Googlemail address	Blocked as no effective change, because `[email protected]` canonicalises to the existing `[email protected]`.
Legacy Googlemail account changes to equivalent Gmail address	Allowed; the account becomes `[email protected]`.
Fan Manager/admin update	The admin update path does not apply the email domain mapping as for fan self-service. This allows an admin to bypass mappings in the case of specific fan requests.

Fan Manager and Admin Updates

Fan Manager can still surface legacy duplicate accounts because the underlying accounts remain present unless they are explicitly migrated or cleaned up. Searching by the full Gmail address returns the Gmail account if it exists. Searching by the full Googlemail address returns the Googlemail account if it exists. Searching by the shared local part, such as name, can return both accounts.

Data Migration Considerations

Before enabling the mapping for a client, review whether any fans have both [email protected] and [email protected] accounts.

If only one account exists for a fan, no duplicate-account data migration is required for that fan.