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): refuse a transactional email to a recipient that can't receive email (#123878)

Harley Alexander375a26098e78
diff --git a/nodejs/src/cdp/cdp-api.serial.test.ts b/nodejs/src/cdp/cdp-api.serial.test.ts
index 2132938a4b3c..233988af94a2 100644
--- a/nodejs/src/cdp/cdp-api.serial.test.ts
+++ b/nodejs/src/cdp/cdp-api.serial.test.ts
@@ -2152,6 +2152,8 @@ describe('CDP API', () => {
mockQueueInvocations = jest.fn().mockResolvedValue(undefined)
api['hogflowQueue'] = { queueInvocations: mockQueueInvocations } as any
hogFlow = await insertHogFlow(transactionalFlow('api', 'active'))
+ // The fixtures send to example.com, which publishes a null MX. Without this every send is refused.
+ jest.spyOn(api['emailValidationService'], 'getRecipientSkipReason').mockResolvedValue(null)
})
afterEach(() => {
@@ -2311,6 +2313,14 @@ describe('CDP API', () => {
'recipient_suppressed',
() => jest.spyOn(api['emailSuppressionService'], 'isSuppressed').mockResolvedValueOnce(true),
],
+ [
+ "the recipient's domain has no mail servers",
+ 'recipient_unreachable',
+ () =>
+ jest
+ .spyOn(api['emailValidationService'], 'getRecipientSkipReason')
+ .mockResolvedValueOnce('Skipping send: the domain has no reachable mail servers.'),
+ ],
] as const)('refuses a send the email worker would skip because %s', async (_desc, code, refuse) => {
refuse()
const refusedBefore = await outcomeCount(code)
diff --git a/nodejs/src/cdp/cdp-api.ts b/nodejs/src/cdp/cdp-api.ts
index f9e7bb144bd0..225ea19ba3c3 100644
--- a/nodejs/src/cdp/cdp-api.ts
+++ b/nodejs/src/cdp/cdp-api.ts
@@ -66,6 +66,7 @@ import { TeamWorkflowsConfigService } from './services/managers/team-workflows-c
import { EMAIL_QUEUE_PRIORITY } from './services/messaging/email-priority'
import { EmailSuppressionService } from './services/messaging/email-suppression.service'
import { EmailTrackingService } from './services/messaging/email-tracking.service'
+import { EmailValidationService } from './services/messaging/email-validation.service'
import { EmailTrackingCodeSigner } from './services/messaging/helpers/tracking-code'
import { RecipientTokensService } from './services/messaging/recipient-tokens.service'
import { HogFunctionMonitoringService } from './services/monitoring/hog-function-monitoring.service'
@@ -198,6 +199,7 @@ export class CdpApi {
private transactionalEmailJwt: ScopedServiceJwt
private transactionalEmailIdempotencyKeys: IdempotencyKeys
private emailSuppressionService: EmailSuppressionService
+ private emailValidationService: EmailValidationService
private teamWorkflowsConfigService: TeamWorkflowsConfigService
private hogFunctionMonitoringService: HogFunctionMonitoringService
private resumeBatchJwt: ScopedServiceJwt
@@ -214,6 +216,7 @@ export class CdpApi {
this.hogFlowManager = services.hogFlowManager
this.recipientTokensService = services.recipientTokensService
this.emailSuppressionService = services.emailSuppressionService
+ this.emailValidationService = services.emailValidationService
this.teamWorkflowsConfigService = services.teamWorkflowsConfigService
this.hogExecutorAsync = services.hogExecutorAsync
this.hogInputsService = services.hogInputsService
@@ -1302,6 +1305,10 @@ export class CdpApi {
if (isLimited) {
return { outcome: 'quota_limited', status: 429 }
}
+ // Last, because a cache miss costs a DNS lookup. A DNS failure lets the send through.
+ if (await this.emailValidationService.getRecipientSkipReason(teamId, to)) {
+ return { outcome: 'recipient_unreachable', status: 422 }
+ }
return null
}
diff --git a/nodejs/src/cdp/cdp-services.ts b/nodejs/src/cdp/cdp-services.ts
index 27b2a785b8ac..47643b470597 100644
--- a/nodejs/src/cdp/cdp-services.ts
+++ b/nodejs/src/cdp/cdp-services.ts
@@ -98,6 +98,7 @@ export interface CdpCoreServices {
recipientsManager: RecipientsManagerService
recipientPreferencesService: RecipientPreferencesService
emailSuppressionService: EmailSuppressionService
+ emailValidationService: EmailValidationService
teamWorkflowsConfigService: TeamWorkflowsConfigService
/** Point lookups for realtime/behavioral cohort membership (behavioral cohorts DB). */
cohortMembershipRepository: CohortMembershipRepository
@@ -596,6 +597,7 @@ export function createCdpCoreServices(
recipientsManager,
recipientPreferencesService,
emailSuppressionService,
+ emailValidationService,
teamWorkflowsConfigService,
cohortMembershipRepository,
hogFlowExecutor,
diff --git a/nodejs/src/cdp/services/hogflows/transactional-email.ts b/nodejs/src/cdp/services/hogflows/transactional-email.ts
index 7fae3a6489b5..5e92bc1f38c2 100644
--- a/nodejs/src/cdp/services/hogflows/transactional-email.ts
+++ b/nodejs/src/cdp/services/hogflows/transactional-email.ts
@@ -27,6 +27,7 @@ export type TransactionalEmailOutcome =
| 'sending_suspended'
| 'sending_paused'
| 'recipient_suppressed'
+ | 'recipient_unreachable'
| 'error'
export const transactionalEmailRequestsTotal = new Counter({
diff --git a/nodejs/src/cdp/services/messaging/email-validation.service.ts b/nodejs/src/cdp/services/messaging/email-validation.service.ts
index a74baae00586..3d9f675ddb2f 100644
--- a/nodejs/src/cdp/services/messaging/email-validation.service.ts
+++ b/nodejs/src/cdp/services/messaging/email-validation.service.ts
@@ -104,12 +104,20 @@ export class EmailValidationService {
// EmailService skips a missing recipient at send time and records email_missing_recipient.
return null
}
+ return this.getRecipientSkipReason(invocation.teamId, rawEmail)
+ }
+
+ /**
+ * The same check for one recipient address, without a workflow action. The transactional email
+ * API runs it before it answers, so the caller learns that the send would be skipped.
+ */
+ public async getRecipientSkipReason(teamId: number, rawEmail: string): Promise<string | null> {
const email = rawEmail.trim()
if (!EMAIL_SYNTAX_RE.test(email)) {
cdpEmailMxValidationTotal.inc({ result: 'invalid_syntax' })
return this.skip(
- invocation.teamId,
+ teamId,
'invalid_syntax',
`Skipping send: "${email}" is not a valid email address, so it would hard bounce.`
)
@@ -124,12 +132,12 @@ export class EmailValidationService {
const domain = domainToASCII(rawDomain) || rawDomain.toLowerCase()
// Above resolveDeliverability on purpose: one verdict is cached and shared across teams for
// up to a day, so a check inside the lookup would miss every send that hits the cache.
- noteOobDomain(domain, 'node_email_validation', { teamId: invocation.teamId })
+ noteOobDomain(domain, 'node_email_validation', { teamId })
const deliverable = await this.resolveDeliverability(domain)
if (!deliverable) {
return this.skip(
- invocation.teamId,
+ teamId,
'invalid_domain',
`Skipping send: the domain "${domain}" has no reachable mail servers, so this message would hard bounce.`
)
diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index 3cf3222bb4d7..666cdc1dea14 100644
--- a/products/messaging/backend/facade/contracts.py
+++ b/products/messaging/backend/facade/contracts.py
@@ -92,6 +92,10 @@ class RecipientSuppressed(TransactionalEmailError):
code = "recipient_suppressed"
+class RecipientUnreachable(TransactionalEmailError):
+ code = "recipient_unreachable"
+
+
class DeliveryUnavailable(Exception):
"""The email pipeline did not accept the send. Safe to retry."""
diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 07a1880036b2..81d76a8562d5 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -441,6 +441,7 @@ class TransactionalEmailRejected(exceptions.APIException):
"sending_suspended": 422,
"sending_paused": 422,
"recipient_suppressed": 422,
+ "recipient_unreachable": 422,
}
# The caller has to change the request. Without this the error handler reports a server error.
default_type = "invalid_request"
@@ -733,9 +734,9 @@ class MessageTemplatesViewSet(
404: OpenApiResponse(description="Template not found"),
409: OpenApiResponse(description="A request with the same Idempotency-Key is still in progress"),
422: OpenApiResponse(
- description="The email can't go out: the recipient is suppressed, sending is suspended for the "
- "project or paused for this transactional email, or the Idempotency-Key was already used for a "
- "different request"
+ description="The email can't go out: the recipient is suppressed or can't receive email, sending is "
+ "suspended for the project or paused for this transactional email, or the Idempotency-Key was already "
+ "used for a different request"
),
429: OpenApiResponse(description="Rate limited, or the project is over its email quota"),
503: OpenApiResponse(description="The email pipeline did not confirm the send"),
diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.py
index de1fdf7b6c63..e899d1abdde2 100644
--- a/products/messaging/backend/services/transactional_email.py
+++ b/products/messaging/backend/services/transactional_email.py
@@ -26,6 +26,7 @@ from products.messaging.backend.facade.contracts import (
QueuedEmail,
QuotaLimited,
RecipientSuppressed,
+ RecipientUnreachable,
SenderUnavailable,
SendingPaused,
SendingSuspended,
@@ -77,6 +78,11 @@ PIPELINE_REFUSALS: dict[str, tuple[type[TransactionalEmailError], str]] = {
"The recipient is on this project's suppression list after a hard bounce or a spam complaint, so the "
"email can't be sent. Remove the address from the suppression list if it can receive email again.",
),
+ "recipient_unreachable": (
+ RecipientUnreachable,
+ "The recipient's address can't receive email: it isn't a valid address, or its domain has no mail servers, "
+ "so the email would bounce. Check the address for a typo.",
+ ),
"not_sendable": (TransactionalEmailPaused, "The template's transactional email isn't active."),
}
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 8d06d53df075..2b6766bb4c24 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -261,6 +261,7 @@ class TestTransactionalEmail(APIBaseTest):
("sending_suspended", 422, 422, "sending_suspended"),
("sending_paused", 422, 422, "sending_paused"),
("recipient_suppressed", 422, 422, "recipient_suppressed"),
+ ("recipient_unreachable", 422, 422, "recipient_unreachable"),
("not_sendable", 400, 400, "transactional_email_paused"),
]
)