: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
fix(messaging): send transactional workflow email unless the address hard-bounced (#124638)
Meikel Ratz312f4893d32a
diff --git a/nodejs/src/cdp/services/messaging/email-suppression.service.test.ts b/nodejs/src/cdp/services/messaging/email-suppression.service.test.tsindex 8bfc8d601c3d..9ded72ae7bf8 100644--- a/nodejs/src/cdp/services/messaging/email-suppression.service.test.ts+++ b/nodejs/src/cdp/services/messaging/email-suppression.service.test.ts@@ -300,21 +300,48 @@ describe('EmailSuppressionService', () => {)})- describe('transactional email to a complaint address', () => {+ describe('transactional email to a suppressed address', () => {it.each([['a complaint alone lets it through', ['complaint'], false],+ ['soft bounces up to the threshold let it through', ['soft', 'soft', 'soft'], false],+ ['soft bounces after a complaint let it through', ['complaint', 'soft', 'soft', 'soft'], false],+ ['a hard bounce blocks it', ['hard'], true],['a hard bounce after the complaint blocks it', ['complaint', 'hard'], true],['a hard bounce before the complaint blocks it', ['hard', 'complaint'], true],- ['soft bounces up to the threshold block it', ['complaint', 'soft', 'soft', 'soft'], true],- ['soft bounces below the threshold let it through', ['complaint', 'soft', 'soft'], false],- ['a delivery resets the soft bounces', ['complaint', 'soft', 'soft', 'delivery', 'soft'], false],+ ['a hard bounce after soft bounces blocks it', ['soft', 'soft', 'soft', 'hard'], true],+ ['a hard bounce on a manual entry blocks it', ['manual', 'hard'], true],+ ['a complaint after a legacy hard bounce still blocks it', ['legacy-hard', 'complaint'], true],+ ['soft bounces after a legacy hard bounce still block it', ['legacy-hard', 'soft', 'soft', 'soft'], true],] as const)('%s', async (_label, steps, blocked) => {process.env.EMAIL_SUPPRESSION_TRANSIENT_BOUNCE_THRESHOLD = '3'const svc = new EmailSuppressionService(hub.postgres, emailSuppressionConfigFromEnv())- const email = '[email protected]'+ const email = '[email protected]'for (const step of steps) {- if (step === 'complaint') {+ if (step === 'manual') {+ await hub.postgres.query(+ PostgresUse.COMMON_WRITE,+ `INSERT INTO posthog_messagesuppression+ (id, team_id, identifier, source, reason, transient_bounce_count,+ suppressed, suppressed_at, deleted, created_at, updated_at)+ VALUES (gen_random_uuid(), $1, $2, 'MANUAL', 'test row', 0,+ true, NOW(), false, NOW(), NOW())`,+ [team.id, email],+ 'test-insert-manual-suppression'+ )+ } else if (step === 'legacy-hard') {+ // A row written before `hard_bounced_at` existed: the mark is only in the reason.+ await hub.postgres.query(+ PostgresUse.COMMON_WRITE,+ `INSERT INTO posthog_messagesuppression+ (id, team_id, identifier, source, reason, transient_bounce_count,+ suppressed, suppressed_at, deleted, created_at, updated_at)+ VALUES (gen_random_uuid(), $1, $2, 'BOUNCE', 'Auto-suppressed after a hard bounce', 0,+ true, NOW(), false, NOW(), NOW())`,+ [team.id, email],+ 'test-insert-legacy-hard-suppression'+ )+ } else if (step === 'complaint') {await svc.recordComplaints(team.id, [email], 'abuse')} else if (step === 'hard') {await svc.recordHardBounces(team.id, [email], 'smtp; 550 5.1.1 user unknown')@@ -372,13 +399,28 @@ describe('EmailSuppressionService', () => {describe('isSuppressed', () => {it.each([- ['a bounce blocks marketing email', 'BOUNCE', false, true],- ['a bounce blocks transactional email', 'BOUNCE', true, true],- ['a manual entry blocks transactional email', 'MANUAL', true, true],- ['a complaint blocks marketing email', 'COMPLAINT', false, true],- ['a complaint lets transactional email through', 'COMPLAINT', true, false],- ['an address that is not on the list is not blocked', null, false, false],- ] as const)('%s', async (_label, source, transactional, expected) => {+ ['a bounce blocks marketing email', 'BOUNCE', 'test row', false, true],+ ['a soft-bounce suppression lets transactional email through', 'BOUNCE', 'test row', true, false],+ [+ 'a hard bounce from before hard_bounced_at blocks transactional email',+ 'BOUNCE',+ 'Auto-suppressed after a hard bounce',+ true,+ true,+ ],+ ['a manual entry blocks marketing email', 'MANUAL', 'test row', false, true],+ ['a manual entry lets transactional email through', 'MANUAL', 'test row', true, false],+ [+ 'an imported Customer.io invalid address blocks transactional email',+ 'BOUNCE',+ 'Imported from Customer.io (invalid address)',+ true,+ true,+ ],+ ['a complaint blocks marketing email', 'COMPLAINT', 'test row', false, true],+ ['a complaint lets transactional email through', 'COMPLAINT', 'test row', true, false],+ ['an address that is not on the list is not blocked', null, null, false, false],+ ] as const)('%s', async (_label, source, reason, transactional, expected) => {const svc = new EmailSuppressionService(hub.postgres, emailSuppressionConfigFromEnv())const email = '[email protected]'if (source) {@@ -387,9 +429,9 @@ describe('EmailSuppressionService', () => {`INSERT INTO posthog_messagesuppression(id, team_id, identifier, source, reason, transient_bounce_count,suppressed, suppressed_at, deleted, created_at, updated_at)- VALUES (gen_random_uuid(), $1, $2, $3, 'test row', 0,+ VALUES (gen_random_uuid(), $1, $2, $3, $4, 0,true, NOW(), false, NOW(), NOW())`,- [team.id, email, source],+ [team.id, email, source, reason],'test-insert-suppression')}diff --git a/nodejs/src/cdp/services/messaging/email-suppression.service.ts b/nodejs/src/cdp/services/messaging/email-suppression.service.tsindex 72268071b6c0..e7aeab8e9c14 100644--- a/nodejs/src/cdp/services/messaging/email-suppression.service.ts+++ b/nodejs/src/cdp/services/messaging/email-suppression.service.ts@@ -33,16 +33,25 @@ export function emailSuppressionConfigFromEnv(): EmailSuppressionConfig {}export type SuppressionCheckOptions = {- // A spam complaint means the recipient doesn't want our mail, not that the address can't receive it.- // Transactional email (login codes, password resets) still goes out to it. Bounce and manual entries block it.+ // Transactional email (invoices, login codes, password resets) is blocked only by a hard bounce, because+ // only then is the address proven dead. A complaint, a manual entry or a full inbox (soft bounces) lets it through.transactional?: boolean}-// An active suppression. A COMPLAINT row keeps its source when the address later bounces, so its bounce-// count decides whether it blocks transactional email: it does once the count reaches the soft-bounce-// threshold. A hard bounce sets the count to the threshold.+// An active suppression. It blocks transactional email only when the address hard-bounced.type SuppressionEntry = { blocksTransactional: boolean }+const HARD_BOUNCE_REASON = 'Auto-suppressed after a hard bounce'++// Reasons that mark a dead address on rows written before `hard_bounced_at` existed: our own hard-bounce+// rows, and the two Customer.io lists the importer maps to BOUNCE. Both writers now set the column, so+// this list is closed and only covers rows already on disk.+const LEGACY_HARD_BOUNCE_REASONS = [+ HARD_BOUNCE_REASON,+ 'Imported from Customer.io (bounced)',+ 'Imported from Customer.io (invalid address)',+]+/*** Per-team email suppression list, backed by `posthog_messagesuppression`.*@@ -125,10 +134,16 @@ export class EmailSuppressionService {const diag = diagnostic ? diagnostic.slice(0, DIAGNOSTIC_MAX_LENGTH) : nullconst reason = `Auto-suppressed after ${this.threshold} consecutive soft bounces`- // Build a single multi-row upsert. Params: teamId, reason, threshold, diag, then one- // identifier per row.+ // Build a single multi-row upsert. Params: teamId, reason, threshold, diag, legacy reasons,+ // then one identifier per row.const valueClauses: string[] = []- const params: (number | string | null)[] = [teamId, reason, this.threshold, diag]+ const params: (number | string | string[] | null)[] = [+ teamId,+ reason,+ this.threshold,+ diag,+ LEGACY_HARD_BOUNCE_REASONS,+ ]identifiers.forEach((identifier, i) => {const p = params.length + 1 + i// gen_random_uuid() for the id, mirroring RecipientsManagerService.optOut. First bounce@@ -164,6 +179,12 @@ export class EmailSuppressionService {WHEN posthog_messagesuppression.source NOT IN ('MANUAL', 'COMPLAINT')AND posthog_messagesuppression.transient_bounce_count + 1 >= $3 THEN $2ELSE posthog_messagesuppression.reason END,+ -- The reason update above replaces the text that an older row carries its hard-bounce+ -- mark in. Move the mark to the column first, so the row keeps blocking transactional email.+ hard_bounced_at = COALESCE(+ posthog_messagesuppression.hard_bounced_at,+ CASE WHEN posthog_messagesuppression.source = 'BOUNCE'+ AND posthog_messagesuppression.reason = ANY($5) THEN NOW() END),-- A provably-undeliverable address coming back over threshold un-deletes itself.deleted = CASEWHEN posthog_messagesuppression.source <> 'MANUAL'@@ -196,15 +217,13 @@ export class EmailSuppressionService {}const diag = diagnostic ? diagnostic.slice(0, DIAGNOSTIC_MAX_LENGTH) : null- const reason = 'Auto-suppressed after a hard bounce'-- // Params: teamId, reason, diag, threshold, then one identifier per row.+ // Params: teamId, reason, diag, then one identifier per row.const valueClauses: string[] = []- const params: (number | string | null)[] = [teamId, reason, diag, this.threshold]+ const params: (number | string | null)[] = [teamId, HARD_BOUNCE_REASON, diag]identifiers.forEach((identifier, i) => {const p = params.length + 1 + ivalueClauses.push(- `(gen_random_uuid(), $1, $${p}, 'BOUNCE', $2, 0, NOW(), $3, true, NOW(), false, NOW(), NOW())`+ `(gen_random_uuid(), $1, $${p}, 'BOUNCE', $2, 0, NOW(), $3, true, NOW(), false, NOW(), NOW(), NOW())`)})params.push(...identifiers)@@ -212,7 +231,8 @@ export class EmailSuppressionService {const query = `INSERT INTO posthog_messagesuppression(id, team_id, identifier, source, reason, transient_bounce_count, last_bounce_at,- last_bounce_diagnostic, suppressed, suppressed_at, deleted, created_at, updated_at)+ last_bounce_diagnostic, suppressed, suppressed_at, deleted, created_at, updated_at,+ hard_bounced_at)VALUES ${valueClauses.join(', ')}ON CONFLICT (team_id, identifier) DO UPDATE SETlast_bounce_at = NOW(),@@ -225,12 +245,9 @@ export class EmailSuppressionService {WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.suppressed_atWHEN posthog_messagesuppression.suppressed = false THEN NOW()ELSE posthog_messagesuppression.suppressed_at END,- -- A COMPLAINT row keeps its source, so the count records the bounce. At the threshold the- -- row also blocks transactional email, because the address can't receive mail.- transient_bounce_count = CASE- WHEN posthog_messagesuppression.source = 'COMPLAINT'- THEN GREATEST(posthog_messagesuppression.transient_bounce_count, $4)- ELSE posthog_messagesuppression.transient_bounce_count END,+ -- Set on every row, manual and complaint entries included: the address can't receive+ -- mail, so transactional email must stop too.+ hard_bounced_at = NOW(),-- A complaint outranks a bounce as the reason a row exists, so it keeps its reason-- here the way a manual entry does. This upsert never reassigns the source, so-- overwriting the reason on a COMPLAINT row would leave the two contradicting each@@ -274,9 +291,9 @@ export class EmailSuppressionService {? `Auto-suppressed after a spam complaint (feedback type: ${feedbackType.slice(0, 100)})`: 'Auto-suppressed after a spam complaint'- // Params: teamId, reason, threshold, then one identifier per row.+ // Params: teamId, reason, legacy reasons, then one identifier per row.const valueClauses: string[] = []- const params: (number | string | null)[] = [teamId, reason, this.threshold]+ const params: (number | string | string[] | null)[] = [teamId, reason, LEGACY_HARD_BOUNCE_REASONS]identifiers.forEach((identifier, i) => {const p = params.length + 1 + ivalueClauses.push(@@ -296,14 +313,6 @@ export class EmailSuppressionService {source = CASEWHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.sourceELSE 'COMPLAINT' END,- -- An address that a bounce already suppressed can't receive mail, so the re-keyed row- -- keeps a count at the threshold and still blocks transactional email.- transient_bounce_count = CASE- WHEN posthog_messagesuppression.source = 'BOUNCE'- AND posthog_messagesuppression.suppressed- AND NOT posthog_messagesuppression.deleted- THEN GREATEST(posthog_messagesuppression.transient_bounce_count, $3)- ELSE posthog_messagesuppression.transient_bounce_count END,suppressed = CASEWHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.suppressedELSE true END,@@ -314,6 +323,12 @@ export class EmailSuppressionService {reason = CASEWHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.reasonELSE EXCLUDED.reason END,+ -- The reason update above replaces the text that an older row carries its hard-bounce+ -- mark in. Move the mark to the column first, so the row keeps blocking transactional email.+ hard_bounced_at = COALESCE(+ posthog_messagesuppression.hard_bounced_at,+ CASE WHEN posthog_messagesuppression.source = 'BOUNCE'+ AND posthog_messagesuppression.reason = ANY($3) THEN NOW() END),-- A soft-deleted row comes back: the complaint is fresh evidence the recipient-- must not be mailed.deleted = CASE@@ -334,8 +349,7 @@ export class EmailSuppressionService {/*** Record successful deliveries. Resets the consecutive-bounce counter for auto (non-manual)- * entries that haven't yet been suppressed, so a transient outage never accumulates. COMPLAINT- * entries reset too, because their counter decides whether they block transactional email.+ * entries that haven't yet been suppressed, so a transient outage never accumulates.** `deliveryTimestamp` guards against out-of-order events: SES delivery and bounce notifications* for different sends can arrive in any order, and a late delivery for an older send must not@@ -358,9 +372,7 @@ export class EmailSuppressionService {WHERE team_id = $1AND identifier = ANY($2)AND source <> 'MANUAL'- -- A COMPLAINT row stays suppressed, but its count decides whether it blocks transactional- -- email, and a delivery proves the address works again.- AND (suppressed = false OR source = 'COMPLAINT')+ AND suppressed = falseAND transient_bounce_count > 0AND (last_bounce_at IS NULL OR ($3::timestamptz IS NOT NULL AND last_bounce_at < $3::timestamptz))`@@ -402,15 +414,20 @@ export class EmailSuppressionService {const entries = new Map<string, SuppressionEntry>()for (const [teamId, identifiers] of byTeam) {+ // The reason check covers rows that hard-bounced before `hard_bounced_at` existed.const result = await this.postgres.query<{ identifier: string; blocks_transactional: boolean }>(PostgresUse.COMMON_READ,- `SELECT identifier, (source <> 'COMPLAINT' OR transient_bounce_count >= $3) AS blocks_transactional+ `SELECT identifier,+ -- A soft-bounce row carries no reason until it crosses the threshold, and+ -- NULL = ANY(...) is NULL, so COALESCE keeps the column a real boolean.+ COALESCE(hard_bounced_at IS NOT NULL OR (source = 'BOUNCE' AND reason = ANY($3)), false)+ AS blocks_transactionalFROM posthog_messagesuppressionWHERE team_id = $1AND identifier = ANY($2)AND suppressed = trueAND deleted = false`,- [teamId, identifiers, this.threshold],+ [teamId, identifiers, LEGACY_HARD_BOUNCE_REASONS],'loadSuppressed')for (const row of result.rows) {diff --git a/nodejs/src/cdp/services/messaging/email-tracking.service.test.ts b/nodejs/src/cdp/services/messaging/email-tracking.service.test.tsindex 644df486e9d3..bedfc201df44 100644--- a/nodejs/src/cdp/services/messaging/email-tracking.service.test.ts+++ b/nodejs/src/cdp/services/messaging/email-tracking.service.test.ts@@ -23,6 +23,7 @@ import { waitForExpect } from '~/tests/helpers/expectations'import { createTestTeamFixture } from '~/tests/helpers/sql'import { Hub, Team } from '../../../types'+import { EmailSuppressionService } from './email-suppression.service'import {METRIC_NAME_TO_EVENT_NAME,PIXEL_GIF,@@ -867,6 +868,38 @@ describe('EmailTrackingService', () => {},])})++ // The webhook write and the pre-send read are covered separately. This joins them end to end:+ // a real SES envelope over the HTTP route, then the check every email step runs before sending.+ // It fails if a Permanent bounce stops marking the row, which would keep sending transactional+ // email to a dead address, or if a soft bounce or complaint starts marking it, which would drop+ // invoices and password resets for a working address.+ it.each([+ ['a transient bounce', postTransientBounce, false],+ ['a complaint', postComplaint, false],+ ['a permanent bounce', postPermanentBounce, true],+ ] as const)(+ '%s suppresses marketing email, and blocks transactional email only for a hard bounce',+ async (_label, postWebhook, blocksTransactional) => {+ const hogFlow = await insertHogFlow(+ hub.postgres,+ new FixtureHogFlowBuilder().withTeamId(team.id).build()+ )+ const email = '[email protected]'++ const res = await postWebhook(hogFlow.id, email)+ expect(res.status).toBe(200)++ const suppression = new EmailSuppressionService(hub.postgres, {+ transientBounceThreshold: hub.EMAIL_SUPPRESSION_TRANSIENT_BOUNCE_THRESHOLD,+ })++ expect(await suppression.isSuppressed(team.id, email)).toBe(true)+ expect(await suppression.isSuppressed(team.id, email, { transactional: true })).toBe(+ blocksTransactional+ )+ }+ )})describe('resolveEmailEngagementDistinctId', () => {diff --git a/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts b/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.tsindex cbf2c8b716d3..84217d319ede 100644--- a/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts+++ b/nodejs/src/cdp/services/messaging/recipient-preferences.service.test.ts@@ -368,33 +368,34 @@ describe('RecipientPreferencesService', () => {})describe('when the recipient is on the suppression list', () => {- // Suppression is a deliverability signal that must apply even to transactional- // messages — the parameterized case guards that ordering.- const insertSuppressionRow = async (email: string): Promise<void> => {+ // A hard bounce must block even transactional messages, ahead of the transactional+ // opt-out bypass. Soft bounces alone must not.+ const insertSuppressionRow = async (email: string, hardBounced = false): Promise<void> => {await hub.postgres.query(PostgresUse.COMMON_WRITE,`INSERT INTO posthog_messagesuppression(id, team_id, identifier, source, reason, transient_bounce_count,- suppressed, suppressed_at, deleted, created_at, updated_at)+ suppressed, suppressed_at, deleted, created_at, updated_at, hard_bounced_at)VALUES (gen_random_uuid(), $1, $2, 'BOUNCE', 'test row', 5,- true, NOW(), false, NOW(), NOW())`,- [team.id, email],+ true, NOW(), false, NOW(), NOW(), CASE WHEN $3 THEN NOW() END)`,+ [team.id, email, hardBounced],'test-insert-suppression')}it.each([- ['marketing', 'marketing' as const],- ['transactional', 'transactional' as const],- ])('skips a %s email to a suppressed recipient', async (_label, categoryType) => {- const email = `suppressed-${categoryType}@example.com`- await insertSuppressionRow(email)+ ['skips a marketing email after soft bounces', 'marketing' as const, false, 'suppressed'],+ ['sends a transactional email after soft bounces', 'transactional' as const, false, null],+ ['skips a transactional email after a hard bounce', 'transactional' as const, true, 'suppressed'],+ ])('%s', async (_label, categoryType, hardBounced, expected) => {+ const email = `suppressed-${categoryType}-${hardBounced}@example.com`+ await insertSuppressionRow(email, hardBounced)const action = createEmailAction(email, '123e4567-e89b-12d3-a456-426614174000', categoryType)const invocation = createFunctionStepInvocation(action)const result = await service.shouldSkipAction(invocation, action)- expect(result).toBe('suppressed')+ expect(result).toBe(expected)})// Suppressed cc and bcc addresses are removed at send time, and a deliverable cc addressdiff --git a/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts b/nodejs/src/cdp/services/messaging/recipient-preferences.service.tsindex 71c21a054a7f..b9963c487801 100644--- a/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts+++ b/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts@@ -115,10 +115,9 @@ export class RecipientPreferencesService {return null}- // Suppression is mostly a deliverability signal, not a messaging preference: an address that can't- // receive mail can't receive it regardless of category. So we check it even for transactional- // messages, and before the transactional opt-out bypass below. Only spam complaints let- // transactional messages through.+ // Suppression is mostly a deliverability signal, not a messaging preference. We check it even for+ // transactional messages, and before the transactional opt-out bypass below. For those, only a hard+ // bounce blocks the send, because then the address can't receive mail.if (await this.isRecipientSuppressed(invocation, action)) {return 'suppressed'}