: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
import { Counter } from 'prom-client'
import { PostgresRouter, PostgresUse } from '~/common/utils/db/postgres'
import { LazyLoader } from '~/common/utils/lazy-loader'
import { logger } from '~/common/utils/logger'
import { isValidTeamId } from '~/common/utils/team-manager'
const cdpEmailSuppressionTotal = new Counter({
name: 'cdp_email_suppression_total',
help: 'Email suppression-list outcomes. `suppressed_hit` = a send skipped because the recipient is on the list; `transient_bounce` = a soft-bounce counter increment; `hard_bounce` = an address suppressed immediately after a permanent bounce; `complaint` = an address suppressed immediately after a spam complaint; `global_hard_bounce` = an address added to the global hard-bounce list; `global_hard_bounce_cleared` = an address removed from that list after a delivery; `global_hard_bounce_hit` = a send skipped because of that list; `global_hard_bounce_shadow_hit` = a send that list would skip once enforced.',
labelNames: ['result'],
})
const DIAGNOSTIC_MAX_LENGTH = 1000
const normalizeIdentifier = (email: string): string => email.trim().toLowerCase()
const toKey = (teamId: number, identifier: string): string => `${teamId}:${identifier}`
export type EmailSuppressionConfig = {
// Consecutive soft bounces before auto-suppression.
transientBounceThreshold: number
globalHardBounceEnforce?: boolean
}
// Test helper — production paths take config from `CdpConfig`; tests that still mutate process.env
// can call this to construct the same shape without duplicating the parse logic.
export function emailSuppressionConfigFromEnv(): EmailSuppressionConfig {
const rawThreshold = process.env.EMAIL_SUPPRESSION_TRANSIENT_BOUNCE_THRESHOLD
const parsedThreshold = rawThreshold ? parseInt(rawThreshold, 10) : NaN
return {
transientBounceThreshold: Number.isFinite(parsedThreshold) && parsedThreshold > 0 ? parsedThreshold : 5,
}
}
export type SuppressionCheckOptions = {
// 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
}
// `unlisted`: no active row on the team's list. `allowsTransactional`: an active row that lets transactional
// email through. `copy`: a row this service copied from the global list, which only holds while the global entry does.
type GlobalCandidate = {
key: string
teamId: number
identifier: string
kind: 'unlisted' | 'allowsTransactional' | 'copy'
}
// An active suppression. It blocks transactional email only when the address hard-bounced.
type SuppressionEntry = { blocksTransactional: boolean; global?: 'shadow' | 'enforce' }
const HARD_BOUNCE_REASON = 'Auto-suppressed after a hard bounce'
// Like the SES global list, an entry expires so a recovered mailbox is retried; a team's own list stays permanent.
const GLOBAL_HARD_BOUNCE_IS_HELD = `last_bounced_at + LEAST(
GREATEST(last_bounced_at - first_bounced_at, INTERVAL '1 day'), INTERVAL '14 days') > NOW()`
const GLOBAL_HARD_BOUNCE_DIAGNOSTIC = "This address doesn't exist. An earlier email to it hard-bounced."
// 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`.
*
* Read path (pre-send): `isSuppressed` is consulted before every email send so we skip
* addresses that can't (or shouldn't) receive mail. Cached via LazyLoader so a big batch to the
* same recipients doesn't hammer Postgres.
*
* Write path (SES webhook): `recordTransientBounces` counts consecutive soft bounces per address
* and flips it to suppressed once the count crosses the threshold; `recordDeliveries` resets the
* count on any successful delivery so a one-off outage never accumulates into a suppression.
* `recordHardBounces` and `recordComplaints` suppress an address immediately — a permanent bounce
* or a spam complaint is definitive. Manual entries (added via the API/UI) are never touched by
* any of this bookkeeping.
*
* Cache invalidation window (v1):
* The LazyLoader cache is per-process. `clear()` only fires on the Node process that performed
* the write, so manual add/remove via the Django API (which never touches Node) and bounce writes
* handled by a different worker won't invalidate other workers' caches immediately. Effect:
* suppression state can be stale for up to LazyLoader's refresh window (~5 minutes) on other pods.
* The pre-send check may allow a send to a just-suppressed address, or block a send to a
* just-removed one, for that window. Acceptable for v1 given the low rate of state changes; a
* follow-up should propagate invalidations via pubsub (see `IntegrationManagerService` for the
* pattern) if the staleness becomes a support issue.
*/
export class EmailSuppressionService {
private readonly threshold: number
private readonly globalHardBounceEnforce: 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.globalHardBounceEnforce = config.globalHardBounceEnforce ?? false
this.lazyLoader = new LazyLoader<SuppressionEntry | false>({
name: 'email_suppression',
loader: async (keys) => await this.loadSuppressed(keys),
})
}
public clear(): void {
this.lazyLoader.clear()
}
/** 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 entry = (await this.lazyLoader.get(toKey(teamId, identifier))) ?? false
if (entry !== false && entry.global === 'shadow') {
cdpEmailSuppressionTotal.inc({ result: 'global_hard_bounce_shadow_hit' })
return false
}
const suppressed = entry !== false && (!transactional || entry.blocksTransactional)
if (suppressed) {
cdpEmailSuppressionTotal.inc({ result: entry.global ? 'global_hard_bounce_hit' : 'suppressed_hit' })
}
return suppressed
} catch (error) {
// Fail open: a lookup error must never block a legitimate send.
logger.error('[EmailSuppression] Failed to check suppression', { teamId, error })
return false
}
}
/**
* Record one or more soft (Transient) bounces. Increments each address's consecutive-bounce
* counter and auto-suppresses it in the same statement once it reaches the threshold. Manual
* entries keep their suppressed state untouched, and complaint entries keep their reason.
*/
public async recordTransientBounces(teamId: number, emails: string[], diagnostic?: string): Promise<void> {
const identifiers = Array.from(new Set(emails.map(normalizeIdentifier).filter(Boolean)))
if (identifiers.length === 0) {
return
}
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, legacy reasons,
// then one identifier per row.
const valueClauses: string[] = []
const params: (number | string | string[] | null)[] = [
teamId,
reason,
this.threshold,
diag,
LEGACY_HARD_BOUNCE_REASONS,
GLOBAL_HARD_BOUNCE_DIAGNOSTIC,
]
identifiers.forEach((identifier, i) => {
const p = params.length + 1 + i
// gen_random_uuid() for the id, mirroring RecipientsManagerService.optOut. First bounce
// starts the count at 1 and only suppresses immediately if the threshold is 1.
valueClauses.push(
`(gen_random_uuid(), $1, $${p}, 'BOUNCE', NULL, 1, NOW(), $4, (1 >= $3), CASE WHEN 1 >= $3 THEN NOW() ELSE NULL END, false, NOW(), NOW())`
)
})
params.push(...identifiers)
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)
VALUES ${valueClauses.join(', ')}
ON CONFLICT (team_id, identifier) DO UPDATE SET
transient_bounce_count = posthog_messagesuppression.transient_bounce_count + 1,
last_bounce_at = NOW(),
-- The diagnostic marks a copy of a global hard bounce, which a delivery must still be able to release.
last_bounce_diagnostic = CASE
WHEN posthog_messagesuppression.source = 'BOUNCE'
AND posthog_messagesuppression.last_bounce_diagnostic = $6
THEN posthog_messagesuppression.last_bounce_diagnostic
ELSE EXCLUDED.last_bounce_diagnostic END,
-- Never downgrade or re-key a manual entry; only auto (BOUNCE) rows can cross the threshold.
suppressed = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.suppressed
WHEN posthog_messagesuppression.transient_bounce_count + 1 >= $3 THEN true
ELSE posthog_messagesuppression.suppressed END,
suppressed_at = CASE
WHEN posthog_messagesuppression.source <> 'MANUAL'
AND posthog_messagesuppression.suppressed = false
AND posthog_messagesuppression.transient_bounce_count + 1 >= $3 THEN NOW()
ELSE posthog_messagesuppression.suppressed_at END,
-- Same precedence as the hard-bounce path: a COMPLAINT row keeps its reason so it
-- can't end up labelled COMPLAINT while reading as a soft-bounce suppression.
reason = CASE
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'
AND posthog_messagesuppression.transient_bounce_count + 1 >= $3 THEN false
ELSE posthog_messagesuppression.deleted END,
updated_at = NOW()
`
try {
await this.postgres.query(PostgresUse.COMMON_WRITE, query, params, 'recordTransientBounces')
cdpEmailSuppressionTotal.inc({ result: 'transient_bounce' }, identifiers.length)
// Only invalidate the keys we touched — cross-team entries stay warm.
this.lazyLoader.markForRefresh(identifiers.map((identifier) => toKey(teamId, identifier)))
} catch (error) {
logger.error('[EmailSuppression] Failed to record transient bounces', { teamId, error })
}
}
/**
* Record one or more hard (Permanent) bounces. Suppresses each address immediately — no
* threshold, no counter — because a permanent bounce is definitive. Manual entries are never
* touched. If a row already exists as an unsuppressed BOUNCE counter, this escalates it. A row
* that a complaint already claimed keeps its source and reason, so the bounce refreshes the
* diagnostic without relabelling why the address is suppressed.
*/
public async recordHardBounces(teamId: number, emails: string[], diagnostic?: string): Promise<void> {
const identifiers = Array.from(new Set(emails.map(normalizeIdentifier).filter(Boolean)))
if (identifiers.length === 0) {
return
}
try {
await this.upsertHardBounces(teamId, identifiers, diagnostic)
cdpEmailSuppressionTotal.inc({ result: 'hard_bounce' }, identifiers.length)
// Only invalidate the keys we touched — cross-team entries stay warm.
this.lazyLoader.markForRefresh(identifiers.map((identifier) => toKey(teamId, identifier)))
} catch (error) {
logger.error('[EmailSuppression] Failed to record hard bounces', { teamId, error })
}
}
private async upsertHardBounces(
teamId: number,
identifiers: string[],
diagnostic?: string,
{ keepRemoved = false }: { keepRemoved?: boolean } = {}
): Promise<void> {
const diag = diagnostic ? diagnostic.slice(0, DIAGNOSTIC_MAX_LENGTH) : null
// Params: teamId, reason, diag, then one identifier per row.
const valueClauses: string[] = []
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(), NOW())`
)
})
params.push(...identifiers)
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,
hard_bounced_at)
VALUES ${valueClauses.join(', ')}
ON CONFLICT (team_id, identifier) DO UPDATE SET
last_bounce_at = NOW(),
last_bounce_diagnostic = EXCLUDED.last_bounce_diagnostic,
-- Manual entries are authoritative; never override them.
suppressed = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.suppressed
ELSE true END,
suppressed_at = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.suppressed_at
WHEN posthog_messagesuppression.suppressed = false THEN NOW()
ELSE posthog_messagesuppression.suppressed_at 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
-- other. The bounce still refreshes the diagnostic and the suppression state above.
reason = CASE
WHEN posthog_messagesuppression.source IN ('MANUAL', 'COMPLAINT') THEN posthog_messagesuppression.reason
ELSE EXCLUDED.reason END,
-- A provably-undeliverable address coming back un-deletes itself.
deleted = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.deleted
ELSE false END,
updated_at = NOW()
${keepRemoved ? 'WHERE NOT posthog_messagesuppression.deleted' : ''}
`
await this.postgres.query(PostgresUse.COMMON_WRITE, query, params, 'recordHardBounces')
}
/** Only for a bounce that proves the address does not exist, or one team could block valid addresses for all. */
public async recordGlobalHardBounces(emails: string[], bounceTimestamp?: string): Promise<void> {
const identifiers = Array.from(new Set(emails.map(normalizeIdentifier).filter(Boolean)))
if (identifiers.length === 0) {
return
}
// Store when SES saw the bounce, because the bounce and delivery webhooks can arrive in either order.
const valueClauses = identifiers.map(
(_, i) => `($${i + 2}, COALESCE($1::timestamptz, NOW()), COALESCE($1::timestamptz, NOW()))`
)
try {
await this.postgres.query(
PostgresUse.COMMON_WRITE,
`INSERT INTO posthog_emailhardbounce (email, first_bounced_at, last_bounced_at)
VALUES ${valueClauses.join(', ')}
ON CONFLICT (email) DO UPDATE SET
first_bounced_at = LEAST(posthog_emailhardbounce.first_bounced_at, EXCLUDED.first_bounced_at),
last_bounced_at = GREATEST(posthog_emailhardbounce.last_bounced_at, EXCLUDED.last_bounced_at)`,
[bounceTimestamp ?? null, ...identifiers],
'recordGlobalHardBounces'
)
cdpEmailSuppressionTotal.inc({ result: 'global_hard_bounce' }, identifiers.length)
} catch (error) {
logger.error('[EmailSuppression] Failed to record global hard bounces', { error })
}
}
/**
* Record one or more spam complaints. Suppresses each address immediately — no threshold —
* because a complaint is the recipient asking us to stop, and provider complaint-rate
* thresholds are far tighter than bounce thresholds. Manual entries are never touched; any
* other existing row is re-keyed to COMPLAINT so the list shows the operative reason. The
* bounce paths then treat COMPLAINT as authoritative, so a later bounce can't relabel the row.
*/
public async recordComplaints(teamId: number, emails: string[], feedbackType?: string): Promise<void> {
const identifiers = Array.from(new Set(emails.map(normalizeIdentifier).filter(Boolean)))
if (identifiers.length === 0) {
return
}
// The feedback type is the provider's classification of the report (e.g. "abuse",
// "fraud"); surface it in the reason for operator visibility.
const reason = feedbackType
? `Auto-suppressed after a spam complaint (feedback type: ${feedbackType.slice(0, 100)})`
: 'Auto-suppressed after a spam complaint'
// Params: teamId, reason, legacy reasons, then one identifier per row.
const valueClauses: string[] = []
const params: (number | string | string[] | null)[] = [teamId, reason, LEGACY_HARD_BOUNCE_REASONS]
identifiers.forEach((identifier, i) => {
const p = params.length + 1 + i
valueClauses.push(
`(gen_random_uuid(), $1, $${p}, 'COMPLAINT', $2, 0, NULL, NULL, true, NOW(), false, NOW(), NOW())`
)
})
params.push(...identifiers)
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)
VALUES ${valueClauses.join(', ')}
ON CONFLICT (team_id, identifier) DO UPDATE SET
-- Manual entries are authoritative; never override them. Any other row re-keys to
-- COMPLAINT: the complaint is the operative reason the address is suppressed now.
source = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.source
ELSE 'COMPLAINT' END,
suppressed = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.suppressed
ELSE true END,
suppressed_at = CASE
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.suppressed_at
WHEN posthog_messagesuppression.suppressed = false THEN NOW()
ELSE posthog_messagesuppression.suppressed_at END,
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
WHEN posthog_messagesuppression.source = 'MANUAL' THEN posthog_messagesuppression.deleted
ELSE false END,
updated_at = NOW()
`
try {
await this.postgres.query(PostgresUse.COMMON_WRITE, query, params, 'recordComplaints')
cdpEmailSuppressionTotal.inc({ result: 'complaint' }, identifiers.length)
// Only invalidate the keys we touched — cross-team entries stay warm.
this.lazyLoader.markForRefresh(identifiers.map((identifier) => toKey(teamId, identifier)))
} catch (error) {
logger.error('[EmailSuppression] Failed to record complaints', { teamId, error })
}
}
/**
* 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.
*
* `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
* erase a fresh bounce for a newer send. Reset only when the delivery is newer than the last
* recorded bounce.
*/
public async recordDeliveries(
teamId: number,
emails: string[],
deliveryTimestamp?: string,
{ clearGlobal = false }: { clearGlobal?: boolean } = {}
): Promise<void> {
const identifiers = Array.from(new Set(emails.map(normalizeIdentifier).filter(Boolean)))
if (identifiers.length === 0) {
return
}
// Fail closed on a missing delivery timestamp: without one we can't prove the delivery is
// newer than the last bounce, so leave the counter alone rather than risk erasing a fresh
// bounce. In practice the SES Delivery schema requires a timestamp, so this branch only
// guards against a caller that forgets to pass it.
const query = `
UPDATE posthog_messagesuppression
SET transient_bounce_count = 0, updated_at = NOW()
WHERE team_id = $1
AND identifier = ANY($2)
AND source <> 'MANUAL'
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))
`
try {
await this.postgres.query(
PostgresUse.COMMON_WRITE,
query,
[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 })
}
if (!clearGlobal) {
return
}
// A delivery proves the address exists. The timestamp guard stops a late, older delivery from
// clearing a fresh bounce.
try {
const result = await this.postgres.query(
PostgresUse.COMMON_WRITE,
`DELETE FROM posthog_emailhardbounce
WHERE email = ANY($1)
AND $2::timestamptz IS NOT NULL
AND last_bounced_at < $2::timestamptz`,
[identifiers, deliveryTimestamp ?? null],
'clearGlobalHardBounces'
)
if (result.rowCount) {
cdpEmailSuppressionTotal.inc({ result: 'global_hard_bounce_cleared' }, result.rowCount)
}
} catch (error) {
logger.error('[EmailSuppression] Failed to clear global hard bounces on delivery', { teamId, error })
}
}
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) => {
const idx = key.indexOf(':')
return { key, teamId: Number(key.slice(0, idx)), identifier: key.slice(idx + 1) }
})
// Group by team_id so we run one indexed `identifier = ANY(...)` scan per team instead of an
// OR-chain of paired lookups. Same UNIQUE (team_id, identifier) index, cheaper plan and
// prepared-statement reuse — matters when the LazyLoader coalesces many keys in a batch.
// In practice most batches are single-team (one workflow, one team), so this is almost
// always a single query regardless of batch size.
const byTeam = new Map<number, string[]>()
for (const p of parsed) {
if (!isValidTeamId(p.teamId)) {
continue
}
const list = byTeam.get(p.teamId) ?? []
list.push(p.identifier)
byTeam.set(p.teamId, list)
}
const entries = new Map<string, SuppressionEntry>()
// A removed row is the team's override of the global list, so it is never a candidate.
const candidates: GlobalCandidate[] = []
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
deleted: boolean
is_global_copy: boolean
blocks_transactional: boolean
}>(
PostgresUse.COMMON_READ,
`SELECT identifier,
deleted,
COALESCE(source = 'BOUNCE' AND last_bounce_diagnostic = $4, false) AS is_global_copy,
-- 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 (deleted = true OR suppressed = true)`,
[teamId, identifiers, LEGACY_HARD_BOUNCE_REASONS, GLOBAL_HARD_BOUNCE_DIAGNOSTIC],
'loadSuppressed'
)
const listed = new Set<string>()
for (const row of result.rows) {
listed.add(row.identifier)
if (row.deleted) {
continue
}
const key = toKey(teamId, row.identifier)
entries.set(key, { blocksTransactional: row.blocks_transactional })
if (row.is_global_copy) {
candidates.push({ key, teamId, identifier: row.identifier, kind: 'copy' })
} else if (!row.blocks_transactional) {
candidates.push({ key, teamId, identifier: row.identifier, kind: 'allowsTransactional' })
}
}
for (const identifier of identifiers) {
if (!listed.has(identifier)) {
candidates.push({ key: toKey(teamId, identifier), teamId, identifier, kind: 'unlisted' })
}
}
}
if (candidates.length > 0) {
await this.applyGlobalHardBounces(candidates, entries)
}
// Default every requested key to false so the LazyLoader caches negatives too.
return Object.fromEntries(parsed.map((p) => [p.key, entries.get(p.key) ?? false]))
}
private async applyGlobalHardBounces(
candidates: GlobalCandidate[],
entries: Map<string, SuppressionEntry>
): Promise<void> {
let bounced: Set<string>
try {
const result = await this.postgres.query<{ email: string }>(
PostgresUse.COMMON_READ,
`SELECT email FROM posthog_emailhardbounce WHERE email = ANY($1) AND ${GLOBAL_HARD_BOUNCE_IS_HELD}`,
[Array.from(new Set(candidates.map((c) => c.identifier)))],
'loadGlobalHardBounces'
)
bounced = new Set(result.rows.map((row) => row.email))
} catch (error) {
// Fail open, like the rest of the pre-send check, and keep the team's own list.
logger.error('[EmailSuppression] Failed to check global hard bounces', { error })
return
}
const hitsByTeam = new Map<number, string[]>()
const releasesByTeam = new Map<number, string[]>()
for (const { key, teamId, identifier, kind } of candidates) {
if (kind === 'copy') {
if (!bounced.has(identifier)) {
entries.delete(key)
releasesByTeam.set(teamId, [...(releasesByTeam.get(teamId) ?? []), identifier])
} else if (!this.globalHardBounceEnforce) {
entries.set(key, { blocksTransactional: false, global: 'shadow' })
}
continue
}
if (!bounced.has(identifier)) {
continue
}
if (kind === 'allowsTransactional') {
// The team's own list already blocks other email, so only transactional email changes.
if (this.globalHardBounceEnforce) {
entries.set(key, { blocksTransactional: true })
}
continue
}
if (!this.globalHardBounceEnforce) {
entries.set(key, { blocksTransactional: false, global: 'shadow' })
continue
}
entries.set(key, { blocksTransactional: true, global: 'enforce' })
hitsByTeam.set(teamId, [...(hitsByTeam.get(teamId) ?? []), identifier])
}
// The copy lets the team see and remove the address. The read can lag the primary, so it never
// touches a row the team removed meanwhile.
for (const [teamId, identifiers] of hitsByTeam) {
try {
await this.upsertHardBounces(teamId, identifiers, GLOBAL_HARD_BOUNCE_DIAGNOSTIC, { keepRemoved: true })
} catch (error) {
logger.error('[EmailSuppression] Failed to copy global hard bounces to the team list', {
teamId,
error,
})
}
}
// The WHERE clause re-checks the row is still an untouched copy, because a real bounce can land
// between the read and this write.
for (const [teamId, identifiers] of releasesByTeam) {
try {
await this.postgres.query(
PostgresUse.COMMON_WRITE,
`UPDATE posthog_messagesuppression
SET suppressed = false, hard_bounced_at = NULL, reason = NULL,
last_bounce_diagnostic = NULL, updated_at = NOW()
WHERE team_id = $1
AND identifier = ANY($2)
AND source = 'BOUNCE'
AND last_bounce_diagnostic = $3
AND deleted = false`,
[teamId, identifiers, GLOBAL_HARD_BOUNCE_DIAGNOSTIC],
'releaseGlobalHardBounceCopies'
)
} catch (error) {
logger.error('[EmailSuppression] Failed to release copied global hard bounces', { teamId, error })
}
}
}
}