: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 integrationManagerconst newGlobals: HogFunctionInvocationGlobalsWithInputs = {@@ -117,14 +118,15 @@ export class HogInputsService {// If we have an email value then we template it out to get the email addressconst 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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`}}