Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
5d29690
feat(migrate-email): map turned-off open and click tracking to track_…
Silthus Nov 9, 2026
ec3783e
feat(migrate-email): map only turned-off open tracking to track_opens…
Silthus Nov 9, 2026
dc66635
feat(migrate-email): map turned-off open tracking to the tracking option
Silthus Nov 10, 2026
a90c30a
fix(migrate-email): use SDK tracking names and skip tracking on templ…
Silthus Nov 10, 2026
07c4c06
feat(migrate-email): map a provider's sensitive or no-track setting t…
Silthus Nov 11, 2026
553a223
fix(migrate-email): mark every migrated code send sensitive
Silthus Nov 11, 2026
bad56da
Merge branch 'feat/migrate-email-all-sdks' into feat/migrate-email-tr…
Silthus Nov 12, 2026
c6f7e9a
fix(migrate-email): move untracked-open sites with opens off, no ask
Silthus Nov 12, 2026
959512a
feat(migrate-email): move a Resend send's attachments to posthog-node
Silthus Nov 12, 2026
2fdadc2
refactor(migrate-email): keep file rules any provider shares in Step 3
Silthus Nov 12, 2026
e8ff4c1
Merge remote-tracking branch 'origin/feat/migrate-email-all-sdks' int…
Silthus Nov 12, 2026
0600160
Merge remote-tracking branch 'origin/feat/migrate-email-track-opens-a…
Silthus Nov 12, 2026
5070619
feat(migrate-email): attach files with every PostHog SDK
Silthus Nov 12, 2026
d8dd2d4
fix(migrate-email): ask for re-imports only when the provider keeps a…
Silthus Nov 12, 2026
af88e18
Merge remote-tracking branch 'origin/feat/migrate-email-all-sdks' int…
Silthus Nov 12, 2026
a041e6f
fix(migrate-email): cover what run 1 on a real app hand-fixed
Silthus Nov 12, 2026
3e77db0
fix(migrate-email): cover what run 2 on a real app hand-fixed
Silthus Nov 12, 2026
d15ba9b
fix(migrate-email): no retry on a used-up upload allowance, and the a…
Silthus Nov 12, 2026
d1f47d8
fix(migrate-email): a lint-safe digest stub, and the tests that check…
Silthus Nov 12, 2026
432da66
fix(migrate-email): a file content type with parameters moves only on…
Silthus Nov 13, 2026
8eddf6d
Name PostHog's header limits on a file's name, content type and conte…
Silthus Nov 13, 2026
41e37f1
Check Step 3's header rules on the mapped value, and put files in the…
Silthus Nov 13, 2026
fe6a07e
Merge feat/migrate-email-resend-attachments into feat/migrate-email-m…
Silthus Nov 13, 2026
de51009
feat(migrate-email): move a Mailjet send's attachments to PostHog
Silthus Nov 13, 2026
763e989
fix(migrate-email): re-cite Mailjet SDK claims to Mailjet's docs, or …
Silthus Nov 13, 2026
2eb48c6
fix(migrate-email): read every spelling Mailjet's pages give for a v3…
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
4 changes: 4 additions & 0 deletions context/skills/migrate-email/references/2-preflight.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ Check which PostHog MCP tools exist.

Do not call a tool that changes anything to find out.

The MCP speaks for one project: the one `project-get`, called without an ID, returns. When the app's project token, read only from its own line as Step 8 says, is not that project's `api_token`, the MCP's answers say nothing about the app's project. Ask the person to switch the MCP to the app's project. When they can't, record `api: not confirmed — the MCP can't see the app's project`, and ask the person, wherever a later step reads the project through the MCP, what that step would read.

When the app already sends email with a PostHog SDK's code send, a send with a template key and content from the code, and the person says it delivers in production, record `api: on — the app already sends code emails`: the project takes sends with content from the code too. This record wins over `not confirmed`, also when the MCP can't see the project.

Those tools confirm sends by template. PostHog enables sends with content from the code separately, and no tool shows it. The report asks the person to confirm it before cutover when a site that moves sends its content from the code.

## The sending tier
Expand Down
41 changes: 36 additions & 5 deletions context/skills/migrate-email/references/3-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,11 +72,40 @@ A template the person asks to make in PostHog moves in the template form, by its

### 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.
PostHog adds its open pixel to every email it sends unless the send turns its `opens` switch off, as Step 7 says. Check for each site that nothing else keeps on the provider whether the provider tracked the opens of its emails, with an open pixel in each one, as the provider's `account.md` says. Never ask the person whether PostHog may add its pixel: the site moves either way.

- 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.
- When a site's emails had no open pixel, because the provider never tracks opens, or open tracking was off or never set up, the site moves with opens off. Write `opens off: <provider name> didn't track its opens` in its note under the sites table.
- 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.
- When the app's docs promise that the site's emails carry no open tracking, as "Code and docs around the sends" below finds, the site moves with opens off, whatever the provider did. Write `opens off: <file> promises no open tracking` in its note.
- 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.

### Files

A site that sends files, which the provider calls attachments, moves only when every file can go through PostHog's send. The provider's `mapping.md` maps each file field to PostHog's, and says which of the provider's own file features keep a site. Whatever the provider, a site with files stays when:

- its language's PostHog SDK has no release that takes files. The reason is `<SDK> has no attachments yet`. Step 7's table names the SDK of each language. Read that table and the "The send" section of the language's rewrite file now, for this check only: it says how to tell whether a release takes files. The release that counts is the one Step 7 would install: the latest on the package registry, or a build the person names as the one to use.
- the list can hold more than 10 files, or the code builds it at run time and you cannot tell that it holds at most 10. The reason is `more than 10 files`.
- a file can be larger than PostHog takes: the email with all its files must stay under 40 MB after Base64 encoding, about 29 MB of files. When the code reads a file whose size it doesn't bound, such as a user's upload, follow it to where it is made. The reason is `files can pass 40 MB`, unless the code already refuses larger files.
- the provider fetches a file from a URL or a path: PostHog fetches no file, and only takes its bytes. The reason is `the provider fetches <file>`.
- a file has no filename, or a filename whose extension PostHog refuses, in any case, such as `report.EXE`: PostHog refuses the whole email, so the file would stop the email from going out. It refuses `.ade`, `.adp`, `.app`, `.asp`, `.bas`, `.bat`, `.cer`, `.chm`, `.cmd`, `.com`, `.cpl`, `.crt`, `.csh`, `.der`, `.exe`, `.fxp`, `.gadget`, `.hlp`, `.hta`, `.inf`, `.ins`, `.isp`, `.its`, `.js`, `.jse`, `.ksh`, `.lib`, `.lnk`, `.mad`, `.maf`, `.mag`, `.mam`, `.maq`, `.mar`, `.mas`, `.mat`, `.mau`, `.mav`, `.maw`, `.mda`, `.mdb`, `.mde`, `.mdt`, `.mdw`, `.mdz`, `.msc`, `.msh`, `.msh1`, `.msh2`, `.mshxml`, `.msh1xml`, `.msh2xml`, `.msi`, `.msp`, `.mst`, `.ops`, `.pcd`, `.pif`, `.plg`, `.prf`, `.prg`, `.reg`, `.scf`, `.scr`, `.sct`, `.shb`, `.shs`, `.sys`, `.ps1`, `.ps1xml`, `.ps2`, `.ps2xml`, `.psc1`, `.psc2`, `.tmp`, `.url`, `.vb`, `.vbe`, `.vbs`, `.vps`, `.vsmacros`, `.vss`, `.vst`, `.vsw`, `.vxd`, `.ws`, `.wsc`, `.wsf`, `.wsh`, `.xnk`. A filename the code builds at run time from a user's input, whose extension it doesn't fix, counts as one that can be refused. The reason is `a file PostHog refuses: <filename or where it comes from>`.
- a file's filename, content type or content ID breaks a rule of PostHog's for email headers: PostHog refuses the whole email. A filename has at most 255 characters and no `/`, `\`, line break or other control character (`unsafe_filename`). A content type has at most 78 characters. A content ID has at most 78 characters and no `<`, `>`, line break or other control character (`unsafe_content_id`). The rules hold for the value the send passes once the provider's `mapping.md` maps it: a content ID that the mapping turns into the bare ID the HTML shows, such as `<logo>` into `logo`, keeps them. A value the code builds at run time from a user's input, which it doesn't bound or clean, counts as one that breaks a rule. The reason is `a <filename, content type or content ID> PostHog refuses: <value or where it comes from>`.

A file whose content type carries parameters, such as `text/calendar; charset=utf-8; method=REQUEST` for a calendar invite, moves only when PostHog takes its parameters: PostHog has refused every parameter with `not_mime_type`, and taking it out changes the email. Without its `method`, a mail app shows a calendar invite as a file, with no invitation. Keep the content type as it is in the plan row, write `content type parameters not checked` in its note under the sites table, and let Step 8's check email decide.

Write each file of a site that moves in the `content` cell of its plan row: its filename, or where the code builds it, its content type, and the content ID the send passes when the HTML shows it inline.

For each site with files that stays, write in its plan row what would let it move, so the report can tell the person: read the file in the app and pass its bytes for a URL or a path, a fixed filename or extension for a refused one, a filename, content type or content ID that keeps PostHog's header rules, a bound on the size or the count, or the SDK release that takes files.

### Code and docs around the sends

The sends are not the only code that knows the provider. Search the repository, docs included, for the provider's name and for each variable that holds its key, and list what touches a site that moves. Change none of it in this step.

- **Switches.** Code that reads the provider's key to decide whether to send at all, such as an `isEmailConfigured()` that checks the variable is set. Note which sites each switch guards: Step 7 says what happens to it.
- **Counts and limits.** Code that counts the sends, labels them, or limits them to fit the provider's plan, such as a daily count stored under the provider's name, a daily cap, a share of that cap, or a pause between sends sized to the provider's rate limit. These stay as they are: the report names each, so the person can size it to PostHog's sending allowance.
- **Promises.** What the app's own docs promise about these emails: a privacy policy or terms that name the provider as a processor, say what it receives or how long it keeps it, or say that the emails carry no open or click tracking, and specs, ADRs, and setup docs that say these emails go through the provider. Note each with its file and line. Never change a legal text: the report asks the person to update it before cutover. A promise of no open or click tracking also turns opens off for the site, as "Opens the provider didn't track" says.
- **What the app's PostHog sends already do.** When the app already sends code emails with a PostHog SDK, note how: the module and client they use, how they read the key, token, and host, whether they turn engagement capture off, such as `tracking: { engagement: false }`, `tracking: false`, or the deprecated capture field set to `false`, and whether they pass a distinct ID. Step 7 follows them.

## Write the plan file

Expand Down Expand Up @@ -104,6 +133,8 @@ A sites table, one row per site, in source tree order:

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

Under the table, for each `template` site that moves, note its provider template's ID or name, whether it moves into the code or to a template made in PostHog, and where its content is: the person's copy, or the temporary file of the API answer. For a template made in PostHog, add its template ID, and `must be marked sensitive: <reason>` when Step 3 says it must be. For any site that moves with an open pixel its emails never had, note `open pixel added: the person agreed`, as Step 3 says under "Opens the provider didn't track".
Under the table, for each `template` site that moves, note its provider template's ID or name, whether it moves into the code or to a template made in PostHog, and where its content is: the person's copy, or the temporary file of the API answer. For a template made in PostHog, add its template ID, and `must be marked sensitive: <reason>` when Step 3 says it must be. For any site that moves with opens off, note `opens off: <reason>`, as Step 3 says under "Opens the provider didn't track".

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.

A list of the code and docs around the sends, under the headings `switches`, `counts and limits`, `promises`, and `app's PostHog sends`, each item with its file, line, and the sites it touches.
6 changes: 4 additions & 2 deletions context/skills/migrate-email/references/5-suppressions.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ The provider keeps a suppression list: addresses that hard-bounced or marked an

## Re-import only

After the migration, while any site still sends through the provider, the provider keeps adding the addresses that bounce or complain to its list, and PostHog never sees them. So the report asks the person to re-import the list weekly. When the person asks only for that re-import, run this step alone. There is no plan file, and no later step checks the run, so:
After the migration, while any site still sends through a provider that keeps a suppression list, the provider keeps adding the addresses that bounce or complain to its list, and PostHog never sees them. So the report asks the person to re-import the list weekly. When the person asks only for that re-import, run this step alone. There is no plan file, and no later step checks the run, so:

1. Make sure the import lands in the project the deployed app sends from, which may not be the one the local env file names. Read the MCP's active project, its name and `api_token`, with the PostHog MCP `project-get` tool, called without an ID, and ask the person once whether production sends from that project, naming it. When the env file's project token differs from that `api_token`, say so in the question. Read only the token's line of the env file, by searching for the token variable's name: the file also holds secret keys, so never open all of it. When the person says no, ask which project production sends from. When `projects-get` lists it, offer to switch to it with `switch-project`, ask again once switched, and when this step ends, switch back to the project you started from and tell the person. When it isn't listed, such as a project in another organization, or they can't tell or don't want the switch, stop before importing.
2. Do "Check the import tool", "Get the list", "Import it" and "The full-access key", reading the provider's `account.md` for them, and skip the other sections. When the import tool is missing, tell the person to add the addresses the provider added since the last import in the production project they confirmed, naming it (Workflows, then Messaging, then Suppression list), and go to "The full-access key".
Expand All @@ -29,6 +29,8 @@ 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 the MCP can't see the app's project, as Step 2 found, whatever it recorded for `api`, the tool would import into another project: never call it. Treat the tool as missing, as below, with `not imported: the MCP can't see the project` in place of `no import tool`.

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`, do what "Calls that change the provider's list" says, 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 @@ -53,7 +55,7 @@ The import copies the list once. After it, a call in the app that adds an addres

## 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>`.
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 provider keeps no suppression list at all, as its `account.md` says, write `- [x] suppressions — empty list: <provider name> keeps no suppression 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

Expand Down
8 changes: 7 additions & 1 deletion context/skills/migrate-email/references/6-key.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@ PostHog's send needs a project secret API key on the server. The provider's key

## The PostHog key

When the app already reads a PostHog project secret key, such as for code sends it already makes, under any name, that is the key: Step 7's email client reads it under the app's name, and you ask for no new one. Write its name into the plan where this step writes `POSTHOG_PROJECT_SECRET_API_KEY`, and in every later step read that name in its place. Check that the key has the `transactional_email:write` or `hog_flow:write` scope only by asking the person.

When the app reads its provider key from its hosting platform's environment and not from a file, such as a Convex deployment's environment variables, a Vercel or Netlify project's, or a Worker's secrets, the PostHog key goes there too: ask the person to set it with the platform's command or dashboard, in every deployment that sends email. Check it, where the platform's command line can list the variables, with a command that prints a count and never the value, such as `convex env list | grep -c '^POSTHOG_PROJECT_SECRET_API_KEY=phs_'`. When it can't, the person's word that they set it is the check.

Otherwise:

- Ask the person to create a project secret API key (it starts with `phs_`) with the `transactional_email:write` scope in their PostHog project settings. A key that already has `hog_flow:write` works too.
- The key goes into `POSTHOG_PROJECT_SECRET_API_KEY`, in the env file the app loads its provider key from, such as `.env` or `.env.local`. Check that git ignores that file. When it doesn't, ask the person where the key goes.
- Ask the person to add the key to that file themselves. Inside the Wizard, ask for it and store it as the "Inside the PostHog Wizard" section of `SKILL.md` says.
Expand All @@ -41,4 +47,4 @@ List each place that sets a value for it, with its file and line: env and env ex

## Write down

Tick the phase in the plan file only when the check above found the key: `- [x] key — POSTHOG_PROJECT_SECRET_API_KEY set in <file>`. Otherwise write `- [ ] key — not set: <why>`, such as `the person adds it to .env`. Under the phase list, add the places of the provider key.
Tick the phase in the plan file only when the check above found the key: `- [x] key — <variable name> set in <file or platform>`, such as `POSTHOG_PROJECT_SECRET_API_KEY set in .env`. Otherwise write `- [ ] key — not set: <why>`, such as `the person adds it to .env`. Under the phase list, add the places of the provider key.
Loading
Loading