Skip to content

refactor(cdp): move the email send checks into one send policy - #121083

Closed
Silthus wants to merge 23 commits into
PostHog:masterfrom
Silthus:feat/email-send-policy
Closed

Silthus wants to merge 23 commits into
PostHog:masterfrom
Silthus:feat/email-send-policy

Conversation

@Silthus

@Silthus Silthus commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem

  • The checks that decide whether an email may go out (team suspension, workflow pause, sender, suppression) live inside the email worker's send method, and suppression is checked twice with two copies of the lookup.
  • The transactional email API needs the same checks before it answers 202, so a 202 never hides a send the worker later skips (contract #120921, "Errors"). It can't reuse checks that are woven into the worker's send.
  • Map: Silthus/posthog#461, slice 02 of strand Silthus/posthog#535. A mechanical refactor with no behavior change.

Stacked on #118924. This fork PR targets master, so the diff here includes #118924. This layer alone: spec/code-managed-templates...feat/email-send-policy.

Impact

Pays into Grow Workflows through billed workflows_emails actions per paying org, by way of the code-content send API this refactor prepares. Not measured yet as a monthly count. In scope: Messaging, email API sends. Expected move: none from this PR alone. Run cost: n/a.

Merge Danger

Warning

🟡 Merge risk: medium · one-way door (merge-risk rubric)

  • The change sits on the email worker's send path for every workflow email. Wrong wiring could skip a suppression or suspension check, and a sent email cannot be unsent.
  • The existing delivery tests keep every case: email.service.test.ts, recipient-preferences.service.test.ts and hog_function.test.ts. The one added case is a suppressed-cc row in the missing-recipient table.
  • No shadow diff compares base and head over the same sends, so the no-behavior-change claim rests on those suites.

Changes

Kind Files Lines
Production 3 +270 −166
Tests 2 +142 −4
Total (this layer) 5 +412 −170
  • New EmailSendPolicy.check(send) in nodejs/src/cdp/services/messaging/email-send-policy.ts. Admission and delivery run the same checks, so check takes no phase.
  • It runs, in today's order: team suspension, workflow pause, the sender (missing, another team's, not email, unverified domain, no address or name), then suppression over to, cc and bcc.
  • It returns { ok: true, sender } or a rejection with a PolicyCode (sending_suspended, template_paused, sender_not_verified, recipient_suppressed), detail, why and fix. detail is the run-log text delivery shows today. why and fix are new, for the API's errors later.
  • EmailService.executeSendEmail calls check(send) and keeps its logs, metrics, skipped flags and thrown sender errors, now from one table per code.
  • The workflow step's suppression check (RecipientPreferencesService) uses the policy's findSuppressedRecipients. It still fails open on a lookup error.
  • Only delivery calls the policy in this layer. The transactional send route calls the same check at admission in a later slice.
  • Rebased onto master on 2026-10-21. master's skip for a send with no to keeps its place: after suspension, pause and the sender checks, before suppression. With no to, the policy gets no recipients, so a suppressed cc or bcc can't turn that skip into a suppression (619d7421be0).
  • One run-log difference: a suppressed send no longer logs "Ignoring the custom sender address" before its skip line, because the policy decides the skip before the sender override resolves.
  • The suspended-team server log keeps its cause field (staff or provider), as on master.
  • Delivery maps every PolicyCode to a skip or a failure in one total table, so a new code must pick one before it compiles.

How did you test this code?

Test seam: the policy's public check, with team config and the suppression list faked at their service interfaces. email-send-policy.test.ts runs each case once, because both callers use the same check.

  • One case per existing check: two suspension causes, two pause kinds, five sender cases, suppression across recipients, and the check order. They lock each code with its detail, so a later change to admission can't drift from delivery.
  • Proof of no behavior change: the delivery suites keep every case and assertion. They gain one row: master's missing-recipient cases got a row with a suppressed cc, red before the fix.
  • The policy test and the three delivery suites pass in the local gate at the stack top 987b927630e, which holds this head unchanged: CDP jest 3690 (1 skipped), cdp-api serial 288, tsc clean, with the rest of the gate green.

Proofs owed:

  • Live run: not owed. A mechanical refactor with the delivery suites unchanged and green.
  • Cross-version: not owed. No queued or stored format changes.
  • Post-deploy watch: owed after merge. Watch email_suppressed, email_suspended and email_paused metrics for a drop.
  • Shadow diff: gap. No run compared base and this head over the same invocations. The delivery suites above stand in for it.
  • Prod shape: gap, accepted until read-only production access arrives on 2026-11-02. Unknown: the stored sender integrations, suspension config and suppression rows the policy meets first.
  • Review: GPT-6.1 Sol read this layer after the rebase. Its one finding, the missing-recipient order above, is fixed. Three more final reads after the restacks found nothing. The stack's QA swarm then fixed the lost cause log field and the partial presentation table in round 1, and a comment in round 2. Final read 1 and the rebase check in final read 3 found nothing.
  • Gap: CI on this fork PR waits for a maintainer to approve the workflow runs. The strict pre-push preflight passed with 0 failures.

Release status

  • No feature flag controls this change

Docs update

None. No behavior change.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Agent: Claude Code, Claude Opus 5.5 (claude-opus-5-5)

  • Skills: /tdd, /writing-tests, /writing-pr-descriptions, plus Michael's impact, qa-swarm (proof rules), merge-risk and pr-description.
  • Fixes from the stack's QA swarm were written by Claude Opus 5.5 (high).

Decisions

Question Answer Who Where
Order The refactors (send policy, send command, idempotent enqueue) land first as mechanical PRs, and the features stack on them 👤 Human Architecture #526
Send policy One module with check(send, phase), called by cdp-api at admission and the email worker at delivery 👍 Accepted default Architecture #526
Presentation The policy decides and names why and fix. Each caller keeps its own logs, metrics and skip flags. Alternative: the policy writes logs and metrics, which would tie admission to delivery's run logs. 🤖 Agent this PR
Sender in the policy A missing, foreign, non-email, unverified or incomplete sender is sender_not_verified, and a pass carries the approved sender. Alternative: leave the sender checks in the worker, which would put them after suppression or duplicate them. 🤖 Agent this PR
Second suppression copy The workflow step keeps its own check but shares the policy's lookup, and still fails open 🤖 Agent this PR
Send phase check(send) takes no phase, because no check read it. Replaces check(send, phase) from the send policy row. 🤖 Agent pending approval

Involvement: no grilling for this slice. Stack QA swarm: design pass (GPT-6.1 Sol high), round 1 (review and team lanes GPT-6.1 Sol high, fresh eyes Claude Opus 5.5 high), round 2 on the fixes (review lane GPT-6.1 Sol high, fresh eyes Claude Opus 5.5 high), final read 1 and final read 3 over the rebase (GPT-6.1 Sol high, both clean); fixers Claude Opus 5.5 high. Proof is the unchanged delivery suites.

🤖 Generated with Claude Code

@trunk-io

trunk-io Bot commented Oct 21, 2026

Copy link
Copy Markdown

Merging to master in this repository is managed by Trunk.

  • To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

Silthus and others added 3 commits October 23, 2026 15:12
A message template gets a code key unique per team, an owner, a source and
a content hash, so code can upload and lock a template by key.

Part 1 of 3 of PostHog#118924.

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

Code uploads an email template by key, which locks it against edits in
PostHog. Giving a template a key adopts it. A send names the template by
key or id and carries a content hash, so a stale upload is refused.

Part 2 of 3 of PostHog#118924.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Silthus and others added 3 commits October 23, 2026 18:05
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Silthus
Silthus force-pushed the feat/email-send-policy branch from 02d26ce to 8ce89fa Compare October 23, 2026 21:24
Silthus and others added 9 commits October 23, 2026 21:37
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The template library marks a code-managed template with its source and
key, shows it read-only, and offers a release back to PostHog.

Part 3 of 3 of PostHog#118924.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Silthus and others added 8 commits October 23, 2026 21:43
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EmailSendPolicy.check(send, phase) holds the team suspension, workflow
pause, sender and suppression checks, each with a code, why and fix.
Delivery runs them through check(send, 'delivery') and keeps its logs,
metrics and skip handling. The step-level suppression check shares the
policy's lookup. Nothing calls the admission phase yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature/agent-infra Feature Tag: Agent infra

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant