From b951bdd927928472079655f663daa085f5aa048f Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Sat, 5 Sep 2026 14:44:02 -0700
Subject: [PATCH] feat(growth): attribute campaign sends per template with a
 bounded Resend tag

Every send_step now carries a campaign_template tag alongside
campaign_version and campaign_step, so replies, bookings, and
unsubscribes can be attributed to the exact template that rendered the
message rather than only its step.

- draftFor returns the chosen template id (immediate, day-3, day-8, or
  the cited evidence angle) and prepareCampaignMessage exposes it.
- RecipientEmailInput accepts campaignTemplate; resend.ts validates it
  against a closed allowlist, requires it for send_step, and rejects it
  on any other job kind. The value is a fixed id, never contact data.
- The webhook receiver's canonical-send check counted send_step tags
  exactly, which would have downgraded every new send's early webhook
  from retryable to dropped. It now accepts the legacy 4-tag shape for
  in-flight sends and the 5-tag shape when the template is allowlisted.

Internal analytics stays step-only by decision; the Resend dashboard is
the v1 surface for per-template numbers.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 apps/lifecycle/src/campaign/send.spec.ts | 12 ++++
 apps/lifecycle/src/campaign/send.ts      | 46 ++++++++++++---
 libs/growth/src/lib/resend.spec.ts       | 71 +++++++++++++++++++++++-
 libs/growth/src/lib/resend.ts            | 53 ++++++++++++++++--
 libs/growth/src/lib/webhooks.spec.ts     | 53 ++++++++++++++++++
 libs/growth/src/lib/webhooks.ts          | 11 +++-
 6 files changed, 229 insertions(+), 17 deletions(-)

diff --git a/apps/lifecycle/src/campaign/send.spec.ts b/apps/lifecycle/src/campaign/send.spec.ts
index 41d777163..4cb7833ee 100644
--- a/apps/lifecycle/src/campaign/send.spec.ts
+++ b/apps/lifecycle/src/campaign/send.spec.ts
@@ -157,6 +157,7 @@ describe('prepareCampaignMessage', () => {
           'Get your agent UI into production',
           'Free engineering session with the Threadplane founder',
         ][step - 1],
+        template: ['immediate', 'day-3', 'day-8'][step - 1],
       });
       if (prepared.status !== 'ready') throw new Error('expected ready');
       expect(prepared.text).toContain(unsubscribeActionUrlValue(UNSUBSCRIBE));
@@ -253,6 +254,11 @@ describe('prepareCampaignMessage', () => {
           'Three checks when the UI stalls',
           'One boundary that makes agent UIs testable',
         ][step - 1],
+        template: [
+          'streaming_foundation',
+          'debugging_layers',
+          'event_state_boundary',
+        ][step - 1],
       });
       if (prepared.status !== 'ready') throw new Error('expected ready');
       expect(prepared.text).toContain(
@@ -458,6 +464,7 @@ describe('dispatchLifecycleAppOwnedJob', () => {
         text: expect.stringContaining('Stop here: '),
         html: expect.stringContaining('Click <a href="'),
         unsubscribeUrl: UNSUBSCRIBE,
+        campaignTemplate: 'immediate',
       }),
       deps.recipientPolicy
     );
@@ -548,6 +555,11 @@ describe('dispatchLifecycleAppOwnedJob', () => {
       }),
       deps.recipientPolicy
     );
+    expect(deps.sendRecipient).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.not.objectContaining({ campaignTemplate: expect.anything() }),
+      deps.recipientPolicy
+    );
     const sent = vi.mocked(deps.sendRecipient).mock.calls[0]?.[1];
     expect(sent?.text.startsWith('Hey Ada,\n\nHere is the guide')).toBe(true);
     expect(
diff --git a/apps/lifecycle/src/campaign/send.ts b/apps/lifecycle/src/campaign/send.ts
index 6aa934f7d..353cd968a 100644
--- a/apps/lifecycle/src/campaign/send.ts
+++ b/apps/lifecycle/src/campaign/send.ts
@@ -32,6 +32,7 @@ import {
   type RecipientEmailInput,
   type RecipientSendResult,
   type SqlExecutor,
+  type CampaignTemplateId,
   type UnsubscribeActionUrl,
 } from '../growth.js';
 import { Resend } from 'resend';
@@ -188,6 +189,12 @@ export type PreparedCampaignMessage = {
   subject: string;
   text: string;
   html: string;
+  /** The template id that rendered this message, attributed as a provider tag. */
+  template: CampaignTemplateId;
+};
+
+type SelectedCampaignDraft = CampaignDraft & {
+  readonly template: CampaignTemplateId;
 };
 
 function campaignStep(job: GrowthJob): 1 | 2 | 3 {
@@ -235,7 +242,7 @@ function validArtifact(
 function draftFor(
   step: 1 | 2 | 3,
   artifact: EnrichmentArtifact | null
-): CampaignDraft {
+): SelectedCampaignDraft {
   // Every step is the founder session offer. A cited research angle only
   // changes which flavor of that offer goes out.
   if (artifact) {
@@ -246,12 +253,18 @@ function draftFor(
         source_ids.includes(selection.source_id)
       );
     if (selection !== null && cited) {
-      return renderEvidenceCampaignTemplate(selection.angle_id, {
-        finalStep: step === 3,
-      });
+      return {
+        ...renderEvidenceCampaignTemplate(selection.angle_id, {
+          finalStep: step === 3,
+        }),
+        template: selection.angle_id,
+      };
     }
   }
-  return renderCampaignTemplate(STEP_NAMES[step]);
+  return {
+    ...renderCampaignTemplate(STEP_NAMES[step]),
+    template: STEP_NAMES[step],
+  };
 }
 
 const FIRST_NAME_PATTERN = /^[A-Za-z][A-Za-z'’-]{0,29}$/u;
@@ -353,6 +366,7 @@ export function prepareCampaignMessage(input: {
     subject: draft.subject,
     text: signedText(body, input.unsubscribeUrl),
     html: signedHtml(body, input.unsubscribeUrl),
+    template: draft.template,
   };
 }
 
@@ -397,7 +411,10 @@ function formSource(
 
 function enrichmentDrafts(context: LifecycleJobContext): CampaignDraft[] {
   const artifact = validArtifact(context.enrichmentArtifact, context.contactId);
-  return ([1, 2, 3] as const).map((step) => draftFor(step, artifact));
+  return ([1, 2, 3] as const).map((step) => {
+    const { subject, body } = draftFor(step, artifact);
+    return { subject, body };
+  });
 }
 
 async function dispatchRecipient(
@@ -408,13 +425,23 @@ async function dispatchRecipient(
   html: string,
   unsubscribeUrl: UnsubscribeActionUrl,
   signal: AbortSignal,
-  dependencies: LifecycleJobDependencies
+  dependencies: LifecycleJobDependencies,
+  campaignTemplate?: CampaignTemplateId
 ): Promise<GrowthDispatchResult> {
   const leaseToken = requireLease(job);
   signal.throwIfAborted();
   const result = await dependencies.sendRecipient(
     executor,
-    { jobId: job.id, leaseToken, subject, text, html, unsubscribeUrl, signal },
+    {
+      jobId: job.id,
+      leaseToken,
+      subject,
+      text,
+      html,
+      unsubscribeUrl,
+      signal,
+      ...(campaignTemplate === undefined ? {} : { campaignTemplate }),
+    },
     dependencies.recipientPolicy
   );
   if (result.accepted) return 'completed';
@@ -518,7 +545,8 @@ export async function dispatchLifecycleAppOwnedJob(
       message.html,
       unsubscribeUrl,
       signal,
-      dependencies
+      dependencies,
+      message.template
     );
   }
 
diff --git a/libs/growth/src/lib/resend.spec.ts b/libs/growth/src/lib/resend.spec.ts
index 3890e0e6c..e3c59fd1b 100644
--- a/libs/growth/src/lib/resend.spec.ts
+++ b/libs/growth/src/lib/resend.spec.ts
@@ -142,6 +142,7 @@ const message = {
   subject: 'A Threadplane architecture note',
   text: 'Hi Sam,\n\nHere is the architecture note.\n\nBrian',
   unsubscribeUrl: unsubscribeActionUrl,
+  campaignTemplate: 'immediate' as const,
 };
 
 describe('sendRecipientEmail', () => {
@@ -178,6 +179,7 @@ describe('sendRecipientEmail', () => {
           { name: 'job_kind', value: 'send_step' },
           { name: 'campaign_version', value: 'v1' },
           { name: 'campaign_step', value: '1' },
+          { name: 'campaign_template', value: 'immediate' },
         ],
       },
       { idempotencyKey: 'campaign:v1:contact:step:1' }
@@ -277,6 +279,73 @@ describe('sendRecipientEmail', () => {
     expect(test.send).not.toHaveBeenCalled();
   });
 
+  it.each([
+    'immediate',
+    'day-3',
+    'day-8',
+    'streaming_foundation',
+    'debugging_layers',
+    'event_state_boundary',
+  ] as const)('tags a send_step with the %s template', async (template) => {
+    const test = harness();
+
+    await sendRecipientEmail(
+      test.database,
+      { ...message, campaignTemplate: template },
+      productionPolicy(),
+      test.dependencies
+    );
+
+    expect(test.send.mock.calls[0]?.[0]).toMatchObject({
+      tags: expect.arrayContaining([
+        { name: 'campaign_template', value: template },
+      ]),
+    });
+  });
+
+  it.each([
+    undefined,
+    '',
+    'day-4',
+    'immediate; developer@example.com',
+    'IMMEDIATE',
+  ])(
+    'rejects a send_step whose template is outside the closed allowlist (%j)',
+    async (template) => {
+      const test = harness();
+
+      await expect(
+        sendRecipientEmail(
+          test.database,
+          { ...message, campaignTemplate: template as never },
+          productionPolicy(),
+          test.dependencies
+        )
+      ).rejects.toThrow(/campaign template/u);
+      expect(test.send).not.toHaveBeenCalled();
+    }
+  );
+
+  it('rejects a campaign template on a non-campaign job', async () => {
+    const test = harness({
+      job: job({
+        kind: 'fulfill',
+        idempotencyKey: 'fulfill:whitepaper:contact',
+        payload: { fulfillment_kind: 'whitepaper' },
+      }),
+    });
+
+    await expect(
+      sendRecipientEmail(
+        test.database,
+        message,
+        productionPolicy(),
+        test.dependencies
+      )
+    ).rejects.toThrow(/campaign template/u);
+    expect(test.send).not.toHaveBeenCalled();
+  });
+
   it('uses a separate fulfillment tag contract without campaign tags', async () => {
     const test = harness({
       job: job({
@@ -288,7 +357,7 @@ describe('sendRecipientEmail', () => {
 
     await sendRecipientEmail(
       test.database,
-      message,
+      { ...message, campaignTemplate: undefined },
       productionPolicy(),
       test.dependencies
     );
diff --git a/libs/growth/src/lib/resend.ts b/libs/growth/src/lib/resend.ts
index e7957ea9f..9ccf487c8 100644
--- a/libs/growth/src/lib/resend.ts
+++ b/libs/growth/src/lib/resend.ts
@@ -53,11 +53,41 @@ export interface RecipientDeliveryPolicy {
   nonProductionRedirectTo?: string;
 }
 
+/**
+ * The closed set of campaign template ids a send_step may be attributed to.
+ * Provider tags are the only per-template signal webhooks and reply handling
+ * can see, so every value here is a fixed identifier and never contact data.
+ */
+export const CAMPAIGN_TEMPLATE_IDS = [
+  'immediate',
+  'day-3',
+  'day-8',
+  'streaming_foundation',
+  'debugging_layers',
+  'event_state_boundary',
+] as const;
+export type CampaignTemplateId = (typeof CAMPAIGN_TEMPLATE_IDS)[number];
+const CAMPAIGN_TEMPLATE_ID_SET: ReadonlySet<string> = new Set(
+  CAMPAIGN_TEMPLATE_IDS
+);
+
+export function isCampaignTemplateId(
+  value: unknown
+): value is CampaignTemplateId {
+  return typeof value === 'string' && CAMPAIGN_TEMPLATE_ID_SET.has(value);
+}
+
 export interface RecipientEmailInput {
   jobId: string;
   leaseToken: string;
   subject: string;
   text: string;
+  /**
+   * Which campaign template rendered this message. Required for send_step
+   * jobs and forbidden otherwise; it is emitted as the bounded
+   * `campaign_template` provider tag.
+   */
+  campaignTemplate?: CampaignTemplateId;
   /**
    * Optional HTML alternative for the same message. It must stay a plain
    * rendering of the text part: paragraphs and HTTPS anchors only, no images,
@@ -291,13 +321,19 @@ function effectiveRecipient(
 function campaignTags(
   environment: DeliveryEnvironment,
   kind: string,
-  payload: Record<string, unknown>
+  payload: Record<string, unknown>,
+  campaignTemplate: unknown
 ): { name: string; value: string }[] {
   const tags = [
     { name: 'environment', value: environment },
     { name: 'job_kind', value: kind },
   ];
-  if (kind !== 'send_step') return tags;
+  if (kind !== 'send_step') {
+    if (campaignTemplate !== undefined) {
+      throw new Error('Only send_step carries a campaign template');
+    }
+    return tags;
+  }
   const campaignVersion = payload['campaign_version'];
   const step = payload['step'];
   if (campaignVersion !== 'v1' || (step !== 1 && step !== 2 && step !== 3)) {
@@ -305,9 +341,13 @@ function campaignTags(
       'send_step requires a registered campaign version and step'
     );
   }
+  if (!isCampaignTemplateId(campaignTemplate)) {
+    throw new Error('send_step requires a registered campaign template');
+  }
   tags.push(
     { name: 'campaign_version', value: campaignVersion },
-    { name: 'campaign_step', value: String(step) }
+    { name: 'campaign_step', value: String(step) },
+    { name: 'campaign_template', value: campaignTemplate }
   );
   return tags;
 }
@@ -379,7 +419,12 @@ export async function sendRecipientEmail(
     job.idempotencyKey,
     256
   );
-  const tags = campaignTags(policy.environment, job.kind, job.payload);
+  const tags = campaignTags(
+    policy.environment,
+    job.kind,
+    job.payload,
+    input.campaignTemplate
+  );
 
   input.signal?.throwIfAborted();
   let response: ResendResponse;
diff --git a/libs/growth/src/lib/webhooks.spec.ts b/libs/growth/src/lib/webhooks.spec.ts
index b7295dec0..602ecf358 100644
--- a/libs/growth/src/lib/webhooks.spec.ts
+++ b/libs/growth/src/lib/webhooks.spec.ts
@@ -169,6 +169,7 @@ function event(
         job_kind: 'send_step',
         campaign_version: 'v1',
         campaign_step: '1',
+        campaign_template: 'immediate',
       },
       ...(type === 'email.failed'
         ? { failed: { reason: 'provider_rejected' } }
@@ -611,6 +612,27 @@ describe('processVerifiedResendWebhook', () => {
       },
       'unmatched_job',
     ],
+    [
+      {
+        environment: 'production',
+        job_kind: 'send_step',
+        campaign_version: 'v1',
+        campaign_step: '1',
+        campaign_template: 'day-4',
+      },
+      'unmatched_job',
+    ],
+    [
+      {
+        environment: 'production',
+        job_kind: 'send_step',
+        campaign_version: 'v1',
+        campaign_step: '1',
+        campaign_template: 'immediate',
+        extra: 'x',
+      },
+      'unmatched_job',
+    ],
     [
       {
         environment: 'production',
@@ -643,6 +665,37 @@ describe('processVerifiedResendWebhook', () => {
     }
   );
 
+  it.each([
+    {
+      environment: 'production',
+      job_kind: 'send_step',
+      campaign_version: 'v1',
+      campaign_step: '1',
+    },
+    {
+      environment: 'production',
+      job_kind: 'send_step',
+      campaign_version: 'v1',
+      campaign_step: '1',
+      campaign_template: 'streaming_foundation',
+    },
+  ])(
+    'retries an unmatched canonical send_step event with or without a template tag %#',
+    async (tags) => {
+      const harness = executorWith({
+        'read-resend-webhook-activity': () => ({ rows: [] }),
+        'discover-resend-webhook-job': () => ({ rows: [] }),
+      });
+
+      await expect(
+        processVerifiedResendWebhook(harness.executor, {
+          providerEventId: 'msg_canonical_tags',
+          payload: event('email.delivered', { tags }),
+        })
+      ).resolves.toEqual({ applied: false, reason: 'retryable_unmatched_job' });
+    }
+  );
+
   it('does not regress a terminal delivered status on delayed or failure events', async () => {
     const delivered = jobRow({ delivery_status: 'delivered' });
     for (const type of ['email.delivery_delayed', 'email.failed']) {
diff --git a/libs/growth/src/lib/webhooks.ts b/libs/growth/src/lib/webhooks.ts
index d98ca3228..ab64d16da 100644
--- a/libs/growth/src/lib/webhooks.ts
+++ b/libs/growth/src/lib/webhooks.ts
@@ -1,6 +1,6 @@
 import type { SqlExecutor, SqlTransaction } from './database.ts';
 import type { GrowthDeliveryStatus } from './models.ts';
-import type { DeliveryEnvironment } from './resend.ts';
+import { isCampaignTemplateId, type DeliveryEnvironment } from './resend.ts';
 import {
   stopContact,
   type CanonicalStopReason,
@@ -432,12 +432,17 @@ function isThreadplaneGrowthSend(tags: Record<string, string>): boolean {
     );
   }
   if (tags['job_kind'] !== 'send_step') return false;
+  // Sends accepted before the template tag shipped carry four tags; newer
+  // sends carry a fifth, bounded to the closed template allowlist.
+  const template = tags['campaign_template'];
+  const expectedTagCount = template === undefined ? 4 : 5;
   return (
-    Object.keys(tags).length === 4 &&
+    Object.keys(tags).length === expectedTagCount &&
     tags['campaign_version'] === 'v1' &&
     (tags['campaign_step'] === '1' ||
       tags['campaign_step'] === '2' ||
-      tags['campaign_step'] === '3')
+      tags['campaign_step'] === '3') &&
+    (template === undefined || isCampaignTemplateId(template))
   );
 }