Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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: 2 additions & 0 deletions context/skills/migrate-email/references/3-inventory.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,4 +108,6 @@ A sites table, one row per site, in source tree order:

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". For each site that stays because it relies on the provider's suppression list, note what would let it move, as Step 3 says after the sender check.

In any step, when the provider's `mapping.md` or `account.md`, or a rewrite file, says to note something for the report's "Before cutover" list, write it under the table as a note that starts with `before cutover:`, such as `before cutover: enable ext-curl where the app runs`. When a later step undoes what a note is about, such as an SDK install that Step 7 undoes under "Set up the SDK", it deletes the note. Step 9 lists each note left.

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.
4 changes: 2 additions & 2 deletions context/skills/migrate-email/references/5-suppressions.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ After the migration, while any site still sends through a provider that keeps a

1. Start with "Read the provider's notes", writing nothing down, since there is no plan file. When `account.md` says the provider keeps no suppression list at all, tell the person there is nothing to re-import, because <provider name> keeps no suppression list, and stop.
2. 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.
3. 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".
3. 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 that the addresses the provider added since the last import can't reach PostHog yet: PostHog's Suppression list page adds an address only as a manual entry, which blocks marketing email but not the moved sends. Then go to "The full-access key".
4. Tell the person how many entries you imported, of how many, or that the import tool was missing, or why you couldn't get the list, and stop when this step ends: do not go on to the next step, and change no other file.

## Read the provider's notes
Expand All @@ -32,7 +32,7 @@ When `account.md` says the provider keeps no suppression list at all, there is n

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`, 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.
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. Adding the addresses by hand doesn't take the import's place: PostHog's Suppression list page adds an address only as a manual entry, which blocks marketing email but not the moved sends. So, outside a re-import, ask the person once whether the provider's list has any entries and, when it does, which sites that move rely on it to skip addresses that bounced, and set each one's `moves` to `no` with Step 3's reason `relies on <provider name>'s suppression list` and the note `to move: import the suppression list once PostHog's import tool is available`. When they can't tell or don't answer, every site that moves stays with that reason. Update the count in the plan's `inventory` line. Then tick the phase as `- [x] suppressions — empty list: no import tool` when the list has no entries, and as `- [ ] suppressions — not imported: no import tool` otherwise, 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.

## Get the list

Expand Down
2 changes: 1 addition & 1 deletion context/skills/migrate-email/references/7-rewrite.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Before you install or upgrade an SDK, check the release you install against ever

When the app already used the SDK and the upgrade crosses a major version, read the installed package's changelog when it ships one, such as `CHANGELOG.md`, and search the whole repository for the app's other calls into the SDK, such as `capture` and `identify`. Fix each call the new major version changed, and note it for the report. A check that reads only syntax doesn't find these.

When the latest release lacks one of these, change no site that needs it. Mark each such row `moves: no — <SDK> has no <capability> yet`, tell the person, and go on with the rest. When the client options lack the provider name, leave it out of the client. When no site is left in a language, undo that SDK's install or upgrade. When no site is left at all, delete each temporary copy of template content, tick the phase with `none moved`, and go to the next step.
When the latest release lacks one of these, change no site that needs it. Mark each such row `moves: no — <SDK> has no <capability> yet`, tell the person, and go on with the rest. When the client options lack the provider name, leave it out of the client. When no site is left in a language, undo that SDK's install or upgrade, with each other change its rewrite file's "Install" made, such as `ext-curl` in `composer.json`, and delete each `before cutover:` note it wrote. When no site is left at all, delete each temporary copy of template content, tick the phase with `none moved`, and go to the next step.

## Set up the client

Expand Down
6 changes: 3 additions & 3 deletions context/skills/migrate-email/references/9-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Read `.posthog-email-migration-plan.md`. Write `posthog-migrate-email-<provider>

<One row per site. Key is the `templateKey` of a moved site, or its `templateId` for a template made in PostHog. A site whose provider template moved into the code names its email's files. Status is "Moved", "Moved without distinctId: <why>", or "Stays on <provider name>: <reason>".>

<Each note under the plan's sites table: each fallback that an empty string now replaces, each site that got a branch for a suppressed recipient, each site whose plan note says `open pixel added`, whose opens PostHog now counts with a pixel its emails never had, and each idempotency key a retry across the deploy could send twice.>
<Each note under the plan's sites table, except a note that starts with `before cutover:`: each fallback that an empty string now replaces, each site that got a branch for a suppressed recipient, each site whose plan note says `open pixel added`, whose opens PostHog now counts with a pixel its emails never had, and each idempotency key a retry across the deploy could send twice.>

## Other <provider name> calls

Expand Down Expand Up @@ -63,13 +63,13 @@ Read `.posthog-email-migration-plan.md`. Write `posthog-migrate-email-<provider>

The moved sites send through PostHog as soon as this code is deployed. Everything in this list has to be done before that deploy.

<A numbered list of everything the person still has to do. Include each unverified domain, a missing or partial suppression import, `POSTHOG_PROJECT_SECRET_API_KEY` in the env file when the plan says it is not set, each place that needs the PostHog key and each new env variable, a tier that is too low or not checked, an API that is not confirmed, sends with content from the code (`html`, `text`, or `react`, and each template brought into the code) when a site that moves has them (confirm with PostHog that the project can send them), a failed check, a dependency upgraded across a major version whose changelog the person should read, each idempotency key a retry across the deploy could send twice, each email brought into the code with its files (compare one send with the provider's, and change the email in the code from now on, not at the provider), each image the provider hosts that such an email shows (host it yourself before you close the provider account), each value such an email now escapes that the provider inserted as it was (check that the email still reads as intended), each template made in PostHog with its ID (send a test of it from PostHog, and check that it is transactional, sends from a verified sender, fills each variable the site sends, and is marked sensitive when its note in the plan says `must be marked sensitive`, with the note's reason), each webhook handler that the moved sends no longer reach, each provider key written in the source rather than read from the environment (the person rotates it at the provider), each item a rewrite file says to note for this list, and each site that stays with what would let it move. Each item is something the person does. Leave out notes that ask for no action. After an import, always end with: import the entries the provider added to its suppression list since the export, right before cutover. When nothing is left, write "Nothing left before cutover.">
<A numbered list of everything the person still has to do. Include each unverified domain, a missing or partial suppression import, `POSTHOG_PROJECT_SECRET_API_KEY` in the env file when the plan says it is not set, each place that needs the PostHog key and each new env variable, a tier that is too low or not checked, an API that is not confirmed, sends with content from the code (`html`, `text`, or `react`, and each template brought into the code) when a site that moves has them (confirm with PostHog that the project can send them), a failed check, a dependency upgraded across a major version whose changelog the person should read, each idempotency key a retry across the deploy could send twice, each email brought into the code with its files (compare one send with the provider's, and change the email in the code from now on, not at the provider), each image the provider hosts that such an email shows (host it yourself before you close the provider account), each value such an email now escapes that the provider inserted as it was (check that the email still reads as intended), each template made in PostHog with its ID (send a test of it from PostHog, and check that it is transactional, sends from a verified sender, fills each variable the site sends, and is marked sensitive when its note in the plan says `must be marked sensitive`, with the note's reason), each webhook handler that the moved sends no longer reach, each provider key written in the source rather than read from the environment (the person rotates it at the provider), each plan note that starts with `before cutover:`, and each site that stays with what would let it move. Each item is something the person does. Leave out notes that ask for no action. After an import, always end with: import the entries the provider added to its suppression list since the export, right before cutover. When nothing is left, write "Nothing left before cutover.">

## After cutover

<What the person removes once the moved emails arrive from PostHog: when no site stays and no other provider call is left, the provider's package and its key in every place listed above. Otherwise, write that the provider stays for the sites and calls listed above, and name each part of the app with its own dependency manifest, such as a worker in another language, where no site or call is left, no code imports or re-exports the provider's package or client for another part, and `mapping.md` doesn't keep the package for other uses: its provider package can go. When the plan says the run created a full-access provider key and the person has not deleted it yet, the person deletes that key at the provider and removes its variable from the env file. Add each app call that removes an address from the provider's suppression list, as Step 5 says under "Calls that change the provider's list".

When a site stays on the provider, it keeps adding addresses that bounce to the provider's suppression list, and PostHog never sees them, so a moved send can mail them. Tell the person to re-import the list weekly while any site sends through the provider, as Step 5 says under "Re-import only": a moved send then mails an address that bounced for a week at most, and a release schedule wouldn't do, since the sites that stay add entries between releases. Give the prompt that re-imports only the list, `Re-import the <provider name> suppression list into PostHog with the migrate-email-<provider folder name> skill`, or, when the plan says the import tool was missing, the PostHog page where the person adds the addresses by hand. Say that a re-import is safe to repeat: an address already on PostHog's list stays on it. Ask for one final import after the deploy that moves the last site off the provider. When no site stays, or the plan says the provider keeps no suppression list, leave this out: the import right before cutover is the last one, or there is no list to grow.
When a site stays on the provider, it keeps adding addresses that bounce to the provider's suppression list, and PostHog never sees them, so a moved send can mail them. Tell the person to re-import the list weekly while any site sends through the provider, as Step 5 says under "Re-import only": a moved send then mails an address that bounced for a week at most, and a release schedule wouldn't do, since the sites that stay add entries between releases. Give the prompt that re-imports only the list, `Re-import the <provider name> suppression list into PostHog with the migrate-email-<provider folder name> skill`, or, when the plan says the import tool was missing, say that those addresses can't reach PostHog until the import tool is available: an address added by hand on PostHog's Suppression list page blocks marketing email only, so a moved send still reaches it. Say that a re-import is safe to repeat: an address already on PostHog's list stays on it. Ask for one final import after the deploy that moves the last site off the provider. When no site stays, or the plan says the provider keeps no suppression list, leave this out: the import right before cutover is the last one, or there is no list to grow.

When a moved send has a template key, list the keys, and tell the person to give each template they save in PostHog from now on another key: a send whose key a saved template has goes out through that template's settings. It fails when that template isn't transactional, and unless the send sets the sensitive flag, it takes the template's sensitive setting, off by default, so its links go through PostHog's click redirect and its subject lands on engagement events.>

Expand Down
2 changes: 1 addition & 1 deletion context/skills/migrate-email/references/rewrite-php.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ For a site in PHP, such as in a Laravel or Symfony app. A site that sends throug

`composer require posthog/posthog-php`, which installs or upgrades it to the latest release that the project's constraints allow. Raise the constraint in `composer.json` when it holds the package back.

The send needs PHP's curl extension, which Composer doesn't ask for: without it every send fails with the code `missing_curl`. Add `"ext-curl": "*"` to `require` in `composer.json`, so an install where it's missing fails instead. When the app's Dockerfile, buildpack, or server setup doesn't show that it installs the extension, such as the official `php` Docker image, which has it built in, or a `php-curl` or `php8.3-curl` package, note it for the report's "Before cutover" list: enable ext-curl where the app runs.
The send needs PHP's curl extension, which Composer doesn't ask for: without it every send fails with the code `missing_curl`. Add `"ext-curl": "*"` to `require` in `composer.json`, so an install where it's missing fails instead. When the app's Dockerfile, buildpack, or server setup doesn't show that it installs the extension, such as the official `php` Docker image, which has it built in, or a `php-curl` or `php8.3-curl` package, note it for the report's "Before cutover" list: `before cutover: enable ext-curl where the app runs`.

## The client

Expand Down
Loading