Skip to content

feat(messaging): refuse transactional sends the email worker would skip - #123019

Merged
trunk-io[bot] merged 2 commits into
masterfrom
posthog/transactional-email-refuse-skipped-sends
Oct 26, 2026
Merged

trunk-io[bot] merged 2 commits into
masterfrom
posthog/transactional-email-refuse-skipped-sends

Conversation

@mayteio

@mayteio mayteio commented Oct 24, 2026

Copy link
Copy Markdown
Contributor

Problem

  • A transactional email API caller gets a 202 for an email that never goes out, and has no way to find out.
  • The email worker skips the send after the 202 when sending is suspended for the project, sending is paused for the workflow, or the recipient is on the suppression list.
  • Why: before the API is released more widely, a caller must learn at send time that an email will not go out.

Changes

  • The send endpoint now returns 422 with a specific code instead of 202 for these three cases. Nothing is queued or billed:
    • sending_suspended
    • sending_paused
    • recipient_suppressed
  • Each error message says how to fix the cause: the Reputation tab, support, or the suppression list.
  • The CDP transactional email route runs these checks next to the existing quota check. A refusal releases the idempotency key, so the same request sends once the cause is fixed.
  • The worker keeps its own checks, because the state can change while a job waits on the queue.
  • Django now maps the CDP refusal by the error code in the body, not by status. A workflow deactivated mid-request now returns 400 transactional_email_paused, not a retryable 503.
  • The internal client in posthog/transactional_email.py exposes the API error code on TransactionalEmailRejected.
  • The Self-driving first-report email cancels on recipient_suppressed. Before, it retried a rejected send on every sweep, so a suppressed address would loop forever.
  • The OpenAPI 422 description lists the new reasons. No generated files change.

How did you test this code?

Test rationale:

  • Node cdp-api.serial.test.ts: added one it.each with a case per refusal. It catches a route that queues a send the worker would skip, or one that keeps the idempotency key after a refusal, which would block the fixed retry.
  • The same block gains afterEach(jest.restoreAllMocks). The quota test's spy leaked into later tests and made them look over quota.
  • Django test_reports_a_send_the_pipeline_refuses: extended with the new codes and not_sendable. It catches a CDP refusal that falls through to 503.
  • Internal client test_confirmed_rejection: one case that catches the API error code being dropped.
  • Signals: test_suppressed_recipient_cancels_the_notification catches the retry loop on a suppressed recipient.

Ran locally: the three Python test modules above, and the transactional email block of the Node test. Not run: the full Node and backend suites, and an end-to-end send through a real worker.

Release status

  • This change is behind a feature flag and is not available to users

Docs update

A posthog.com docs PR for the transactional email API follows, and it documents these codes.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Agent: PostHog Desktop (Claude Code), Claude Opus 5.5

  • Skills invoked: /improving-drf-endpoints, /writing-tests, /writing-code-comments, /writing-pr-descriptions.
  • The assignee asked for this check as part of getting the transactional email API ready for a wider release. They chose to reject skipped sends rather than accept them with a warning.
  • Duplicate search: draft feat(messaging): refuse a transactional email the send checks would skip #121850 covers a broader version of this check, stacked on a send refactor. This PR is a small change that stands alone on master.
  • No customer material is in this PR.

🤖 Generated with Claude Code


Created with PostHog Desktop

The CDP transactional email route now checks project suspension, the
workflow's email pause and the suppression list before it queues a send,
and returns a code for each. Django maps those codes to 422s, and maps a
deactivated workflow to transactional_email_paused instead of a 503.

The internal transactional email client carries the API error code, and
the Self-driving first-report email cancels on recipient_suppressed
instead of retrying on every sweep.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Generated-By: PostHog Desktop
Task-Id: a0274fa0-d9be-48bf-b601-f153decf241d
@mayteio mayteio self-assigned this Oct 24, 2026
@trunk-io

trunk-io Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

😎 Merged successfully - details.

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

🤖 CI report

⚠️ Trunk lane — backend Python lane, mixes lanes

This PR is assigned to the backend Python lane. It runs backend Python tests and may merge in parallel with PRs in other lanes.

This PR changes Python or frontend code (posthog/test/test_transactional_email.py, posthog/transactional_email.py, products/messaging/backend/facade/contracts.py and 5 more) and Node or Rust code (nodejs/src/cdp/cdp-api.serial.test.ts, nodejs/src/cdp/cdp-api.ts, nodejs/src/cdp/services/hogflows/transactional-email.ts) together. In the merge queue, every Node or Rust PR behind it in the same lane then runs the Django and frontend suites too, so the cross-lane check fails. Split it, or add the cross-lane-change label if the halves must land together.

✅ Duplication (Python) — clean

New Python code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.

✅ Duplication (TypeScript) — clean

New TypeScript code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.

⚠️ Comment density — 3% of added code lines are comments (6 of 192)

This section warns when comments are more than 3% of the code lines a PR adds, and alerts above 6%. Before agent-assisted PRs, the typical share was about 2%. Only full-line comments count. Docstrings, generated files, snapshots, migrations, and workflow files are left out.

Comments that restate the code, record how the change came about, or narrate the next line add noise for the next reader. Keep the comments that explain a reason the code cannot show, and remove the rest. See .agents/skills/writing-code-comments/SKILL.md for the house rules.

Files with the most added comment lines:

File Comment lines Added lines
nodejs/src/cdp/cdp-api.ts 3 34
products/messaging/backend/services/transactional_email.py 2 46
products/signals/backend/first_report_notification.py 1 4

This check does not block merging. It updates on every push and clears when the share drops.

⚠️ Playwright — 1 flaky

🎭 Playwright report · View test results →

⚠️ 1 flaky test:

  • Creating a SQL insight with a variable and overriding it on a dashboard (chromium)

These issues are not necessarily caused by your changes.
Annoyed by this section? Help fix flakies and failures and it will go green!

@trunk-io

trunk-io Bot commented Oct 24, 2026 •

Copy link
Copy Markdown

Static Badge   Static Badge   Static Badge

Failed Test Failure Summary Logs
Dashboards › Creating a SQL insight with a variable and overriding it on a dashboard The test exceeded the maximum allowed time and timed out. Logs ↗︎

View Full Report ↗︎ ⋅ Docs

@mayteio mayteio added cross-lane-change Allow for cross lane (i.e. django + rust) changes to merge at once reviewhog labels Oct 24, 2026

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 77ff839: 1 Should fix.

This Standard review started from the posthog-review label. Comment @posthog review --deep for a Deep review, or @posthog help to see all commands.

See this review and its findings in PostHog Review.

"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.",
),
"not_sendable": (TransactionalEmailPaused, "The template's transactional email isn't active."),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 · Return the refusal code from Node for inactive workflows

When a workflow is deactivated after Django's check, Node returns error: 'Workflow is not an active transactional email', not not_sendable. This new mapping never matches, so the API still returns retryable 503 instead of 400 transactional_email_paused. Return the machine code from Node and make the test exercise that actual response.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 36cf68b: Node now returns { error: 'not_sendable' } for an inactive or non-API workflow, and the Node test asserts that body, so it matches the Django mapping.

@posthog posthog Bot removed the reviewhog label Oct 24, 2026
…al workflows

Django maps a CDP refusal by the `error` code in the body. The inactive-workflow branch returned a sentence, so the mapping to transactional_email_paused never matched and the API fell back to a retryable 503.

Generated-By: PostHog Desktop
Task-Id: e466108a-be48-4e99-ac1a-d2523810860c
@mayteio
mayteio marked this pull request as ready for review October 26, 2026 10:19
@parameterai

parameterai Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

Risk: No findings

This change makes the transactional email pipeline refuse sends up front (422 with a stable code) for suspension, pause, and suppression instead of accepting them with a 202 the worker then silently skips, and teaches the Django wrapper, internal client, and the signals first-report sweep to react to the new codes. I found no security vulnerabilities introduced: the new checks run after the scoped-JWT and team/workflow scoping on the CDP route, the lookups are parameterized, the idempotency-key release on refusal is correctly guarded against freeing another request's reservation, and the refusal-code mapping cannot turn a non-retryable state into caller-visible confusion beyond what the codes describe.

Sentinel reviewed 36cf68b · Review settings

@pr-assigner-resolver-posthog
pr-assigner-resolver-posthog Bot requested review from a team October 26, 2026 10:20

@stamphog stamphog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved.

Risky API and write-path changes have assurance through owning-team authorship and STRONG familiarity, with focused regression tests. The older bot concern is fixed in the current code and covered by matching Node and Django assertions; no outstanding substantive concerns remain.

  • Author wrote 86% of the modified lines and has 64 merged PRs in these paths (familiarity STRONG).
Gate mechanics and policy version
Gate Result
prerequisites ✓ all clear
deny-list ✓ no deny categories matched
size ✓ 150L, 7F substantive, 244L/11F incl. docs/generated/snapshots — within ceiling
tier ✓ T1-agent / T1d-complex (244L, 11F, cross-cutting, feat)
stamphog 2.6.1 .stamphog/policy.yml @ 36cf68b · reviewed head 36cf68b

mayteio commented Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

/trunk merge

@trunk-io
trunk-io Bot merged commit 02ce58f into master Oct 26, 2026
361 of 412 checks passed
@trunk-io
trunk-io Bot deleted the posthog/transactional-email-refuse-skipped-sends branch October 26, 2026 11:25
@deployment-status-posthog

deployment-status-posthog Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

Deploy status

Environment Status Deployed At Workflow
dev ✅ Deployed 2026-10-26 11:58 UTC Run
prod-us ✅ Deployed 2026-10-26 12:10 UTC Run
prod-eu ✅ Deployed 2026-10-26 12:10 UTC Run

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cross-lane-change Allow for cross lane (i.e. django + rust) changes to merge at once

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant