The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Record campaign clicks (#26638)
neo773954c3231ae34
diff --git a/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/record-campaign-engagement-job.constant.ts b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/record-campaign-engagement-job.constant.tsnew file mode 100644index 00000000000..526768d6774--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/emailing-domain/constants/record-campaign-engagement-job.constant.ts@@ -0,0 +1 @@+export const RECORD_CAMPAIGN_ENGAGEMENT_JOB = 'RecordCampaignEngagementJob';diff --git a/packages/twenty-server/src/engine/core-modules/message-queue/message-queue-worker-config.constant.ts b/packages/twenty-server/src/engine/core-modules/message-queue/message-queue-worker-config.constant.tsindex 2096129b37f..72601162fe2 100644--- a/packages/twenty-server/src/engine/core-modules/message-queue/message-queue-worker-config.constant.ts+++ b/packages/twenty-server/src/engine/core-modules/message-queue/message-queue-worker-config.constant.ts@@ -94,6 +94,15 @@ export const MESSAGE_QUEUE_WORKER_CONFIG: Record<boundedShutdownDrain: false,},},+ [MessageQueue.campaignEngagementQueue]: {+ priority: 8,+ workerOptions: {+ concurrency: 50,+ lockDuration: 30_000,+ maxStalledCount: 1,+ boundedShutdownDrain: false,+ },+ },[MessageQueue.calendarQueue]: {priority: 4,workerOptions: {diff --git a/packages/twenty-server/src/engine/core-modules/message-queue/message-queue.constants.ts b/packages/twenty-server/src/engine/core-modules/message-queue/message-queue.constants.tsindex 458091e58a1..e7b64c1849a 100644--- a/packages/twenty-server/src/engine/core-modules/message-queue/message-queue.constants.ts+++ b/packages/twenty-server/src/engine/core-modules/message-queue/message-queue.constants.ts@@ -11,6 +11,7 @@ export enum MessageQueue {emailQueue = 'email-queue',campaignQueue = 'campaign-queue',campaignSendQueue = 'campaign-send-queue',+ campaignEngagementQueue = 'campaign-engagement-queue',calendarQueue = 'calendar-queue',connectedAccountSyncWebhookQueue = 'connected-account-sync-webhook-queue',contactCreationQueue = 'contact-creation-queue',diff --git a/packages/twenty-server/src/engine/core-modules/metrics/types/metrics-keys.type.ts b/packages/twenty-server/src/engine/core-modules/metrics/types/metrics-keys.type.tsindex a326af881e0..e127e075e09 100644--- a/packages/twenty-server/src/engine/core-modules/metrics/types/metrics-keys.type.ts+++ b/packages/twenty-server/src/engine/core-modules/metrics/types/metrics-keys.type.ts@@ -99,4 +99,6 @@ export enum MetricsKeys {WorkspaceMigrationActionCount = 'workspace-migration/action-count',OrmV2ReadPathUsed = 'orm-v2/read-path-used',OrmV2WritePathUsed = 'orm-v2/write-path-used',+ CampaignEngagementCaptureFailed = 'campaign-engagement/capture-failed',+ CampaignEngagementCaptureThrottled = 'campaign-engagement/capture-throttled',}diff --git a/packages/twenty-server/src/modules/emailing/constants/campaign-engagement-capture-rate-limit-per-link.constant.ts b/packages/twenty-server/src/modules/emailing/constants/campaign-engagement-capture-rate-limit-per-link.constant.tsnew file mode 100644index 00000000000..90075bb2612--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/constants/campaign-engagement-capture-rate-limit-per-link.constant.ts@@ -0,0 +1,4 @@+export const CAMPAIGN_ENGAGEMENT_CAPTURE_RATE_LIMIT_PER_LINK = {+ maxRequests: 60,+ windowMs: 60_000,+};diff --git a/packages/twenty-server/src/modules/emailing/constants/campaign-engagement-capture-rate-limit-per-requester.constant.ts b/packages/twenty-server/src/modules/emailing/constants/campaign-engagement-capture-rate-limit-per-requester.constant.tsnew file mode 100644index 00000000000..faaf7cdfb85--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/constants/campaign-engagement-capture-rate-limit-per-requester.constant.ts@@ -0,0 +1,4 @@+export const CAMPAIGN_ENGAGEMENT_CAPTURE_RATE_LIMIT_PER_REQUESTER = {+ maxRequests: 600,+ windowMs: 60_000,+};diff --git a/packages/twenty-server/src/modules/emailing/constants/campaign-engagement-insert-busy-timeout-ms.constant.ts b/packages/twenty-server/src/modules/emailing/constants/campaign-engagement-insert-busy-timeout-ms.constant.tsnew file mode 100644index 00000000000..f38a6a98bbf--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/constants/campaign-engagement-insert-busy-timeout-ms.constant.ts@@ -0,0 +1 @@+export const CAMPAIGN_ENGAGEMENT_INSERT_BUSY_TIMEOUT_MS = 1_000;diff --git a/packages/twenty-server/src/modules/emailing/constants/short-link-click-table.constant.ts b/packages/twenty-server/src/modules/emailing/constants/short-link-click-table.constant.tsnew file mode 100644index 00000000000..2461d302b43--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/constants/short-link-click-table.constant.ts@@ -0,0 +1 @@+export const SHORT_LINK_CLICK_TABLE = 'shortLinkClick';diff --git a/packages/twenty-server/src/modules/emailing/controllers/campaign-tracking.controller.ts b/packages/twenty-server/src/modules/emailing/controllers/campaign-tracking.controller.tsindex 507a6266fe1..1cdcd87a6eb 100644--- a/packages/twenty-server/src/modules/emailing/controllers/campaign-tracking.controller.ts+++ b/packages/twenty-server/src/modules/emailing/controllers/campaign-tracking.controller.ts@@ -3,12 +3,15 @@ import {Controller,Get,Header,+ Headers,NotFoundException,Param,Redirect,+ Req,UseGuards,} from '@nestjs/common';import { isNonEmptyString } from '@sniptt/guards';+import { type Request } from 'express';import { ApiPath } from 'twenty-shared/types';import { isDefined } from 'twenty-shared/utils';@@ -18,6 +21,7 @@ import { NoPermissionGuard } from 'src/engine/guards/no-permission.guard';import { PublicEndpointGuard } from 'src/engine/guards/public-endpoint.guard';import { ShortLinkService } from 'src/engine/core-modules/short-link/services/short-link.service';import { TRACKABLE_URL_PATTERN } from 'src/modules/emailing/constants/trackable-url-pattern.constant';+import { CampaignEngagementCaptureService } from 'src/modules/emailing/services/campaign-engagement-capture.service';const FOUND_STATUS_CODE = 302;@@ -26,7 +30,10 @@ const CAMPAIGN_TRACKING_TOKEN_FORMAT = /^[A-Za-z0-9_-]+$/;@Controller(ApiPath.Emailing)@UseGuards(PublicEndpointGuard, NoPermissionGuard)export class CampaignTrackingController {- constructor(private readonly shortLinkService: ShortLinkService) {}+ constructor(+ private readonly shortLinkService: ShortLinkService,+ private readonly campaignEngagementCaptureService: CampaignEngagementCaptureService,+ ) {}@Get('c/:token')@Redirect()@@ -34,6 +41,8 @@ export class CampaignTrackingController {@Header('Referrer-Policy', 'no-referrer')async handleTrackedLinkClick(@Param('token') token: string,+ @Headers('user-agent') userAgent: string | undefined,+ @Req() request: Request,): Promise<{ url: string; statusCode: number }> {const payload = this.decodeTokenOrThrow(token);const shortLink = await this.shortLinkService.findById({@@ -55,6 +64,12 @@ export class CampaignTrackingController {throw new NotFoundException('Invalid tracked link destination');}+ await this.campaignEngagementCaptureService.capture({+ payload,+ userAgent: userAgent ?? null,+ requesterIp: request.ip ?? null,+ });+return { url: destinationUrl, statusCode: FOUND_STATUS_CODE };}diff --git a/packages/twenty-server/src/modules/emailing/emailing.module.ts b/packages/twenty-server/src/modules/emailing/emailing.module.tsindex dbecf23f656..07f369ead6b 100644--- a/packages/twenty-server/src/modules/emailing/emailing.module.ts+++ b/packages/twenty-server/src/modules/emailing/emailing.module.ts@@ -6,6 +6,8 @@ import { BillingModule } from 'src/engine/core-modules/billing/billing.module';import { EmailingDomainModule } from 'src/engine/core-modules/emailing-domain/emailing-domain.module';import { EmailingDomainEntity } from 'src/engine/core-modules/emailing-domain/emailing-domain.entity';import { ShortLinkModule } from 'src/engine/core-modules/short-link/short-link.module';+import { ClickHouseModule } from 'src/database/clickhouse/clickhouse.module';+import { MetricsModule } from 'src/engine/core-modules/metrics/metrics.module';import { UnsubscribeTopicEntity } from 'src/engine/core-modules/emailing-domain/unsubscribe-topic.entity';import { FeatureFlagModule } from 'src/engine/core-modules/feature-flag/feature-flag.module';import { UsageModule } from 'src/engine/core-modules/usage/usage.module';@@ -21,6 +23,10 @@ import { WorkspaceEventEmitterModule } from 'src/engine/workspace-event-emitter/import { UsageLimitModule } from 'src/engine/core-modules/usage-limit/usage-limit.module';import { CampaignTrackingController } from 'src/modules/emailing/controllers/campaign-tracking.controller';import { UnsubscribeController } from 'src/modules/emailing/controllers/unsubscribe.controller';+import { RecordCampaignEngagementJob } from 'src/modules/emailing/jobs/record-campaign-engagement.job';+import { CampaignEngagementCaptureService } from 'src/modules/emailing/services/campaign-engagement-capture.service';+import { CampaignEngagementEventService } from 'src/modules/emailing/services/campaign-engagement-event.service';+import { CampaignEngagementRecordingService } from 'src/modules/emailing/services/campaign-engagement-recording.service';import { CampaignTrackingContentService } from 'src/modules/emailing/services/campaign-tracking-content.service';import { EmailingOngoingStaleCronCommand } from 'src/modules/emailing/crons/commands/emailing-ongoing-stale.cron.command';import { EmailingOngoingStaleCronJob } from 'src/modules/emailing/crons/jobs/emailing-ongoing-stale.cron.job';@@ -66,6 +72,8 @@ import { SaveCampaignTool } from 'src/modules/emailing/tools/save-campaign-tool'WorkspaceCacheModule,WorkspaceManyOrAllFlatEntityMapsCacheModule,UsageLimitModule,+ ClickHouseModule,+ MetricsModule,ShortLinkModule,TypeOrmModule.forFeature([MessageChannelEntity,@@ -101,6 +109,10 @@ import { SaveCampaignTool } from 'src/modules/emailing/tools/save-campaign-tool'UnsubscribeTopicResolver,provideWorkspaceScopedRepository(EmailingDomainEntity),CampaignTrackingContentService,+ CampaignEngagementCaptureService,+ CampaignEngagementRecordingService,+ CampaignEngagementEventService,+ RecordCampaignEngagementJob,provideWorkspaceScopedRepository(UnsubscribeTopicEntity),EmailingOngoingStaleCronCommand,EmailingOngoingStaleCronJob,diff --git a/packages/twenty-server/src/modules/emailing/jobs/record-campaign-engagement.job.ts b/packages/twenty-server/src/modules/emailing/jobs/record-campaign-engagement.job.tsnew file mode 100644index 00000000000..d4428373a11--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/jobs/record-campaign-engagement.job.ts@@ -0,0 +1,18 @@+import { RECORD_CAMPAIGN_ENGAGEMENT_JOB } from 'src/engine/core-modules/emailing-domain/constants/record-campaign-engagement-job.constant';+import { Process } from 'src/engine/core-modules/message-queue/decorators/process.decorator';+import { Processor } from 'src/engine/core-modules/message-queue/decorators/processor.decorator';+import { MessageQueue } from 'src/engine/core-modules/message-queue/message-queue.constants';+import { CampaignEngagementRecordingService } from 'src/modules/emailing/services/campaign-engagement-recording.service';+import { type CampaignEngagementObservation } from 'src/modules/emailing/types/campaign-engagement-observation.type';++@Processor(MessageQueue.campaignEngagementQueue)+export class RecordCampaignEngagementJob {+ constructor(+ private readonly campaignEngagementRecordingService: CampaignEngagementRecordingService,+ ) {}++ @Process(RECORD_CAMPAIGN_ENGAGEMENT_JOB)+ async handle(observation: CampaignEngagementObservation): Promise<void> {+ await this.campaignEngagementRecordingService.record(observation);+ }+}diff --git a/packages/twenty-server/src/modules/emailing/services/campaign-engagement-capture.service.ts b/packages/twenty-server/src/modules/emailing/services/campaign-engagement-capture.service.tsnew file mode 100644index 00000000000..e8147deec70--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/services/campaign-engagement-capture.service.ts@@ -0,0 +1,128 @@+import { Injectable, Logger } from '@nestjs/common';++import { v4 } from 'uuid';++import { RECORD_CAMPAIGN_ENGAGEMENT_JOB } from 'src/engine/core-modules/emailing-domain/constants/record-campaign-engagement-job.constant';+import { type CampaignTrackingTokenPayload } from 'src/engine/core-modules/emailing-domain/types/campaign-tracking-token-payload.type';+import { InjectMessageQueue } from 'src/engine/core-modules/message-queue/decorators/message-queue.decorator';+import { MessageQueue } from 'src/engine/core-modules/message-queue/message-queue.constants';+import { MessageQueueService } from 'src/engine/core-modules/message-queue/services/message-queue.service';+import { MetricsService } from 'src/engine/core-modules/metrics/metrics.service';+import { MetricsKeys } from 'src/engine/core-modules/metrics/types/metrics-keys.type';+import { ThrottlerException } from 'src/engine/core-modules/throttler/throttler.exception';+import { ThrottlerService } from 'src/engine/core-modules/throttler/throttler.service';+import { CampaignEngagementEventService } from 'src/modules/emailing/services/campaign-engagement-event.service';+import { type CampaignEngagementObservation } from 'src/modules/emailing/types/campaign-engagement-observation.type';+import { getCampaignEngagementThrottleLimits } from 'src/modules/emailing/utils/get-campaign-engagement-throttle-limits.util';++const RESPONSE_RELEASE_BUDGET_MS = 100;++@Injectable()+export class CampaignEngagementCaptureService {+ private readonly logger = new Logger(CampaignEngagementCaptureService.name);++ constructor(+ @InjectMessageQueue(MessageQueue.campaignEngagementQueue)+ private readonly messageQueueService: MessageQueueService,+ private readonly throttlerService: ThrottlerService,+ private readonly metricsService: MetricsService,+ private readonly campaignEngagementEventService: CampaignEngagementEventService,+ ) {}++ async capture({+ payload,+ userAgent,+ requesterIp,+ }: {+ payload: CampaignTrackingTokenPayload;+ userAgent: string | null;+ requesterIp: string | null;+ }): Promise<void> {+ if (!this.campaignEngagementEventService.isAvailable()) {+ return;+ }++ const observation: CampaignEngagementObservation = {+ eventId: v4(),+ occurredAt: new Date().toISOString(),+ workspaceId: payload.workspaceId,+ deliveryId: payload.deliveryId,+ shortLinkId: payload.shortLinkId,+ userAgent,+ };++ await this.releaseResponseAfterBudget(+ this.throttleAndEnqueue({ payload, observation, requesterIp }),+ );+ }++ private async throttleAndEnqueue({+ payload,+ observation,+ requesterIp,+ }: {+ payload: CampaignTrackingTokenPayload;+ observation: CampaignEngagementObservation;+ requesterIp: string | null;+ }): Promise<void> {+ try {+ for (const limit of getCampaignEngagementThrottleLimits({+ payload,+ requesterIp,+ })) {+ await this.throttlerService.tokenBucketThrottleOrThrow(+ limit.key,+ 1,+ limit.maxRequests,+ limit.windowMs,+ );+ }++ await this.messageQueueService.add<CampaignEngagementObservation>(+ RECORD_CAMPAIGN_ENGAGEMENT_JOB,+ observation,+ {+ retryLimit: 14,+ backoff: {+ strategy: 'exponential',+ initialDelayMilliseconds: 5_000,+ jitter: 0.5,+ },+ },+ );+ } catch (error) {+ const isThrottled = error instanceof ThrottlerException;++ this.metricsService.incrementCounterBy({+ key: isThrottled+ ? MetricsKeys.CampaignEngagementCaptureThrottled+ : MetricsKeys.CampaignEngagementCaptureFailed,+ amount: 1,+ });++ if (isThrottled) {+ return;+ }++ this.logger.warn(+ `Dropped click event for delivery ${observation.deliveryId}: ${error}`,+ );+ }+ }++ private async releaseResponseAfterBudget(+ enqueueing: Promise<void>,+ ): Promise<void> {+ let releaseTimer: NodeJS.Timeout | undefined;++ const release = new Promise<void>((resolve) => {+ releaseTimer = setTimeout(resolve, RESPONSE_RELEASE_BUDGET_MS);+ });++ try {+ await Promise.race([enqueueing, release]);+ } finally {+ clearTimeout(releaseTimer);+ }+ }+}diff --git a/packages/twenty-server/src/modules/emailing/services/campaign-engagement-event.service.ts b/packages/twenty-server/src/modules/emailing/services/campaign-engagement-event.service.tsnew file mode 100644index 00000000000..69748ea3cdf--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/services/campaign-engagement-event.service.ts@@ -0,0 +1,42 @@+import { Injectable } from '@nestjs/common';++import { isDefined } from 'twenty-shared/utils';++import { ClickHouseService } from 'src/database/clickhouse/clickhouse.service';+import { formatDateTimeForClickHouse } from 'src/database/clickhouse/utils/format-date-time-for-clickhouse.util';+import { CAMPAIGN_ENGAGEMENT_INSERT_BUSY_TIMEOUT_MS } from 'src/modules/emailing/constants/campaign-engagement-insert-busy-timeout-ms.constant';+import { SHORT_LINK_CLICK_TABLE } from 'src/modules/emailing/constants/short-link-click-table.constant';+import { type CampaignEngagementActivityClass } from 'src/modules/emailing/types/campaign-engagement-activity-class.type';++type ShortLinkClickEvent = {+ workspaceId: string;+ messageCampaignId: string;+ shortLinkId: string;+ deliveryId: string;+ eventId: string;+ occurredAt: string;+ activityClass: CampaignEngagementActivityClass;+};++@Injectable()+export class CampaignEngagementEventService {+ constructor(private readonly clickHouseService: ClickHouseService) {}++ isAvailable(): boolean {+ return isDefined(this.clickHouseService.getMainClient());+ }++ async insertClickOrThrow(event: ShortLinkClickEvent): Promise<void> {+ const result = await this.clickHouseService.insert(+ SHORT_LINK_CLICK_TABLE,+ [{ ...event, occurredAt: formatDateTimeForClickHouse(event.occurredAt) }],+ {+ asyncInsertBusyTimeoutMaxMs: CAMPAIGN_ENGAGEMENT_INSERT_BUSY_TIMEOUT_MS,+ },+ );++ if (!result.success) {+ throw result.error;+ }+ }+}diff --git a/packages/twenty-server/src/modules/emailing/services/campaign-engagement-recording.service.ts b/packages/twenty-server/src/modules/emailing/services/campaign-engagement-recording.service.tsnew file mode 100644index 00000000000..b9b05648341--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/services/campaign-engagement-recording.service.ts@@ -0,0 +1,55 @@+import { Injectable } from '@nestjs/common';+import { InjectRepository } from '@nestjs/typeorm';++import { Repository } from 'typeorm';+import { isDefined } from 'twenty-shared/utils';++import { WorkspaceEntity } from 'src/engine/core-modules/workspace/workspace.entity';+import { buildSystemAuthContext } from 'src/engine/twenty-orm/utils/build-system-auth-context.util';+import { WorkspaceOrmManager } from 'src/engine/twenty-orm/workspace-orm.manager';+import { CampaignEngagementEventService } from 'src/modules/emailing/services/campaign-engagement-event.service';+import { CampaignDeliveryWorkspaceEntity } from 'src/modules/emailing/standard-objects/campaign-delivery.workspace-entity';+import { type CampaignEngagementObservation } from 'src/modules/emailing/types/campaign-engagement-observation.type';+import { buildCampaignClickEvent } from 'src/modules/emailing/utils/build-campaign-click-event.util';++@Injectable()+export class CampaignEngagementRecordingService {+ constructor(+ private readonly workspaceOrmManager: WorkspaceOrmManager,+ @InjectRepository(WorkspaceEntity)+ private readonly workspaceRepository: Repository<WorkspaceEntity>,+ private readonly campaignEngagementEventService: CampaignEngagementEventService,+ ) {}++ async record(observation: CampaignEngagementObservation): Promise<void> {+ const delivery = await this.workspaceOrmManager.executeInWorkspaceContext(+ () =>+ this.workspaceOrmManager+ .getRepository(CampaignDeliveryWorkspaceEntity, {+ shouldBypassPermissionChecks: true,+ })+ .findOneBy({ id: observation.deliveryId }),+ buildSystemAuthContext(observation.workspaceId),+ );++ if (!isDefined(delivery)) {+ return;+ }++ const workspace = await this.workspaceRepository.findOneBy({+ id: observation.workspaceId,+ });++ const clickEvent = buildCampaignClickEvent({+ delivery,+ workspace,+ observation,+ });++ if (!isDefined(clickEvent)) {+ return;+ }++ await this.campaignEngagementEventService.insertClickOrThrow(clickEvent);+ }+}diff --git a/packages/twenty-server/src/modules/emailing/services/campaign-tracking-content.service.ts b/packages/twenty-server/src/modules/emailing/services/campaign-tracking-content.service.tsindex 1c9ad084f6f..b7df7e5d75c 100644--- a/packages/twenty-server/src/modules/emailing/services/campaign-tracking-content.service.ts+++ b/packages/twenty-server/src/modules/emailing/services/campaign-tracking-content.service.ts@@ -25,6 +25,7 @@ import { WorkspaceScopedRepository } from 'src/engine/twenty-orm/workspace-scopeimport { TRACKABLE_URL_PATTERN } from 'src/modules/emailing/constants/trackable-url-pattern.constant';import { CAMPAIGN_BATCH_VARIABLE_TAG_PATTERN } from 'src/modules/emailing/constants/campaign-batch-variable-tag-pattern.constant';import { CAMPAIGN_TRACKING_TAG_PREFIX_BY_MESSAGE_PART } from 'src/modules/emailing/constants/campaign-tracking-tag-prefix-by-message-part.constant';+import { CampaignEngagementEventService } from 'src/modules/emailing/services/campaign-engagement-event.service';import { collectTrackableLinkUrls } from 'src/modules/emailing/utils/collect-trackable-link-urls.util';import { replaceTrackableLinkUrls } from 'src/modules/emailing/utils/replace-trackable-link-urls.util';@@ -59,6 +60,7 @@ export class CampaignTrackingContentService {private readonly workspaceRepository: Repository<WorkspaceEntity>,private readonly shortLinkService: ShortLinkService,private readonly twentyConfigService: TwentyConfigService,+ private readonly campaignEngagementEventService: CampaignEngagementEventService,) {}async prepareBatch({@@ -85,7 +87,7 @@ export class CampaignTrackingContentService {return untracked;}- if (!isNonEmptyString(this.twentyConfigService.get('CLICKHOUSE_URL'))) {+ if (!this.campaignEngagementEventService.isAvailable()) {return untracked;}diff --git a/packages/twenty-server/src/modules/emailing/types/campaign-engagement-activity-class.type.ts b/packages/twenty-server/src/modules/emailing/types/campaign-engagement-activity-class.type.tsnew file mode 100644index 00000000000..a310e9ca44d--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/types/campaign-engagement-activity-class.type.ts@@ -0,0 +1,4 @@+export type CampaignEngagementActivityClass =+ | 'UNCLASSIFIED'+ | 'SUSPECTED_AUTOMATION'+ | 'PRIVACY_PROXY';diff --git a/packages/twenty-server/src/modules/emailing/types/campaign-engagement-observation.type.ts b/packages/twenty-server/src/modules/emailing/types/campaign-engagement-observation.type.tsnew file mode 100644index 00000000000..5a7c6bbd396--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/types/campaign-engagement-observation.type.ts@@ -0,0 +1,8 @@+export type CampaignEngagementObservation = {+ eventId: string;+ occurredAt: string;+ workspaceId: string;+ deliveryId: string;+ shortLinkId: string;+ userAgent: string | null;+};diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-click-event.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-click-event.util.spec.tsnew file mode 100644index 00000000000..ad65363685d--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/build-campaign-click-event.util.spec.ts@@ -0,0 +1,53 @@+import { type CampaignEngagementObservation } from 'src/modules/emailing/types/campaign-engagement-observation.type';+import { buildCampaignClickEvent } from 'src/modules/emailing/utils/build-campaign-click-event.util';++const WORKSPACE_ID = '4fe04fe4-dcd6-4123-bf05-ec8f989cda29';+const DELIVERY = {+ id: '7b1b78df-f57c-4367-88ba-31b41e38ab91',+ campaignId: '81110623-55f6-4dae-becd-1944d4d88078',+};+const OBSERVATION: CampaignEngagementObservation = {+ eventId: 'b55db0be-cd10-4802-b332-0cb3e81a02c8',+ occurredAt: '2026-09-23T12:00:00.000Z',+ workspaceId: WORKSPACE_ID,+ deliveryId: DELIVERY.id,+ shortLinkId: 'e589543a-287d-4a83-ae31-55f9ef6c1cb3',+ userAgent: null,+};++describe('buildCampaignClickEvent', () => {+ it('does not create an event when tracking is disabled', () => {+ expect(+ buildCampaignClickEvent({+ delivery: DELIVERY,+ workspace: { isCampaignClickTrackingEnabled: false },+ observation: OBSERVATION,+ }),+ ).toBeNull();+ });++ it('takes the workspace from the observation and preserves the observation event ID', () => {+ const event = buildCampaignClickEvent({+ delivery: DELIVERY,+ workspace: { isCampaignClickTrackingEnabled: true },+ observation: OBSERVATION,+ });++ expect(event).toEqual({+ workspaceId: WORKSPACE_ID,+ messageCampaignId: DELIVERY.campaignId,+ deliveryId: DELIVERY.id,+ shortLinkId: OBSERVATION.shortLinkId,+ eventId: OBSERVATION.eventId,+ occurredAt: OBSERVATION.occurredAt,+ activityClass: 'UNCLASSIFIED',+ });+ expect(+ buildCampaignClickEvent({+ delivery: DELIVERY,+ workspace: { isCampaignClickTrackingEnabled: true },+ observation: OBSERVATION,+ })?.eventId,+ ).toBe(OBSERVATION.eventId);+ });+});diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/classify-engagement-user-agent.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/classify-engagement-user-agent.util.spec.tsnew file mode 100644index 00000000000..49010baa7f8--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/classify-engagement-user-agent.util.spec.ts@@ -0,0 +1,27 @@+import { classifyEngagementUserAgent } from 'src/modules/emailing/utils/classify-engagement-user-agent.util';++describe('classifyEngagementUserAgent', () => {+ it('treats the Apple Mail privacy proxy as a proxy, not a person', () => {+ expect(classifyEngagementUserAgent('Mozilla/5.0')).toBe('PRIVACY_PROXY');+ });++ it('flags a security scanner as automation', () => {+ expect(+ classifyEngagementUserAgent(+ 'Mozilla/5.0 (compatible; Mimecast Link Scanner)',+ ),+ ).toBe('SUSPECTED_AUTOMATION');+ });++ it('leaves a desktop mail client unclassified', () => {+ expect(+ classifyEngagementUserAgent(+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Safari/605.1.15',+ ),+ ).toBe('UNCLASSIFIED');+ });++ it('handles a missing user agent', () => {+ expect(classifyEngagementUserAgent(null)).toBe('UNCLASSIFIED');+ });+});diff --git a/packages/twenty-server/src/modules/emailing/utils/__tests__/get-campaign-engagement-throttle-limits.util.spec.ts b/packages/twenty-server/src/modules/emailing/utils/__tests__/get-campaign-engagement-throttle-limits.util.spec.tsnew file mode 100644index 00000000000..75efe60d0ba--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/utils/__tests__/get-campaign-engagement-throttle-limits.util.spec.ts@@ -0,0 +1,45 @@+import { type CampaignTrackingTokenPayload } from 'src/engine/core-modules/emailing-domain/types/campaign-tracking-token-payload.type';+import { getCampaignEngagementThrottleLimits } from 'src/modules/emailing/utils/get-campaign-engagement-throttle-limits.util';++const PAYLOAD: CampaignTrackingTokenPayload = {+ workspaceId: '4fe04fe4-dcd6-4123-bf05-ec8f989cda29',+ deliveryId: '7b1b78df-f57c-4367-88ba-31b41e38ab91',+ shortLinkId: 'e589543a-287d-4a83-ae31-55f9ef6c1cb3',+};++describe('getCampaignEngagementThrottleLimits', () => {+ it('only limits the delivery-link when the requester IP is unavailable', () => {+ expect(+ getCampaignEngagementThrottleLimits({+ payload: PAYLOAD,+ requesterIp: null,+ }),+ ).toEqual([+ {+ key: `campaign-engagement:${PAYLOAD.deliveryId}:${PAYLOAD.shortLinkId}`,+ maxRequests: 60,+ windowMs: 60_000,+ },+ ]);+ });++ it('limits both requester and delivery-link when the IP is known', () => {+ expect(+ getCampaignEngagementThrottleLimits({+ payload: PAYLOAD,+ requesterIp: '192.0.2.1',+ }),+ ).toEqual([+ {+ key: 'campaign-engagement:requester:192.0.2.1',+ maxRequests: 600,+ windowMs: 60_000,+ },+ {+ key: `campaign-engagement:${PAYLOAD.deliveryId}:${PAYLOAD.shortLinkId}`,+ maxRequests: 60,+ windowMs: 60_000,+ },+ ]);+ });+});diff --git a/packages/twenty-server/src/modules/emailing/utils/build-campaign-click-event.util.ts b/packages/twenty-server/src/modules/emailing/utils/build-campaign-click-event.util.tsnew file mode 100644index 00000000000..7d42cc453e4--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/utils/build-campaign-click-event.util.ts@@ -0,0 +1,31 @@+import { type WorkspaceEntity } from 'src/engine/core-modules/workspace/workspace.entity';+import { type CampaignEngagementEventService } from 'src/modules/emailing/services/campaign-engagement-event.service';+import { type CampaignDeliveryWorkspaceEntity } from 'src/modules/emailing/standard-objects/campaign-delivery.workspace-entity';+import { type CampaignEngagementObservation } from 'src/modules/emailing/types/campaign-engagement-observation.type';+import { classifyEngagementUserAgent } from 'src/modules/emailing/utils/classify-engagement-user-agent.util';++export const buildCampaignClickEvent = ({+ delivery,+ workspace,+ observation,+}: {+ delivery: Pick<CampaignDeliveryWorkspaceEntity, 'id' | 'campaignId'>;+ workspace: Pick<WorkspaceEntity, 'isCampaignClickTrackingEnabled'> | null;+ observation: CampaignEngagementObservation;+}):+ | Parameters<CampaignEngagementEventService['insertClickOrThrow']>[0]+ | null => {+ if (!workspace?.isCampaignClickTrackingEnabled) {+ return null;+ }++ return {+ workspaceId: observation.workspaceId,+ messageCampaignId: delivery.campaignId,+ shortLinkId: observation.shortLinkId,+ deliveryId: delivery.id,+ eventId: observation.eventId,+ occurredAt: observation.occurredAt,+ activityClass: classifyEngagementUserAgent(observation.userAgent),+ };+};diff --git a/packages/twenty-server/src/modules/emailing/utils/classify-engagement-user-agent.util.ts b/packages/twenty-server/src/modules/emailing/utils/classify-engagement-user-agent.util.tsnew file mode 100644index 00000000000..706b52c36ad--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/utils/classify-engagement-user-agent.util.ts@@ -0,0 +1,38 @@+import { isNonEmptyString } from '@sniptt/guards';++import { type CampaignEngagementActivityClass } from 'src/modules/emailing/types/campaign-engagement-activity-class.type';++const PRIVACY_PROXY_PATTERNS = [+ /GoogleImageProxy/i,+ /YahooMailProxy/i,+ /^Mozilla\/5\.0$/,+];++const AUTOMATION_PATTERNS = [+ /mimecast/i,+ /proofpoint/i,+ /barracuda/i,+ /symantec|norton/i,+ /Slackbot|Slack-ImgProxy/i,+ /Twitterbot|facebookexternalhit|LinkedInBot|WhatsApp|Discordbot|TelegramBot|Applebot/i,+ /curl|wget|python-requests|Go-http-client|okhttp|HeadlessChrome|PhantomJS|Java\//i,+ /bot|crawler|spider|scanner/i,+];++export const classifyEngagementUserAgent = (+ userAgent: string | null,+): CampaignEngagementActivityClass => {+ if (!isNonEmptyString(userAgent)) {+ return 'UNCLASSIFIED';+ }++ if (PRIVACY_PROXY_PATTERNS.some((pattern) => pattern.test(userAgent))) {+ return 'PRIVACY_PROXY';+ }++ if (AUTOMATION_PATTERNS.some((pattern) => pattern.test(userAgent))) {+ return 'SUSPECTED_AUTOMATION';+ }++ return 'UNCLASSIFIED';+};diff --git a/packages/twenty-server/src/modules/emailing/utils/get-campaign-engagement-throttle-limits.util.ts b/packages/twenty-server/src/modules/emailing/utils/get-campaign-engagement-throttle-limits.util.tsnew file mode 100644index 00000000000..aeb3d801130--- /dev/null+++ b/packages/twenty-server/src/modules/emailing/utils/get-campaign-engagement-throttle-limits.util.ts@@ -0,0 +1,32 @@+import { isNonEmptyString } from '@sniptt/guards';++import { type CampaignTrackingTokenPayload } from 'src/engine/core-modules/emailing-domain/types/campaign-tracking-token-payload.type';+import { CAMPAIGN_ENGAGEMENT_CAPTURE_RATE_LIMIT_PER_LINK } from 'src/modules/emailing/constants/campaign-engagement-capture-rate-limit-per-link.constant';+import { CAMPAIGN_ENGAGEMENT_CAPTURE_RATE_LIMIT_PER_REQUESTER } from 'src/modules/emailing/constants/campaign-engagement-capture-rate-limit-per-requester.constant';++type CampaignEngagementThrottleLimit = {+ key: string;+ maxRequests: number;+ windowMs: number;+};++export const getCampaignEngagementThrottleLimits = ({+ payload,+ requesterIp,+}: {+ payload: CampaignTrackingTokenPayload;+ requesterIp: string | null;+}): CampaignEngagementThrottleLimit[] => [+ ...(isNonEmptyString(requesterIp)+ ? [+ {+ key: `campaign-engagement:requester:${requesterIp}`,+ ...CAMPAIGN_ENGAGEMENT_CAPTURE_RATE_LIMIT_PER_REQUESTER,+ },+ ]+ : []),+ {+ key: `campaign-engagement:${payload.deliveryId}:${payload.shortLinkId}`,+ ...CAMPAIGN_ENGAGEMENT_CAPTURE_RATE_LIMIT_PER_LINK,+ },+];