Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
85 commits
Select commit Hold shift + click to select a range
f034ecd
fix(skills): ship a variant's own reference folder in its bundle
Silthus Oct 22, 2026
177e741
refactor(skills): share the email sender setup as a partial
Silthus Oct 22, 2026
8169d7e
feat(skills): add the migrate-email skill with a Resend variant
Silthus Oct 22, 2026
5e019aa
fix(skills): keep migrate-email's summary values bare and define a site
Silthus Oct 22, 2026
6e902dc
fix(skills): point migrate-email at the transactional email docs and …
Silthus Oct 31, 2026
0286e23
fix(skills): check migrate-email's API access with the real tools and…
Silthus Nov 1, 2026
0920218
refactor(skills): share the posthog-node client setup as a partial
Silthus Oct 22, 2026
64a2397
feat(skills): move Resend sends to posthog-node in migrate-email
Silthus Oct 22, 2026
ad4b0c7
fix(skills): keep migrate-email from splitting sends or faking the ol…
Silthus Oct 22, 2026
b2965cc
fix(skills): handle suppressed recipients and dynamic subjects in mig…
Silthus Oct 22, 2026
f8f4fea
fix(skills): keep a suppressed copy address from passing as a sent email
Silthus Oct 22, 2026
8dcd459
fix(skills): warn that retrying a send with a suppressed copy address…
Silthus Oct 22, 2026
154e8f5
fix(skills): leave migratedFrom off the posthog-node client in migrat…
Silthus Oct 31, 2026
9cd85f5
fix(skills): check that posthog-node has the code form before migrate…
Silthus Nov 1, 2026
41ca66a
fix(skills): detect resend over smtp, stop without sends, and record …
Silthus Nov 1, 2026
0e526b9
refactor(scripts): ship variant references through the local referenc…
Silthus Nov 1, 2026
e51df39
merge: feat/migrate-email-resend into feat/migrate-email-resend-cutover
Silthus Nov 1, 2026
8c841cd
fix(skills): tie migrate-email's test send to its own events and repo…
Silthus Nov 1, 2026
4ad8c6e
fix(skills): let migrate-email move on when DNS waits and read templa…
Silthus Nov 1, 2026
020b877
merge: feat/migrate-email-resend into feat/migrate-email-resend-cutover
Silthus Nov 1, 2026
8452a82
fix(skills): pin migrate-email's test start to the database clock and…
Silthus Nov 1, 2026
53a190c
fix(skills): keep migrate-email's test clock uncached and report depe…
Silthus Nov 1, 2026
50b5f27
fix(skills): keep migrate-email's chain query uncached on its rerun
Silthus Nov 1, 2026
8f77354
fix(skills): keep cc, bcc, headers, tags and attachments sites on Res…
Silthus Nov 2, 2026
d871b8e
Merge feat/migrate-email-resend into feat/migrate-email-resend-cutover
Silthus Nov 2, 2026
b9d785e
Drop local templates and parked fields from the cutover steps
Silthus Nov 2, 2026
5edeb92
feat(migrate-email): set migratedFrom on the posthog-node client
Silthus Nov 2, 2026
64cf8ef
fix(migrate-email): ask for the PostHog template ID before a template…
Silthus Nov 2, 2026
85f6096
fix(migrate-email): check each PostHog template and its sender before…
Silthus Nov 2, 2026
a759ff4
fix(migrate-email): ask about a repeat import and test a send that na…
Silthus Nov 2, 2026
5c8a34b
fix(migrate-email): ask for the PostHog template ID and sender before…
Silthus Nov 2, 2026
e053dab
Merge feat/migrate-email-resend into feat/migrate-email-resend-cutover
Silthus Nov 2, 2026
efa4933
fix(skills): read Dirent.path when parentPath is missing in the migra…
Silthus Nov 2, 2026
5e40f2a
Merge feat/migrate-email-resend into feat/migrate-email-resend-cutover
Silthus Nov 2, 2026
2c36853
fix(migrate-email): match account.md's template-content rule to Step 3
Silthus Nov 2, 2026
8dcf6e7
fix(migrate-email): keep a site on Resend when its idempotency key do…
Silthus Nov 2, 2026
07dbf3a
fix(migrate-email): name PostHog's idempotency key rule exactly
Silthus Nov 2, 2026
a1376c0
Merge feat/migrate-email-resend into feat/migrate-email-resend-cutover
Silthus Nov 2, 2026
21f683e
fix(migrate-email): end Step 8's email check when the person declines…
Silthus Nov 2, 2026
d157859
docs(migrate-email): say where a send without distinctId lands
Silthus Nov 3, 2026
5dcdd21
docs(migrate-email): test Step 8 on a site that passes distinctId
Silthus Nov 3, 2026
4fc8d41
docs(migrate-email): say why cc, bcc and attachments stay on Resend
Silthus Nov 4, 2026
9664659
docs(migrate-email): name the real reason a field stays on Resend
Silthus Nov 4, 2026
4e5a672
docs(migrate-email): give scheduled sends and topics a reason too
Silthus Nov 4, 2026
8d88206
fix(migrate-email): keep a site on Resend when its key length is unbo…
Silthus Nov 4, 2026
5863a99
fix(migrate-email): quote Resend fallbacks with single quotes only
Silthus Nov 4, 2026
eed16c6
fix(migrate-email): record the PostHog key as set only after a check …
Silthus Nov 4, 2026
2d91936
fix(migrate-email): accept spaces around = in the key check
Silthus Nov 4, 2026
074130e
fix(migrate-email): check the last assignment of the PostHog key
Silthus Nov 4, 2026
5c92245
docs(migrate-email): ask for the transactional_email:write scope
Silthus Nov 5, 2026
f5080a7
Merge remote-tracking branch 'origin/feat/migrate-email-resend' into …
Silthus Nov 5, 2026
254dbb9
fix(migrate-email): name the transactional email scope in the preflight
Silthus Nov 5, 2026
464644f
Merge branch 'feat/migrate-email-resend' into feat/migrate-email-rese…
Silthus Nov 5, 2026
4ce6c2d
docs(migrate-email): record engagement events only when engagement ca…
Silthus Nov 9, 2026
0192a3d
fix(migrate-email): keep an app's PostHog key, and a Resend HTTP call…
Silthus Nov 12, 2026
5c996de
fix(migrate-email): keep email off a disabled client, and pass numeri…
Silthus Nov 12, 2026
e22fa6c
Merge branch 'main' into feat/migrate-email-resend
Silthus Nov 12, 2026
ae88e6e
Merge branch 'feat/migrate-email-resend' into feat/migrate-email-rese…
Silthus Nov 12, 2026
487262b
fix(skills): close the migrate-email preparation gaps the QA swarm found
Silthus Nov 12, 2026
00b9aa3
fix(skills): tighten the migrate-email key check and template rules
Silthus Nov 12, 2026
bde5bb6
Merge branch 'feat/migrate-email-resend' into feat/migrate-email-rese…
Silthus Nov 12, 2026
708f7f1
fix(migrate-email): keep each site's own HTTP deadline
Silthus Nov 12, 2026
56158d1
fix(migrate-email): keep marketing sends on the provider
Silthus Nov 12, 2026
04e7c84
fix(migrate-email): read the provider's report notes without the impo…
Silthus Nov 12, 2026
7c388d1
Merge branch 'feat/migrate-email-resend' into feat/migrate-email-rese…
Silthus Nov 12, 2026
0186ee2
fix(migrate-email): answer the round 1 review of the rewrite and veri…
Silthus Nov 12, 2026
30f3873
fix(migrate-email): match baseline typecheck errors without their line
Silthus Nov 12, 2026
dc18f5d
fix(migrate-email): count each baseline typecheck error
Silthus Nov 12, 2026
a2994e9
fix(migrate-email): keep a named recipient on Resend
Silthus Nov 12, 2026
bde40bc
Merge remote-tracking branch 'origin/feat/migrate-email-resend' into …
Silthus Nov 12, 2026
497d017
fix(migrate-email): keep a site on Resend when it needs a suppressed …
Silthus Nov 12, 2026
69edcdd
fix(migrate-email): keep a Resend SDK send with an abortable signal o…
Silthus Nov 12, 2026
a66e15b
fix(migrate-email): upgrade mocked send tests to the HTTP boundary
Silthus Nov 12, 2026
18ab351
fix(migrate-email): fake fetch instead of keeping a send mock
Silthus Nov 12, 2026
cff58f5
fix(migrate-email): route a network failure the way Resend's code did
Silthus Nov 12, 2026
2df1f26
fix(migrate-email): read the project token with project-get
Silthus Nov 12, 2026
5e0607f
fix(migrate-email): keep sites a Resend webhook handler acts on, and …
Silthus Nov 13, 2026
eeed7cb
fix(migrate-email): check every error in a rewritten line against its…
Silthus Nov 13, 2026
77b680b
fix(migrate-email): give Step 8 one rule for which typecheck errors a…
Silthus Nov 13, 2026
1d85155
fix(migrate-email): tie the kept Resend error names to posthog-node, …
Silthus Nov 13, 2026
013a98e
Merge #450 (feat/migrate-email-resend) into feat/migrate-email-resend…
Silthus Nov 13, 2026
19b1b90
fix(migrate-email): mark secret emails sensitive, check template keys…
Silthus Nov 13, 2026
fdea2d3
fix(migrate-email): send sensitive only with rendered content, and on…
Silthus Nov 13, 2026
2fe8430
fix(migrate-email): check the app's Node version and count removed er…
Silthus Nov 13, 2026
a090b5b
chore: merge main after #450 landed
Silthus Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion context/skills/migrate-email/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
type: skill
template: description.md
category: migrate
description: Migrate transactional email from {display_name} to PostHog. Use when asked to migrate from {display_name}, replace {display_name} with PostHog, or switch email providers. It finds every {display_name} send in the code, sets up the sender and DNS next to {display_name}'s records, imports {display_name}'s suppression list, hands over the PostHog secret key, and writes a migration report. It changes no send call site yet.
description: Migrate transactional email from {display_name} to PostHog. Use when asked to migrate from {display_name}, replace {display_name} with PostHog, or switch email providers. It finds every {display_name} send in the code, sets up the sender and DNS next to {display_name}'s records, imports {display_name}'s suppression list, moves each send PostHog can take to posthog-node, and writes a migration report that lists the sends that stay.
tags: [migration, workflows]
cli:
role: command
Expand Down
14 changes: 7 additions & 7 deletions context/skills/migrate-email/description.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Use this skill to move an app's transactional email, such as welcome emails, password resets, and receipts, from {display_name} to PostHog.

This version prepares the move and changes no send call site. It finds every {display_name} send, sets up the PostHog sender and its DNS records next to {display_name}'s, imports {display_name}'s suppression list, hands over the PostHog secret key, and writes a report. Both providers can send during the cutover.
It finds every {display_name} send, sets up the PostHog sender and its DNS records next to {display_name}'s, imports {display_name}'s suppression list, and hands over the PostHog secret key. Then it moves every send PostHog can take to `posthog-node`, checks one email on one person, and writes a report. Sends PostHog can't take stay on {display_name} with a reason, so both providers send during the cutover.

The transactional email API is in beta. PostHog enables it per project.

Expand All @@ -17,8 +17,8 @@ Read the step files in order, one at a time. Each step names the next one. Do no
The folder `references/<provider>/` holds everything specific to {display_name}. The steps tell you when to read each file:

- `sdk-reference.md`: how {display_name} looks in code, so you can find every send.
- `mapping.md`: how each send field maps to PostHog, and what keeps a call site on {display_name}.
- `account.md`: {display_name}'s DNS records and how to export its suppression list.
- `mapping.md`: how each send field maps to PostHog, what keeps a call site on {display_name}, and how to rewrite a site that moves.
- `account.md`: {display_name}'s DNS records, and how to get its templates and its suppression list.

Everything you need is on disk. Do not fetch {display_name}'s docs.

Expand All @@ -28,10 +28,10 @@ The plan file `.posthog-email-migration-plan.md` lives at the project root. Step

## Rules

- Change no send call site. This version only prepares the move.
- Change send code only in Step 7, and fix it only in Step 8: the sites that move, the helpers, callers, and tests they need, and other `posthog-node` code that the upgrade breaks. Leave every site that stays as it is.
- Never touch DNS or the {display_name} account. Give the person the records and the links, and let them make the change.
- Never remove the {display_name} package, its client, or its API key.
- Never create, upload, or edit a template in PostHog.
- Never remove the {display_name} package or its API key. The report tells the person when to remove them.
- Never create, upload, or edit a template in PostHog. The person makes each template that moves to PostHog.
- Never write a recipient's email address into a file in the repository, the plan, or the report. Count addresses instead.
- Keep keys in environment variables. Never hardcode a key, and never ask the person to paste one into the chat.
- Do not commit. The person reviews the diff and commits.
Expand All @@ -54,4 +54,4 @@ Outside the Wizard, skip the `[STATUS]` lines, and tell the person why you stopp

`transactional-emails.md` is the transactional email overview. It covers how to create a transactional email and its API key, idempotency, and the error codes. `api.md` covers the send route, including content from your code, and the checks of a send.

When the `sending-transactional-emails` skill is available, read it too. Its `moving-from-other-providers.md` moves any provider's sends to a PostHog template. This skill adds what is specific to {display_name}: it finds every send, sets up the sender next to {display_name}'s DNS records, imports {display_name}'s suppression list, and hands over the key.
When the `sending-transactional-emails` skill is available, read it for the PostHog side of a send. Its `moving-from-other-providers.md` moves sends to a template stored in PostHog. This skill moves {display_name}'s sends to `posthog-node`, with the content in the app's code, or to a template the person makes in PostHog. Where the two disagree, this skill's steps win.
22 changes: 19 additions & 3 deletions context/skills/migrate-email/references/3-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ next_step: 4-sender.md

# Step 3, list and classify every send

List every place the code sends email through the provider, and decide for each one whether PostHog can send it. Change no source file. The only file you write is the plan file.
List every place the code sends email through the provider, and decide for each one whether PostHog can send it. Change no source file. The only files you write are the plan file and the template files below.

## Status

Expand Down Expand Up @@ -33,6 +33,8 @@ For each site, read the surrounding code and record:

Also list every other call to the provider that is not a send, such as reading an email's status, contacts, or domains. These calls stay on the provider. Note what each one does, because a site whose code reads the status back stays on the provider too.

When `sdk-reference.md` has a "Webhooks" section, also list each webhook handler: a route of the app that receives the provider's delivery events. Note the events it handles, what it does with them, and how it finds the send an event belongs to, such as by the provider's message id, by a value the send set, or by the recipient's address. `mapping.md` says under "Webhooks" which sites a handler keeps on the provider.

When you find no site, stop before you write the plan file:

```
Expand All @@ -47,10 +49,20 @@ Then go through `mapping.md` field by field. A site **moves** when PostHog can s

When the code passes a value you can't read, such as a list of recipients built at run time, follow it to its callers. When you still can't tell, the site stays, and the reason says what you could not check.

A `template` site moves only to a template made in PostHog, and the person makes that template. Check the site's other fields first: a site that another field keeps on the provider stays with that reason, and needs no question about its template. Ask the person once, for every other template the sites send, whether to move it to PostHog or keep it on the provider for now. A template they keep stays, and the reason is `kept on <provider name> for now`. For each template they move, ask them to copy it from the provider's dashboard into a file outside the repository, and to tell you where they saved it. Read those files to classify the site, and never write the content into the plan. When the person can't give the content, the site stays, and the reason is `template content not checked`.
A `template` site moves only to a template made in PostHog, and the person makes that template. Check the site's other fields first: a site that another field keeps on the provider stays with that reason, and needs no question about its template. Ask the person once, for every other template the sites send, whether to move it to PostHog or keep it on the provider for now. A template they keep stays, and the reason is `kept on <provider name> for now`.

A template they move needs its content to be classified. Read the provider's `account.md`, and ask the person once for every template they move: copies from the dashboard that they save in files outside the repository and tell you where, or a read through the API. Read the person's copies where they saved them. Write an API answer to a file in the system's temporary folder, never in the repository or the plan, and delete that file as soon as its site is classified. When the person can't give the content, the site stays, and the reason is `template content not checked`.

A template whose content passes the checks moves only once the person has made it in PostHog. Ask them once, for every such template, to make it in PostHog from the provider's template and give you its template ID and the address it sends from, usually the provider template's sender. PostHog makes a template transactional only once a verified sender covers its address: ask them to make it transactional now when the project has one, and otherwise once Step 4 verifies the sender. When the email carries a login code, a reset link, or another secret, ask them to mark the template sensitive, as `mapping.md` says. The report lists both before cutover either way. Tell them how its placeholders change, as `mapping.md` says under "Content". Record each template ID with its site under the sites table, and write the address in the site's `from` column, so Step 4 sets up a sender for its domain. A template without an ID stays, and the reason is `PostHog template not made yet`.

### Opens the provider didn't track

PostHog adds its open pixel to every email it sends, in the code form and from a template made in PostHog alike. Check this for each site that nothing else keeps on the provider, as the provider's `account.md` says: whether the provider tracked the opens of its emails, with an open pixel in each one.

- When a site's emails had no open pixel, because the provider never tracks opens, or open tracking was off or never set up, ask the person once, for all such sites together, whether PostHog may add its open pixel to emails that never had one. Yes: those sites move, and the report says that PostHog now counts their opens. No, or no answer: they stay, and the reason is `open tracking off`.
- When nobody can tell whether the provider tracked a site's opens, the site stays, and the reason is `open tracking not checked`.
- For each site that moves with the person's yes, write `open pixel added: the person agreed` in its note under the sites table, so the report names it.

## Write the plan file

Write `.posthog-email-migration-plan.md` at the project root with three sections. Never write an email address of a recipient into it. A `from` address is fine.
Expand All @@ -63,8 +75,12 @@ A phase checklist, in this order. Tick `preflight` with what Step 2 recorded, an
- [ ] sender
- [ ] suppressions
- [ ] key
- [ ] rewrite
- [ ] verify
```

When the run created a full-access provider key, as `account.md` says, add a line under the checklist: `full-access key β€” created: <variable name>`. Step 5 adds whether the person deleted it.

A sites table, one row per site, in source tree order:

```
Expand All @@ -73,4 +89,4 @@ A sites table, one row per site, in source tree order:

`moves` is `yes` or `no`. `reason` is empty when the site moves.

A list of the other provider calls, each with its file, line, and what it does.
A list of the other provider calls, each with its file, line, and what it does, and a list of the webhook handlers, each with its file, line, the events it handles, and how it finds the send.
8 changes: 6 additions & 2 deletions context/skills/migrate-email/references/5-suppressions.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Read the provider's `account.md` first, whether or not the import runs. Its "For

Look for the PostHog MCP tool `email-suppressions-add`, and read its schema with `info`.

When it is missing, the import is not available to this person yet. Do not try other tools, and do not use the opt-out tools: opt-outs are marketing preferences, and transactional email ignores them. Tick the phase as `- [ ] suppressions β€” not imported: no import tool`, and continue to the next step. The report tells the person to add the addresses in PostHog (Workflows, then Messaging, then Suppression list) right before cutover, so the list holds the entries the provider adds until then.
When it is missing, the import is not available to this person yet. Do not try other tools, and do not use the opt-out tools: opt-outs are marketing preferences, and transactional email ignores them. Tick the phase as `- [ ] suppressions β€” not imported: no import tool`, ask about the full-access key as the last section says, and continue to the next step. The report tells the person to add the addresses in PostHog (Workflows, then Messaging, then Suppression list) right before cutover, so the list holds the entries the provider adds until then.

## Get the list

Expand All @@ -37,8 +37,12 @@ The provider's `account.md` says how to export the list, which entries to take,
- Repeating an import is safe: an address already on the list stays on it.
- The provider keeps adding to its list while it sends, so the report asks the person for one last import right before cutover.
- Never print the addresses, and never write them into the plan or the report. Count them.
- When a call fails, read its error and fix the call. When it fails again, stop the import and record how many entries you imported.
- When a call fails, read its error and fix the call. When it fails again, stop the import, record how many entries you imported, and ask the person once whether to repeat it now. Repeat it when they say yes.

## Write down

Tick the phase in the plan file only when every entry is imported: `- [x] suppressions β€” <entries>/<entries> imported`. When the list is empty, write `- [x] suppressions β€” empty list`. When the import stopped partway, write `- [ ] suppressions β€” <imported>/<entries> imported: <the error>`. When the person has no export and no key, write `- [ ] suppressions β€” not imported: <why>`.

## The full-access key

Every way out of this step ends here. When the plan says the run created a full-access provider key, ask the person now to delete it at the provider and remove its variable from the env file, as `account.md` says. After a partial import, ask once the person said no to a repeat, or the repeat ended. Note in the plan whether they did.
2 changes: 1 addition & 1 deletion context/skills/migrate-email/references/6-key.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Hand over the PostHog secret key
next_step: 7-report.md
next_step: 7-rewrite.md
---

# Step 6, hand over the PostHog secret key
Expand Down
83 changes: 0 additions & 83 deletions context/skills/migrate-email/references/7-report.md

This file was deleted.

Loading
Loading