Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(workflows): carry the sending email in unsubscribe link tokens (#115831)

Daniel Marchuk3a8168e47883
diff --git a/nodejs/src/cdp/cdp-api.ts b/nodejs/src/cdp/cdp-api.ts
index 649511b14f71..f9e7bb144bd0 100644
--- a/nodejs/src/cdp/cdp-api.ts
+++ b/nodejs/src/cdp/cdp-api.ts
@@ -1879,6 +1879,8 @@ export class CdpApi {
valid: result.valid,
team_id: result.team_id,
identifier: result.identifier,
+ app_source_id: result.app_source_id,
+ instance_id: result.instance_id,
})
} catch (error) {
logger.error('[CdpApi] Error validating preferences token', error)
diff --git a/nodejs/src/cdp/services/hog-executor-async.service.ts b/nodejs/src/cdp/services/hog-executor-async.service.ts
index a59cb6f96fd1..2c8878bc4bc2 100644
--- a/nodejs/src/cdp/services/hog-executor-async.service.ts
+++ b/nodejs/src/cdp/services/hog-executor-async.service.ts
@@ -29,7 +29,7 @@ import { HogInputsService } from './hog-inputs.service'
import { EMAIL_QUEUE_PRIORITY, getEmailQueuePriorityClass } from './messaging/email-priority'
import { EmailService } from './messaging/email.service'
import { PushNotificationService } from './messaging/push-notification.service'
-import { RecipientTokensService } from './messaging/recipient-tokens.service'
+import { RecipientTokensService, preferencesTokenSourceForInvocation } from './messaging/recipient-tokens.service'
import {
SELF_LOOP_MAX_DEPTH,
getSelfLoopDepth,
@@ -245,10 +245,10 @@ export class HogExecutorAsyncService {
functions: {
generateMessagingPreferencesUrl: (identifier): string | null => {
return identifier && typeof identifier === 'string'
- ? this.deps.recipientTokensService.generatePreferencesUrl({
- team_id: invocation.teamId,
- identifier,
- })
+ ? this.deps.recipientTokensService.generatePreferencesUrl(
+ { team_id: invocation.teamId, identifier },
+ preferencesTokenSourceForInvocation(invocation)
+ )
: null
},
...options.functions,
diff --git a/nodejs/src/cdp/services/hog-executor.service.ts b/nodejs/src/cdp/services/hog-executor.service.ts
index d2fda75473c2..7b2a33a6c8ba 100644
--- a/nodejs/src/cdp/services/hog-executor.service.ts
+++ b/nodejs/src/cdp/services/hog-executor.service.ts
@@ -24,6 +24,7 @@ import { execHog } from '../utils/hog-exec'
import { convertToHogFunctionFilterGlobal, filterFunctionInstrumented } from '../utils/hog-function-filtering'
import { createInvocationResult } from '../utils/invocation-utils'
import { HogInputsService } from './hog-inputs.service'
+import type { PreferencesTokenSource } from './messaging/recipient-tokens.service'
export interface HogExecutorConfig {
/** Hard wall-clock limit for one Hog program. The VM aborts the invocation once it elapses. */
@@ -100,9 +101,15 @@ export class HogExecutorService {
async buildInputsWithGlobals(
hogFunction: HogFunctionType,
globals: HogFunctionInvocationGlobals,
- additionalInputs?: Record<string, any>
+ additionalInputs?: Record<string, any>,
+ preferencesTokenSource?: PreferencesTokenSource
): Promise<HogFunctionInvocationGlobalsWithInputs> {
- return this.hogInputsService.buildInputsWithGlobals(hogFunction, globals, additionalInputs)
+ return this.hogInputsService.buildInputsWithGlobals(
+ hogFunction,
+ globals,
+ additionalInputs,
+ preferencesTokenSource
+ )
}
/**
diff --git a/nodejs/src/cdp/services/hog-inputs.service.test.ts b/nodejs/src/cdp/services/hog-inputs.service.test.ts
index eda5d61c29c6..3b400c371700 100644
--- a/nodejs/src/cdp/services/hog-inputs.service.test.ts
+++ b/nodejs/src/cdp/services/hog-inputs.service.test.ts
@@ -362,7 +362,10 @@ describe('Hog Inputs', () => {
expect(inputs.connection).toBeNull()
})
- it('should add unsubscribe url if email input is present', async () => {
+ it.each([
+ { name: 'a hog function', source: undefined },
+ { name: 'a workflow email step', source: { appSourceId: 'flow-1', instanceId: 'action-1' } },
+ ])('should add unsubscribe url if email input is present for $name', async ({ source }) => {
hogFunction.inputs = {
email: {
templating: 'liquid',
@@ -375,11 +378,11 @@ describe('Hog Inputs', () => {
hogFunction.inputs_schema = [{ key: 'email', type: 'native_email', required: true, templating: true }]
- const inputs = await hogInputsService.buildInputs(hogFunction, globals)
+ const inputs = await hogInputsService.buildInputs(hogFunction, globals, undefined, source)
expect(inputs.email.to.email).toEqual('[email protected]')
const recipient = { team_id: team.id, identifier: '[email protected]' }
expect(inputs.email.html).toEqual(
- `<div>Manage subscription preferences here <a href="${recipientTokensService.generatePreferencesUrl(recipient)}">here</a>Or, click <a href="${recipientTokensService.generateOneClickUnsubscribeUrl(recipient)}">here</a> to immediately unsubscribe from all marketing emails</div>`
+ `<div>Manage subscription preferences here <a href="${recipientTokensService.generatePreferencesUrl(recipient, source)}">here</a>Or, click <a href="${recipientTokensService.generateOneClickUnsubscribeUrl(recipient, source)}">here</a> to immediately unsubscribe from all marketing emails</div>`
)
})
diff --git a/nodejs/src/cdp/services/hog-inputs.service.ts b/nodejs/src/cdp/services/hog-inputs.service.ts
index 5d9867675933..e227bb1cc736 100644
--- a/nodejs/src/cdp/services/hog-inputs.service.ts
+++ b/nodejs/src/cdp/services/hog-inputs.service.ts
@@ -11,7 +11,7 @@ import { execHog } from '../utils/hog-exec'
import { LiquidRenderBudget, LiquidRenderer } from '../utils/liquid'
import { NATIVE_PUSH_TEMPLATE_ID, getDevicePushSubscriptionToken } from '../utils/push-subscription-utils'
import { IntegrationManagerService } from './managers/integration-manager.service'
-import { RecipientTokensService } from './messaging/recipient-tokens.service'
+import { PreferencesTokenSource, RecipientTokensService } from './messaging/recipient-tokens.service'
export const EXTEND_OBJECT_KEY = '$$_extend_object'
@@ -47,7 +47,8 @@ export class HogInputsService {
public async buildInputs(
hogFunction: HogFunctionType,
globals: HogFunctionInvocationGlobals,
- additionalInputs?: Record<string, any>
+ additionalInputs?: Record<string, any>,
+ preferencesTokenSource?: PreferencesTokenSource
): Promise<Record<string, any>> {
// TODO: Load the values from the integrationManager
const newGlobals: HogFunctionInvocationGlobalsWithInputs = {
@@ -117,14 +118,15 @@ export class HogInputsService {
// If we have an email value then we template it out to get the email address
const emailValue = await _formatInput(emailInput, emailInputSchema.key)
if (emailValue?.to?.email) {
- newGlobals.unsubscribe_url = this.recipientTokensService.generatePreferencesUrl({
- team_id: hogFunction.team_id,
- identifier: emailValue.to.email,
- })
- newGlobals.unsubscribe_url_one_click = this.recipientTokensService.generateOneClickUnsubscribeUrl({
- team_id: hogFunction.team_id,
- identifier: emailValue.to.email,
- })
+ const recipient = { team_id: hogFunction.team_id, identifier: emailValue.to.email }
+ newGlobals.unsubscribe_url = this.recipientTokensService.generatePreferencesUrl(
+ recipient,
+ preferencesTokenSource
+ )
+ newGlobals.unsubscribe_url_one_click = this.recipientTokensService.generateOneClickUnsubscribeUrl(
+ recipient,
+ preferencesTokenSource
+ )
}
}
@@ -155,11 +157,12 @@ export class HogInputsService {
public async buildInputsWithGlobals(
hogFunction: HogFunctionType,
globals: HogFunctionInvocationGlobals,
- additionalInputs?: Record<string, any>
+ additionalInputs?: Record<string, any>,
+ preferencesTokenSource?: PreferencesTokenSource
): Promise<HogFunctionInvocationGlobalsWithInputs> {
return {
...globals,
- inputs: await this.buildInputs(hogFunction, globals, additionalInputs),
+ inputs: await this.buildInputs(hogFunction, globals, additionalInputs, preferencesTokenSource),
}
}
diff --git a/nodejs/src/cdp/services/hogflows/hogflow-functions.service.ts b/nodejs/src/cdp/services/hogflows/hogflow-functions.service.ts
index 2cdd30cf8ed6..0272e55af062 100644
--- a/nodejs/src/cdp/services/hogflows/hogflow-functions.service.ts
+++ b/nodejs/src/cdp/services/hogflows/hogflow-functions.service.ts
@@ -127,7 +127,12 @@ export class HogFlowFunctionsService {
state: invocation.state.currentAction?.hogFunctionState ?? {
globals: await this.hogFunctionExecutor.hogExecutor.buildInputsWithGlobals(
hogFunction,
- globalsWithSource
+ globalsWithSource,
+ undefined,
+ {
+ appSourceId: invocation.parentRunId ?? invocation.hogFlow.id,
+ instanceId: invocation.state.currentAction?.id,
+ }
),
timings: [],
attempts: 0,
diff --git a/nodejs/src/cdp/services/messaging/email.service.test.ts b/nodejs/src/cdp/services/messaging/email.service.test.ts
index 7c3cd05338a0..ff3b05045580 100644
--- a/nodejs/src/cdp/services/messaging/email.service.test.ts
+++ b/nodejs/src/cdp/services/messaging/email.service.test.ts
@@ -32,6 +32,7 @@ import {
import { MailDevAPI } from './helpers/maildev'
import { EmailTrackingCodeSigner } from './helpers/tracking-code'
import { MessageAssetsService } from './message-assets.service'
+import { RecipientTokensService } from './recipient-tokens.service'
class ThrottlingException extends Error {
constructor(message: string) {
@@ -1514,20 +1515,53 @@ describe('EmailService', () => {
expect(sentCommand.input.Content.Simple.Body.Html.Data).toMatch(expected)
})
- it('should include unsubscribe headers for non-transactional emails', async () => {
- sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
- invocation.hogFunction.metadata = { message_category_type: 'marketing' }
- const result = await service.executeSendEmail(invocation)
- expect(result.error).toBeUndefined()
- const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
- const headers = sentCommand.input.Content.Simple.Headers
- expect(headers).toEqual(
- expect.arrayContaining([
- expect.objectContaining({ Name: 'List-Unsubscribe' }),
- expect.objectContaining({ Name: 'List-Unsubscribe-Post' }),
- ])
- )
- })
+ it.each([
+ { name: 'a hog function send', fromHogFlow: false, parentRunId: null, expectedSource: {} },
+ {
+ name: 'a workflow send',
+ fromHogFlow: true,
+ parentRunId: null,
+ expectedSource: { app_source_id: 'function-1', instance_id: 'action-email' },
+ },
+ {
+ name: 'a broadcast send',
+ fromHogFlow: true,
+ parentRunId: 'batch-run-1',
+ expectedSource: { app_source_id: 'batch-run-1', instance_id: 'action-email' },
+ },
+ ])(
+ 'includes unsubscribe headers for $name, attributed to the email it came from',
+ async ({ fromHogFlow, parentRunId, expectedSource }) => {
+ sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
+ invocation.hogFunction.metadata = { message_category_type: 'marketing' }
+ if (fromHogFlow) {
+ Object.assign(invocation, { hogFlow: { id: 'function-1', version: 1 }, parentRunId })
+ invocation.state.actionId = 'action-email'
+ }
+ const result = await service.executeSendEmail(invocation)
+ expect(result.error).toBeUndefined()
+ const sentCommand = sendEmailSpy.mock.calls[0][0] as { input: any }
+ const headers = sentCommand.input.Content.Simple.Headers
+ expect(headers).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ Name: 'List-Unsubscribe' }),
+ expect.objectContaining({ Name: 'List-Unsubscribe-Post' }),
+ ])
+ )
+ const unsubscribeUrl = headers.find((h: { Name: string }) => h.Name === 'List-Unsubscribe').Value
+ const token = unsubscribeUrl.match(/messaging-preferences\/([^/]+)\//)[1]
+ const validated = new RecipientTokensService(
+ hub.ENCRYPTION_SALT_KEYS,
+ hub.SITE_URL
+ ).validatePreferencesToken(token)
+ expect(validated).toEqual({
+ valid: true,
+ team_id: team.id,
+ identifier: '[email protected]',
+ ...expectedSource,
+ })
+ }
+ )
it('should not include unsubscribe headers for transactional emails (but tracking-code header is still set)', async () => {
sendEmailSpy.mockResolvedValue({ MessageId: 'test-message-id' })
diff --git a/nodejs/src/cdp/services/messaging/email.service.ts b/nodejs/src/cdp/services/messaging/email.service.ts
index ff83d8746de4..a918740f840a 100644
--- a/nodejs/src/cdp/services/messaging/email.service.ts
+++ b/nodejs/src/cdp/services/messaging/email.service.ts
@@ -33,7 +33,11 @@ import { SES_SENSITIVE_TAG } from './helpers/ses'
import { EmailTrackingCodeSigner, TRACKING_CODE_HEADER_NAME } from './helpers/tracking-code'
import { addUtmTagsToEmail, renderUtmOverrides, resolveUtmTags } from './helpers/utm'
import { MessageAssetsService } from './message-assets.service'
-import { RecipientTokensService } from './recipient-tokens.service'
+import {
+ PreferencesTokenSource,
+ RecipientTokensService,
+ preferencesTokenSourceForInvocation,
+} from './recipient-tokens.service'
const sesThrottleResponsesTotal = new Counter({
name: 'cdp_ses_throttle_responses_total',
@@ -1176,10 +1180,10 @@ export class EmailService {
const isTransactionalEmail = result.invocation.hogFunction?.metadata?.message_category_type === 'transactional'
if (sendEmailParams.Content?.Simple) {
const unsubscribeHeaders = !isTransactionalEmail
- ? this.generateUnsubscribeHeaders({
- team_id: result.invocation.teamId,
- identifier: params.to.email,
- })
+ ? this.generateUnsubscribeHeaders(
+ { team_id: result.invocation.teamId, identifier: params.to.email },
+ preferencesTokenSourceForInvocation(result.invocation)
+ )
: []
sendEmailParams.Content.Simple.Headers = [...unsubscribeHeaders, trackingHeader, AUTO_SUBMITTED_HEADER]
}
@@ -1214,12 +1218,13 @@ export class EmailService {
}
private generateUnsubscribeHeaders(
- recipient: Pick<RecipientManagerRecipient, 'team_id' | 'identifier'>
+ recipient: Pick<RecipientManagerRecipient, 'team_id' | 'identifier'>,
+ source: PreferencesTokenSource | undefined
): MessageHeader[] {
return [
{
Name: 'List-Unsubscribe',
- Value: `<${this.recipientTokensService.generateOneClickUnsubscribeUrl(recipient)}>`,
+ Value: `<${this.recipientTokensService.generateOneClickUnsubscribeUrl(recipient, source)}>`,
},
{
Name: 'List-Unsubscribe-Post',
diff --git a/nodejs/src/cdp/services/messaging/recipient-tokens.service.test.ts b/nodejs/src/cdp/services/messaging/recipient-tokens.service.test.ts
index 49e1d96ab944..f69af91a9f2b 100644
--- a/nodejs/src/cdp/services/messaging/recipient-tokens.service.test.ts
+++ b/nodejs/src/cdp/services/messaging/recipient-tokens.service.test.ts
@@ -17,10 +17,18 @@ describe('RecipientTokensService', () => {
`"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZWFtX2lkIjoxLCJpZGVudGlmaWVyIjoidGVzdEB0ZXN0LmNvbSIsImlhdCI6MTczNTY4OTYwMCwiZXhwIjoxNzM2Mjk0NDAwLCJhdWQiOiJwb3N0aG9nOm1lc3NhZ2luZzpzdWJzY3JpcHRpb25fcHJlZmVyZW5jZXMifQ.qpYA4Yx5lYA2ABEd_lgjn-rSGPgl-gg4PIbH3QXIZ7g"`
)
})
- it('should validate a valid token', () => {
- const token = service.generatePreferencesToken({ team_id: 1, identifier: '[email protected]' })
+ it.each([
+ { name: 'no source', source: undefined, claims: {} },
+ {
+ name: 'a workflow source',
+ source: { appSourceId: 'flow-1', instanceId: 'action-1' },
+ claims: { app_source_id: 'flow-1', instance_id: 'action-1' },
+ },
+ { name: 'a source without an action', source: { appSourceId: 'run-1' }, claims: { app_source_id: 'run-1' } },
+ ])('should validate a token minted with $name', ({ source, claims }) => {
+ const token = service.generatePreferencesToken({ team_id: 1, identifier: '[email protected]' }, source)
const result = service.validatePreferencesToken(token)
- expect(result).toEqual({ valid: true, team_id: 1, identifier: '[email protected]' })
+ expect(result).toEqual({ valid: true, team_id: 1, identifier: '[email protected]', ...claims })
})
it('should not accept a valid token with a different audience', () => {
const token = service['jwt'].sign({ team_id: 1, identifier: '[email protected]' }, 'other' as any, {
diff --git a/nodejs/src/cdp/services/messaging/recipient-tokens.service.ts b/nodejs/src/cdp/services/messaging/recipient-tokens.service.ts
index 144d8ef97fc3..0f7f88eb0746 100644
--- a/nodejs/src/cdp/services/messaging/recipient-tokens.service.ts
+++ b/nodejs/src/cdp/services/messaging/recipient-tokens.service.ts
@@ -1,8 +1,36 @@
import { logger } from '~/common/utils/logger'
+import type { CyclotronJobInvocationHogFunction } from '../../types'
import { JWT, PosthogJwtAudience } from '../../utils/jwt-utils'
import { RecipientManagerRecipient } from '../managers/recipients-manager.service'
+type PreferencesRecipient = Pick<RecipientManagerRecipient, 'team_id' | 'identifier'>
+
+/** The workflow email a preferences link came from, so an opt-out can be counted against it. */
+export type PreferencesTokenSource = {
+ /** The key the email's other metrics use: the batch run id for a broadcast, otherwise the hog flow id. */
+ appSourceId: string
+ /** The email action id. */
+ instanceId?: string
+}
+
+export type ValidatedPreferencesToken =
+ | { valid: false }
+ | { valid: true; team_id: number; identifier: string; app_source_id?: string; instance_id?: string }
+
+export function preferencesTokenSourceForInvocation(
+ invocation: Pick<CyclotronJobInvocationHogFunction, 'functionId' | 'parentRunId' | 'state'>
+): PreferencesTokenSource | undefined {
+ // Hog function destinations send email too, but only hog flow metrics are keyed this way.
+ if (!('hogFlow' in invocation)) {
+ return undefined
+ }
+ return {
+ appSourceId: invocation.parentRunId ?? invocation.functionId,
+ instanceId: invocation.state.actionId || undefined,
+ }
+}
+
export class RecipientTokensService {
private jwt: JWT
@@ -13,9 +41,7 @@ export class RecipientTokensService {
this.jwt = new JWT(encryptionSaltKeys ?? '')
}
- public validatePreferencesToken(
- token: string
- ): { valid: false } | { valid: true; team_id: number; identifier: string } {
+ public validatePreferencesToken(token: string): ValidatedPreferencesToken {
try {
const decoded = this.jwt.verify(token, PosthogJwtAudience.SUBSCRIPTION_PREFERENCES, {
ignoreVerificationErrors: true,
@@ -25,33 +51,44 @@ export class RecipientTokensService {
return { valid: false }
}
- const { team_id, identifier } = decoded as { team_id: number; identifier: string }
- return { valid: true, team_id, identifier }
+ const { team_id, identifier, app_source_id, instance_id } = decoded as {
+ team_id: number
+ identifier: string
+ app_source_id?: unknown
+ instance_id?: unknown
+ }
+ return {
+ valid: true,
+ team_id,
+ identifier,
+ ...(typeof app_source_id === 'string' ? { app_source_id } : {}),
+ ...(typeof instance_id === 'string' ? { instance_id } : {}),
+ }
} catch (error) {
logger.error('Error validating preferences token:', error)
return { valid: false }
}
}
- public generatePreferencesToken(recipient: Pick<RecipientManagerRecipient, 'team_id' | 'identifier'>): string {
+ public generatePreferencesToken(recipient: PreferencesRecipient, source?: PreferencesTokenSource): string {
return this.jwt.sign(
{
team_id: recipient.team_id,
identifier: recipient.identifier,
+ ...(source ? { app_source_id: source.appSourceId } : {}),
+ ...(source?.instanceId ? { instance_id: source.instanceId } : {}),
},
PosthogJwtAudience.SUBSCRIPTION_PREFERENCES,
{ expiresIn: '7d' }
)
}
- public generatePreferencesUrl(recipient: Pick<RecipientManagerRecipient, 'team_id' | 'identifier'>): string {
- const token = this.generatePreferencesToken(recipient)
+ public generatePreferencesUrl(recipient: PreferencesRecipient, source?: PreferencesTokenSource): string {
+ const token = this.generatePreferencesToken(recipient, source)
return `${this.siteUrl}/messaging-preferences/${token}/` // NOTE: Trailing slash is required for the preferences page to work
}
- public generateOneClickUnsubscribeUrl(
- recipient: Pick<RecipientManagerRecipient, 'team_id' | 'identifier'>
- ): string {
- return `${this.generatePreferencesUrl(recipient)}?one_click_unsubscribe=1`
+ public generateOneClickUnsubscribeUrl(recipient: PreferencesRecipient, source?: PreferencesTokenSource): string {
+ return `${this.generatePreferencesUrl(recipient, source)}?one_click_unsubscribe=1`
}
}