Skip to content

feat(migrate-email): map provider tracking settings to tracking and sensitive - #486

Merged
edwinyjlim merged 221 commits into
mainfrom
feat/migrate-email-track-opens-and-clicks
Nov 18, 2026
Merged

edwinyjlim merged 221 commits into
mainfrom
feat/migrate-email-track-opens-and-clicks

Conversation

@Silthus

@Silthus Silthus commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem

  • PostHog's code send gets two new optional fields. tracking replaces track_opens_and_clicks, which this PR used before and which never shipped. sensitive marks an email that carries login links, reset tokens, or codes.
  • An app that turned off open tracking at its old provider would get open pixels after migrate-email moves it. The skill had no way to leave them out.
tracking Opens Clicks Engagement events
Left out On Off when sensitive, on when not On
On On On On
Off Off Off Off
Switches opens, on by default clicks, by default as left out engagement, on by default

A code send left without sensitive takes the setting of the template in PostHog with the same key, and is sensitive when no template has that key.

Note

🔵 Merge risk: low, 🟡 once a release reaches people · two-way door at merge, one-way once a person applies the released skill's rewrites: the sends it rewrites stay in their app

  • A migrate-email run moves a Resend or SendGrid site with the wrong tracking: an email gains or loses open counts, or a site that a webhook handler needs moves when it should stay. A site where tracking matters (opens off, opens set at run time, or a click handler) never moves to a PostHog template: it moves into the code or stays. Few teams run the skill, in both regions.
  • Two outcomes the skill now guards against: a SendGrid send with a fixed openTracking.enable: false gaining a pixel from the account's setting, and a person making a PostHog template transactional before the skill finds a value it can't type-check.
  • Step 7 now upgrades the SDK when a moving code send needs tracking or the sensitive flag. That can upgrade an app's SDK, sometimes across a major version, which Step 7 checks against the changelog.
  • Switch-off: none: the skill text is live once a release ships it. Fix forward with a new release.
  • Tier: non-critical (b to g do not hold: low grade and two-way at merge, since a separate release PR publishes the skill; no migration, release, or send)

Rollout

  • Stages: merges after SendGrid (#459); reaches people only with the next release PR.
  • Decided: untracked opens move with opens off and no question, and every code send is sensitive (Michael, 2026-11-12). SendGrid is the only new provider for now; Mailgun, Mandrill, SparkPost and Mailjet are parked (Michael, 2026-11-14).
  • Watch: no alert. A wrong move shows in the report the skill writes for the person.

Impact

No metric: the skill runs in the person's own agent and sends no events per site. A run's report lists each site's tracking, which is where a wrong move shows.

Changes

  • 7-rewrite.md:

    • A new "Sensitive emails and tracking" section explains the sensitive flag and its default, and holds the table. It says why clicks follow the flag (a link can carry a sign-in or reset token), that a clicks switch the send sets wins, that off also stops engagement events, and which sends PostHog refuses. It also says the SDK's capture_engagement field is deprecated and never written.
    • "Rewrite each site": when the old send had open tracking off and the site moves to a code send, it turns off only the opens switch, so engagement events stay on. It never sends tracking off.
    • Every code send is marked sensitive. A send without the flag would take the setting of a PostHog template with the same key, and the skill can't see the project's templates or tell whether a link carries a token. The flag also carries over an old send that turned off click tracking for that one email, or marked it sensitive. The report says so, and says how to count clicks for an email whose links are safe to rewrite.
    • The skill never turns on clicks and never marks a send as not sensitive, because it can't tell whether a link carries a token. A site whose provider tracked clicks goes in the report, so the person can choose.
    • A site that moves to a template made in PostHog sends neither field. The report asks the person to check the template's settings.
    • "Set up the SDK", the rule against new fields, and "Write down" now name both fields.
  • Each rewrite-<sdk>.md gives sensitive and tracking in that SDK's syntax, the form for open tracking off, and the deprecated engagement field.

  • 3-inventory.md: a site whose emails had no open pixel, or whose open tracking nobody can confirm, moves with opens off and the note opens off: <reason>. This replaces feat(migrate-email): move Resend sends in every PostHog SDK's language #472's question that asked the person whether PostHog may add its pixel.

  • 9-report.md: lists each site sent with opens off and why, each site whose clicks PostHog no longer counts, and says that every code send is marked sensitive.

  • resend/account.md and resend/mapping.md: Resend sets tracking per domain. The skill asks once, in one question, whether open and click tracking are on for each sending domain. For opens, off or no answer means the site moves with opens off. A domain that tracks clicks gets a note in the plan and the report, because every code send is marked sensitive and counts no clicks (review comment).

  • Engagement events: Step 7's "Link emails to your users", its tracking section, and resend/mapping.md "Webhooks" now say PostHog records them when the project's Capture email engagement events setting is on and the send's tracking doesn't turn engagement off. Before, they said "when engagement capture is on", naming the deprecated field.

  • Clicks: the email.clicked row, the email.clicked handler rule, and Step 9's handler note no longer say a code send can never count clicks. They say PostHog counts a code send's clicks when its tracking leaves them on, as Step 7's table says. They also say the skill's own code sends count none, because Step 7 marks each one sensitive and never turns clicks on, until the person changes that.

  • A site whose email.clicked or click handler needs clicks stays on its provider with the reason its clicks feed a webhook handler: a code send counts no clicks, and a PostHog template is no longer an option for it (review finding).

  • A site whose open tracking nobody can confirm, and whose emails a webhook handler acts on for the provider's open event (email.opened in Resend, open in SendGrid), stays with the reason open tracking not checked. With opens off, PostHog would send that handler no opened events (PostHog Review finding). Every other site with unknown open tracking still moves with opens off.

  • sendgrid/account.md and sendgrid/mapping.md, new on main with #459, follow the same policy. A site whose emails had no open pixel, or whose open tracking nobody can confirm, moves with opens off. The account question asks about SendGrid's settings, never about PostHog's pixel. "Open and click tracking" no longer says PostHog adds its pixel to every email, and a click handler on a site with opens off keeps it on SendGrid, as for Resend.

  • A site where tracking matters never moves to a template made in PostHog, because a send by template ID can't set tracking. Step 3 checks this once it knows the sender, before the template rules. A site with opens off moves into the code with opens off, or stays with opens off needs a code send. A site whose open tracking changes from send to send, such as enable: !recipient.optedOut, stays with open tracking set at run time (review findings and comment).

  • In SendGrid, a send's fixed enable wins over the account's setting, so a fixed enable: false never gains a pixel. A site whose click tracking changes from send to send moves into the code or stays with click tracking set at run time. Step 3 checks a template's value types before asking the person to make it. Both account guides point to Step 3's exception for a site whose open events feed a handler (review findings).

  • sendgrid/mapping.md says Step 7 never writes the deprecated captureEngagement field, and rewrite-go.md shows its replacement as Tracking: posthog.EmailTrackingWith(...) (review comments).

  • To restore clicks, the report and Step 7 say to turn clicks on, with opens on, and keep the sensitive flag, only for an email whose links are safe to rewrite. The note for a site with opens off says clicks need opens on first (review findings).

  • The click rows in resend/mapping.md and sendgrid/mapping.md count clicks only for a template that is not marked sensitive and has tracking on (review finding).

  • 9-report.md keeps #525's before cutover: notes and this PR's lines on opens off and sensitive sends.

  • Merging feat(migrate-email): move Resend sends in every PostHog SDK's language #472 at 808f61d, fd58f93, 1bcc53c, d00e808 and 4db6763: its new commits mark only secret emails sensitive, ask before adding an open pixel, and name capture_engagement in the SDK lines. Where they conflict, this PR keeps its own policy (every code send sensitive, untracked opens move with opens off, tracking and sensitive in each SDK line). It keeps feat(migrate-email): move Resend sends in every PostHog SDK's language #472's template key check, language version check, and the report's template key item.

SDK names. Each rewrite file uses the names of the released SDKs: Python 7.89.0, Node.js 5.71.0, Go 1.43.0, Rust 0.32.0, Ruby 3.33.0, PHP 4.24.0, Elixir 2.21.0, and .NET 2.24.0. The Go, .NET, Rust and Elixir names are checked against those tags.

Based on main, merged forward at 7f3e6b8 with SendGrid (#459) and #525.

PostHog PRs, merged and deployed:

All 8 SDKs have released tracking and sensitive, and the docs are live (posthog.com#22088).

Decided: a site whose emails had no open pixel moves with opens off and no question to the person, and every code send carries sensitive: true (Michael, 2026-11-12).

Order with #541. The two PRs conflict in Steps 7 and 9. Whichever merges first, the other merges main, keeps both changes, and checks that the built Resend and SendGrid skills carry the tracking and the retry text.

Providers. Resend and SendGrid follow this policy. Mailgun #461, Mandrill #467, SparkPost #468 and Mailjet #466 are parked as drafts. Each takes the same policy before it lands. Amazon SES needs no change: PostHog keeps and honors ses:no-track.

Follow-up, not in this PR. Step 8 matches the test send by template key or ID. When two sites share an ID, another site's send can pass the check. It should match the invocation ID the test call returns. This predates this PR.

Known issues

  • major: context/skills/migrate-email/references/sendgrid/mapping.md:32 SendGrid decides opens and clicks one at a time, so a send that sets only clickTracking still takes the account's open setting. The paragraph says the account applies only when the send sets neither. Tracked as a follow-up.
  • major: context/skills/migrate-email/references/7-rewrite.md:130 PostHog rewrites only HTML links, so a plain-text SendGrid email whose text links SendGrid tracked can't get its click counts back. The advice should cover HTML links only, and the report should name that loss. Tracked in the same follow-up.

How I checked it

I ran the repo's build workflow steps at d43cc1d, after merging main at d3e32c3:

  • pnpm install --frozen-lockfile, pnpm check:browser-snippets, bash scripts/lint-env-naming.sh: passed.
  • pnpm test: 400 tests passed, including the check that each "Step N says under" reference names a real section.
  • pnpm build: passed. Each skill zip is under 1 MB. The built migrate-email-resend.zip and migrate-email-sendgrid.zip carry the Step 3 tracking rules (opens off needs a code send, open tracking set at run time, its clicks feed a webhook handler), and neither provider's mapping still moves a click-handler site to a PostHog template.
  • A grep of the skill finds none of the removed ask: no "person's yes", "the person agreed", "open pixel added", or "places its own pixel".
  • I didn't run the Warlock skill scan, because it needs CI's gateway token.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

  • Claude Code, Claude Opus 5.5 (claude-opus-5-5), as a worker in a T3 Code thread.
  • The behavior comes from the decided tracking and sensitive contract that the PostHog PRs above implement.

🤖 Generated with Claude Code

Silthus and others added 30 commits October 31, 2026 09:51
The migrate group keeps Statsig's mapping and SDK reference under
references/statsig/, and its step files point there, but the generator
copied only the top-level reference files. Copy references/<variant-id>/
into each variant's bundle, and nothing of the other variants.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Move the sender setup of send-transactional-email's STEP 3 into
context/shared/email-sender-setup.md, so the email migration skill
includes the same text. A partial now takes the indentation of its
{{> name}} line on every line, so it nests under a step. The built
send skill is unchanged byte for byte.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
v0 prepares a move off Resend and changes no send call site. It finds
every Resend send, classifies each one as ready to move or staying on
Resend with a reason, sets up the PostHog sender next to Resend's DNS
records, imports Resend's suppression list when the import tool exists,
hands over the project secret key, checks the sending tier, and writes
posthog-migrate-email-resend-report.md with a summary block.

Steps are provider-neutral; references/resend/ holds what is specific
to Resend. Statsig and Resend now publish as wizard migrate subcommands.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fixture runs wrote reasons into the summary block, which the Wizard
can't parse, and counted a forwarding helper as one site or as each
caller. The report step now shows bare values, and a site is the place
that decides a send's content and fields.

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

The send-transactional-email skill is gone from this stack, so migrate-email
bundles the transactional email pages and names the sending-transactional-emails
skill for the general move.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… PostHog's reply-to rules

The preflight looked for two MCP tools that don't exist. It now looks
for the make-transactional pair, and a missing pair records the API as
not confirmed instead of stopping, because it can also mean a missing
scope. The mapping now keeps a site on Resend for reply-to addresses
with a name or more than 10, and lists every reserved header and the
header and tag length limits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The migrate-email skill now rewrites every call site PostHog can send:
hosted Resend templates become local templates, React and html/text sites
send rendered content, and the client carries migratedFrom. It checks the
build and one email on one person before it writes the report.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d provider in tests

Fixture runs looped over or truncated a one-recipient list, and one run
mocked posthog-node to rebuild a Resend request. The rewrite now narrows
the helper's parameter to one address, and the verify step asserts on the
fields posthog.emails.send gets.

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

A moved site now treats recipient_suppressed like a send that went out,
a site-built subject becomes a module placeholder so the template hash
stays stable, fallbacks use single quotes, and the report warns that
idempotency keys don't cross providers. The rules and Step 7 no longer
contradict the mapping.

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

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

posthog-node has no migratedFrom option. The Wizard records the migration
on its setup wizard finished event instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-email rewrites a site

A posthog-node release with posthog.emails can still lack templateKey,
local template content, or the extra send fields. The rewrite now checks
the installed types for what each moving site needs, and keeps a site
on Resend when the latest release lacks it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…partial imports in migrate-email

Step 1 now admits the SMTP host and a framework mailer and needs at least one
send; step 3 stops when it finds no site. A suppression import that stops
partway stays unticked and lands in the report's "Before cutover" list. A
template site needs its content from the person or stays on Resend. The
sender setup is inlined into step 4, which keeps the existing `from` domain and
records an unverified domain instead of waiting. AGENTS.md says the migrate
subcommands run once the wizard runs migrate as a family.

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

The selected variant's `references/<variant-id>/` files now go through the same
loop as the root reference files, so the separate copy helper is gone. The
partial expander drops the indentation it gained for the sender partial, which
nothing includes any more, and the bundle test drops the migrate-statsig case
that guarded nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rt every behaviour change

Step 8 checks that the app sends to the MCP's project, notes the start of the
test, and counts only events since then whose workflow matches the send. It
compares typecheck errors with a baseline step 7 takes before it changes code.
A template's content waits in a temporary file for step 7 instead of in memory,
an HTML fallback keeps a template on Resend, and a derived templateKey is
normalized and unique. The report lists each suppressed-recipient branch,
copy-address refusal, and cross-provider idempotency risk, and reminds the
person to delete the full-access Resend key. The posthog-node client setup is
inlined into step 7, and description.md says this skill wins over the general
moving guide.

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

Step 4 records a domain as not verified, with its records or Domain Connect
link, when the person can't publish them during the run. Step 3 asks the person
to save each template from the dashboard to a file outside the repository and
reads it, since the Wizard can't take pasted HTML.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… keep template files traceable

Step 8 takes the start of the test from `execute-sql` and compares Unix
timestamps, so the project's timezone can't shift the window. The plan lists
each saved template file, step 7 reads the module from it, and step 9 deletes
every listed file. A derived templateKey falls back to the template id when
the name normalizes to nothing and stays unique across the run. Step 8 may fix
other posthog-node code the upgrade breaks, and the report lists those files.

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

The clock query carries a fresh random literal so a cached answer can't widen
the test window. Step 3 may write the template files it saves, the dashboard
copy includes the template's alias or name for its key, and a major
dependency upgrade lands in the report's "Before cutover" list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…end, and move templates only to PostHog

The first PostHog release sends a template made in PostHog by template id, or rendered html and text. A Resend template site moves only once the person makes the template in PostHog, or stays on Resend for now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolves the inventory, mapping and report conflicts toward the scope cut:
a Resend template site moves only to a template made in PostHog, sent by
templateId, and headers, tags and attachments stay on Resend.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Under the scope cut, a moved template site sends a template made in
PostHog by templateId with templateData. Rendered sends keep templateKey,
subject, html and text. No local-template module, no upload on first send,
and no cc, bcc, headers, tags or attachments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
posthog-node's migratedFrom client option sends the provider a send
moved from with every email request. Step 7 now sets it, and the
Resend mapping names its value.

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

Review round 1 on #451:
- Step 3 asks for the template ID once the person made the template in
  PostHog. A template without one stays: PostHog template not made yet.
- Step 7 checks that the client takes migratedFrom, and undoes the
  posthog-node install when no site is left to move.
- Template files from an API read are deleted once their site is
  classified, and the full-access Resend key right after Step 5.
- Step 8 reads only the token's line of the env file, and picks a
  signed-in flow for the test email.
- replyTo moves as one address or a list.

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

Review round 2 on #451:
- Step 3 asks for the address a PostHog template sends from and writes it
  in the site's from column, so Step 4 sets up a sender for its domain.
- The report asks the person to send a test of each PostHog template and
  check that it is transactional, has a verified sender and fills its
  variables.
- Step 5 asks to delete the full-access key on every way out of the step,
  and after a partial import only once the person won't repeat it.
- Step 8 allows a signed-out flow: the person signs in as the recipient
  afterwards, so product events show on the same distinct ID.
- migratedFrom is set only when the client options take it.

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

Review round 3 on #451:
- Step 5 asks once whether to repeat an import that stopped partway, and
  asks about the full-access key after that answer or the repeat.
- Step 8's test email comes from a moved site that passes distinctId;
  without one, the chain is recorded as not checked.
- The client example marks migratedFrom as conditional.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
main's tree equals #472's final head 418cc5a, merged in the parent commit, so this merge takes no content.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Silthus
Silthus changed the base branch from feat/migrate-email-all-sdks to main November 13, 2026 16:31
Silthus and others added 3 commits November 17, 2026 10:40
Brings in SendGrid (#459) and the before-cutover notes of #525. Step 9
keeps both: notes that start with `before cutover:` stay out of the
sites notes, and the opens-off and sensitive lines stay in. SendGrid's
tracking text moves to the opens-off policy: an untracked or unchecked
site moves with opens off and no ask, and every code send is sensitive.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The report no longer tells the person to turn opens on for an email
whose provider tracked them, a case no opens-off site has. Turning
clicks on for a send with opens off needs opens on too. SendGrid's
click row matches Resend's. Sites that share one template made in
PostHog but differ on opens get a note naming both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The note now fires only when the other site moves to the same template
made in PostHog, Step 3's note list names it, and Step 9's template
check asks the person to pick the shared template's opens setting
instead of turning opens off for both sites.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Silthus
Silthus marked this pull request as ready for review November 17, 2026 10:03

@sarahxsanders sarahxsanders left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Once one of #486 and #541 lands, update the other and check that the built Resend and SendGrid skills include both the tracking and retry changes. The two PRs conflict in Steps 7 and 9.

Silthus and others added 2 commits November 18, 2026 18:52
…s test send

A site that moves to a template made in PostHog with `opens off` in its
note takes the template's tracking, so Step 8's real test email could
carry an open pixel the site's emails never had. Step 8 now leaves such
a site out unless the person confirms the template's open tracking is
off, and records why when no other site fits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Silthus and others added 2 commits November 18, 2026 19:27
…cked site shares its template

One PostHog template can't count opens for one site and not for
another, and splitting it left the moved call on the old template ID.
Such a site now stays, with the reason `template shared with a tracked
site`, and the note, its Step 9 branch, and the second-template advice
are gone. The `click` rows now need the template's tracking on.

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

@gewenyu99 gewenyu99 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

🥸 Reviewed by NotVincent, totally not Vincent. The real Vincent will review it separately. Probably slop, please disregard.

- When nobody can tell whether the provider tracked a site's opens, the site moves with opens off too, so PostHog adds no pixel the old emails may not have had. Write `opens off: open tracking not checked` in its note. A site whose emails a webhook handler acts on for the provider's open event, such as `email.opened` in Resend or `open` in SendGrid, stays instead, and the reason is `open tracking not checked`: with opens off, PostHog sends no opened events in place of the provider's.
- When the provider tracked the site's opens, the site moves with nothing to note.

A site that moves to a template made in PostHog keeps its `opens off` note too, but its send takes no tracking: the template uses its own setting, so the report asks the person to check it. When another site that moves to the same template made in PostHog has no `opens off` note, one setting can't serve both: the site with `opens off` stays, and the reason is `template shared with a tracked site`.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I think an opens off site that moves to a template made in PostHog will still get an open pixel, and the report will send the person to a template setting that may not exist. I haven't reproduced this, it's a hunch, because:

  • PostHog turns tracking off for a send when the email step's tracking_enabled is false or a code send's tracking.opens is false.
  • I found no opens setting on a transactional template in PostHog's Transactional screens, only sensitive, which keeps the open pixel.
  • This paragraph, and the Step 8 change for the thread above, both rely on "the template's setting".

Could you confirm where a person turns opens off for a transactional template? If there is no such setting, keep these sites on the provider or bring the template into the code, where tracking turns opens off.

- `from`, `subject`, `html`, `text`, and the reply-to address keep their values, under the PostHog SDK's names.
- A send with rendered content gets a template key, as Step 7 says.
- The idempotency key moves into the send, under the PostHog SDK's name for it.
- Resend sets open and click tracking per domain, not per send, so the call doesn't show it. Step 3 reads the domain's open tracking from the person, as `account.md` says under "Open tracking". A site whose plan note says `opens off` turns off the `opens` switch of tracking, as Step 7 says. Click tracking needs no question: Step 7 marks every code send sensitive, so PostHog doesn't track its clicks, and Step 7 never turns them on. When the domain tracks clicks in Resend, note in the report that PostHog doesn't count these emails' clicks.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I think a Resend migration that moves only code sends can't report lost click tracking, because:

  • Resend sets click tracking per domain, so the send call doesn't show it.
  • This bullet says click tracking needs no question, and account.md asks about clicks only when a site moves to a template made in PostHog.
  • The agent never learns whether the domain tracked clicks, and Step 9 forbids a fact that is not in the plan.
Suggested change
- Resend sets open and click tracking per domain, not per send, so the call doesn't show it. Step 3 reads the domain's open tracking from the person, as `account.md` says under "Open tracking". A site whose plan note says `opens off` turns off the `opens` switch of tracking, as Step 7 says. Click tracking needs no question: Step 7 marks every code send sensitive, so PostHog doesn't track its clicks, and Step 7 never turns them on. When the domain tracks clicks in Resend, note in the report that PostHog doesn't count these emails' clicks.
- Resend sets open and click tracking per domain, not per send, so the call doesn't show it. Step 3 reads the domain's open and click tracking from the person in one question, as `account.md` says under "Open tracking" and "Click tracking". A site whose plan note says `opens off` turns off the `opens` switch of tracking, as Step 7 says. Step 7 marks every code send sensitive and never turns `clicks` on, so when the domain tracks clicks in Resend, note in the plan and the report that PostHog doesn't count these emails' clicks.

| `personalizations` | the fields of its one entry | It holds more than one entry. One entry moves when each field in it moves |

**Open and click tracking.** PostHog adds its open pixel to every email it sends, and a send in the code form counts no clicks, as Step 7 says. No field changes this: `captureEngagement` decides only whether the email's events land on the recipient's person, so tracking never maps to it. SendGrid decides opens and clicks one at a time. When the send's `trackingSettings` sets `openTracking` or `clickTracking`, that setting's `enable` decides for it. Otherwise the account's setting decides, as `account.md` says under "Tracking".
**Open and click tracking.** No SendGrid field maps to PostHog's tracking: Step 7 sets it from the plan, as it says under "Sensitive emails and tracking". `captureEngagement` decides only whether the email's events land on the recipient's person, so tracking never maps to it either. SendGrid decides opens and clicks one at a time. When the send's `trackingSettings` sets `openTracking` or `clickTracking`, that setting's `enable` decides for it. Otherwise the account's setting decides, as `account.md` says under "Tracking".

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

nit: I think it's possible an agent reads this as captureEngagement still being a field to write, because:

  • Step 7 says the field is deprecated and never to write it.
  • This paragraph describes what captureEngagement decides without saying that.
Suggested change
**Open and click tracking.** No SendGrid field maps to PostHog's tracking: Step 7 sets it from the plan, as it says under "Sensitive emails and tracking". `captureEngagement` decides only whether the email's events land on the recipient's person, so tracking never maps to it either. SendGrid decides opens and clicks one at a time. When the send's `trackingSettings` sets `openTracking` or `clickTracking`, that setting's `enable` decides for it. Otherwise the account's setting decides, as `account.md` says under "Tracking".
**Open and click tracking.** No SendGrid field maps directly in the call to PostHog's tracking: Step 7 sets `tracking` from the plan, as it says under "Sensitive emails and tracking", and never writes the deprecated `captureEngagement` field. SendGrid decides opens and clicks one at a time. When the send's `trackingSettings` sets `openTracking` or `clickTracking`, that setting's `enable` decides for it. Otherwise the account's setting decides, as `account.md` says under "Tracking".

## The send

- Code send: `client.Emails().Send(ctx, posthog.CodeEmail{To, TemplateKey, Subject, HTML, Text, DistinctID, IdempotencyKey})`, with `From`, `ReplyTo`, `CaptureEngagement` (`posthog.Ptr(false)`), and `Sensitive` (`posthog.Ptr(true)`) optional.
- Code send: `client.Emails().Send(ctx, posthog.CodeEmail{To, TemplateKey, Subject, HTML, Text, DistinctID, IdempotencyKey})`, with `From`, `ReplyTo`, `Sensitive`, and `Tracking` optional. `Tracking` takes `posthog.EmailTrackingOn()`, `posthog.EmailTrackingOff()`, or `posthog.EmailTrackingWith(posthog.EmailTrackingOptions{Opens, Clicks, Engagement})` with `posthog.Ptr` values. Open tracking off is `Tracking: posthog.EmailTrackingWith(posthog.EmailTrackingOptions{Opens: posthog.Ptr(false)})`. `CaptureEngagement` is deprecated: use `posthog.EmailTrackingOptions{Engagement: posthog.Ptr(false)}`. Sensitive is `Sensitive: posthog.Ptr(true)`.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

nit: I think it's possible an agent copies the CaptureEngagement replacement as written and gets a compile error, because:

  • CodeEmail.Tracking takes a *posthog.EmailTracking, which posthog.EmailTrackingWith(...) builds.
  • The replacement shows the bare posthog.EmailTrackingOptions{...} without Tracking: or the wrapper, unlike the opens example earlier on the line.
Suggested change
- Code send: `client.Emails().Send(ctx, posthog.CodeEmail{To, TemplateKey, Subject, HTML, Text, DistinctID, IdempotencyKey})`, with `From`, `ReplyTo`, `Sensitive`, and `Tracking` optional. `Tracking` takes `posthog.EmailTrackingOn()`, `posthog.EmailTrackingOff()`, or `posthog.EmailTrackingWith(posthog.EmailTrackingOptions{Opens, Clicks, Engagement})` with `posthog.Ptr` values. Open tracking off is `Tracking: posthog.EmailTrackingWith(posthog.EmailTrackingOptions{Opens: posthog.Ptr(false)})`. `CaptureEngagement` is deprecated: use `posthog.EmailTrackingOptions{Engagement: posthog.Ptr(false)}`. Sensitive is `Sensitive: posthog.Ptr(true)`.
- Code send: `client.Emails().Send(ctx, posthog.CodeEmail{To, TemplateKey, Subject, HTML, Text, DistinctID, IdempotencyKey})`, with `From`, `ReplyTo`, `Sensitive`, and `Tracking` optional. `Tracking` takes `posthog.EmailTrackingOn()`, `posthog.EmailTrackingOff()`, or `posthog.EmailTrackingWith(posthog.EmailTrackingOptions{Opens, Clicks, Engagement})` with `posthog.Ptr` values. Open tracking off is `Tracking: posthog.EmailTrackingWith(posthog.EmailTrackingOptions{Opens: posthog.Ptr(false)})`. `CaptureEngagement` is deprecated: use `Tracking: posthog.EmailTrackingWith(posthog.EmailTrackingOptions{Engagement: posthog.Ptr(false)})`. Sensitive is `Sensitive: posthog.Ptr(true)`.

Silthus and others added 7 commits November 18, 2026 20:01
…acking wording

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

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…efore template checks"

This reverts commit 5b0b757: the read found a major in it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A site with opens off, open tracking set at run time, or a click handler
never moves to a PostHog template. Tracking is checked once the sender is
known, before the template rules. To restore clicks, turn on clicks with
opens on and keep the sensitive flag.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@edwinyjlim
edwinyjlim merged commit ee1402d into main Nov 18, 2026
17 checks passed
Silthus added a commit that referenced this pull request Nov 18, 2026
Keeps #486's tracking text, opens-off rule and opens-first sentence, and
#541's retry text. Steps 7 and 9 list both the opens-off sites and the
removed retries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Silthus added a commit that referenced this pull request Nov 19, 2026
#486 landed on main as a squash. Merged with #486's old head c6f7e9a, the
one this branch merged, as the base. Each conflict keeps main's text and adds
back only this branch's attachment, runtime, key-name and header-rule lines.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants