feat(messaging): link emails by Reply-To as a REPLY_TO participant (#22216)

Relay senders (e.g. a website form sending as a shared address with the real contact in Reply-To) never linked to the contact because matching only used From/To/Cc/Bcc. Record Reply-To addresses under a new REPLY_TO participant role across the Gmail, Microsoft and IMAP drivers, excluding any that just repeat the sender. Adds the REPLY_TO option to the messageParticipant role field and a 2.17 workspace command to backfill it for existing workspaces. QAed with real test run  <a href="https://cubic.dev/pr/twentyhq/twenty/pull/22216?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
2026-06-26 17:58:51 +05:30
parent ebe067f65c
commit 9747e3a7a3
12 changed files with 363 additions and 5 deletions
@@ -1,6 +1,7 @@
 import { Module } from '@nestjs/common';

 import { WorkspaceIteratorModule } from 'src/database/commands/command-runners/workspace-iterator.module';
+import { AddReplyToMessageParticipantRoleOptionCommand } from 'src/database/commands/upgrade-version-command/2-17/2-17-workspace-command-1801000001000-add-reply-to-message-participant-role-option.command';
 import { SyncCallRecordingNavigationCommandMenuItemAvailabilityExpressionCommand } from 'src/database/commands/upgrade-version-command/2-17/2-17-workspace-command-1801000000000-sync-call-recording-navigation-command-menu-item-availability-expression.command';
 import { ApplicationModule } from 'src/engine/core-modules/application/application.module';
 import { WorkspaceCacheModule } from 'src/engine/workspace-cache/workspace-cache.module';
@@ -15,6 +16,7 @@ import { WorkspaceMigrationModule } from 'src/engine/workspace-manager/workspace
  ],
  providers: [
    SyncCallRecordingNavigationCommandMenuItemAvailabilityExpressionCommand,
+    AddReplyToMessageParticipantRoleOptionCommand,
  ],
 })
 export class V2_17_UpgradeVersionCommandModule {}
@@ -0,0 +1,93 @@
+import { Command } from 'nest-commander';
+
+import { ActiveOrSuspendedWorkspaceCommandRunner } from 'src/database/commands/command-runners/active-or-suspended-workspace.command-runner';
+import { WorkspaceIteratorService } from 'src/database/commands/command-runners/workspace-iterator.service';
+import { type RunOnWorkspaceArgs } from 'src/database/commands/command-runners/workspace.command-runner';
+import { buildReplyToMessageParticipantRoleOptionSyncOperations } from 'src/database/commands/upgrade-version-command/2-17/utils/build-reply-to-message-participant-role-option-sync-operations.util';
+import { ApplicationService } from 'src/engine/core-modules/application/application.service';
+import { RegisteredWorkspaceCommand } from 'src/engine/core-modules/upgrade/decorators/registered-workspace-command.decorator';
+import { WorkspaceCacheService } from 'src/engine/workspace-cache/services/workspace-cache.service';
+import { WorkspaceMigrationValidateBuildAndRunService } from 'src/engine/workspace-manager/workspace-migration/services/workspace-migration-validate-build-and-run-service';
+
+@RegisteredWorkspaceCommand('2.17.0', 1801000001000)
+@Command({
+  name: 'upgrade:2-17:add-reply-to-message-participant-role-option',
+  description:
+    'Add the Reply To option to the messageParticipant role field in existing workspaces',
+})
+export class AddReplyToMessageParticipantRoleOptionCommand extends ActiveOrSuspendedWorkspaceCommandRunner {
+  constructor(
+    protected readonly workspaceIteratorService: WorkspaceIteratorService,
+    private readonly applicationService: ApplicationService,
+    private readonly workspaceCacheService: WorkspaceCacheService,
+    private readonly workspaceMigrationValidateBuildAndRunService: WorkspaceMigrationValidateBuildAndRunService,
+  ) {
+    super(workspaceIteratorService);
+  }
+
+  override async runOnWorkspace({
+    workspaceId,
+    options,
+  }: RunOnWorkspaceArgs): Promise<void> {
+    const isDryRun = options.dryRun ?? false;
+
+    const { flatFieldMetadataMaps } =
+      await this.workspaceCacheService.getOrRecompute(workspaceId, [
+        'flatFieldMetadataMaps',
+      ]);
+
+    const fieldMetadataOperations =
+      buildReplyToMessageParticipantRoleOptionSyncOperations({
+        existingFlatFieldMetadataMaps: flatFieldMetadataMaps,
+        now: new Date().toISOString(),
+      });
+
+    if (fieldMetadataOperations.flatEntityToUpdate.length === 0) {
+      this.logger.log(
+        `messageParticipant role REPLY_TO option already present for workspace ${workspaceId}, skipping`,
+      );
+
+      return;
+    }
+
+    this.logger.log(
+      `${isDryRun ? '[DRY RUN] ' : ''}Adding REPLY_TO option to messageParticipant role field for workspace ${workspaceId}`,
+    );
+
+    if (isDryRun) {
+      return;
+    }
+
+    const { twentyStandardFlatApplication } =
+      await this.applicationService.findWorkspaceTwentyStandardAndCustomApplicationOrThrow(
+        { workspaceId },
+      );
+
+    const validateAndBuildResult =
+      await this.workspaceMigrationValidateBuildAndRunService.validateBuildAndRunWorkspaceMigration(
+        {
+          isSystemBuild: true,
+          workspaceId,
+          applicationUniversalIdentifier:
+            twentyStandardFlatApplication.universalIdentifier,
+          allFlatEntityOperationByMetadataName: {
+            fieldMetadata: fieldMetadataOperations,
+          },
+        },
+      );
+
+    if (validateAndBuildResult.status === 'fail') {
+      this.logger.error(
+        `Failed to add REPLY_TO option to messageParticipant role field:\n${JSON.stringify(validateAndBuildResult, null, 2)}`,
+      );
+
+      throw new Error(
+        `Failed to add REPLY_TO option to messageParticipant role field for workspace ${workspaceId}`,
+      );
+    }
+
+    this.logger.log(
+      `Successfully added REPLY_TO option to messageParticipant role field for workspace ${workspaceId}`,
+    );
+  }
+}
@@ -0,0 +1,107 @@
+import { STANDARD_OBJECTS } from 'twenty-shared/metadata';
+import {
+  type FieldMetadataComplexOption,
+  FieldMetadataType,
+  MessageParticipantRole,
+} from 'twenty-shared/types';
+
+import {
+  buildReplyToMessageParticipantRoleOptionSyncOperations,
+  REPLY_TO_MESSAGE_PARTICIPANT_ROLE_OPTION,
+} from 'src/database/commands/upgrade-version-command/2-17/utils/build-reply-to-message-participant-role-option-sync-operations.util';
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { getFlatFieldMetadataMock } from 'src/engine/metadata-modules/flat-field-metadata/__mocks__/get-flat-field-metadata.mock';
+import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+
+const ROLE_FIELD_UNIVERSAL_IDENTIFIER =
+  STANDARD_OBJECTS.messageParticipant.fields.role.universalIdentifier;
+const NOW = '2026-06-26T00:00:00.000Z';
+
+const buildRoleOption = (
+  value: MessageParticipantRole,
+  position: number,
+): FieldMetadataComplexOption => ({
+  id: `option-${value}`,
+  value,
+  label: value,
+  position,
+  color: 'gray',
+});
+
+const buildFlatFieldMetadataMaps = (
+  flatFieldMetadatas: FlatFieldMetadata[],
+): FlatEntityMaps<FlatFieldMetadata> => ({
+  byUniversalIdentifier: Object.fromEntries(
+    flatFieldMetadatas.map((flatFieldMetadata) => [
+      flatFieldMetadata.universalIdentifier,
+      flatFieldMetadata,
+    ]),
+  ),
+  universalIdentifierById: Object.fromEntries(
+    flatFieldMetadatas.map((flatFieldMetadata) => [
+      flatFieldMetadata.id,
+      flatFieldMetadata.universalIdentifier,
+    ]),
+  ),
+  universalIdentifiersByApplicationId: {},
+});
+
+const buildRoleField = (options: FieldMetadataComplexOption[]) =>
+  getFlatFieldMetadataMock({
+    universalIdentifier: ROLE_FIELD_UNIVERSAL_IDENTIFIER,
+    objectMetadataId: 'message-participant-object-id',
+    type: FieldMetadataType.SELECT,
+    options,
+  });
+
+describe('buildReplyToMessageParticipantRoleOptionSyncOperations', () => {
+  it('appends the Reply To option to the existing role options without touching them', () => {
+    const roleField = buildRoleField([
+      buildRoleOption(MessageParticipantRole.FROM, 0),
+      buildRoleOption(MessageParticipantRole.TO, 1),
+      buildRoleOption(MessageParticipantRole.CC, 2),
+      buildRoleOption(MessageParticipantRole.BCC, 3),
+    ]);
+
+    const { flatEntityToUpdate } =
+      buildReplyToMessageParticipantRoleOptionSyncOperations({
+        existingFlatFieldMetadataMaps: buildFlatFieldMetadataMaps([roleField]),
+        now: NOW,
+      });
+
+    expect(flatEntityToUpdate).toHaveLength(1);
+    expect(flatEntityToUpdate[0]).toMatchObject({
+      universalIdentifier: ROLE_FIELD_UNIVERSAL_IDENTIFIER,
+      updatedAt: NOW,
+      options: [
+        ...(roleField.options as FieldMetadataComplexOption[]),
+        REPLY_TO_MESSAGE_PARTICIPANT_ROLE_OPTION,
+      ],
+    });
+  });
+
+  it('does nothing when the Reply To option is already present so the upgrade can be re-run safely', () => {
+    const roleField = buildRoleField([
+      buildRoleOption(MessageParticipantRole.FROM, 0),
+      REPLY_TO_MESSAGE_PARTICIPANT_ROLE_OPTION,
+    ]);
+
+    const { flatEntityToUpdate } =
+      buildReplyToMessageParticipantRoleOptionSyncOperations({
+        existingFlatFieldMetadataMaps: buildFlatFieldMetadataMaps([roleField]),
+        now: NOW,
+      });
+
+    expect(flatEntityToUpdate).toHaveLength(0);
+  });
+
+  it('does nothing when the workspace has no messageParticipant role field', () => {
+    const { flatEntityToUpdate } =
+      buildReplyToMessageParticipantRoleOptionSyncOperations({
+        existingFlatFieldMetadataMaps: buildFlatFieldMetadataMaps([]),
+        now: NOW,
+      });
+
+    expect(flatEntityToUpdate).toHaveLength(0);
+  });
+});
@@ -0,0 +1,64 @@
+import { STANDARD_OBJECTS } from 'twenty-shared/metadata';
+import {
+  type FieldMetadataComplexOption,
+  FieldMetadataType,
+  MessageParticipantRole,
+} from 'twenty-shared/types';
+
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatEntityToCreateDeleteUpdate } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-to-create-delete-update.type';
+import { type FlatFieldMetadata } from 'src/engine/metadata-modules/flat-field-metadata/types/flat-field-metadata.type';
+
+const MESSAGE_PARTICIPANT_ROLE_FIELD_UNIVERSAL_IDENTIFIER =
+  STANDARD_OBJECTS.messageParticipant.fields.role.universalIdentifier;
+
+export const REPLY_TO_MESSAGE_PARTICIPANT_ROLE_OPTION: FieldMetadataComplexOption =
+  {
+    id: '20202020-3b1a-4e2c-9d7f-8a6b5c4d3e2f',
+    value: MessageParticipantRole.REPLY_TO,
+    label: 'Reply To',
+    position: 4,
+    color: 'purple',
+  };
+
+export const buildReplyToMessageParticipantRoleOptionSyncOperations = ({
+  existingFlatFieldMetadataMaps,
+  now,
+}: {
+  existingFlatFieldMetadataMaps: FlatEntityMaps<FlatFieldMetadata>;
+  now: string;
+}): FlatEntityToCreateDeleteUpdate<'fieldMetadata'> => {
+  const roleField =
+    existingFlatFieldMetadataMaps.byUniversalIdentifier[
+      MESSAGE_PARTICIPANT_ROLE_FIELD_UNIVERSAL_IDENTIFIER
+    ];
+
+  const existingOptions = (roleField?.options ??
+    []) as FieldMetadataComplexOption[];
+
+  const replyToOptionIsMissing =
+    roleField?.type === FieldMetadataType.SELECT &&
+    !existingOptions.some(
+      (option) => option.id === REPLY_TO_MESSAGE_PARTICIPANT_ROLE_OPTION.id,
+    );
+
+  if (!replyToOptionIsMissing) {
+    return {
+      flatEntityToCreate: [],
+      flatEntityToDelete: [],
+      flatEntityToUpdate: [],
+    };
+  }
+
+  return {
+    flatEntityToCreate: [],
+    flatEntityToDelete: [],
+    flatEntityToUpdate: [
+      {
+        ...roleField,
+        options: [...existingOptions, REPLY_TO_MESSAGE_PARTICIPANT_ROLE_OPTION],
+        updatedAt: now,
+      },
+    ],
+  };
+};