Skip to content

The open alternative to Salesforce, designed for AI.

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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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-scope
import { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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,
+ },
+];