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.

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.ts
index 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.ts
index 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) : null
const 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 $2
ELSE 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 = CASE
WHEN 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 + i
valueClauses.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 SET
last_bounce_at = NOW(),
@@ -225,12 +245,9 @@ export class EmailSuppressionService {
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.suppressed_at
WHEN 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 + i
valueClauses.push(
@@ -296,14 +313,6 @@ export class EmailSuppressionService {
source = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.source
ELSE '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 = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.suppressed
ELSE true END,
@@ -314,6 +323,12 @@ export class EmailSuppressionService {
reason = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.reason
ELSE 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 = $1
AND 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 = false
AND transient_bounce_count > 0
AND (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_transactional
FROM posthog_messagesuppression
WHERE team_id = $1
AND identifier = ANY($2)
AND suppressed = true
AND 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.ts
index 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.ts
index 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 address
diff --git a/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts b/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts
index 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'
}