code · pull · Jan 9, 2026 · Jan 9, 2026 · Jan 9, 2026 · Jan 9, 2026
diff --git a/apps/api/src/app/inbox/inbox.controller.ts b/apps/api/src/app/inbox/inbox.controller.ts
@@ -173,6 +173,7 @@ export class InboxController {
         organizationId: subscriberSession._organizationId,
         subscriberId: subscriberSession.subscriberId,
         environmentId: subscriberSession._environmentId,
+        contextKeys: subscriberSession.contextKeys,
         tags: query.tags,
         severity: query.severity,
         criticality: query.criticality,
@@ -188,6 +189,7 @@ export class InboxController {
         organizationId: subscriberSession._organizationId,
         environmentId: subscriberSession._environmentId,
         subscriberId: subscriberSession.subscriberId,
+        contextKeys: subscriberSession.contextKeys,
         includeInactiveChannels: false,
         subscriber: subscriberSession,
       })
@@ -376,6 +378,7 @@ export class InboxController {
         organizationId: subscriberSession._organizationId,
         subscriberId: subscriberSession.subscriberId,
         environmentId: subscriberSession._environmentId,
+        contextKeys: subscriberSession.contextKeys,
         level: PreferenceLevelEnum.GLOBAL,
         chat: body.chat,
         email: body.email,
@@ -403,6 +406,7 @@ export class InboxController {
         organizationId: subscriberSession._organizationId,
         subscriberId: subscriberSession.subscriberId,
         environmentId: subscriberSession._environmentId,
+        contextKeys: subscriberSession.contextKeys,
         preferences: body.preferences,
       })
     );
@@ -420,6 +424,7 @@ export class InboxController {
         organizationId: subscriberSession._organizationId,
         subscriberId: subscriberSession.subscriberId,
         environmentId: subscriberSession._environmentId,
+        contextKeys: subscriberSession.contextKeys,
         level: PreferenceLevelEnum.TEMPLATE,
         all: {
           ...(body.enabled !== undefined && { enabled: body.enabled }),
@@ -450,6 +455,7 @@ export class InboxController {
         organizationId: subscriberSession._organizationId,
         subscriberId: subscriberSession.subscriberId,
         environmentId: subscriberSession._environmentId,
+        contextKeys: subscriberSession.contextKeys,
         level: PreferenceLevelEnum.TEMPLATE,
         subscriptionIdentifier,
         all: {

diff --git a/apps/api/src/app/inbox/usecases/bulk-update-preferences/bulk-update-preferences.usecase.ts b/apps/api/src/app/inbox/usecases/bulk-update-preferences/bulk-update-preferences.usecase.ts
@@ -102,6 +102,7 @@ export class BulkUpdatePreferences {
             organizationId: command.organizationId,
             subscriberId: command.subscriberId,
             environmentId: command.environmentId,
+            contextKeys: command.contextKeys,
             level: PreferenceLevelEnum.TEMPLATE,
             subscriptionIdentifier: preference.subscriptionIdentifier,
             ...(isUpdatingSubscriptionPreference && {

diff --git a/apps/api/src/app/inbox/usecases/get-inbox-preferences/get-inbox-preferences.spec.ts b/apps/api/src/app/inbox/usecases/get-inbox-preferences/get-inbox-preferences.spec.ts
@@ -107,6 +107,7 @@ describe('GetInboxPreferences', () => {
       environmentId: 'env-1',
       organizationId: 'org-1',
       subscriberId: 'test-mockSubscriber',
+      contextKeys: [],
       criticality: WorkflowCriticalityEnum.NON_CRITICAL,
     });
 
@@ -133,6 +134,7 @@ describe('GetInboxPreferences', () => {
       organizationId: command.organizationId,
       environmentId: command.environmentId,
       subscriberId: command.subscriberId,
+      contextKeys: [],
       includeInactiveChannels: false,
       subscriber: {
         _id: 'test-mockSubscriber',
@@ -151,6 +153,7 @@ describe('GetInboxPreferences', () => {
       environmentId: command.environmentId,
       subscriberId: command.subscriberId,
       organizationId: command.organizationId,
+      contextKeys: [],
       tags: undefined,
       severity: undefined,
       includeInactiveChannels: false,
@@ -220,6 +223,7 @@ describe('GetInboxPreferences', () => {
       environmentId: 'env-1',
       organizationId: 'org-1',
       subscriberId: 'test-mockSubscriber',
+      contextKeys: [],
       tags: ['newsletter', 'security'],
       severity: [SeverityLevelEnum.HIGH],
       criticality: WorkflowCriticalityEnum.NON_CRITICAL,
@@ -248,6 +252,7 @@ describe('GetInboxPreferences', () => {
       organizationId: command.organizationId,
       environmentId: command.environmentId,
       subscriberId: command.subscriberId,
+      contextKeys: [],
       includeInactiveChannels: false,
       subscriber: {
         _id: 'test-mockSubscriber',
@@ -266,6 +271,7 @@ describe('GetInboxPreferences', () => {
       environmentId: command.environmentId,
       subscriberId: command.subscriberId,
       organizationId: command.organizationId,
+      contextKeys: [],
       tags: command.tags,
       severity: command.severity,
       includeInactiveChannels: false,

diff --git a/apps/api/src/app/inbox/usecases/get-inbox-preferences/get-inbox-preferences.usecase.ts b/apps/api/src/app/inbox/usecases/get-inbox-preferences/get-inbox-preferences.usecase.ts
@@ -35,6 +35,7 @@ export class GetInboxPreferences {
         organizationId: command.organizationId,
         environmentId: command.environmentId,
         subscriberId: command.subscriberId,
+        contextKeys: command.contextKeys,
         includeInactiveChannels: false,
         subscriber,
       })
@@ -56,6 +57,7 @@ export class GetInboxPreferences {
         environmentId: command.environmentId,
         subscriberId: command.subscriberId,
         organizationId: command.organizationId,
+        contextKeys: command.contextKeys,
         tags: command.tags,
         severity,
         subscriber,

diff --git a/apps/api/src/app/inbox/usecases/session/session.usecase.ts b/apps/api/src/app/inbox/usecases/session/session.usecase.ts
@@ -237,6 +237,7 @@ export class Session {
       environment,
       defaultSchedule: command.requestData.defaultSchedule,
       subscriber: subscriberEntity,
+      contextKeys,
     });
 
     const [{ removeNovuBranding }, maxSnoozeDurationHours, schedule] = await Promise.all([
@@ -292,10 +293,12 @@ export class Session {
     environment,
     defaultSchedule,
     subscriber,
+    contextKeys,
   }: {
     environment: EnvironmentEntity;
     defaultSchedule?: ScheduleDto;
     subscriber: SubscriberEntity;
+    contextKeys: string[];
   }): Promise<Schedule | undefined> {
     const isSubscribersScheduleEnabled = await this.featureFlagsService.getFlag({
       key: FeatureFlagsKeysEnum.IS_SUBSCRIBERS_SCHEDULE_ENABLED,
@@ -326,6 +329,7 @@ export class Session {
         environmentId: environment._id,
         subscriber,
         subscriberId: subscriber.subscriberId,
+        contextKeys,
         level: PreferenceLevelEnum.GLOBAL,
         includeInactiveChannels: false,
         schedule: defaultSchedule,

diff --git a/apps/api/src/app/inbox/usecases/update-preferences/update-preferences.spec.ts b/apps/api/src/app/inbox/usecases/update-preferences/update-preferences.spec.ts
@@ -1,4 +1,5 @@
 import {
+  FeatureFlagsService,
   GetSubscriberTemplatePreference,
   GetWorkflowByIdsUseCase,
   SendWebhookMessage,
@@ -54,6 +55,7 @@ describe('UpdatePreferences', () => {
   let sendWebhookMessageMock: sinon.SinonStubbedInstance<SendWebhookMessage>;
   let topicSubscribersRepositoryMock: sinon.SinonStubbedInstance<TopicSubscribersRepository>;
   let preferencesRepositoryMock: sinon.SinonStubbedInstance<PreferencesRepository>;
+  let featureFlagsServiceMock: sinon.SinonStubbedInstance<FeatureFlagsService>;
   beforeEach(() => {
     subscriberRepositoryMock = sinon.createStubInstance(SubscriberRepository);
     getSubscriberGlobalPreferenceMock = sinon.createStubInstance(GetSubscriberGlobalPreference);
@@ -63,6 +65,7 @@ describe('UpdatePreferences', () => {
     sendWebhookMessageMock = sinon.createStubInstance(SendWebhookMessage);
     topicSubscribersRepositoryMock = sinon.createStubInstance(TopicSubscribersRepository);
     preferencesRepositoryMock = sinon.createStubInstance(PreferencesRepository);
+    featureFlagsServiceMock = sinon.createStubInstance(FeatureFlagsService);
 
     updatePreferences = new UpdatePreferences(
       subscriberRepositoryMock as any,
@@ -72,7 +75,8 @@ describe('UpdatePreferences', () => {
       getWorkflowByIdsUsecase as any,
       sendWebhookMessageMock as any,
       topicSubscribersRepositoryMock as any,
-      preferencesRepositoryMock as any
+      preferencesRepositoryMock as any,
+      featureFlagsServiceMock as any
     );
   });
 
@@ -105,6 +109,7 @@ describe('UpdatePreferences', () => {
       environmentId: 'env-1',
       organizationId: 'org-1',
       subscriberId: 'test-mockSubscriber',
+      contextKeys: [],
       level: PreferenceLevelEnum.GLOBAL,
       chat: true,
       includeInactiveChannels: false,
@@ -121,6 +126,7 @@ describe('UpdatePreferences', () => {
         environmentId: command.environmentId,
         organizationId: command.organizationId,
         subscriberId: mockedSubscriber.subscriberId,
+        contextKeys: [],
         includeInactiveChannels: false,
       }),
     ]);

diff --git a/apps/api/src/app/inbox/usecases/update-preferences/update-preferences.usecase.ts b/apps/api/src/app/inbox/usecases/update-preferences/update-preferences.usecase.ts
@@ -1,5 +1,6 @@
 import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
 import {
+  FeatureFlagsService,
   GetPreferences,
   GetSubscriberTemplatePreference,
   GetSubscriberTemplatePreferenceCommand,
@@ -13,14 +14,17 @@ import {
   UpsertSubscriberWorkflowPreferencesCommand,
 } from '@novu/application-generic';
 import {
+  EnforceEnvOrOrgIds,
   NotificationTemplateEntity,
+  PreferencesDBModel,
   PreferencesRepository,
   SubscriberEntity,
   SubscriberRepository,
   TopicSubscribersRepository,
 } from '@novu/dal';
 import {
   buildWorkflowPreferences,
+  FeatureFlagsKeysEnum,
   IPreferenceChannels,
   PreferenceLevelEnum,
   PreferencesTypeEnum,
@@ -31,6 +35,7 @@ import {
   WorkflowPreferences,
   WorkflowPreferencesPartial,
 } from '@novu/shared';
+import { FilterQuery } from 'mongoose';
 import {
   GetSubscriberGlobalPreference,
   GetSubscriberGlobalPreferenceCommand,
@@ -48,7 +53,8 @@ export class UpdatePreferences {
     private getWorkflowByIdsUsecase: GetWorkflowByIdsUseCase,
     private sendWebhookMessage: SendWebhookMessage,
     private topicSubscribersRepository: TopicSubscribersRepository,
-    private preferencesRepository: PreferencesRepository
+    private preferencesRepository: PreferencesRepository,
+    private featureFlagsService: FeatureFlagsService
   ) {}
 
   @InstrumentUsecase()
@@ -131,6 +137,7 @@ export class UpdatePreferences {
       organizationId: command.organizationId,
       environmentId: command.environmentId,
       _subscriberId: subscriber._id,
+      contextKeys: command.contextKeys,
       workflowId,
       subscriptionId: internalSubscriptionId,
       schedule: command.schedule,
@@ -161,13 +168,18 @@ export class UpdatePreferences {
       command.workflowIdOrIdentifier &&
       workflow
     ) {
-      const preferenceEntity = await this.preferencesRepository.findOne({
+      const contextQuery = await this.buildContextExactMatchQuery(command.contextKeys, command.organizationId);
+
+      const query: FilterQuery<PreferencesDBModel> & EnforceEnvOrOrgIds = {
         _environmentId: command.environmentId,
         _subscriberId: subscriber._id,
         _templateId: workflow._id,
         _topicSubscriptionId: internalSubscriptionId,
         type: PreferencesTypeEnum.SUBSCRIPTION_SUBSCRIBER_WORKFLOW,
-      });
+        ...contextQuery,
+      };
+
+      const preferenceEntity = await this.preferencesRepository.findOne(query);
 
       const builtPreferences = buildWorkflowPreferences(preferenceEntity?.preferences);
       const channels = GetPreferences.mapWorkflowPreferencesToChannelPreferences(preferenceEntity?.preferences || {});
@@ -200,7 +212,8 @@ export class UpdatePreferences {
           subscriber,
           includeInactiveChannels: command.includeInactiveChannels,
           subscriptionId: internalSubscriptionId,
-        })
+          contextKeys: command.contextKeys,
+        } as GetSubscriberTemplatePreferenceCommand)
       );
 
       return {
@@ -225,6 +238,7 @@ export class UpdatePreferences {
         environmentId: command.environmentId,
         subscriberId: command.subscriberId,
         includeInactiveChannels: command.includeInactiveChannels,
+        contextKeys: command.contextKeys,
       })
     );
 
@@ -240,6 +254,7 @@ export class UpdatePreferences {
     organizationId: string;
     _subscriberId: string;
     environmentId: string;
+    contextKeys?: string[];
     workflowId?: string;
     subscriptionId?: string;
     schedule?: Schedule;
@@ -270,6 +285,7 @@ export class UpdatePreferences {
           templateId: item.workflowId,
           topicSubscriptionId: item.subscriptionId,
           preferences,
+          contextKeys: item.contextKeys,
           returnPreference: false,
         })
       );
@@ -285,6 +301,7 @@ export class UpdatePreferences {
           _subscriberId: item._subscriberId,
           templateId: item.workflowId,
           preferences,
+          contextKeys: item.contextKeys,
           returnPreference: false,
         })
       );
@@ -300,7 +317,33 @@ export class UpdatePreferences {
         _subscriberId: item._subscriberId,
         returnPreference: false,
         schedule: item.schedule,
+        contextKeys: item.contextKeys,
       })
     );
   }
+
+  private async buildContextExactMatchQuery(
+    contextKeys: string[] | undefined,
+    organizationId: string
+  ): Promise<Record<string, unknown>> {
+    const useContextFiltering = await this.featureFlagsService.getFlag({
+      key: FeatureFlagsKeysEnum.IS_CONTEXT_PREFERENCES_ENABLED,
+      defaultValue: false,
+      organization: { _id: organizationId },
+    });
+
+    if (!useContextFiltering) {
+      return {};
+    }
+
+    if (contextKeys === undefined || contextKeys.length === 0) {
+      return {
+        $or: [{ contextKeys: { $exists: false } }, { contextKeys: [] }],
+      };
+    }
+
+    return {
+      contextKeys: { $all: contextKeys, $size: contextKeys.length },
+    };
+  }
 }
diff --git a/...ers/usecases/get-subscriber-global-preference/get-subscriber-global-preference.command.ts b/...ers/usecases/get-subscriber-global-preference/get-subscriber-global-preference.command.ts
@@ -1,6 +1,6 @@
-import { EnvironmentWithSubscriber } from '@novu/application-generic';
 import { SubscriberEntity } from '@novu/dal';
 import { IsBoolean, IsDefined, IsOptional } from 'class-validator';
+import { EnvironmentWithSubscriber } from '../../../shared/commands/project.command';
 
 export class GetSubscriberGlobalPreferenceCommand extends EnvironmentWithSubscriber {
   @IsBoolean()