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): stop suppression refusals dropping transactional email (#123492)

Harley Alexander4b4425593ff8
diff --git a/nodejs/src/cdp/cdp-api.serial.test.ts b/nodejs/src/cdp/cdp-api.serial.test.ts
index cfb6a3226e6d..64baeb284314 100644
--- a/nodejs/src/cdp/cdp-api.serial.test.ts
+++ b/nodejs/src/cdp/cdp-api.serial.test.ts
@@ -14,6 +14,7 @@ import { setupExpressApp } from '~/common/api/router'
import { deleteKeysWithPrefix } from '~/common/redis/_tests/redis'
import { createRedisV2PoolFromConfig } from '~/common/redis/redis-v2'
import { closeHub, createHub } from '~/common/utils/db/hub'
+import { PostgresUse } from '~/common/utils/db/postgres'
import { parseJSON } from '~/common/utils/json-parse'
import { UUIDT } from '~/common/utils/utils'
import { waitForExpect } from '~/tests/helpers/expectations'
@@ -2308,6 +2309,24 @@ describe('CDP API', () => {
expect(mockQueueInvocations).toHaveBeenCalledTimes(1)
})
+ it('sends to a recipient whose only suppression is a spam complaint', async () => {
+ 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, 'COMPLAINT', 'test row', 0,
+ true, NOW(), false, NOW(), NOW())`,
+ [team.id, body.to],
+ 'test-insert-suppression'
+ )
+
+ const res = await send(hogFlow.id, { Authorization: `Bearer ${mintToken(team.id, hogFlow.id)}` })
+
+ expect(res.status).toEqual(202)
+ expect(mockQueueInvocations).toHaveBeenCalledTimes(1)
+ })
+
it.each([
['a workflow with another trigger', 'schedule', 'active'],
['a transactional email that is not active', 'api', 'draft'],
diff --git a/nodejs/src/cdp/cdp-api.ts b/nodejs/src/cdp/cdp-api.ts
index 9be10fb21696..649511b14f71 100644
--- a/nodejs/src/cdp/cdp-api.ts
+++ b/nodejs/src/cdp/cdp-api.ts
@@ -1295,7 +1295,7 @@ export class CdpApi {
if (hogFlow.email_sending_paused_at) {
return { outcome: 'sending_paused', status: 422 }
}
- if (await this.emailSuppressionService.isSuppressed(teamId, to)) {
+ if (await this.emailSuppressionService.isSuppressed(teamId, to, { transactional: true })) {
return { outcome: 'recipient_suppressed', status: 422 }
}
const { isLimited } = await checkHogFlowQuotaLimits(hogFlow, teamId, this.deps.quotaLimiting)
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 820c15f12ee8..8bfc8d601c3d 100644
--- a/nodejs/src/cdp/services/messaging/email-suppression.service.test.ts
+++ b/nodejs/src/cdp/services/messaging/email-suppression.service.test.ts
@@ -300,6 +300,37 @@ describe('EmailSuppressionService', () => {
)
})
+ describe('transactional email to a complaint address', () => {
+ it.each([
+ ['a complaint alone lets it through', ['complaint'], false],
+ ['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],
+ ] 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]'
+
+ for (const step of steps) {
+ 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')
+ } else if (step === 'soft') {
+ await svc.recordTransientBounces(team.id, [email], 'smtp; 421 try again later')
+ } else {
+ // Bounces stamp last_bounce_at with NOW(), so a delivery has to be newer than that.
+ await svc.recordDeliveries(team.id, [email], new Date(Date.now() + 60_000).toISOString())
+ }
+ }
+
+ expect(await svc.isSuppressed(team.id, email, { transactional: true })).toBe(blocked)
+ expect(await svc.isSuppressed(team.id, email)).toBe(true)
+ })
+ })
+
describe('cache invalidation', () => {
it("a write for one team does not evict another team's cached entries", async () => {
// Guards against a regression from markForRefresh(touchedKeys) back to clear() — clear()
@@ -341,25 +372,29 @@ describe('EmailSuppressionService', () => {
describe('isSuppressed', () => {
it.each([
- ['returns true for a suppressed row', true],
- ['returns false for an identifier that is not on the list', false],
- ])('%s', async (_label, expected) => {
+ ['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) => {
const svc = new EmailSuppressionService(hub.postgres, emailSuppressionConfigFromEnv())
- const email = expected ? '[email protected]' : '[email protected]'
- if (expected) {
+ const email = '[email protected]'
+ if (source) {
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', 'test row', 5,
+ VALUES (gen_random_uuid(), $1, $2, $3, 'test row', 0,
true, NOW(), false, NOW(), NOW())`,
- [team.id, email],
+ [team.id, email, source],
'test-insert-suppression'
)
}
- expect(await svc.isSuppressed(team.id, email)).toBe(expected)
+ expect(await svc.isSuppressed(team.id, email, { transactional })).toBe(expected)
})
// isSuppressed fails open. A load that throws would therefore let a suppressed address receive mail.
diff --git a/nodejs/src/cdp/services/messaging/email-suppression.service.ts b/nodejs/src/cdp/services/messaging/email-suppression.service.ts
index b7d9561928b7..72268071b6c0 100644
--- a/nodejs/src/cdp/services/messaging/email-suppression.service.ts
+++ b/nodejs/src/cdp/services/messaging/email-suppression.service.ts
@@ -32,6 +32,17 @@ 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?: 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.
+type SuppressionEntry = { blocksTransactional: boolean }
+
/**
* Per-team email suppression list, backed by `posthog_messagesuppression`.
*
@@ -58,14 +69,15 @@ export function emailSuppressionConfigFromEnv(): EmailSuppressionConfig {
*/
export class EmailSuppressionService {
private readonly threshold: number
- private readonly lazyLoader: LazyLoader<boolean>
+ // A key's active suppression, or false when it has none.
+ private readonly lazyLoader: LazyLoader<SuppressionEntry | false>
constructor(
private postgres: PostgresRouter,
config: EmailSuppressionConfig
) {
this.threshold = config.transientBounceThreshold
- this.lazyLoader = new LazyLoader({
+ this.lazyLoader = new LazyLoader<SuppressionEntry | false>({
name: 'email_suppression',
loader: async (keys) => await this.loadSuppressed(keys),
})
@@ -75,14 +87,19 @@ export class EmailSuppressionService {
this.lazyLoader.clear()
}
- /** Pre-send check: is this recipient currently on the team's suppression list? */
- public async isSuppressed(teamId: number, email: string): Promise<boolean> {
+ /** Pre-send check: does the team's suppression list block this recipient for this kind of email? */
+ public async isSuppressed(
+ teamId: number,
+ email: string,
+ { transactional = false }: SuppressionCheckOptions = {}
+ ): Promise<boolean> {
const identifier = normalizeIdentifier(email)
if (!identifier) {
return false
}
try {
- const suppressed = (await this.lazyLoader.get(toKey(teamId, identifier))) ?? false
+ const entry = (await this.lazyLoader.get(toKey(teamId, identifier))) ?? false
+ const suppressed = entry !== false && (!transactional || entry.blocksTransactional)
if (suppressed) {
cdpEmailSuppressionTotal.inc({ result: 'suppressed_hit' })
}
@@ -181,9 +198,9 @@ 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, then one identifier per row.
+ // Params: teamId, reason, diag, threshold, then one identifier per row.
const valueClauses: string[] = []
- const params: (number | string | null)[] = [teamId, reason, diag]
+ const params: (number | string | null)[] = [teamId, reason, diag, this.threshold]
identifiers.forEach((identifier, i) => {
const p = params.length + 1 + i
valueClauses.push(
@@ -208,6 +225,12 @@ 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,
-- 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
@@ -251,9 +274,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, then one identifier per row.
+ // Params: teamId, reason, threshold, then one identifier per row.
const valueClauses: string[] = []
- const params: (number | string | null)[] = [teamId, reason]
+ const params: (number | string | null)[] = [teamId, reason, this.threshold]
identifiers.forEach((identifier, i) => {
const p = params.length + 1 + i
valueClauses.push(
@@ -273,6 +296,14 @@ 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,
@@ -303,7 +334,8 @@ 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.
+ * 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.
*
* `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
@@ -326,7 +358,9 @@ export class EmailSuppressionService {
WHERE team_id = $1
AND identifier = ANY($2)
AND source <> 'MANUAL'
- AND suppressed = false
+ -- 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 transient_bounce_count > 0
AND (last_bounce_at IS NULL OR ($3::timestamptz IS NOT NULL AND last_bounce_at < $3::timestamptz))
`
@@ -337,12 +371,13 @@ export class EmailSuppressionService {
[teamId, identifiers, deliveryTimestamp ?? null],
'resetBounceCounts'
)
+ this.lazyLoader.markForRefresh(identifiers.map((identifier) => toKey(teamId, identifier)))
} catch (error) {
logger.error('[EmailSuppression] Failed to reset bounce counts on delivery', { teamId, error })
}
}
- private async loadSuppressed(keys: string[]): Promise<Record<string, boolean>> {
+ private async loadSuppressed(keys: string[]): Promise<Record<string, SuppressionEntry | false>> {
// keys are `${teamId}:${identifier}`. Identifiers may contain ':' only in exotic cases; the
// stored identifier is an email so split on the first ':' only.
const parsed = keys.map((key) => {
@@ -365,25 +400,25 @@ export class EmailSuppressionService {
byTeam.set(p.teamId, list)
}
- const suppressedKeys = new Set<string>()
+ const entries = new Map<string, SuppressionEntry>()
for (const [teamId, identifiers] of byTeam) {
- const result = await this.postgres.query<{ identifier: string }>(
+ const result = await this.postgres.query<{ identifier: string; blocks_transactional: boolean }>(
PostgresUse.COMMON_READ,
- `SELECT identifier
+ `SELECT identifier, (source <> 'COMPLAINT' OR transient_bounce_count >= $3) AS blocks_transactional
FROM posthog_messagesuppression
WHERE team_id = $1
AND identifier = ANY($2)
AND suppressed = true
AND deleted = false`,
- [teamId, identifiers],
+ [teamId, identifiers, this.threshold],
'loadSuppressed'
)
for (const row of result.rows) {
- suppressedKeys.add(toKey(teamId, row.identifier))
+ entries.set(toKey(teamId, row.identifier), { blocksTransactional: row.blocks_transactional })
}
}
// Default every requested key to false so the LazyLoader caches negatives too.
- return Object.fromEntries(parsed.map((p) => [p.key, suppressedKeys.has(p.key)]))
+ return Object.fromEntries(parsed.map((p) => [p.key, entries.get(p.key) ?? false]))
}
}
diff --git a/nodejs/src/cdp/services/messaging/email.service.ts b/nodejs/src/cdp/services/messaging/email.service.ts
index 9b377c8145a6..ff83d8746de4 100644
--- a/nodejs/src/cdp/services/messaging/email.service.ts
+++ b/nodejs/src/cdp/services/messaging/email.service.ts
@@ -21,7 +21,7 @@ import { RecipientManagerRecipient, RecipientsManagerService } from '../managers
import { TeamWorkflowsConfigService } from '../managers/team-workflows-config.service'
import { RateLimiterService } from '../rate-limiter/rate-limiter.service'
import { selectEmailSenderIntegrationId } from './email-sender-selection'
-import { EmailSuppressionService } from './email-suppression.service'
+import { EmailSuppressionService, SuppressionCheckOptions } from './email-suppression.service'
import {
addTrackingToEmail,
resolveEmailEngagementDistinctId,
@@ -515,7 +515,9 @@ export class EmailService {
// of whether the invocation came from a workflow action or an email destination hog
// function. Checking here means callers can't bypass it by taking a different upstream
// route. Covers `to`, `cc`, and `bcc`; a suppressed address anywhere blocks the send.
- const skipReason = await this.buildSuppressionSkipReason(invocation.teamId, params)
+ const skipReason = await this.buildSuppressionSkipReason(invocation.teamId, params, {
+ transactional: invocation.hogFunction?.metadata?.message_category_type === 'transactional',
+ })
if (skipReason) {
addLog('info', skipReason)
result.emailSendResult = { status: 'skipped', reason: skipReason }
@@ -866,7 +868,8 @@ export class EmailService {
// matching against the normalized suppression identifier.
private async buildSuppressionSkipReason(
teamId: number,
- params: CyclotronInvocationQueueParametersEmailType
+ params: CyclotronInvocationQueueParametersEmailType,
+ options: SuppressionCheckOptions
): Promise<string | null> {
const recipients: string[] = []
if (params.to?.email && params.to.email.trim()) {
@@ -881,7 +884,7 @@ export class EmailService {
const results = await Promise.all(
recipients.map(async (email) => ({
email,
- suppressed: await this.emailSuppressionService.isSuppressed(teamId, email),
+ suppressed: await this.emailSuppressionService.isSuppressed(teamId, email, options),
}))
)
const suppressed = results.filter((r) => r.suppressed).map((r) => r.email)
diff --git a/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts b/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts
index fb3070ba79c0..fe308e069c55 100644
--- a/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts
+++ b/nodejs/src/cdp/services/messaging/recipient-preferences.service.ts
@@ -125,9 +125,10 @@ export class RecipientPreferencesService {
return null
}
- // Suppression is 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.
+ // 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.
if (await this.isRecipientSuppressed(invocation, action)) {
return 'suppressed'
}
@@ -166,7 +167,11 @@ export class RecipientPreferencesService {
try {
const results = await Promise.all(
- recipients.map((email) => this.emailSuppressionService.isSuppressed(invocation.teamId, email))
+ recipients.map((email) =>
+ this.emailSuppressionService.isSuppressed(invocation.teamId, email, {
+ transactional: action.config.message_category_type === 'transactional',
+ })
+ )
)
return results.some(Boolean)
} catch (error) {
diff --git a/posthog/email.py b/posthog/email.py
index e81fabf2477a..4a1f0df47af7 100644
--- a/posthog/email.py
+++ b/posthog/email.py
@@ -218,6 +218,10 @@ WORKFLOWS_TRANSACTIONAL_EMAIL_FLAG = "transactional-emails-via-workflows"
# Matches how long the send API keeps an idempotency key, which outlasts every Celery retry.
WORKFLOWS_PIN_TTL_SECONDS = 24 * 60 * 60
+# 422 codes for an email the send API refused before queueing it: sending is suspended for the project or paused for
+# the workflow, or the recipient is on the suppression list. Customer.io sends these emails instead.
+WORKFLOWS_NOT_QUEUED_422_CODES = frozenset({"sending_suspended", "sending_paused", "recipient_suppressed"})
+
EMAIL_WORKFLOWS_FALLBACK_COUNTER = Counter(
"posthog_email_workflows_fallback_total",
"Emails that Workflows refused and Customer.io sent instead, by template.",
@@ -283,10 +287,13 @@ def _workflows_error_allows_fallback(err: WorkflowsEmailError) -> bool:
# A connection that was never made and a client that queued nothing sent nothing. Any other network
# failure can come after Workflows queued the email.
return err.code in ("connection_error", "not_queued")
- # Redirects and 4xx answers come before anything is queued, apart from 408 and the two idempotency answers:
- # 409 (an attempt with this key is in flight) and 422 (this key already queued an email). A 5xx can follow a
- # queued email, because the send API also returns 503 when the workflow service queued it but failed to answer.
- return 300 <= err.status_code < 500 and err.status_code not in (408, 409, 422)
+ if err.status_code == 422:
+ # The send API refuses these before it queues anything. Any other 422 means this key already queued an email.
+ return err.code in WORKFLOWS_NOT_QUEUED_422_CODES
+ # Redirects and 4xx answers come before anything is queued, apart from 408 and 409 (an attempt with this key is
+ # in flight). A 5xx can follow a queued email, because the send API also returns 503 when the workflow service
+ # queued it but failed to answer.
+ return 300 <= err.status_code < 500 and err.status_code not in (408, 409)
def _never_connected(err: requests.ConnectionError) -> bool:
diff --git a/posthog/test/test_email.py b/posthog/test/test_email.py
index 2695f126c7e2..72b060a57c99 100644
--- a/posthog/test/test_email.py
+++ b/posthog/test/test_email.py
@@ -441,6 +441,22 @@ class TestEmail(BaseTest):
["transactional email workflows rejected", "transactional email triggered"],
),
("workflows_in_flight_sends_nothing", True, [409], ["workflows"], None, ["transactional email failed"]),
+ (
+ "workflows_refuses_suppressed_recipient_falls_back",
+ True,
+ [(422, {"type": "invalid_request", "code": "recipient_suppressed"}), 200],
+ ["workflows", "customer_io"],
+ "customer_io",
+ ["transactional email workflows rejected", "transactional email triggered"],
+ ),
+ (
+ "workflows_key_already_used_sends_nothing",
+ True,
+ [(422, {"type": "invalid_request", "code": "idempotency_key_reused"})],
+ ["workflows"],
+ None,
+ ["transactional email failed"],
+ ),
("workflows_server_error_sends_nothing", True, [503], ["workflows"], None, ["transactional email failed"]),
(
"workflows_accepts_without_message_id_sends_nothing",
diff --git a/products/messaging/backend/models/message_suppression.py b/products/messaging/backend/models/message_suppression.py
index b65b75a0a673..18765cafa2ea 100644
--- a/products/messaging/backend/models/message_suppression.py
+++ b/products/messaging/backend/models/message_suppression.py
@@ -32,6 +32,8 @@ class MessageSuppression(TeamScopedRootMixin, UUIDModel):
The pre-send path consults this list (see the Node `EmailSuppressionService`) and skips
matching recipients. Unlike opt-outs, a suppression is a deliverability signal, not a
messaging preference, so it applies regardless of message category (including transactional).
+ The one exception is a COMPLAINT entry: the recipient objected to our mail, but the address
+ still works, so transactional messages still go out to it.
"""
# db_constraint=False on these hot-table FKs so CreateModel takes no lock on