diff --git a/context/skills/migrate-email/config.yaml b/context/skills/migrate-email/config.yaml index 8becd4c8..6f9a304f 100644 --- a/context/skills/migrate-email/config.yaml +++ b/context/skills/migrate-email/config.yaml @@ -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, moves each send PostHog can take to posthog-node, and writes a migration report that lists the sends that stay. +description: Migrate transactional email from {display_name} to PostHog. Use when asked to migrate from {display_name}, replace {display_name} with PostHog, switch email providers, or re-import the {display_name} suppression list into PostHog after a migration. It finds every {display_name} send in the code, sets up the sender and DNS next to the records the app sends with now, imports the suppression list, moves each send PostHog can take to PostHog's SDK for its language (Node.js, Python, Go, Ruby, PHP, .NET, Rust, or Elixir), and writes a migration report that lists the sends that stay. tags: [migration, workflows] cli: role: command diff --git a/context/skills/migrate-email/description.md b/context/skills/migrate-email/description.md index b36e4c43..94b07dfd 100644 --- a/context/skills/migrate-email/description.md +++ b/context/skills/migrate-email/description.md @@ -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. -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. +It finds every {display_name} send, sets up the PostHog sender and its DNS records next to the records the app sends with now, imports the suppression list, and hands over the PostHog secret key. Then it moves every send PostHog can take to PostHog's SDK for its language (Node.js, Python, Go, Ruby, PHP, .NET, Rust, or Elixir), 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. @@ -12,15 +12,19 @@ The transactional email API is in beta. PostHog enables it per project. Read the step files in order, one at a time. Each step names the next one. Do not read a step before the one before it tells you to. +When the person asks only to re-import the {display_name} suppression list into PostHog, after a migration, skip the workflow: read `5-suppressions.md` under "Re-import only" and do only that. + ## Provider files The folder `references//` 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, 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. +- `account.md`: the DNS records the app sends with now, and how to get the templates and the suppression list. + +The rewrite files next to the step files, `rewrite-.md`, have PostHog's email send in each language the sites can move in. Step 7 says which one to read. `template-to-code.md` says how a send of a template stored at {display_name} moves with its email in the app's code. Steps 3 and 7 say when to read it. -Everything you need is on disk. Do not fetch {display_name}'s docs. +Everything you need is on disk. Do not fetch the {display_name} docs. Never tell the person how PostHog behaves where these files don't say: say that you can't tell. ## Plan file @@ -28,7 +32,7 @@ The plan file `.posthog-email-migration-plan.md` lives at the project root. Step ## Rules -- 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. +- 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 SDK code that the SDK's 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 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. @@ -54,4 +58,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 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. +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 the {display_name} sends to PostHog's SDKs with the content in the app's code, and brings a template stored at {display_name} into the code too. It moves a send to a template the person makes in PostHog only when they ask for one. Where the two disagree, this skill's steps win. diff --git a/context/skills/migrate-email/references/1-detect.md b/context/skills/migrate-email/references/1-detect.md index fd4a47d3..e6549240 100644 --- a/context/skills/migrate-email/references/1-detect.md +++ b/context/skills/migrate-email/references/1-detect.md @@ -19,8 +19,8 @@ Read the provider's `sdk-reference.md`. It lists the provider's packages, import The provider is in this project when at least one of these is true: -- Its package is in a dependency manifest, such as `package.json`, `requirements.txt`, `pyproject.toml`, `Gemfile`, `composer.json`, or `go.mod`. -- Source code imports it or creates its client. +- Its package is in a dependency manifest, such as `package.json`, `requirements.txt`, `pyproject.toml`, `Gemfile`, `composer.json`, `go.mod`, a `.csproj` file, `mix.exs`, or `Cargo.toml`. +- Source code imports it or creates its client, including a module of the language's standard library that `sdk-reference.md` names. - Source code calls its HTTP host. - Source code, mail config, or an example env file names its SMTP host or its framework mailer. diff --git a/context/skills/migrate-email/references/3-inventory.md b/context/skills/migrate-email/references/3-inventory.md index 85f2e7c2..dcab8f2c 100644 --- a/context/skills/migrate-email/references/3-inventory.md +++ b/context/skills/migrate-email/references/3-inventory.md @@ -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 files you write are the plan file and the template files below. +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 temporary copies of template content below. ## Status @@ -20,18 +20,23 @@ Read the provider's `sdk-reference.md` for the call shapes, and its `mapping.md` A **site** is one place in the code that decides what a send contains: its content and its fields. Usually that is the `emails.send(...)` call or the HTTP request itself. -- When a helper builds the send from a few parameters, such as a subject and a template name, the helper is one site, however many places call it. Read its callers anyway: they decide values such as how many recipients a send has. -- When a helper only forwards a payload that its callers build, each caller is a site, and the helper is not. +- When a helper builds the send from a few parameters, such as a subject and a template name, the helper is one site, however many places call it. Read its callers anyway: they decide values such as how many recipients a send has. When some callers pass one address and others several, the helper stays, and the plan row names the callers that pass one address, so the person can give them a send of their own. +- When a helper only forwards a payload that its callers build, each caller is a site, and the helper is not. The same holds for a queue job or a transport that posts a message built elsewhere, such as a JSON string: each place that builds the message is a site. +- Find a helper's callers by searching the repository. When you can't find or read every caller, each send through the helper stays, and the reason names the caller or the value you could not read. +- A forwarding helper that nothing in the repository calls is not a site, unless the repository is a library that exports it: no code builds a message for it. List it with the other provider calls, and leave it as it is. A function that builds its own send stays a site, even when nothing in the repository calls it. +- When one function chooses between this provider and others, by a setting or as a fallback when a send fails, the branch that sends through this provider is the site. Move only that branch, and leave the other branches as they are. For each site, read the surrounding code and record: - The file and the line of the call. +- The language of the call, such as `node`, `python`, `go`, `ruby`, `php`, `dotnet`, `rust`, or `elixir`, by the name of its rewrite file in Step 7. A call in any other language, such as Java, is recorded under its own name: `mapping.md` keeps it on the provider. - How it sends: `sdk`, `http`, or `smtp`. - The content: `template` for a template stored at the provider, `react` for a component the provider renders, `html`, or `text`. A site that sets both `html` and `text` is `html`. - Every field the site sets, including fields set on the payload object after it is created and fields set through options, such as an idempotency key. - Where `from` comes from: the literal address, or the name of the environment variable or config value that holds it. +- For a `template` site, where its template ID comes from: the literal, or the environment variable or config value that holds it, read the same way as `from`. -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. +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. Also note where each provider client takes its key from: the environment variable or config value, or a key written in the source, which the report asks the person to rotate. 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. @@ -45,15 +50,27 @@ When you find no site, stop before you write the plan file: Check what each site sends first. PostHog's transactional send ignores marketing opt-outs, so it is only for an email that a person needs, such as a password reset, a receipt, or an invite. A site that sends marketing, such as a newsletter, a promotion, or a product announcement, stays, and the reason is `marketing email`. When neither the code nor the template's name tells you, ask the person once for every such site. A site they call marketing, or don't answer for, stays with that reason. -Then go through `mapping.md` field by field. A site **moves** when PostHog can send every field it sets. A site **stays** on the provider when any one field or feature keeps it there: record that field or feature as the reason. Never plan to drop a field. +Then go through `mapping.md` field by field. A site **moves** when PostHog can send every field it sets, in a language that `mapping.md` moves. A site **stays** on the provider when any one field or feature keeps it there: record that field or feature as the reason. Never plan to drop a field, unless `mapping.md` says the site moves without it: then note it in the plan. -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 field set to an empty value, such as `""`, `[]`, `{}`, or `null`, or to its off value, such as `false` for a flag that is off unless set, counts as not set, even where `mapping.md` keeps every site that sets the field, unless its row names that empty or off value. A field that the code sets on some sends only, such as under a condition or from a caller's argument, counts as set. -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 for now`. +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 it comes from an environment variable or a config value, read it from the config, or ask the person once what it holds in production. An example env file names the variable, but its value is often a placeholder: trust it only when it is clearly the deployed value. When you still can't tell, the site stays, and the reason says what you could not check. -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`. +For a template the person asks to make in PostHog, a value that the provider template tests or loops over, which `mapping.md` needs to be a boolean or a list, must have that type at run time: the code builds it, such as a literal or a value it computes, or checks it, such as with a schema or a parse. A type the code only declares, such as a TypeScript type or a cast, checks nothing at run time. When the value comes from request input, a file, or another service without such a check, such as `req.body`, the site stays, and the reason is ` is not checked to be a `: the provider's template and Liquid can render a value such as `0` or `""` differently. -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`. +A site stays when no sender can be verified for its `from`: an address on a free mail domain, such as `gmail.com` or `outlook.com`, on the provider's shared or sandbox domain, on a domain whose DNS records the person can't publish, such as a school's or another company's, or taken from a user, a customer, or a tenant at run time. The reason names the address or where it comes from. When a site that is not a `template` site sets no `from`, the provider sent from the account's default sender: ask the person for that address once, and the site stays when they can't name it. + +Unless the provider's `account.md` says it keeps no suppression list, ask the person once, for the sites the checks above leave moving, which of them they rely on that list to stop mailing an address someone added to it, by hand in the provider's dashboard or with a call the app makes, such as an unsubscribe handler. PostHog blocks a moved send only to an address that hard-bounced, so a moved send reaches such an address, whenever it was added. Each site they name stays, and the reason is `relies on 's suppression list`. When they can't tell or don't answer, every such site stays with that reason. Write `to move: the app keeps its own record of those addresses, the ones added before included, and skips them before the send` in the note of each site that stays with that reason, under the sites table, for the report. + +A `template` site moves by bringing its email into the code: the code renders the provider template's content and sends it in the code form. Read `template-to-code.md` up to "Where the email goes" now, and Step 7 reads the rest. 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, listing every other template the sites send, with the plan for each: it moves into the code, in a file next to its send, and from then on they change the email there. For each one, they can also say to keep it on the provider for now, or to make it a template in PostHog instead, such as when people who don't change code edit that email. A template they keep stays, and the reason is `kept on for now`. + +Each template that moves needs its content to be checked. Read the provider's `account.md`, and ask the person once for every such template: copies from the dashboard that they save in files outside the repository and tell you where, or a read through the API, where `account.md` says the API returns the content. Check each one as `template-to-code.md` says under "Check", with the provider's `mapping.md` under "Templates". When the person can't give the content, the site stays, and the reason is `template content not checked`. A template whose check fails stays, and the reason names the part that keeps it. Write the site's `from` column with the address the send uses: the call's own `from` when it sets one, and the template's sender otherwise, so Step 4 sets up a sender for its domain, and classify that address as any other `from`. + +### A template in PostHog, when the person asks for one + +A template the person asks to make in PostHog moves in the template form, by its template ID, and the person makes that template: never make one yourself. Its content needs the same check, against the part of `mapping.md` on templates made 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. Ask them the same when the provider didn't track the site's clicks, or nobody knows whether it did, as the provider's `account.md` says: PostHog sends each link of a template that is not marked sensitive through its click redirect, which those links never went through. Tell them that a sensitive template keeps no copy of each sent email's body or filled-in subject. When they don't mark it, the site stays, and the reason is `click tracking off`, or `click tracking not checked` when nobody knows. The report lists both before cutover either way. For a template that must be marked sensitive, for a secret in the email or for its clicks, write `must be marked sensitive: ` in its note under the sites table, so the report's "Before cutover" list checks it. Tell them how its placeholders change, as that part of `mapping.md` says. Quote every Liquid string with single quotes, such as `default: 'there'`: PostHog's email builder saves the template as JSON, which escapes double quotes, and the template then fails with a `TokenizationError`. A fallback or a compared value that holds a `'` keeps the template on the provider. Record each template ID with its site under the sites table, and write the address in the site's `from` column. A template without an ID stays, and the reason is `PostHog template not made yet`. ### Opens the provider didn't track @@ -84,9 +101,11 @@ When the run created a full-access provider key, as `account.md` says, add a lin A sites table, one row per site, in source tree order: ``` -| site | file | line | sends | content | from | moves | reason | +| site | file | line | language | sends | content | from | moves | reason | ``` `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: ` 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. + 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. diff --git a/context/skills/migrate-email/references/4-sender.md b/context/skills/migrate-email/references/4-sender.md index 10dee345..57ec72db 100644 --- a/context/skills/migrate-email/references/4-sender.md +++ b/context/skills/migrate-email/references/4-sender.md @@ -37,6 +37,7 @@ Send from the domain of the existing `from` address, so the emails keep their se - Create the sender with `integrations-email-create`, then get its DNS records with `integrations-email-verify-create`. - PostHog never writes DNS. Call `integrations-domain-connect-check-retrieve` with the domain. When `supported` is true, give the person the URL from `integrations-domain-connect-apply-url-create`: they approve the records at their DNS host. Otherwise, give them the records that are not `success` as a table with type, name, value, and priority. - Always include both SPF records, merged into an existing `v=spf1` record when there is one. Never add a second `_dmarc` record when the domain already has one. +- A name that holds a CNAME can hold no other record. When a record PostHog needs falls on a name where the provider keeps a CNAME, such as the sending domain itself, don't ask the person to replace it: the provider's sends depend on it. Record the domain as not verified, tell the person which records clash, and suggest a sending subdomain without the CNAME. `account.md` names the provider's CNAMEs. - Call `integrations-email-verify-create` again after the records are published, at least a minute apart. `success` means verified. `failed` means fix the records, then verify again. After about 15 minutes of `pending` with every record published, tell the person that DNS is still propagating and that they can ask you to check again later, record the domain as not verified, and continue. - When the person can't publish the records during this run, such as when another team owns DNS, record the domain as not verified with its records or its Domain Connect link, and continue. - A 403 that says the person lacks permissions in the project means a project admin must verify the sender. Do not retry: record the domain as not verified, and continue. diff --git a/context/skills/migrate-email/references/5-suppressions.md b/context/skills/migrate-email/references/5-suppressions.md index e5dff94e..48577351 100644 --- a/context/skills/migrate-email/references/5-suppressions.md +++ b/context/skills/migrate-email/references/5-suppressions.md @@ -5,7 +5,7 @@ next_step: 6-key.md # Step 5, import the suppression list -The provider keeps a suppression list: addresses that hard-bounced or marked an email as spam. It skips them on every send. PostHog keeps its own list and starts empty, so without an import the first PostHog sends go to these addresses again. That hurts the sending reputation of the project and the domain. Import the list before cutover. +The provider keeps a suppression list: addresses that hard-bounced or marked an email as spam. It skips them on every send. PostHog keeps its own list and starts empty, so without an import the first PostHog sends go to the addresses that hard-bounced again. That hurts the sending reputation of the project and the domain. Import the list before cutover. PostHog blocks a moved send, which is transactional, only to an address that hard-bounced: an address that complained or was added by hand blocks only PostHog's marketing email, so the moved sends reach it. ## Status @@ -13,36 +13,53 @@ The provider keeps a suppression list: addresses that hard-bounced or marked an [STATUS] Importing the suppression list ``` +## Re-import only + +After the migration, while any site still sends through a provider that keeps a suppression list, the provider keeps adding the addresses that bounce 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. 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 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". +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 Read the provider's `account.md` first, whether or not the import runs. Its "For the report" section, when it has one, names facts the report carries, such as a count of entries the import leaves out. Find each one as the section says, and write it under the phase in the plan file. Never write an address. +When `account.md` says the provider keeps no suppression list at all, there is nothing to import, now or later. Tick the phase as `- [x] suppressions — empty list: keeps no suppression list`, do what "Calls that change the provider's list" and "The full-access key" say, and continue to the next step. + ## Check the import tool 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`, 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. 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 -The provider's `account.md` says how to export the list, which entries to take, and how each entry maps to PostHog. +The provider's `account.md` says how to export the list, which entries to take, and how each entry maps to PostHog. When the provider has no export or no API that lists it, `account.md` says where else the list comes from. - Prefer the export the person downloads from the provider's dashboard. Ask them where they saved the file. -- Read the list from the provider's API only when the person gives you a key that can read it, through an environment variable that `account.md` names. The app's own sending key usually can't. +- Read the list from the provider's API only when the person gives you a key that can read it, through an environment variable that `account.md` names. The app's own sending key usually can't, unless `account.md` says it can. - Keep the list out of the repository. Read the file where the person saved it, or write the API's answer to a file in the system's temporary folder, and delete that file when the import is done. ## Import it -- Send the entries to `email-suppressions-add` in batches of the size its schema allows. Give each entry the source and the reason `account.md` names. +- Send the entries to `email-suppressions-add` in batches of the size its schema allows. Give each entry the `reason` that `account.md` maps it to: `bounce`, `complaint`, or `manual`. PostHog writes the entry's reason text itself, such as `Imported (bounced)`. - 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. +- The provider keeps adding to its list while it sends, so the report asks the person for one last import right before cutover, and for the weekly re-import of "Re-import only" while any site stays on the provider after it. - 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, record how many entries you imported, and ask the person once whether to repeat it now. Repeat it when they say yes. +## Calls that change the provider's list + +The import copies the list once. After it, a call in the app that adds an address to the provider's suppression list, or removes one from it, such as an unsubscribe handler or a reactivation, changes only the provider's list. Don't make the call change PostHog's list too: PostHog's list records no source the app could check before it removes an entry, and an app can't call the import tool. Every moved send is transactional, and PostHog blocks a transactional send only to an address that hard-bounced. It records that itself when a moved send bounces. Step 3 kept the sites that rely on the addresses added to the provider's list. For each call that removes an address, add an item to the report's "After cutover": an address it removes stays blocked in PostHog when the import took it as a bounce, so a moved send to it fails with `recipient_suppressed`. When that happens for an address the app reactivated, the person removes it from PostHog's list too, in PostHog (Workflows, then Messaging, then Suppression list). A re-import doesn't add back an address removed from PostHog's list. When the address hard-bounces on a moved send again, PostHog blocks it by itself. + +The call keeps its provider write while any send still goes through the provider. The provider's `mapping.md` names its calls. + ## Write down Tick the phase in the plan file only when every entry is imported: `- [x] suppressions — / imported`. When the list is empty, write `- [x] suppressions — empty list`. When the import stopped partway, write `- [ ] suppressions — / imported: `. When the person has no export and no key, write `- [ ] suppressions — not imported: `. ## 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. +Every way out of this step ends here. When the plan says the run created a full-access provider key, or a re-import created one, 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, outside a re-import. diff --git a/context/skills/migrate-email/references/6-key.md b/context/skills/migrate-email/references/6-key.md index cbad5fa5..4ba71e4c 100644 --- a/context/skills/migrate-email/references/6-key.md +++ b/context/skills/migrate-email/references/6-key.md @@ -35,9 +35,9 @@ A person who says they will add the key later has not set it, and neither has on ## Every other place the provider key lives -The provider's `sdk-reference.md` names its key's environment variable. Search the whole repository for that name, including CI workflows, deploy and hosting config, Docker and compose files, env example files, and docs. Skip `node_modules` and build output. +The provider's `sdk-reference.md` names the environment variables that hold its key, one or more. Search the whole repository for each name, including CI workflows, deploy and hosting config, Docker and compose files, env example files, and docs. Skip `node_modules` and build output. -List each place with its file and line. Each one needs `POSTHOG_PROJECT_SECRET_API_KEY` too before the cutover, for example as a CI secret or a hosting environment variable. Do not change these files: the person adds the secret where the platform stores it. +List each place that sets a value for it, with its file and line: env and env example files, CI, deploy and hosting config, Docker and compose files, and docs that tell people to set it. Source code that only reads the variable is not a place. Each place needs `POSTHOG_PROJECT_SECRET_API_KEY` too before the cutover, for example as a CI secret or a hosting environment variable. Do not change these files: the person adds the secret where the platform stores it. ## Write down diff --git a/context/skills/migrate-email/references/7-rewrite.md b/context/skills/migrate-email/references/7-rewrite.md index 924ead98..1c0e0f42 100644 --- a/context/skills/migrate-email/references/7-rewrite.md +++ b/context/skills/migrate-email/references/7-rewrite.md @@ -5,80 +5,109 @@ next_step: 8-verify.md # Step 7, move every site that can move -Rewrite each site whose `moves` is `yes` in the plan to send with `posthog-node`. The provider's `mapping.md` has the rewrite of each field, call, and content form under "Rewrite". +Rewrite each site whose `moves` is `yes` in the plan to send with PostHog's SDK for the site's language. The provider's `mapping.md` has the rewrite of each field, call, and content form under "Rewrite". The SDK's rewrite file has the PostHog side: the install, the client, the send, the answer, and the check to run. + +| Language of the site | PostHog SDK | Rewrite file | +|---|---|---| +| JavaScript or TypeScript on a server: Node.js, or an edge runtime such as Cloudflare Workers or Vercel Edge Functions | `posthog-node` | `rewrite-node.md` | +| Python | `posthog` | `rewrite-python.md` | +| Go | `github.com/posthog/posthog-go` | `rewrite-go.md` | +| Ruby | `posthog-ruby` | `rewrite-ruby.md` | +| PHP | `posthog/posthog-php` | `rewrite-php.md` | +| C# or F# on .NET | `PostHog` | `rewrite-dotnet.md` | +| Rust | `posthog-rs` | `rewrite-rust.md` | +| Elixir | `posthog` | `rewrite-elixir.md` | + +Read the rewrite file of each language that has a site that moves, and only those. + +## What every SDK's send takes and answers + +- Each call sends one email to one `to` address, in one of two forms. The code form takes a template key, a subject, and HTML, text, or both, with an optional from address, reply-to addresses, and engagement capture, which is on unless the send turns it off. The template form takes a template ID with optional template data, for a template made in PostHog, and none of the code form's fields. +- Both forms take a distinct ID and an idempotency key. +- No SDK takes `cc`, `bcc`, attachments, headers, tags, a send time, or several `to` addresses yet. The provider's `mapping.md` keeps a site that sets one. +- The message ID in the answer is PostHog's, not the provider's. It is a UUID, as a string of 36 characters such as `0b9f6d2e-3c1a-4f8e-9a7b-5d2c1e0f4a6b`, so a column or field that holds a UUID takes it. +- An error's name is a coarse category with Resend's error names: `validation_error`, `missing_api_key`, `invalid_permission`, `not_found`, `concurrent_idempotent_requests`, `invalid_idempotent_request`, `rate_limit_exceeded`, `monthly_quota_exceeded`, `service_unavailable`, or `application_error`. Its code is PostHog's own, such as `recipient_suppressed`, `sender_not_verified`, or `quota_limited`: branch on the code. A send to a suppressed address fails with the code `recipient_suppressed` and the name `validation_error`. +- The answer carries no response headers. An error carries the retry delay PostHog named, when it named one, under the name the rewrite file gives under "The answer". +- Every SDK retries network errors and rate limits by itself, with the same idempotency key. A network error that is left after the retries comes back as the same error type as an API error, with the code `network_error`. +- A bad argument fails before any request: as the language's argument error, or as the email error with a code that starts with `invalid_`. The rewrite file says which. ## Status ``` -[STATUS] Setting up posthog-node for email +[STATUS] Setting up the PostHog SDK for email [STATUS] Moving the send call sites ``` ## Before you change code - Change only the sites whose `moves` is `yes`. Never change a site that stays, and never change a line that a site that stays still needs. -- When no site moves, tick the phase in the plan with `none moved` and go to the next step. -- Run the project's typecheck, such as its `typecheck` script or `tsc --noEmit`, or its build when it has no typecheck, and write each error's file, code, and message, such as `TS2345` and its text, with how many times it shows, under the rewrite phase in the plan: Step 8 compares with them. Leave out the line: the rewrite moves it. +- When no site moves, delete each temporary copy of template content that Step 3 wrote, tick the phase in the plan with `none moved`, and go to the next step. +- Run the check that the rewrite file names under "Check", on the whole project, and write each error's and warning's file, code, and message, with how many times it shows, under the rewrite phase in the plan: Step 8 compares with them. Leave out the line: the rewrite moves it. For a site in JavaScript or TypeScript, that is the project's typecheck. -## Set up the client +## Set up the SDK -Install `posthog-node` with the project's package manager when the app doesn't have it. `posthog.emails` alone is not enough: early releases send only a template made in PostHog, by `templateId`. Check the installed package's types for what the moving sites need, and upgrade it to its latest release only when they lack one of these: +Install the SDK as the rewrite file says under "Install" when the app doesn't have it. Early releases of an SDK may not send email, or may send only a template made in PostHog. Check the installed version for what the moving sites need, and upgrade it to its latest release, as the rewrite file says, only when it lacks one of these: -- a site with `html`, `text`, or a component: `posthog.emails.send` takes `templateKey` with `subject` and `html` or `text`; -- a site that sets `replyTo`: the send takes `replyTo`; -- a site with rendered content whose email carries a login code, a reset link, or another secret: the send takes `sensitive`; -- the client: the client options take `migratedFrom`. +- a site with `html`, `text`, or a component, and a `template` site that moves into the code: the send takes a template key with a subject and an HTML or text body; +- a site with rendered content whose email carries a login code, a reset link, or another secret: the send takes a sensitive flag; +- each other field a site sets, such as a reply-to address or engagement capture: the send takes it; +- the client: the client options take the provider name, under the name the rewrite file gives. -Before you install or upgrade `posthog-node`, check that the app runs on a Node.js version the release you install supports: compare the `engines` field the registry lists for it with the version the app runs in production, from its `engines`, `.nvmrc`, `.node-version`, Dockerfile base image, or hosting config. When you can't tell that version, ask the person. When the release doesn't support it, change no site: an older Node lacks what the client needs, such as `crypto.randomUUID()`, and every send fails. Mark each moving row `moves: no — the app runs Node , which posthog-node doesn't support`, tell the person, tick the phase with `none moved`, and go to the next step. +Before you install or upgrade an SDK, check the release you install against every server whose build installs the dependency manifest it goes into, directly or through a workspace or a root lockfile install, such as one `requirements.txt` or `package.json` that two images build on different versions, or that a server and an edge function share. Compare what the registry lists for that release, such as `engines` for `posthog-node` or `Requires-Python` for `posthog`, with the language version each such server runs in production, from its version files, Dockerfile base image, or hosting config. When you can't tell a version, ask the person. When the release doesn't support one of those servers, every moving site whose code installs from that manifest stays, an edge site too, since the install would reach that server: an older runtime can lack what the SDK needs, such as `crypto.randomUUID()` in Node.js, and every send fails, and a strict package manager fails the build. Mark each of their rows `moves: no — the app runs , which doesn't support`. Otherwise, a site on an edge runtime, such as Cloudflare Workers or Vercel Edge Functions, which has no Node.js version of its own, moves only when the rewrite file names that runtime as one the SDK supports, and its row is otherwise `moves: no — doesn't name as a runtime it supports`. Tell the person about each row that stays for this, and go on with the rest. -When the latest release lacks one of these, change no site that needs it. Mark each such row `moves: no — posthog-node has no yet`, tell the person, and go on with the rest. When the client options lack `migratedFrom`, leave it out of the client. When no site is left, undo the install or upgrade of `posthog-node`, tick the phase with `none moved`, and go to the next step. +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. -Configure a server-side client of its own for email, also when the app already has a `posthog-node` client: +When the latest release lacks one of these, change no site that needs it. Mark each such row `moves: no — has no 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. -```js -import { PostHog } from 'posthog-node' +## Set up the client -export const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, { - host: process.env.POSTHOG_HOST, - secretKey: process.env.POSTHOG_PROJECT_SECRET_API_KEY, - enableLocalEvaluation: false, - migratedFrom: '', // only when the client options take it -}) -``` +Configure a server-side client of its own for email in each language that has a site that moves, as the rewrite file says under "The client", also when the app already has a PostHog client in that language. When a language's sites mix synchronous and asynchronous code, and its SDK has a separate client for each that one app can use side by side, such as Python, configure one of each, and have each site use the client that matches its call: -- When the client options take `migratedFrom`, set it to the value that the provider's `mapping.md` names under "The PostHog client". posthog-node sends it with every email request, so PostHog knows that the sends moved from that provider. -- Never change the app's own `posthog-node` client for email. posthog-node also uses `secretKey` for its flags and remote config, so the email key, or `enableLocalEvaluation: false`, would change how the app's flags evaluate, and a client the app disables answers every send with `client_disabled`. +- Set the secret key from `POSTHOG_PROJECT_SECRET_API_KEY`, which Step 6 set up. Read it, and the token and host, without raising when a variable is missing, as the rewrite file shows: Step 6 can leave the key unset, and an app that can't start takes down the sends that stay on the provider too. A send without the key fails with its own error. +- Set the provider name to the value the provider's `mapping.md` names under "The PostHog client", when the client options take it. The SDK sends it with every email request, so PostHog knows that the sends moved from that provider. +- Never change the app's own PostHog client for email. The SDKs also use the secret key for local flag evaluation and remote config, so the email key would change how the app's flags evaluate, and a client the app disables, such as outside production, refuses every send. +- The rewrite file says what to set on a client that only sends email, so that it loads no feature flag definitions with the secret key. Set it. - When the project token or the host is not configured yet, get the token from the PostHog MCP `project-get` tool, called without an ID (`api_token`). The host is `https://us.i.posthog.com` for US Cloud and `https://eu.i.posthog.com` for EU Cloud. Ask the person which one when you can't tell. -- When `host` is a reverse proxy or a self-hosted instance, also set `appHost` to the PostHog app URL, such as `https://us.posthog.com`. posthog-node never sends the secret key to a proxy, and without `appHost` the send fails with `missing_app_host`. -- Put the client in its own server-only module, next to the provider's client, and import it where the sites send. -- A site whose request had its own deadline keeps it: the provider's `mapping.md` says how, under "HTTP". Each distinct deadline gets its own client like the one above, with that timeout, in the same module. +- When the app's host is a reverse proxy, set the email client's host to PostHog's own host, such as `https://us.i.posthog.com`. A client with the secret key loads flag definitions from its host with it, when it starts or when it evaluates a flag, which would hand the key to the proxy. +- On a self-hosted instance, also set the app host, under the name the rewrite file gives, to the instance's app URL. The email send goes only to the app host, and without it the send fails with `missing_app_host`. +- Put the email client in its own server-only module, next to the provider's client, and use it where the sites send. +- A site whose request had its own deadline keeps it, as the provider's `mapping.md` says under "HTTP": the send gets that deadline, and no retries, since the request never retried. Every SDK otherwise waits up to 15 seconds for each request and retries twice, which can run past the site's deadline. The rewrite file names the timeout and retry options under "A deadline". Where the send takes the deadline itself, as Go's context and .NET's cancellation token do, pass it there; the SDK still ends each request at its own timeout, so a deadline longer than that also needs a client of its own with the timeout set to it. Otherwise each distinct deadline gets an email client of its own with that timeout, in the same module, and its sites send through it. Sites without a deadline keep the first client. Never give a site a deadline it didn't have, or change one it had. A request with its own deadline whose HTTP client the code also set up to retry a POST did retry, and the send that keeps the deadline takes no retries: the site stays, `moves: no — the PostHog SDK can't keep the request's retries`. Such setups include `axios-retry`, which by default retries a network error on any method, a `requests` session adapter with a urllib3 `Retry` or a number as its `max_retries`, such as `HTTPAdapter(max_retries=3)`, which by default retries a failed connection on any method, or Faraday's `retry` middleware with `:post` in its `methods:` or a `retry_if`. Read the options the code gives the setup, such as `axios-retry`'s `retries` and `retryCondition`, or `Retry`'s `total`, `connect` and `allowed_methods`, where a number stands for `total`, to tell whether it retries the POST. A retry setup that skips a POST, such as Faraday's `retry` with its default methods or a setup with no retries left, never retried the send, and the site keeps its deadline with no retries. Only a limit the code sets is the site's own deadline: a library's default, such as `httpx`'s 5 seconds or `ky`'s 10, is not one, like a provider SDK's default, and such a site sends with the PostHog SDK's own timeout and retries. The SDK keeps a deadline only of the kind its timeout is. Every SDK's timeout limits the whole request, except Python's and Ruby's, which limit each wait on the network, as their rewrite files say. A limit of another kind is one the SDK can't keep: axios's `timeout` in Node.js ends a request only after that long without data, and `ky`'s `timeout` ends once the answer's headers arrive. Every SDK has one timeout for connecting and reading alike, so a request that limits only connecting, or limits connecting and reading apart, such as Faraday's `open_timeout`, Guzzle's `connect_timeout`, `requests`' `timeout=(1, 10)`, or an `httpx.Timeout` with its own `connect`, has a deadline the SDK can't keep, unless the rewrite file says under "A deadline" how its client keeps such a limit, as Go's does. When the SDK can't hold the deadline, as there or with a deadline that is not whole seconds in Rust, the site stays: `moves: no — the PostHog SDK can't keep the request's deadline`. - Use the env variable names the app already uses for the PostHog token and host. Add each new name, without a value, to the env example file. ## Link emails to your users -PostHog records each send, and its sent, opened and clicked events when engagement capture is on, against the person the send names with `distinctId`. Pass the ID the app already passes to `identify()`: +PostHog records each send, and its sent, opened and clicked events when engagement capture is on, against the person the send names with its distinct ID. Pass the ID the app already passes to `identify()`: -- Find the app's identify call, such as `posthog.identify(user.id)` in posthog-js, or the `distinctId` of its `posthog-node` captures. -- At each site, pass the same ID for the recipient, such as `distinctId: user.id`. `distinctId` takes a string, and posthog-js turns a number into its string, so a numeric ID becomes `distinctId: String(user.id)`. Follow the recipient back through the callers when the site only has the address. -- Without `distinctId`, PostHog records the email against a person whose distinct ID is the recipient's address. Unless the app identifies people by their address, that is a separate person from the user. -- When the recipient isn't a user yet, such as an invite or an address check before the account exists, isn't a user at all, such as a team inbox, or the site has no way to know the user, leave `distinctId` out and note it in the plan row. +- Find the app's identify call, such as `posthog.identify(user.id)` in posthog-js, or the distinct ID of its server-side PostHog captures. +- At each site, pass the same ID for the recipient, such as `user.id`. The SDKs take the distinct ID as a string, so a numeric ID is passed as its string, such as `String(user.id)` in Node.js and `str(user.id)` in Python, the same string the app's identify call sends. Follow the recipient back through the callers when the site only has the address. +- Without a distinct ID, PostHog records the email against a person whose distinct ID is the recipient's address. Unless the app identifies people by their address, that is a separate person from the user. +- When the recipient isn't a user yet, such as an invite or an address check before the account exists, isn't a user at all, such as a team inbox, or the site has no way to know the user, leave the distinct ID out and note it in the plan row. - When the app identifies no one in PostHog, use the app's own user ID, and note it for the report. ## Rewrite each site For each site that moves, in plan order: -- Rewrite the call as the provider's `mapping.md` says, for the site's content form: `html` and `text` content, a component the app renders, or a template made in PostHog. -- Give each send with rendered content a `templateKey` that names the kind of email, such as `welcome` or `password-reset`, with letters, digits, `-`, and `_` only. Two sites that send the same email share a key. A send whose key a template saved in PostHog already has goes out through that template's settings, and fails when that template isn't transactional. The PostHog MCP doesn't list template keys, so ask the person once, for all the keys together, whether a template in the project already has any of them, and give each such send another key. -- A send with rendered content whose email carries a login code, a reset link, or another secret gets `sensitive: true`. Without it, a send whose key matches a template saved in PostHog takes that template's setting, which is off by default, and PostHog then sends the email's links through its click tracking and puts its subject on engagement events. A send by `templateId` takes no `sensitive`: PostHog refuses it, and the template made in PostHog holds that setting, as Step 3 asks. +- Rewrite the call as the provider's `mapping.md` says, for the site's language and content form: `html` and `text` content, a component the app renders, a provider template brought into the code, or a template made in PostHog. Write the PostHog send as the rewrite file says under "The send". +- For a provider template that moves into the code, read the rest of `template-to-code.md` first. Write its email from the content Step 3 checked, render it at the site, and send the result in the code form, with the subject, `from`, and reply-to address the provider template set. Then delete the temporary copy of its content. +- Give each send with rendered content a template key that names the kind of email, such as `welcome` or `password-reset`, with letters, digits, `-`, and `_` only. Two sites that send the same email share a key, in any language. A send whose key a template saved in PostHog already has goes out through that template's settings, and fails when that template isn't transactional. The PostHog MCP doesn't list template keys, so ask the person once, for all the keys together, whether a template in the project already has any of them, and give each such send another key. +- A send with rendered content whose email carries a login code, a reset link, or another secret sets the send's sensitive flag, as the rewrite file names it under "The send". Without it, a send whose key matches a template saved in PostHog takes that template's setting, which is off by default, and PostHog then sends the email's links through its click redirect and puts its subject on engagement events. A send by template ID takes no sensitive flag: PostHog refuses it, and the template made in PostHog holds that setting, as Step 3 asks. - A site that moves to a template made in PostHog sends the template ID the person gave in Step 3, never one you guess. -- Install `@react-email/render` with the project's package manager when a site renders a component and the app doesn't have it. - Keep the site's idempotency key, error branches, logging, and return value working as before. Keep the code around the send unchanged where you can. -- `posthog.emails.send` never throws on an API error: it returns `{ data, error }`. When the old call threw on an error, or the code checked an HTTP status, check `error` so the site fails the same way. -- Never add a field that the old call didn't set, apart from `templateKey`, `templateId`, `distinctId`, `sensitive: true` on a send with rendered content that carries a secret, and a field the provider's `mapping.md` says to add, such as `maxRetries: 0` on a request that kept its own deadline. `templateData` takes the place of the provider's template variables. - -When a site turns out to need something `mapping.md` keeps on the provider, undo its change, set `moves` to `no` with the reason, and go on. +- Keep the site failing the same way it did. The rewrite file says under "The answer" how its SDK reports an error: Node.js answers `{ data, error }` and never throws on an API error, and the other languages raise or return an error value. When the old call threw on an error, or the code checked a status, check PostHog's error so the site fails the same way, as the provider's `mapping.md` says under "Rewrite". +- When the old call answered a refused send without raising, and the code never read that answer, such as a raw HTTP call whose status the code never checked, the site went on as if the send worked, and only a network failure raised or returned an error. Keep that: catch PostHog's error, log it and go on. Raise or return it when its code is `network_error` only where the old call raised on a network failure: Resend's Node.js send answers a network failure in `{ data, error }` too, so such a site goes on for `network_error` as well. The argument error that the rewrite file names, such as Python's `ValueError` for an empty subject, was a refused send before too: catch it the same way, around the send only. Note the site in the plan. +- When the old code caught only some errors, such as one error class or one status, catch PostHog's error and branch on its `code` or status code for those, and raise or return every other error as before. Several handlers of the provider's error classes on one `try` become one catch of PostHog's error that branches in their order: the first of several catches of the same error type would take every error. Never widen a catch. PostHog reports a network error with the same error type as an API error, with the code `network_error`. When the old catch took only the provider's answers, such as an HTTP error class, and a network failure passed it, raise or return `network_error` the way the old code let a network failure through. When a later handler of the same `try`, such as a broader `rescue` or `except` after it, took that network failure, run that handler's code for `network_error`: a raise inside one handler skips the handlers after it. A catch of every error around the send, such as a bare `except:`, `except Exception`, `rescue => e`, or `catch (\Throwable $e)`, caught network failures before too: it stays as it is, and lets no `network_error` through, here and in the bullet above. +- When the old code told one kind of network failure from another, the site stays: `moves: no — catches one kind of network failure`. That is a branch on the transport's error code or class, such as `err.code === 'ECONNRESET'` or `'ETIMEDOUT'` in Node.js, `requests.Timeout`, `requests.ConnectionError`, or `e.errno` in Python, `Faraday::ConnectionFailed`, `Net::ReadTimeout`, or `Errno::ECONNRESET` in Ruby, or curl's error number in PHP. Every SDK retries network failures and reports what is left as one `network_error`, which doesn't say which kind it was, so the branch would never run. A catch that takes every network failure alike, such as a `catch` around `fetch`, which throws only when no answer arrived, is not such a branch: it becomes a branch on `network_error`, as above. The one exception is the timeout of a deadline the site keeps, where the send takes the deadline itself: + - Go: `Send` ends at the context's deadline with a `*posthog.EmailError` that unwraps to the request's error, so `errors.Is(err, context.DeadlineExceeded)`, and a `net.Error` read with `errors.As` whose `Timeout()` is true, still match. + - .NET: the deadline's token cancels `SendAsync` with an `OperationCanceledException`, a `TaskCanceledException` from `HttpClient`, never an `EmailException`, so a `catch` of either keeps working. A check for an inner `TimeoutException`, which only `HttpClient.Timeout` sets, becomes a check that the deadline's token is cancelled. + - In every other SDK the deadline is the client's timeout, and its timeout is a `network_error` like any other network failure: a branch on it stays. +- A branch on the provider's answer to an invalid send, such as a `400` or a `422`, becomes a branch on PostHog's error name `validation_error`, never on a status code: PostHog's statuses for invalid sends differ from the provider's, and `recipient_suppressed` is a `validation_error` with status `422`. Handle `recipient_suppressed` before that branch, as the provider's `mapping.md` says. +- A branch on the provider's rate limit, such as a retry, a wait, or a re-queue on status `429`, becomes a branch on PostHog's status code `429` with a code other than `quota_limited`. PostHog answers a used-up sending quota with status `429` and the code `quota_limited`, which no retry fixes: it takes the path of every other error. +- When the old code handled the provider's answer to a bad value that the app passes at run time, such as an empty recipient, also catch the argument error that the rewrite file names, or check the value before the send. +- Never add a field that the old call didn't set, apart from the template key, the template ID, the distinct ID, the sensitive flag on a send with rendered content that carries a secret, the subject, body, `from`, and reply-to address that a provider template brought into the code held, and a field that the provider's `mapping.md` or this step says to add because the old send behaved that way without setting it, such as no retries for a request that kept its own deadline. Open or click tracking never adds one: engagement capture decides only whether the email's events land on the recipient's person, and PostHog adds its open pixel either way, so a site whose emails had none moves only with the person's yes, as Step 3 says under "Opens the provider didn't track". It sends each link through its click redirect only when the email is not sensitive, and a send in the code form is sensitive, since no template saved in PostHog has its key, as the rule on keys above makes sure, so PostHog counts its opens and no clicks. For a template made in PostHog, the template data takes the place of the provider's template variables. For a template brought into the code, the code renders them, and the send has no template data. + +When a site turns out to need something `mapping.md` keeps on the provider, undo its change, set `moves` to `no` with the reason, delete the temporary copy of its template content when no other moving site sends that template, and go on. ## Write down -Tick the phase in the plan: `- [x] rewrite — sites moved`. Add a `key` column to the sites table with each moved site's `templateKey`, or its `templateId` for a template made in PostHog. Under the table, note each site without a `distinctId`, each fallback that an empty string now replaces, each site that got a branch for a suppressed recipient, each idempotency key a retry across the deploy could send twice, each new dependency, each upgraded one with its old and new version, and each new env variable name. +Delete each temporary copy of template content that is still there. Tick the phase in the plan: `- [x] rewrite — sites moved`. Add a `key` column to the sites table with each moved site's template key, or its template ID for a template made in PostHog. Write down each email brought into the code, as `template-to-code.md` says under "Write down". Under the table, note each site without a distinct ID, each fallback that an empty string now replaces, each site that got a branch for a suppressed recipient, each idempotency key a retry across the deploy could send twice, each value the move changed, such as a recipient name the To line loses, each new dependency, each upgraded one with its old and new version, and each new env variable name. diff --git a/context/skills/migrate-email/references/8-verify.md b/context/skills/migrate-email/references/8-verify.md index aa53a9fe..26ae665b 100644 --- a/context/skills/migrate-email/references/8-verify.md +++ b/context/skills/migrate-email/references/8-verify.md @@ -16,12 +16,14 @@ Check that the app still builds, its tests still pass, and one moved email reach ## Build and tests -- Run the project's typecheck, such as its `typecheck` script or `tsc --noEmit`, or its build when it has no typecheck. Fix each error whose file, code, and message are not in the list Step 7 wrote into the plan, in any file: the rewrite or the posthog-node upgrade caused it. An error in a line the rewrite changed is new too, even when the list has it, unless the line's old version in `git diff` had it, such as in a value the rewrite carried over as it was: fix it. For each error in the list, take the number of times the list says, less the copies that changed lines had in their old version and no longer have. When the error still shows more times than that, and the changed lines don't explain the extra ones, look for them in the unchanged lines that use what the rewrite changed, such as the send's result, its error, or the client, and fix them there. Note each file you fix outside the moved sites for the report. Every other error in the list was there before: note it, and leave it. +- Run the check that each moved site's rewrite file names under "Check", on the whole project, as Step 7 did. Fix each error or warning whose file, code, and message are not in the list Step 7 wrote into the plan, in any file: the rewrite or the PostHog SDK's install or upgrade caused it. Below, an error means an error or a warning. An error in a line the rewrite changed is new too, even when the list has it, unless the line's old version in `git diff` had it, such as in a value the rewrite carried over as it was: fix it. For each error in the list, take the number of times the list says, less the copies that changed lines had in their old version and no longer have. When the error still shows more times than that, and the changed lines don't explain the extra ones, look for them in the unchanged lines that use what the rewrite changed, such as the send's result, its error, or the client, and fix them there. Note each file you fix outside the moved sites for the report. Every other error in the list was there before: note it, and leave it. - Run the tests that cover the files you changed. Never delete or skip a test, and never turn a PostHog send back into the provider's request shape to keep an old assertion. - - A test of a moved site runs the real `posthog-node` client and intercepts PostHog's send request at the HTTP boundary, as `api.md` describes the request. It asserts on the request PostHog gets and on what the app does, with the same expected values the old test had. A test that intercepted the provider's HTTP requests now intercepts PostHog's. A test that mocked the provider's client, such as `jest.mock('resend')`, drops that mock and becomes such a test too. A test that mocks the app's own email module stays as it is. - - The test sets the env variables Step 7's email client reads: any project token and secret key, and the PostHog host the app uses, such as `https://us.i.posthog.com`. Without them the send fails before it makes a request. It intercepts the app host the client sends to, such as `https://us.posthog.com` for that host. A test that answers with a 429 or a 503 answers each of the client's two retries too, which wait about one second, then two. - - Intercept with the tool the test suite already uses for HTTP. posthog-node sends with the global `fetch`, which `msw`, `nock` 14 or later, and undici's `MockAgent` intercept; `nock` before 14 doesn't see `fetch`. When the suite has none of them, the test replaces `globalThis.fetch` with a fake that records the request and answers it, and puts the real one back after, so no dependency is added. -- Search the changed files for the provider's calls: a moved site has none left, and each moved site has one `posthog.emails.send`. + - A test of a moved site runs the real PostHog SDK and intercepts PostHog's send request at the HTTP boundary, as `api.md` describes the request. It asserts on the request PostHog gets and on what the app does, with the same expected values the old test had. A test that intercepted the provider's HTTP requests now intercepts PostHog's. A test that mocked the provider's client, such as `jest.mock('resend')` or a `mock.patch` of `resend.Emails.send`, drops that mock and becomes such a test too. A test that mocks the app's own email module stays as it is. + - The test sets the env variables Step 7's email client reads: any project token and secret key, and the PostHog host the app uses, such as `https://us.i.posthog.com`. Without them the send fails before it makes a request. A test that answers with an error the SDK retries, such as a 503, answers each retry too, two by default. + - In Node.js, Python and Ruby, the test intercepts the app host the client sends to, such as `https://us.posthog.com` for that host, with the tool the suite already uses for HTTP. posthog-node sends with the global `fetch`: `msw`, `nock` 14 or later (an older `nock` doesn't see `fetch`), or undici's `MockAgent`, and with none of them, a fake that the test puts on `globalThis.fetch` and takes off after, so no dependency is added. posthog-python sends with `requests` from `Posthog`, and with `httpx` from `AsyncPosthog`: `responses` or `requests-mock`, and `respx` or `pytest-httpx`. posthog-ruby sends with `Net::HTTP`: `webmock`. + - In Go, .NET, PHP, Rust and Elixir, a test can't swap the SDK's HTTP client, so it runs a local HTTP server and sets the email client's host and app host to its URL. Use the server the suite already uses, or Go's `httptest`, .NET's `HttpListener` or `WireMock.Net`, PHP's built-in server (`php -S`) with a router script, `wiremock`, `mockito` or `httpmock` in Rust, and `Bypass` in Elixir. The server answers the send request; the SDK's other requests to it, such as Go's flag polling, can get a 404. When Step 7's email client doesn't read its app host from the environment, have it read an optional one, such as `POSTHOG_APP_HOST`, and pass it only when it is set, and add the name to the env example file. Go and .NET refuse an `http://` app host unless `AllowInsecureAppHost` is set: set it only when that app host is a loopback address, such as `http://127.0.0.1:` or `http://localhost:`, so the secret key never goes over plain HTTP off the machine. + - Never add a test tool as a dev dependency, such as `WireMock.Net`, `responses`, `webmock`, `wiremock` or `Bypass`, without asking the person once. Node.js, Go, .NET and PHP need none: the fake `fetch`, `httptest`, `HttpListener` and the built-in server come with them. In Python, Ruby, Rust and Elixir, when the suite has none of the tools above, ask. When the person declines, the test runs a local server from the language's standard library and points the email client's host and app host at it, as above: Python's `http.server` in a thread, Ruby's `TCPServer` from `socket`, or WEBrick when the app already depends on it, Rust's `std::net::TcpListener`, and Erlang's `:httpd` from `:inets`, or `:gen_tcp`, in Elixir. No test keeps a mock of the PostHog SDK's send. +- Search the changed files for the provider's calls: a moved site has none left, and each moved site has one PostHog send. ## One email on one person @@ -49,4 +51,4 @@ Never write the address or the distinct ID into a file. ## Write down -Tick the phase in the plan: `- [x] verify — typecheck: , tests: , chain: `. +Tick the phase in the plan: `- [x] verify — check: , tests: , chain: `. diff --git a/context/skills/migrate-email/references/9-report.md b/context/skills/migrate-email/references/9-report.md index 47bb4a7a..36915a45 100644 --- a/context/skills/migrate-email/references/9-report.md +++ b/context/skills/migrate-email/references/9-report.md @@ -27,7 +27,7 @@ Read `.posthog-email-migration-plan.md`. Write `posthog-migrate-email- | File | Line | Content | Key | Status | |------|------|---------|-----|--------| -", or "Stays on : ".> +", or "Stays on : ".> @@ -35,13 +35,17 @@ Read `.posthog-email-migration-plan.md`. Write `posthog-migrate-email- .> +## Webhook handlers + + events it handles, and the PostHog events that take their place for the moved sends, from `mapping.md` under "Webhooks". Say that the handler keeps getting events for the sites that stay, that moved sends no longer reach it, that PostHog records their events on the person only when engagement events are on for the project, that a send in the code form counts no clicks, and that a webhook destination in PostHog (Data pipelines, then Destinations) can post those events to an endpoint, in PostHog's shape, not the provider's.> + ## Sender and DNS ## Suppression list - + ## PostHog secret key @@ -49,7 +53,7 @@ Read `.posthog-email-migration-plan.md`. Write `posthog-migrate-email- ## Checks - + ## Sending tier @@ -59,11 +63,15 @@ Read `.posthog-email-migration-plan.md`. Write `posthog-migrate-email- The moved sites send through PostHog as soon as this code is deployed. Everything in this list has to be done before that deploy. - + ## After cutover - + suppression list into PostHog with the migrate-email- 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 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.> ## Summary ``` diff --git a/context/skills/migrate-email/references/resend/account.md b/context/skills/migrate-email/references/resend/account.md index 92eca841..842eb748 100644 --- a/context/skills/migrate-email/references/resend/account.md +++ b/context/skills/migrate-email/references/resend/account.md @@ -24,18 +24,22 @@ The app's own Resend key is usually a sending-only key, and it can't read templa ## Template content -A site whose template the person moves to PostHog needs the template's content, to check it before they make the PostHog template. +A site whose template moves needs the template's content: Step 3 checks it, and Step 7 brings it into the code, or the person makes a template in PostHog from it when they ask for one. The API returns the content. -**Copy from the dashboard.** In Resend: Templates, then the template. Ask the person for its alias or name, its HTML, its plain text when it has one, its subject, its `from` and reply-to when they are set, and each variable's fallback. +**Copy from the dashboard.** In Resend: Templates, then the template. Ask the person for its alias or name, its HTML, its plain text when it has one, its subject, its `from` and reply-to when they are set, and each variable's fallback. A copy can't tell a template without plain text, whose emails get one that Resend makes from the HTML, from one whose plain text is set to an empty string, whose emails go out with none. So when it has no plain text, ask the person which. In Step 3, also offer to make the key that "Full-access key" describes, so you read that template from the API. When neither settles it, the site stays, and the reason is `plain-text part not checked`. However you read a template, from here or from the API, write what its plain text is in its note under the sites table: `text: its own`, `text: made from the HTML`, or `text: none`. A copy made again in Step 7 then needs no new question. **Read from the API.** `GET https://api.resend.com/templates/{id or alias}` with `Authorization: Bearer $RESEND_FULL_ACCESS_API_KEY`. The answer holds `alias`, `name`, `subject`, `from`, `reply_to`, `html`, `text`, and `variables`, a list of `{ key, type, fallback_value }`. -Read the person's copies where they saved them. An API answer goes only into the temporary file Step 3 writes, which Step 3 deletes once the site is classified. Never write the content into the plan or the report. +Read the person's copies where they saved them. An API answer goes only into the temporary file Step 3 writes, which is deleted as `template-to-code.md` says. Never write the content into the plan or the report. ## Open tracking Resend tracks opens per sending domain, only when open tracking is on for it: Domains, then the domain, then Configuration. Ask the person once, for each sending domain of the sites that move, whether open tracking is on. Off means the site's emails had no open pixel, and no answer means nobody knows whether they had one, as Step 3 says under "Opens the provider didn't track". +## Click tracking + +Resend tracks clicks per sending domain, only when click tracking is on for it: Domains, then the domain, then Configuration. When a site moves to a template made in PostHog, ask the person once, for each sending domain of such sites, whether click tracking is on. Off means Resend didn't track the site's clicks, and no answer means nobody knows, as Step 3 says under "A template in PostHog". + ## Suppression list Resend suppresses an address after a hard bounce or a spam complaint, and keeps addresses the team added by hand. @@ -51,10 +55,10 @@ Resend suppresses an address after a hard bounce or a spam complaint, and keeps **Map each entry.** -| Resend `origin` | PostHog source | Reason | -|---|---|---| -| `bounce` | bounce | `Imported from Resend: hard bounce` | -| `complaint` | complaint | `Imported from Resend: spam complaint` | -| `manual` | manual | `Imported from Resend: added by hand` | +| Resend `origin` | PostHog `reason` | +|---|---| +| `bounce` | `bounce` | +| `complaint` | `complaint` | +| `manual` | `manual` | **Leave out unsubscribed contacts.** A Resend contact with `unsubscribed: true` still gets transactional email, and PostHog's opt-outs apply to marketing messages only. They are not suppressions. diff --git a/context/skills/migrate-email/references/resend/mapping.md b/context/skills/migrate-email/references/resend/mapping.md index 49404222..1fa1d5f1 100644 --- a/context/skills/migrate-email/references/resend/mapping.md +++ b/context/skills/migrate-email/references/resend/mapping.md @@ -2,6 +2,8 @@ This file decides, field by field, whether PostHog can send a Resend call site. A site moves only when every field it sets moves. Otherwise it stays on Resend, and the reason names the first field or feature that keeps it there. `api.md` has the PostHog side in full. +The field names below are Node.js's. Every Resend SDK sends the same fields under its language's spelling, such as `reply_to` in Python, Ruby, PHP, and Elixir, `ReplyTo` in Go and .NET, and `with_reply` in Rust, and each PostHog SDK's rewrite file names its own. + ## Fields | Resend | PostHog | A site stays on Resend when | @@ -10,9 +12,9 @@ This file decides, field by field, whether PostHog can send a Resend call site. | `to` | `to`, one bare address | `to` can hold more than one address, its entry carries a name, such as `Jane `, or the code builds it at run time and you cannot tell that it holds a bare address only. A list with exactly one bare address moves as that address | | `subject` | `subject` | Never | | `html` | `html` | Never | -| `text` | `text` | Never | -| `react` | `html`, rendered in the app | Never. The app renders the component | -| `template` | a template made in PostHog, sent by its `templateId` with `templateData` | The person keeps it on Resend for now, its content can't be read, it uses syntax beyond variables and fallbacks, the app fills a variable with HTML, or the site sets `from`, `replyTo` / `reply_to`, or `subject` next to it | +| `text` | `text` | It is an empty string next to `html` or `react`, or the code builds it at run time and it can be one, such as a helper's default `text = ''` or `input.text ?? ''`: Resend then sends no text part, and PostHog makes one from the HTML whenever a send has no text. The reason is `turns the plain-text part off`. A `text` left out moves: Resend made the text part from the HTML too. So does an empty `Text` in Go, whose SDK leaves an empty `Text` out of the request | +| `react` (Node.js only) | `html`, rendered in the app | Never. The app renders the component | +| `template` | the template's email, brought into the code and rendered with the site's `variables`, sent as `subject`, `html`, and `text`. A template made in PostHog, by its `templateId` with `templateData`, only when the person asks for one | See "Templates" | | `cc`, `bcc` | none | Always. PostHog's send doesn't take it yet | | `replyTo` / `reply_to` | `replyTo`, one address or a list | An entry carries a name, such as `Jane `, there are more than 10, or the code builds the value at run time and you cannot tell that it holds bare addresses only | | `headers` | none | Always. PostHog's send doesn't take it yet | @@ -26,27 +28,54 @@ This file decides, field by field, whether PostHog can send a Resend call site. | Resend call | A site stays on Resend when | |---|---| -| `emails.send`, `emails.create`, `Emails.send`, `POST /emails` | A field above keeps it | -| `batch.send`, `Batch.send`, `POST /emails/batch` | Always | +| A send: `resend.emails.send` or `resend.emails.create` (Node.js), `resend.Emails.send` or `send_async` (Python), `Resend::Emails.send` (Ruby), `$resend->emails->send` or `create` (PHP), `client.Emails.Send`, `SendWithContext`, or `SendWithOptions` (Go), `EmailSendAsync` (.NET), `resend.emails.send` (Rust), `Resend.Emails.send` (Elixir), or `POST /emails` | A field above keeps it | +| A batch: `batch.send`, `Batch.send`, `Batch.Send`, `EmailBatchAsync`, `send_batch`, or `POST /emails/batch` | Always | | SMTP through `smtp.resend.com` | Always. PostHog has no SMTP relay | -| Laravel's or Rails' `resend` mailer | Always. PostHog has no mailer driver | -| A send in a language other than JavaScript or TypeScript | Always, until the skill moves that language | +| A framework mailer that sends through Resend: Laravel's or Rails' `resend` mailer, the `Resend.Swoosh.Adapter` Swoosh adapter in Elixir, or `Resend.FluentEmail` in .NET | Always. PostHog has no mailer driver | +| A send in a language without a PostHog SDK that sends email, such as Java or Kotlin | Always. Step 7 lists the languages PostHog's SDKs cover | ## Code around the send | Code | A site stays on Resend when | |---|---| -| `if (error.name === '...')` | The name is not one of posthog-node's, which every site that moves sends through, an HTTP site too: PostHog's HTTP API answers with `type` and `code`, and only posthog-node gives these names: `validation_error`, `missing_api_key`, `invalid_permission`, `not_found`, `concurrent_idempotent_requests`, `invalid_idempotent_request`, `rate_limit_exceeded`, `monthly_quota_exceeded`, `service_unavailable`, `application_error` | +| A branch on Resend's error name: `error.name` in Node.js, Go, and Elixir, `error_type` in Python, `getErrorType()` in PHP, or `ErrorType` in .NET | The name is not one of PostHog's: `validation_error`, `missing_api_key`, `invalid_permission`, `not_found`, `concurrent_idempotent_requests`, `invalid_idempotent_request`, `rate_limit_exceeded`, `monthly_quota_exceeded`, `service_unavailable`, `application_error` | | `emails.get(id)` and a branch on `last_event` | Always: the send and its status read stay together. PostHog's status is not `last_event` | | `data.id` stored for a webhook or a status read | Always, when Resend webhooks or status reads use the id | -| A `signal` the code can abort, such as one a caller passes in or an `AbortController` it aborts, on a `fetch` or axios request or in the options of `resend.emails.send(payload, { signal })`, which the SDK passes to its request | Always: `posthog.emails.send` takes no signal, so an email the old code cancelled would go out. A fixed `AbortSignal.timeout(...)` is a deadline, and moves as "HTTP" below says, in an SDK send too | +| Code that reads what Resend's answer carries from its response headers: `headers` on the answer in Node.js, `http_headers` on the answer or `headers` on an error in Python, `headers` on the answer or an error in Ruby, and `RateLimitExceededError`'s `rate_limit_limit`, `rate_limit_remaining`, `rate_limit_reset`, and `retry_after`, the fields of `*resend.RateLimitError` in Go, `Limits` on the answer or the exception in .NET, the `ratelimit_*` fields of `Error::RateLimit` in Rust, the headers of an HTTP request's answer, and the same in any SDK whose answer or error carries them | When it reads anything but the retry delay of a refused send, such as a `retry-after` header of a `429`: PostHog's answer carries no headers, and its error carries only the retry delay. The reason is `reads
from Resend's answer`. The retry delay moves as "The retry delay" says. A `headers` the code takes from the answer and never uses goes away | +| A send the code can cancel, such as a request with a `signal` a caller passes in or an `AbortController` it aborts, on a `fetch` or axios request or in the options of `resend.emails.send(payload, { signal })`, which the SDK passes to its request, or a Go `context` or .NET cancellation token that a caller can cancel | Unless the PostHog send in that language takes the same cancellation, as Go's `Send(ctx, ...)` and .NET's `SendAsync(..., cancellationToken)` do: pass it there. Otherwise always, as in Node.js, whose send takes no signal: an email the old code cancelled would go out. A fixed deadline, such as `AbortSignal.timeout(...)`, moves as Step 7 says | ## Content - `html`, `text`, and `react` content is rendered for one recipient before the send. PostHog sends it as it is. -- A `template` site moves only to a template made in PostHog. This skill never makes one: the person makes it from the Resend template and gives you its template ID, and makes it transactional once a verified sender covers its address, as Step 3 says. Until they give the ID, the site stays on Resend. -- An email that carries a login code, a reset link, or another secret needs its PostHog template marked sensitive: PostHog then keeps no copy of each sent email's body or filled-in subject, and a clicked link keeps only the site's address. Templates are not sensitive by default. -- The check needs the template's content, because the code has only its id. `account.md` says how to get it. + +## Templates + +A `template` site moves by bringing the template into the code, as `template-to-code.md` says. The check needs the template's content, because the code has only its id or alias. `account.md` says how to get it. The code renders the template's HTML, text, and subject with the site's `variables`, and the send sets the rendered `subject`, `html`, and `text`. + +Resend templates hold only variables, with an optional fallback. In the code: + +| Resend | In the code | +|---|---| +| `{{{NAME}}}` in the HTML | The value. Resend inserts it as it is and never escapes it, so it falls under the rule of `template-to-code.md`: escape it, unless the code builds it as HTML itself, such as a link or a list it joins. Then insert it as it is, and name it in the plan row | +| `{{{NAME}}}` in the subject or the text | The value as it is, with no escaping | +| `{{{NAME\|there}}}`, and a variable whose definition has a `fallback_value` | The value, or the fallback when the site doesn't pass the variable. Resend inserts an empty string as it is, so `""` renders as nothing, not as the fallback. A fallback is the template's own text: in the HTML it goes in as it is, so a fallback that holds HTML, such as a link, renders as before | +| A variable of type `number` | The number written as a decimal, such as `3` or `2.5`. Note in the plan row where the language writes a whole float differently, such as Python's `3.0` | +| The template's `subject` | The send's `subject`, rendered with the same variables. A subject the site sets next to `template` wins: Resend sends the value the send passes over the template's | +| The template's `from` and `reply_to` | The send's `from` and reply-to address. A value the site sets next to `template` wins, the same way. A value the send takes from the template meets the rules of "Fields" as one the site sets: a reply-to address with a name, such as `Support `, keeps the site on Resend | +| The template's `html` and `text` | The send's `html` and `text`. A template without `text` sends `html` only: Resend made its text part from the HTML, and PostHog does the same. A template whose `text` is an empty string sent no text part, which a PostHog send can't do: it stays on Resend, and the reason is `turns the plain-text part off` | + +Write the `\|` above as a plain `|`. The table escapes it. + +- Any other syntax in the template, such as a section, a loop, or a condition, keeps it on Resend: these files say what only variables and fallbacks do. The reason names the syntax. +- A variable the template reads without a fallback, which the site can leave out, keeps the template on Resend: these files don't say what Resend renders then. The reason is ` can be missing`. A site that always passes it moves. +- These files name no host where Resend keeps a template's images. List each image whose host isn't the app's own, and ask the person once whether Resend hosts any of them, so the report can name those, as `template-to-code.md` says. + +### Templates made in PostHog + +Only for a template the person asks to make in PostHog, as Step 3 says. The person makes it from the Resend template and gives you its template ID, and makes it transactional once a verified sender covers its address, as Step 3 says. Until they give the ID, the site stays on Resend. + +An email that carries a login code, a reset link, or another secret needs its PostHog template marked sensitive: PostHog then keeps no copy of each sent email's body or filled-in subject, and sends its links as they are, without its click redirect. Templates are not sensitive by default. + - In the PostHog template, `{{{NAME}}}` becomes `{{ variables.NAME }}`, and the name keeps its case. `{{{NAME|there}}}` becomes `{{ variables.NAME | default: 'there' }}`, and a variable with a `fallback_value` in the template's definition gets the same `default`. Quote every fallback with `'`: a `"` inside the template's JSON body raises `TokenizationError`. Liquid has no escape character in a quoted value, so a fallback that holds a `'` keeps the site on Resend. - Liquid's `default` also replaces an empty string, which Resend inserts as it is. When the code can pass an empty string for a variable with a fallback, the email shows the fallback instead. Note it in the report. - Resend inserts a variable's value as it is. PostHog's Liquid escapes HTML in a value, so `` shows as text. A variable is HTML when the code fills it with markup or with a renderer's output, and such a variable keeps the site on Resend. A variable the app fills with plain values, such as names, numbers, and URLs, renders the same. @@ -55,34 +84,108 @@ This file decides, field by field, whether PostHog can send a Resend call site. ## Webhooks -Resend stops sending email events for a site that moves, and PostHog's events carry no Resend `email_id` and no `tags`. A site whose emails a webhook handler acts on stays, however the handler finds the send an event belongs to: by `email_id`, by a tag, or by anything else, such as the recipient's address. The reason is `its events feed a webhook handler`. When you can't tell which sites' emails a handler acts on, such as one that finds the send by the recipient's address, every site whose emails can reach it stays. The handler itself keeps working for the sites that stay. Never change it. +Resend stops sending email events for a site that moves. PostHog records the events of a moved send on the person it names with `distinctId`, when engagement capture is on: -## Rewrite +| Resend event | PostHog event | +|---|---| +| `email.sent` | `$workflows_email_sent` | +| `email.delivered` | `$workflows_email_delivered` | +| `email.bounced` | `$workflows_email_bounced` | +| `email.complained` | `$workflows_email_blocked` | +| `email.opened` | `$workflows_email_opened` | +| `email.clicked` | `$workflows_email_link_clicked`, only for a template made in PostHog that is not marked sensitive. PostHog treats a send in the code form as sensitive when no template saved in PostHog has its key, which Step 7 makes sure: its links go out as they are, and it counts no clicks | +| Every other email event, such as `email.delivery_delayed` | none | + +PostHog's events carry no Resend `email_id` and no `tags`. A site whose events a handler matches by `email_id` or by a tag stays on Resend. For every other handler, the report tells the person which events it handles, which PostHog events take their place, and that a webhook destination in PostHog (Data pipelines, then Destinations) can post them to an endpoint. The handler itself keeps working for the sites that stay. Never change it. -How a site that moves is written with `posthog-node`. Step 7 says when to use each part. +A site whose emails a handler acts on for an event that has no PostHog event in the table, such as `email.delivery_delayed`, stays, and the reason is `its events feed a webhook handler`. A site whose emails an `email.clicked` handler acts on moves only to a template made in PostHog that is not marked sensitive, since a send in the code form counts no clicks. Otherwise it stays, and the reason is `its clicks feed a webhook handler`. -**The PostHog client.** Set `migratedFrom: 'resend'` on the `posthog-node` client that Step 7 configures, when its client options take it. +## Calls that change the suppression list -**The call.** `resend.emails.send(payload, { idempotencyKey })` and `resend.emails.create(...)` become one `posthog.emails.send({ ... })`. The options object goes away: `idempotencyKey` moves into the payload. A `signal` in it is code around the send, as the table above says. +Step 3 and Step 5 say what to do with each of these calls. They are not sends, and they stay on Resend. + +| Adds an address | Removes an address | +|---|---| +| `resend.suppressions.add(...)`, `resend.suppressions.batch.add(...)`, `POST /suppressions`, `POST /suppressions/batch/add`, and each SDK's spelling of them, such as `Resend::Suppressions.add` in Ruby or `client.Suppressions.Add` in Go | `resend.suppressions.remove(...)`, `resend.suppressions.batch.remove(...)`, `DELETE /suppressions/{id or email}`, `POST /suppressions/batch/remove`, and each SDK's spelling of them | + +A contact's `unsubscribed` flag is not on this list, as `account.md` says, so a call that sets it is not one of these. + +## Rewrite + +How a site that moves is written with PostHog's SDK for its language. Step 7 says when to use each part, and the SDK's rewrite file gives the PostHog side of each call. + +**The PostHog client.** Set the provider name to `resend` on the PostHog client that Step 7 configures, under the name the rewrite file gives, such as `migratedFrom: 'resend'` in Node.js or `migrated_from="resend"` in Python, when the client options take it. **The fields.** -- `to: ['jane@example.com']` becomes `to: 'jane@example.com'`. A value that is a list with one entry becomes that entry. +- A `to` that is a list with one entry becomes that entry, such as `to: ['jane@example.com']` becoming `to: 'jane@example.com'`. - When a helper takes a list of recipients and every caller passes one address, change the parameter to one address and update the callers, so the type keeps a second address out. Never send one email per address in a loop, and never drop the addresses after the first. -- `from`, `subject`, `html`, `text`, and `replyTo` keep their names and values. -- A send with rendered content gets a `templateKey`, as Step 7 says. +- `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. + +**Templates brought into the code.** The site renders the email from its `variables`, as "Templates" says, and sends the template key, the rendered subject, HTML, and text, and the `from` and reply-to address: the site's own where it sets them, otherwise the template's. It sends no template ID and no template data. + +**Templates made in PostHog.** The site sends the template ID the person gave, and the template data with the site's `variables`. It sends no template key, subject, body, `from`, or reply-to address: the template holds them. + +**HTTP.** A request to `https://api.resend.com/emails`, through `fetch`, `axios`, `requests`, `httpx`, `net/http`, Faraday, Guzzle, `HttpClient`, `reqwest`, `Req`, or `curl`, becomes the SDK's send in that language. The `Idempotency-Key` header becomes the send's idempotency key. Code that read the response status reads the SDK's error instead. A request with its own deadline, such as `signal: AbortSignal.timeout(5000)` or `requests.post(..., timeout=5)`, keeps it, as Step 7 says under "Set up the client". An axios `timeout: 5000` in Node.js is a limit the SDK can't keep, as Step 7 says there. + +**Suppressed recipients.** Resend takes a send to a suppressed address and drops it later. PostHog refuses it with the error code `recipient_suppressed` (name `validation_error`). When the site throws, retries, or reports a failure on any error, handle that code before that branch, as the rewrite file shows, the way the site handled a send that went out: log it and go on. A suppressed send has no message ID: when the code after the send uses the ID for more than a log line, such as returning it to its callers or storing it, the site stays, and the reason is `uses the message id of a suppressed send`, unless its callers already handle a send without an ID. Note each site that got this branch in the report. + +**Error handlers.** The parts below change Resend's error to PostHog's. When the same `try`, `begin`, or error check also covers a call that stays on Resend, such as `resend.Contacts.create`, keep Resend's handler for that call and add PostHog's next to it. Resend's API names a `503` answer `service_unavailable`, and every PostHog SDK also names a network failure that is left after its retries `service_unavailable`, with the code `network_error`. So a branch on the name `service_unavailable` also checks that the code is not `network_error`, such as `error.name === 'service_unavailable' && error.code !== 'network_error'`, and a network failure takes the path the old code gave it, as Step 7 says under "Rewrite each site", such as Node.js's branch on `application_error` below, wherever that branch stands. + +**The retry delay.** A site that reads the retry delay of a refused send reads the PostHog error's instead, under the name and in the unit its rewrite file gives under "The answer". Resend carries it in the `retry-after` header, in seconds: in `headers` on the answer in Node.js, `headers` on the error in Python, `RateLimitExceededError`'s `retry_after`, a whole number, in Ruby, `*resend.RateLimitError`'s `RetryAfter`, a string, in Go, and `Limits.RetryAfter` in .NET. Convert where the units differ. PostHog sets it only when its answer named a wait, so keep the path the old code gave a missing header. A send through a client with retries has already waited and retried a rate limit by itself by then. A site that keeps its own deadline sends with no retries, as Step 7 says under "Set up the client", so its own wait and retry stay as they are. + +**The Resend client.** Keep Resend's client, its import, and its setup while any site or other call still uses them. When nothing uses them, remove the import and the client, and keep the Resend package and its key: the person removes them after the cutover. + +### Node.js + +- `resend.emails.send(payload, { idempotencyKey })` and `resend.emails.create(...)` become one `posthog.emails.send({ ... })`. The options object goes away: `idempotencyKey` moves into the payload. A `signal` in it is code around the send, as the table above says. +- `react: ` becomes `html: await render()`, with `import { render } from '@react-email/render'`. Keep a `text` the site already passes. +- An HTTP body's snake_case fields become camelCase: `reply_to` becomes `replyTo`. +- posthog-node answers `{ data, error }` like Resend and never throws on an API error. `data.id` is PostHog's message ID, so code that logs it or stores it for the app's own use keeps working for a send that goes out. A suppressed send has none, as "Suppressed recipients" says. `error.name` uses Resend's names, so `if (error.name === 'rate_limit_exceeded')` keeps working, and `error.message` and `error.statusCode` keep their names. +- Resend answers a network failure as an `error` with the name `application_error` and a `statusCode` of `null`. posthog-node answers it with the code `network_error`, the name `service_unavailable`, and no `statusCode`. A branch on `error.name === 'application_error'` took network failures too: it also takes `error.code === 'network_error'`. A check of `error.statusCode === null` becomes `error.statusCode == null`, which a local argument error matches too, as Resend's `null` did. + +### Python + +- `resend.Emails.send(params, options={"idempotency_key": key})` becomes `posthog.emails.send(...)` with keyword arguments: `params["from"]` becomes `from_=`, and the options' `idempotency_key` becomes `idempotency_key=`. `resend.Emails.send_async` becomes the same call on `AsyncPosthog`, awaited. +- Resend answers a dict, and PostHog a `SendEmailResult`: `response["id"]` becomes `result.id`. +- Both raise on an API error. `except resend.exceptions.ResendError` becomes `except EmailError`, from `posthog.emails`. A class that stands for an HTTP status, such as `resend.exceptions.RateLimitError` for `429`, becomes `EmailError` with a check of `error.status_code`, such as `error.status_code == 429`, because one status covers more than one PostHog name. +- Resend's `error.code` is the HTTP status, and PostHog's is a string error code. Code that read `error.code` reads `error.status_code`, and code that read `error.error_type` reads `error.name`. + +### Ruby + +- `Resend::Emails.send(params, options: { idempotency_key: key })` becomes `POSTHOG.emails.send(...)` with keyword arguments, and the options' `idempotency_key` becomes `idempotency_key:`. +- Resend answers a hash-like response, and PostHog a `SendResult`: `response[:id]` becomes `result.id`. +- Both raise on an API error. `rescue Resend::Error` becomes `rescue PostHog::EmailError`. A class that stands for an HTTP status, such as `Resend::Error::RateLimitExceededError` for `429`, becomes `PostHog::EmailError` with a check of `e.status_code`, such as `e.status_code == 429`, because one status covers more than one PostHog name. + +### PHP + +- `$resend->emails->send([...], ['idempotency_key' => $key])`, `$resend->emails->create(...)`, and Laravel's `Resend::emails()->send(...)` facade become `$posthog->emails()->send([...])` on the email client the rewrite file sets up, and the options' `idempotency_key` moves into the array. +- Resend answers a `Resend\Email`, and PostHog a `SendEmailResult`: `$email->id` becomes `$result->getId()`. +- Both throw on an API error. `catch (\Resend\Exceptions\ErrorException $e)` becomes `catch (\PostHog\EmailError $e)`. +- Resend's `getErrorCode()` is the HTTP status as an `int`, and PostHog's `getErrorCode()` is a string error code. Code that read `getErrorCode()` reads `getStatusCode()`, and code that read `getErrorType()` reads `getErrorName()`. + +### Go + +- `client.Emails.Send(params)`, `SendWithContext(ctx, params)`, and `SendWithOptions(ctx, params, &resend.SendEmailOptions{IdempotencyKey: key})` become `client.Emails().Send(ctx, posthog.CodeEmail{...})`. Pass the site's context, or `context.Background()` where the old call had none. `Html` becomes `HTML`, and the options' `IdempotencyKey` moves into the email. +- Both answer a pointer and an error: `resp.Id` becomes `result.ID`. +- `*resend.ResendError` becomes `*posthog.EmailError`, read with `errors.As`. `StatusCode` and `Name` keep their names. Every other check of a Resend error, such as one for the rate limit, with its own type or sentinel, becomes `errors.As` with `*posthog.EmailError` and a check of `StatusCode`, such as `StatusCode == 429`. -**React.** `react: ` becomes `html: await render()`, with `import { render } from '@react-email/render'`. Keep a `text` the site already passes. +### .NET -**HTTP.** A `fetch` or `axios` call to `https://api.resend.com/emails` becomes `posthog.emails.send` with the camelCase fields: `reply_to` becomes `replyTo`, and the `Idempotency-Key` header becomes `idempotencyKey`. Code that read the response status reads `error` instead. A request with its own deadline, such as `signal: AbortSignal.timeout(5000)` or axios `timeout: 5000`, keeps it: set `emailRequestTimeoutMs` to that value on the client the sends use, and pass `maxRetries: 0` on the send, since the request never retried. posthog-node otherwise waits up to 15 seconds and retries twice, which can run past the site's deadline. The timeout belongs to the client, so each distinct deadline gets its own client, set up as Step 7 says with that `emailRequestTimeoutMs`, and its sites send through it. Sites without a deadline keep the shared client, and with it the SDK's limit: up to 15 seconds per request and two retries with the same idempotency key, so a retry never sends twice, and a send slower than 15 seconds on every try now ends in `network_error` where it used to wait. Never give a site a deadline it didn't have. +- `await resend.EmailSendAsync(message)` and `EmailSendAsync(idempotencyKey, message)` become `await emails.SendAsync(new SendCodeEmailOptions { ... })`. `HtmlBody` becomes `Html`, `TextBody` becomes `Text`, and the idempotency key moves into the options. +- Resend answers a `ResendResponse`, and PostHog a `SendEmailResult`: `response.Content` becomes `result.Id`, a `string` that holds a UUID, as Step 7 says. Where the code keeps the ID as a `Guid`, it becomes `Guid.Parse(result.Id)`, for a send that goes out, as "Suppressed recipients" says. +- Resend throws `ResendException` unless its options set `ThrowExceptions = false`, and PostHog always throws `EmailException`. `catch (ResendException e)` becomes `catch (EmailException e)`, and a check of `e.ErrorType`, an enum such as `ErrorType.RateLimitExceeded`, becomes a check of `e.Name`, a string such as `"rate_limit_exceeded"`. Code that checked `response.Success` catches `EmailException` instead. -**Templates made in PostHog.** The site sends `templateId` with the template ID the person gave, and `templateData` with the site's `variables` object. It sends no `templateKey`, `subject`, `html`, `text`, `from`, or `replyTo`: the template holds them. +### Rust -**The answer.** posthog-node answers `{ data, error }` like Resend and never throws on an API error. +- `resend.emails.send(CreateEmailBaseOptions::new(from, to, subject).with_html(html))`, with `.with_text(...)`, `.with_reply(...)`, and `.with_idempotency_key(key)`, becomes `posthog.emails().send(CodeEmail::new(to, template_key, subject).html(html))`, with `.text(...)`, `.reply_to(...)`, `.idempotency_key(key)`, and `.from(from)` for the sender the old call passed. +- Both answer a `Result`: `response.id` becomes `result.id`. +- `resend_rs::Error` becomes `posthog_rs::EmailError`. A match on Resend's error name becomes a match on `error.kind().as_str()`. -- `data.id` is PostHog's message id. Code that logs it or stores it for the app's own use keeps working. -- `error.name` uses Resend's names for the API's answers, so `if (error.name === 'rate_limit_exceeded')` keeps working. `error.message` and `error.statusCode` keep their names. -- A network failure is the exception. Resend answers it as an `error` with the name `application_error` and a `statusCode` of `null`. posthog-node answers it, once its retries are spent, with the code `network_error`, the name `service_unavailable`, and no `statusCode`. So a branch on `error.name === 'application_error'` also takes `error.code === 'network_error'`, and a branch on `error.name === 'service_unavailable'`, which took only Resend's `503` answers, also checks `error.code !== 'network_error'`, wherever it stands: a network failure then takes the path the old code gave it. A check of `error.statusCode === null` becomes `error.statusCode == null`, which a local argument error matches too, as Resend's `null` did. -- Resend takes a send to a suppressed address and drops it later. PostHog refuses it with `error.code` `recipient_suppressed` (name `validation_error`). When the site throws, retries, or reports a failure on any error, add `if (error?.code === 'recipient_suppressed')` before that branch and handle it the way the site handled a send that went out: log it and go on. A suppressed send has no `data.id`: when the code after the send uses the id for more than a log line, such as returning it to its callers or storing it, the site stays, and the reason is `uses the message id of a suppressed send`, unless its callers already handle a send without an id. Note each site that got this branch in the report. +### Elixir -**The Resend client.** Keep `new Resend(...)` and its import while any site or other call still uses it. When nothing uses it, remove the import and the client, and keep the `resend` package and its key: the person removes them after the cutover. +- `Resend.Emails.send(%{from: ..., to: ..., ...})`, with or without a client as the first argument, becomes `PostHog.Emails.send(MyApp.PostHogEmail, from: ..., to: ..., ...)` with the email instance's name first and a keyword list. Resend's Elixir SDK takes no idempotency key, so the site sends none unless the old code set one some other way. +- `{:ok, %Resend.Emails.Email{id: id}}` becomes `{:ok, result}` with `result.id`. +- `{:error, %Resend.Error{}}` becomes `{:error, %PostHog.Emails.Error{}}`. Resend's `name` is a string and PostHog's is an atom: a match on `name: "rate_limit_exceeded"` becomes `name: :rate_limit_exceeded`. diff --git a/context/skills/migrate-email/references/resend/sdk-reference.md b/context/skills/migrate-email/references/resend/sdk-reference.md index cb0b72b6..472072e6 100644 --- a/context/skills/migrate-email/references/resend/sdk-reference.md +++ b/context/skills/migrate-email/references/resend/sdk-reference.md @@ -32,7 +32,7 @@ import resend resend.api_key = os.environ["RESEND_API_KEY"] ``` -Look for `new Resend(`, `from 'resend'`, `require('resend')`, `import resend`, `Resend::`, and `resend.NewClient(`. +Look for `new Resend(`, `from 'resend'`, `require('resend')`, `import resend`, `Resend.api_key`, `Resend::`, `Resend::client(`, `resend.NewClient(`, `AddResend(`, `IResend`, `ResendClient`, `Resend::new(` in Rust, and `Resend.client(` or `config :resend` in Elixir. ## Sends @@ -47,15 +47,29 @@ const { data, error } = await resend.emails.send({ }, { idempotencyKey: `welcome:${user.id}` }) ``` -**Python.** `resend.Emails.send(params)`, with the same fields in snake_case, and `options={"idempotency_key": ...}`. It raises on API errors. +**Python.** `resend.Emails.send(params, options)` and `await resend.Emails.send_async(...)`, with the same fields in snake_case in a dict, and `options={"idempotency_key": ...}`. It answers a dict with `"id"`, and raises a `resend.exceptions.ResendError` subclass on an API error, with `code` (the HTTP status) and `error_type` (the error name). -**Batch.** `resend.batch.send([...])` in Node.js and `resend.Batch.send([...])` in Python send up to 100 emails in one call. +**Ruby.** `Resend::Emails.send(params, options: { idempotency_key: ... })`, with symbol keys in snake_case. It answers a hash-like response with `[:id]`, and raises a `Resend::Error` subclass for the HTTP status, such as `Resend::Error::RateLimitExceededError`. + +**PHP.** `$resend = Resend::client($key)`, then `$resend->emails->send([...], ['idempotency_key' => ...])` or its alias `create`, with snake_case keys. Laravel apps use the facade, `Resend\Laravel\Facades\Resend::emails()->send(...)`. It answers a `Resend\Email` with `->id`, and throws `Resend\Exceptions\ErrorException` with `getErrorType()` (the error name) and `getErrorCode()` (the HTTP status). + +**Go.** `client := resend.NewClient(key)`, then `client.Emails.Send(params)`, `client.Emails.SendWithContext(ctx, params)`, or `client.Emails.SendWithOptions(ctx, params, &resend.SendEmailOptions{IdempotencyKey: ...})`, with a `*resend.SendEmailRequest{From, To, Subject, Html, Text, ReplyTo, ...}`. It answers a `*resend.SendEmailResponse` with `Id` and an error, which is a `*resend.ResendError` with `StatusCode` and `Name` for an API error. + +**.NET.** `IResend`, registered with `services.AddResend(...)` or created as a `ResendClient`, then `await resend.EmailSendAsync(message)` or `EmailSendAsync(idempotencyKey, message)`, with an `EmailMessage { From, To, Subject, HtmlBody, TextBody, ReplyTo, ... }`. It answers a `ResendResponse` with `Content`, and throws `ResendException` with `StatusCode` and `ErrorType` on an API error, unless its options set `ThrowExceptions = false`: then the response has `Success` and `Exception`. + +**Rust.** `let resend = Resend::new(key)`, then `resend.emails.send(CreateEmailBaseOptions::new(from, to, subject).with_html(...))`, with `.with_text(...)`, `.with_reply(...)`, and `.with_idempotency_key(...)`. It answers a `Result` with a `CreateEmailResponse { id }`, or a `resend_rs::Error`. + +**Elixir.** `Resend.Emails.send(%{from: ..., to: ..., subject: ..., html: ...})`, or `Resend.Emails.send(client, %{...})`, with the API key in `config :resend, Resend.Client, api_key: ...`. It takes no idempotency key. It answers `{:ok, %Resend.Emails.Email{id: ...}}` or `{:error, %Resend.Error{name: ..., status_code: ...}}`. + +**Java.** `resend.emails().send(...)` in `com.resend:resend-java`. PostHog has no SDK that sends email in Java, so these sends stay. + +**Batch.** `resend.batch.send([...])` in Node.js, `resend.Batch.send([...])` in Python, `Resend::Batch.send([...])` in Ruby, `$resend->batch->send([...])` in PHP, `client.Batch.Send(...)` in Go, `EmailBatchAsync(...)` in .NET, `resend.batch.send(...)` in Rust, and `Resend.Emails.send_batch(...)` in Elixir send up to 100 emails in one call. **HTTP.** `POST https://api.resend.com/emails` with `Authorization: Bearer `, a JSON body with the snake_case fields, and an optional `Idempotency-Key` header. `POST https://api.resend.com/emails/batch` is the batch send. Look for `api.resend.com` in `fetch`, `axios`, `got`, `requests`, `httpx`, and `curl` calls. **SMTP.** Resend also takes mail over SMTP at `smtp.resend.com`, with the user `resend` and the API key as the password. Look for that host in Nodemailer transports, `MAIL_HOST` or `SMTP_HOST` settings, and framework mail config. -**Frameworks.** Laravel's `resend` mailer (`MAIL_MAILER=resend`) and Rails' `resend` delivery method send every framework mail through Resend: each mailable or mailer that sends is a site. +**Frameworks.** Laravel's `resend` mailer (`MAIL_MAILER=resend`), Rails' `resend` delivery method, the Swoosh adapter `Resend.Swoosh.Adapter` in Elixir, and the `Resend.FluentEmail` sender in .NET send every framework mail through Resend: each mailable or mailer that sends is a site. ## Send fields diff --git a/context/skills/migrate-email/references/rewrite-dotnet.md b/context/skills/migrate-email/references/rewrite-dotnet.md new file mode 100644 index 00000000..2aad21e9 --- /dev/null +++ b/context/skills/migrate-email/references/rewrite-dotnet.md @@ -0,0 +1,65 @@ +--- +title: Send with the PostHog .NET SDK +description: The PostHog side of a moved site in C# or F# on .NET +--- + +# Send with the PostHog .NET SDK + +For a site in C# or F# on .NET. A site that sends through a mailer library, such as FluentEmail, stays on the provider: the provider's `mapping.md` says so. + +## Install + +`dotnet add package PostHog`, which adds its latest release. + +## The client + +Set these on `PostHogOptions`: + +- `SecretKey`, from `POSTHOG_PROJECT_SECRET_API_KEY`. Read it where the app reads its provider key, such as an environment variable, user secrets, or `appsettings.json` with the value from the environment. +- `MigratedFrom`, set to ``, only when `PostHogOptions` has it. +- `AppHost`, the app host option. + +Create a `PostHogClient` of its own for email, also when the app registers PostHog with ASP.NET's `builder.AddPostHog()`. That registration is the app's own client, and the `IPostHogEmails` it registers is that client's `Emails`, so setting `PostHog:SecretKey` there would change the app's client. Leave the app's `PostHog` configuration as it is: + +```csharp +var emailClient = new PostHogClient(new PostHogOptions +{ + ProjectToken = configuration["POSTHOG_PROJECT_TOKEN"], + HostUrl = new Uri(string.IsNullOrWhiteSpace(configuration["POSTHOG_HOST"]) ? "https://us.i.posthog.com" : configuration["POSTHOG_HOST"]!), + SecretKey = configuration["POSTHOG_PROJECT_SECRET_API_KEY"], + MigratedFrom = "", // only when PostHogOptions has it +}); +``` + +Create it once, such as in a singleton class of the app's own that holds it, and send with `emailClient.Emails`, the `emails` below. Never inject the `IPostHogEmails` that `AddPostHog()` registers for these sites. + +With `SecretKey` set, the client loads flag definitions from its host with it when it evaluates a flag. A client that only sends email never evaluates one, so it needs no other setting. + +## The send + +- Code send: `await emails.SendAsync(new SendCodeEmailOptions { To, TemplateKey, Subject, Html, Text, DistinctId, IdempotencyKey })`, with `From`, `ReplyTo`, `CaptureEngagement`, and `Sensitive = true` optional. +- Template send: `await emails.SendAsync(new SendTemplateEmailOptions { To, TemplateId, TemplateData, DistinctId, IdempotencyKey })`. +- `ReplyTo` is a list, and `TemplateId` is a `Guid`. +- There is no synchronous send. A site in a method that is not `async` and doesn't return the send's `Task` stays, with the reason `synchronous .NET send`, unless the person agrees to make the method and its callers `async`. Never block on `SendAsync` with `.Result` or `.Wait()`. + +## A deadline + +For a site whose request had its own deadline, as `7-rewrite.md` says under "Set up the client": + +- `SendAsync` keeps to its cancellation token: pass one with the site's deadline, such as from `using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(5))`, and set `MaxRetries = 0` on the email options. A token the caller can cancel, such as a request's `HttpContext.RequestAborted`, cancels the send the same way. +- The client also ends each request at its `EmailRequestTimeout`. A deadline up to that timeout needs no client of its own. A longer one needs a client of its own with `EmailRequestTimeout` set to it, or the send fails before the site's deadline. +- The client's `HttpClient` also ends each request at 100 seconds, .NET's default. A deadline longer than 100 seconds can't be kept: the site stays, as Step 7 says. +- `PostHogOptions.EmailRequestTimeout` is the time each email request may take, 15 seconds by default, and `EmailRequestMaxRetries` its retries, 2 by default. + +## The answer + +- The send returns a `SendEmailResult`. `Id` is the message ID, a `string`. +- On an API error it throws `EmailException`. `Code` is PostHog's error code, such as `recipient_suppressed`, `Name` is one of the coarse names that `7-rewrite.md` lists under "What every SDK's send takes and answers", and `StatusCode` is the HTTP status. +- Suppressed recipient: `catch (EmailException e) when (e.Code == "recipient_suppressed")`. +- It throws the same `EmailException` for a network error that is left after the retries, with the code `network_error`. `Message` is there too. +- An error PostHog answered with a wait carries it as `e.RetryAfter`, a `TimeSpan?`; it is `null` when PostHog named none. +- A bad argument throws `ArgumentException`, before any request. + +## Check + +`dotnet build` on the solution or the project that holds the sites. diff --git a/context/skills/migrate-email/references/rewrite-elixir.md b/context/skills/migrate-email/references/rewrite-elixir.md new file mode 100644 index 00000000..c4686ee6 --- /dev/null +++ b/context/skills/migrate-email/references/rewrite-elixir.md @@ -0,0 +1,58 @@ +--- +title: Send with the posthog Elixir SDK +description: The PostHog side of a moved site in Elixir +--- + +# Send with the posthog Elixir SDK + +For a site in Elixir, such as in a Phoenix app. A site that sends through the Swoosh mailer adapter stays on the provider: the provider's `mapping.md` says so. + +## Install + +Add `{:posthog, "~> "}` to the deps in `mix.exs`, or raise the version there, then run `mix deps.get`. + +## The client + +Give email a named instance of its own in the application's children, also when the app doesn't use PostHog yet. When the app has a `:posthog` config, leave it as it is: + +```elixir +{PostHog.Supervisor, + PostHog.Config.validate!( + supervisor_name: MyApp.PostHogEmail, + api_host: System.get_env("POSTHOG_HOST") || Application.get_env(:posthog, :api_host) || "https://us.i.posthog.com", + api_key: System.get_env("POSTHOG_PROJECT_TOKEN") || Application.get_env(:posthog, :api_key) || "", + secret_key: System.get_env("POSTHOG_PROJECT_SECRET_API_KEY"), + enable_local_evaluation: false, + migrated_from: "" # only when the config takes it + )} +``` + +- With `secret_key` set, the SDK loads flag definitions from `api_host` with it when it starts. `enable_local_evaluation: false` stops that, so the key needs no flag scope. Behind a reverse proxy, set the instance's `api_host` to PostHog's own host, as Step 7 says. Turning it off on the app's existing config would break the flags the app evaluates locally, so the existing config keeps its own settings. +- `api_host` and `api_key` must be strings, and a `nil` stops the app from starting, so each one falls back as above: to the app's own `:posthog` value, then, when that is unset or `nil`, to the US Cloud host and an empty token. Use `https://eu.i.posthog.com` for EU Cloud. `secret_key` can be `nil`, and a send without it fails with its own error. +- The app host option is `app_host`. +- Name the instance after the app, such as `MyApp.PostHogEmail`, and pass that name first to each call below. + +## The send + +- Code send: `PostHog.Emails.send(MyApp.PostHogEmail, to: ..., template_key: ..., subject: ..., html: ..., text: ..., distinct_id: ..., idempotency_key: ...)`, with `from:`, `reply_to:`, `capture_engagement:`, and `sensitive: true` optional. +- `reply_to:` takes one address or a list of addresses. +- Template send: `PostHog.Emails.send(MyApp.PostHogEmail, to: ..., template_id: ..., template_data: %{...}, distinct_id: ..., idempotency_key: ...)`. + +## A deadline + +For a site whose request had its own deadline, as `7-rewrite.md` says under "Set up the client": + +- The config's `email_request_timeout_ms` is the time each email request may take, 15000 by default, and `email_request_max_retries` its retries, 2 by default. A send's `max_retries: 0` turns its retries off. +- The send takes no deadline of its own, so a deadline needs a named instance of its own, as above, with `email_request_timeout_ms` set to it. + +## The answer + +- The send returns `{:ok, result}`, and `result.id` is the message ID. +- An API error is `{:error, %PostHog.Emails.Error{}}`. `code` is PostHog's error code, a string such as `"recipient_suppressed"`, and `name` is one of the coarse names that `7-rewrite.md` lists under "What every SDK's send takes and answers", as an atom, such as `:rate_limit_exceeded`. +- Suppressed recipient: match `{:error, %PostHog.Emails.Error{code: "recipient_suppressed"}}`. +- A network error that is left after the retries is the same `{:error, %PostHog.Emails.Error{}}`, with the code `"network_error"`, and so is a bad argument, with a code that starts with `invalid_`. `message` and `status_code` are there too. +- An error PostHog answered with a wait carries it as `retry_after_ms`, in milliseconds; it is `nil` when PostHog named none. + +## Check + +`mix compile --force`, comparing its warnings with the ones Step 7 kept: an undefined function shows only as a warning. diff --git a/context/skills/migrate-email/references/rewrite-go.md b/context/skills/migrate-email/references/rewrite-go.md new file mode 100644 index 00000000..68f89f5c --- /dev/null +++ b/context/skills/migrate-email/references/rewrite-go.md @@ -0,0 +1,54 @@ +--- +title: Send with posthog-go +description: The PostHog side of a moved site in Go +--- + +# Send with posthog-go + +For a site in Go. + +## Install + +`go get github.com/posthog/posthog-go@latest`. Run `go mod tidy` only after the sites import it, in Step 8: before that, it removes the new requirement. + +## The client + +```go +client, err := posthog.NewWithConfig(os.Getenv("POSTHOG_PROJECT_TOKEN"), posthog.Config{ + Endpoint: os.Getenv("POSTHOG_HOST"), + SecretKey: os.Getenv("POSTHOG_PROJECT_SECRET_API_KEY"), + MigratedFrom: "", // only when posthog.Config has it +}) +``` + +- With `SecretKey` set, the client starts polling flag definitions from `Endpoint` with it as soon as it's built, and there is no option to turn that off. Give the key the feature flag read scope too, or it logs a failed poll each time. Tell the person. +- The app host option is `AppHost`. +- Close the client when the app exits. + +## 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. +- Template send: `client.Emails().Send(ctx, posthog.TemplateEmail{To, TemplateID, TemplateData, DistinctID, IdempotencyKey})`. +- `ReplyTo` is a `[]string`, a list of addresses: wrap one address as `[]string{addr}`. +- A site with no `context.Context` passes `context.Background()`. + +## A deadline + +For a site whose request had its own deadline, as `7-rewrite.md` says under "Set up the client": + +- `Send` keeps to its context: pass a context with the site's deadline, such as `ctx, cancel := context.WithTimeout(ctx, 5*time.Second)` and `defer cancel()`, and set `MaxRetries: posthog.Ptr(0)` on the email. A context the caller can cancel cancels the send the same way. +- The client also ends each request at its `EmailRequestTimeout`. A deadline up to that timeout needs no client of its own. A longer one needs a client of its own with `EmailRequestTimeout` set to it, or the send fails before the site's deadline. +- `posthog.Config`'s `EmailRequestTimeout` is the time each email request may take, 15 seconds by default, and `EmailRequestMaxRetries` its retries, 2 by default. +- The email send uses `posthog.Config`'s `Transport`. A limit the request set on its `http.Transport`, such as a `net.Dialer`'s `Timeout` in its `DialContext`, `TLSHandshakeTimeout`, or `ResponseHeaderTimeout`, is kept by giving the email client that transport, or one with the same limits, as `Transport`. Such a client is one of its own, like a client for a longer deadline. + +## The answer + +- The send returns a `*posthog.SendEmailResult` and an error. `ID` is the message ID. +- An API error is a `*posthog.EmailError`: read it with `errors.As`. `Code` is PostHog's error code, such as `recipient_suppressed`, `Name` is one of the coarse names that `7-rewrite.md` lists under "What every SDK's send takes and answers", and `StatusCode` is the HTTP status. +- Suppressed recipient: `var emailErr *posthog.EmailError` and `if errors.As(err, &emailErr) && emailErr.Code == "recipient_suppressed"`. +- Every error from the send is a `*posthog.EmailError`: also a network error that is left after the retries, with the code `network_error`, and a bad argument, with a code that starts with `invalid_`. `Message` is there too. +- An error PostHog answered with a wait carries it as `RetryAfter`, a `time.Duration`; it is `0` when PostHog named none. + +## Check + +`go build ./...` and `go vet ./...`. diff --git a/context/skills/migrate-email/references/rewrite-node.md b/context/skills/migrate-email/references/rewrite-node.md new file mode 100644 index 00000000..a5498103 --- /dev/null +++ b/context/skills/migrate-email/references/rewrite-node.md @@ -0,0 +1,56 @@ +--- +title: Send with posthog-node +description: The PostHog side of a moved site in JavaScript or TypeScript on Node.js +--- + +# Send with posthog-node + +For a site in JavaScript or TypeScript that runs on a server: Node.js, or an edge runtime such as Cloudflare Workers or Vercel Edge Functions, which posthog-node also supports. A site that runs in the browser never sends email: the secret key stays on the server. + +## Install + +Install or upgrade `posthog-node` to its latest release with the project's package manager. Install `@react-email/render` too when a site renders a component and the app doesn't have it. + +## The client + +```js +import { PostHog } from 'posthog-node' + +export const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, { + host: process.env.POSTHOG_HOST, + secretKey: process.env.POSTHOG_PROJECT_SECRET_API_KEY, + enableLocalEvaluation: false, + migratedFrom: '', // only when the client options take it +}) +``` + +- The client polls feature flag definitions with the secret key, so a client that only sends email sets `enableLocalEvaluation: false`. +- The app host option is `appHost`. +- On an edge runtime without `process.env`, read the variables the way the app reads its provider key, such as from a Worker's `env`. + +## The send + +- Code send: `posthog.emails.send({ templateKey, to, subject, html, text, distinctId, idempotencyKey })`, with `from`, `replyTo`, `captureEngagement`, and `sensitive: true` optional. +- `replyTo` takes one address or a list of addresses. +- Template send: `posthog.emails.send({ to, templateId, templateData, distinctId, idempotencyKey })`. +- A component the provider rendered, such as React Email, is rendered in the app with `render` from `@react-email/render`, and sent as `html`. + +## A deadline + +For a site whose request had its own deadline, as `7-rewrite.md` says under "Set up the client": + +- The client's `emailRequestTimeoutMs` is the time each email request may take, 15000 by default, and `emailRequestMaxRetries` its retries, 2 by default. A send's `maxRetries: 0` turns its retries off. +- The send takes no abort signal, so a deadline needs a client of its own with `emailRequestTimeoutMs` set to it. + +## The answer + +- `posthog.emails.send` never throws on an API error: it returns `{ data, error }`. When the old call threw on an error, or the code checked an HTTP status, check `error` so the site fails the same way. +- `data.id` is the message ID. +- A network error that is left after the retries comes back as `error` with the code `network_error`. A bad argument comes back as `error` too, with a code that starts with `invalid_`. +- An error PostHog answered with a wait carries it as `error.retryAfterMs`, in milliseconds; it is unset when PostHog named none. +- `error.code` is PostHog's error code, such as `recipient_suppressed`. `error.name` is one of the coarse names that `7-rewrite.md` lists under "What every SDK's send takes and answers". `error.message` and `error.statusCode` are there too. +- Suppressed recipient: `if (error?.code === 'recipient_suppressed')`. + +## Check + +The project's typecheck, such as its `typecheck` script or `tsc --noEmit`, or its build when it has no typecheck. diff --git a/context/skills/migrate-email/references/rewrite-php.md b/context/skills/migrate-email/references/rewrite-php.md new file mode 100644 index 00000000..6f54eadb --- /dev/null +++ b/context/skills/migrate-email/references/rewrite-php.md @@ -0,0 +1,60 @@ +--- +title: Send with posthog-php +description: The PostHog side of a moved site in PHP +--- + +# Send with posthog-php + +For a site in PHP, such as in a Laravel or Symfony app. A site that sends through Laravel's mailer stays on the provider: the provider's `mapping.md` says so. + +## Install + +`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 client + +```php +use PostHog\Client; + +$posthog = new Client( + getenv('POSTHOG_PROJECT_TOKEN') ?: null, + [ + 'host' => getenv('POSTHOG_HOST') ?: null, + 'migrated_from' => '', // only when the options take it + ], + loadFeatureFlags: false, + secretKey: getenv('POSTHOG_PROJECT_SECRET_API_KEY') ?: null, +); +``` + +- Give email its own client, as above, and leave the app's `PostHog::init` as it is: calling `PostHog::init` again replaces the client the app's captures use. With a secret key, a client loads flag definitions with it when it starts, so the email client is built with `loadFeatureFlags: false`, which also keeps the key off a proxy. +- Create it once, such as in a service container binding, and use it where the sites send. +- The app host option is `app_host`. +- Read the env variables the way the app reads its provider key, such as `env()` or `$_ENV` in a framework. + +## The send + +- Code send: `$posthog->emails()->send(['to' => ..., 'template_key' => ..., 'subject' => ..., 'html' => ..., 'text' => ..., 'distinct_id' => ..., 'idempotency_key' => ...])`, with `'from'`, `'reply_to'`, `'capture_engagement'`, and `'sensitive' => true` optional. +- `'reply_to'` takes one address or a list of addresses. +- Template send: `$posthog->emails()->send(['to' => ..., 'template_id' => ..., 'template_data' => [...], 'distinct_id' => ..., 'idempotency_key' => ...])`. + +## A deadline + +For a site whose request had its own deadline, as `7-rewrite.md` says under "Set up the client": + +- The client option `'email_request_timeout_ms'` is the time each email request may take, 15000 by default, and `'email_request_max_retries'` its retries, 2 by default. A send's `'max_retries' => 0` turns its retries off. +- The send takes no deadline of its own, so a deadline needs a client of its own with `'email_request_timeout_ms'` set to it. + +## The answer + +- The send returns a `SendEmailResult`. `getId()` is the message ID. +- On an API error it throws `PostHog\EmailError`. `getErrorCode()` is PostHog's error code, a string such as `recipient_suppressed`, `getErrorName()` is one of the coarse names that `7-rewrite.md` lists under "What every SDK's send takes and answers", and `getStatusCode()` is the HTTP status. +- Suppressed recipient: `catch (\PostHog\EmailError $e)` with `if ($e->getErrorCode() === 'recipient_suppressed')`. +- It throws the same `PostHog\EmailError` for a network error that is left after the retries, with the code `network_error`, and for a bad argument, with a code that starts with `invalid_`. `getMessage()` is there too. +- An error PostHog answered with a wait carries it as `$e->getRetryAfterMs()`, in milliseconds; it is `null` when PostHog named none. + +## Check + +`php -l` on each changed file, and the project's static analyzer on the whole project when it has one, such as PHPStan or Psalm. diff --git a/context/skills/migrate-email/references/rewrite-python.md b/context/skills/migrate-email/references/rewrite-python.md new file mode 100644 index 00000000..ac2e66aa --- /dev/null +++ b/context/skills/migrate-email/references/rewrite-python.md @@ -0,0 +1,60 @@ +--- +title: Send with the posthog Python SDK +description: The PostHog side of a moved site in Python +--- + +# Send with the posthog Python SDK + +For a site in Python. + +## Install + +Install or upgrade `posthog` to its latest release with the project's tool, such as `uv add posthog`, `poetry add posthog@latest`, or a `posthog>=` line in `requirements.txt`. An app with sites in `async` code installs `posthog[async]` for its `AsyncPosthog` client. + +## The client + +```python +import os +from posthog import Posthog + +posthog = Posthog( + os.environ.get("POSTHOG_PROJECT_TOKEN"), + host=os.environ.get("POSTHOG_HOST"), + secret_key=os.environ.get("POSTHOG_PROJECT_SECRET_API_KEY"), + enable_local_evaluation=False, + migrated_from="", # only when the client takes it +) +``` + +- With `secret_key` set, the client loads flag definitions from `host` with it the first time it evaluates a flag, and a worker forked from a process that made the client, such as under Gunicorn's `preload_app`, starts polling them at once. `enable_local_evaluation=False` stops both, so the key needs no flag scope. +- The app host option is `app_host`. +- `AsyncPosthog`, from `posthog[async]`, takes the same options except `enable_local_evaluation`: it has no such option and never polls flags, so leave it out there, or the constructor raises `TypeError`. Await each call below on it. A synchronous site uses `Posthog`, and an `async` site uses `AsyncPosthog`: a call on `AsyncPosthog` without `await` sends nothing. +- `AsyncPosthog` binds to the first event loop it runs on, and raises `RuntimeError` on any other. Create it where one loop runs for the app's life, such as an ASGI app's startup, and `await posthog.shutdown()` when it stops. Where each task runs its own loop, such as `asyncio.run` per job or `async` views under WSGI, create it inside that loop and `await posthog.shutdown()` before the loop ends. +- Without the `async` extra, the first send on `AsyncPosthog` fails before it reaches PostHog. + +## The send + +- Code send: `posthog.emails.send(template_key=..., to=..., subject=..., html=..., text=..., distinct_id=..., idempotency_key=...)`, with `from_`, `reply_to`, `capture_engagement`, and `sensitive=True` optional. `from` is a Python keyword, so the argument is `from_`. +- `reply_to` takes one address or a list of addresses. +- Template send: `posthog.emails.send(to=..., template_id=..., template_data=..., distinct_id=..., idempotency_key=...)`. + +## A deadline + +For a site whose request had its own deadline, as `7-rewrite.md` says under "Set up the client": + +- The client's `email_request_timeout_seconds` is the time each email request may take, 15 by default, and it takes a fraction, such as `2.5`. `email_request_max_retries` is its retries, 2 by default. A send's `max_retries=0` turns its retries off. `AsyncPosthog` takes the same. +- The send takes no deadline of its own, so a deadline needs a client of its own with `email_request_timeout_seconds` set to it. +- The SDK hands that timeout to `requests` or `httpx` as one number, which limits each wait on the network, such as connecting or the next part of the answer, not the whole request. A `requests` or `httpx` `timeout` of one number is the same limit. A limit on the whole request in the HTTP library's options, such as aiohttp's `ClientTimeout(total=5)`, is a deadline the SDK can't keep: the site stays, as Step 7 says. A timer the code puts around the call, such as `asyncio.wait_for(..., 5)`, is code around the send and stays around it. + +## The answer + +- The send returns a `SendEmailResult`. Its `id` is the message ID. +- On an API error it raises `EmailError`, imported from `posthog.emails`. `code` is PostHog's error code, such as `recipient_suppressed`, `name` is one of the coarse names that `7-rewrite.md` lists under "What every SDK's send takes and answers", and `status_code` is the HTTP status. +- Suppressed recipient: `except EmailError as error:` with `if error.code == "recipient_suppressed":`. +- It raises the same `EmailError` for a network error that is left after the retries, with the code `network_error`. `message` is there too. +- An error PostHog answered with a wait carries it as `error.retry_after`, in seconds, as a float; it is `None` when PostHog named none. +- A bad argument raises `TypeError` or `ValueError`, before any request. + +## Check + +The project's type checker on the whole project when it has one, such as `mypy` or `pyright`, and `python -m compileall -q` on the app's source directories. diff --git a/context/skills/migrate-email/references/rewrite-ruby.md b/context/skills/migrate-email/references/rewrite-ruby.md new file mode 100644 index 00000000..3290403d --- /dev/null +++ b/context/skills/migrate-email/references/rewrite-ruby.md @@ -0,0 +1,55 @@ +--- +title: Send with posthog-ruby +description: The PostHog side of a moved site in Ruby +--- + +# Send with posthog-ruby + +For a site in Ruby, such as in a Rails app. A site that sends through Rails' mailer stays on the provider: the provider's `mapping.md` says so. + +## Install + +`bundle add posthog-ruby`. When the app has it, raise its version constraint in the `Gemfile` when the constraint holds back the latest release, then run `bundle update posthog-ruby`. Require it with `require 'posthog'`. + +## The client + +```ruby +POSTHOG = PostHog::Client.new({ + api_key: ENV['POSTHOG_PROJECT_TOKEN'], + host: ENV['POSTHOG_HOST'], + secret_key: ENV['POSTHOG_PROJECT_SECRET_API_KEY'], + feature_flags_async_load: true, + migrated_from: '' # only when the client takes it +}) +``` + +- With `secret_key` set, the client loads flag definitions from `host` with it, and keeps polling. Give the key the feature flag read scope too. Tell the person. `feature_flags_async_load: true` loads them on the polling thread, so a slow answer never holds the app's boot; set it on any client that gets the key. +- The app host option is `app_host`. +- In Rails, create the client once, such as in an initializer. + +## The send + +- Code send: `POSTHOG.emails.send(to:, template_key:, subject:, html:, text:, distinct_id:, idempotency_key:)`, with `from:`, `reply_to:`, `capture_engagement:`, and `sensitive: true` optional. +- `reply_to:` takes one address or a list of addresses. +- Template send: `POSTHOG.emails.send(to:, template_id:, template_data:, distinct_id:, idempotency_key:)`. + +## A deadline + +For a site whose request had its own deadline, as `7-rewrite.md` says under "Set up the client": + +- The client's `email_request_timeout_seconds:` is the time each email request may take, 15 by default, and `email_request_max_retries:` its retries, 2 by default. A send's `max_retries: 0` turns its retries off. +- The send takes no deadline of its own, so a deadline needs a client of its own with `email_request_timeout_seconds:` set to it. +- The SDK sets `Net::HTTP`'s open, read and write timeouts to that number, which limits each wait on the network, not the whole request. `Net::HTTP`'s own timeouts, and Faraday's `timeout` on its default `net_http` adapter, are the same kind of limit, and the SDK keeps one only when the request sets open, read and write to one number. A request that sets only some of them, such as only `read_timeout: 3`, which leaves the others at `Net::HTTP`'s 60 seconds, or sets them to different numbers, is a mix the SDK can't keep: the site stays. A limit on the whole request, such as Typhoeus's `timeout` or Faraday's `timeout` on another adapter, such as `:typhoeus`, is a deadline the SDK can't keep: the site stays, as Step 7 says. A `Timeout.timeout` the code puts around the call is code around the send and stays around it. + +## The answer + +- The send returns a `SendResult`. Its `id` is the message ID. +- On an API error it raises `PostHog::EmailError`. `code` is PostHog's error code, such as `recipient_suppressed`, `name` is one of the coarse names that `7-rewrite.md` lists under "What every SDK's send takes and answers", and `status_code` is the HTTP status. +- Suppressed recipient: `rescue PostHog::EmailError => e` with `if e.code == 'recipient_suppressed'`. +- It raises the same `PostHog::EmailError` for a network error that is left after the retries, with the code `network_error`. `message` is there too. +- An error PostHog answered with a wait carries it as `e.retry_after`, in seconds, as a float; it is `nil` when PostHog named none. +- A bad argument raises `ArgumentError`, before any request. + +## Check + +`ruby -c` on each changed file, the project's type checker on the whole project when it has one, such as Sorbet or Steep, and the app's boot, such as `bin/rails runner 'true'` in Rails. diff --git a/context/skills/migrate-email/references/rewrite-rust.md b/context/skills/migrate-email/references/rewrite-rust.md new file mode 100644 index 00000000..e426bf40 --- /dev/null +++ b/context/skills/migrate-email/references/rewrite-rust.md @@ -0,0 +1,56 @@ +--- +title: Send with posthog-rs +description: The PostHog side of a moved site in Rust +--- + +# Send with posthog-rs + +For a site in Rust. + +## Install + +`cargo add posthog-rs`, also when the app has it: it moves the version requirement to the latest release, which `cargo update` doesn't do across a 0.x minor version. An app that sends from async code uses the crate's `async-client` feature, and a blocking app builds without it. The async client runs only on Tokio with its timers on, as `#[tokio::main]` and `enable_all()` set up: it waits between retries with `tokio::time::sleep`. A site whose async code runs on another runtime, such as async-std or smol, or on a Tokio runtime built without timers, stays, with the reason `posthog-rs's async client needs Tokio with timers`. + +## The client + +```rust +let mut options = posthog_rs::ClientOptionsBuilder::default(); +options + .api_key(std::env::var("POSTHOG_PROJECT_TOKEN").unwrap_or_default()) + .host(std::env::var("POSTHOG_HOST").unwrap_or_default()) + .secret_key(std::env::var("POSTHOG_PROJECT_SECRET_API_KEY").unwrap_or_default()) + .migrated_from(""); // only when the builder has it +let posthog = posthog_rs::client(options.build()?).await; // with `async-client` +// let posthog = posthog_rs::client(options.build()?); // without it, the blocking client +``` + +- The client loads flag definitions only with `enable_local_evaluation` on, so a client that only sends email needs no other setting. +- The app host option is `app_host`. +- Create the client once, and share it where the sites send. A blank secret key counts as none, so a send without it fails with its own error. +- The crate builds one client: the async one with the `async-client` feature, and the blocking one without it. Use the one the app's features give. A site whose code doesn't match it, such as a blocking site in an app built with `async-client`, stays, with the reason `posthog-rs builds only the client here`. + +## The send + +- Code send: `posthog.emails().send(CodeEmail::new(to, template_key, subject).html(...).text(...).distinct_id(...).idempotency_key(...))`, with `.from(...)`, `.reply_to(...)`, `.capture_engagement(false)`, and `.sensitive(true)` optional. +- Template send: `posthog.emails().send(TemplateEmail::new(to, template_id).template_data(...).distinct_id(...).idempotency_key(...))`. +- With the async client, await the send. +- Call `.reply_to(...)` once per address. + +## A deadline + +For a site whose request had its own deadline, as `7-rewrite.md` says under "Set up the client": + +- The builder's `email_request_timeout_seconds` is the time each email request may take, 15 by default, in whole seconds, and `email_request_max_retries` its retries, 2 by default. A send's `.max_retries(0)` turns its retries off. +- The send takes no deadline of its own, so a deadline needs a client of its own with `email_request_timeout_seconds` set to it. A deadline that is not whole seconds can't be kept: the site stays. + +## The answer + +- The send returns a `Result`. On success, `SendEmailResult`'s `id` is the message ID. +- An API error is a `posthog_rs::EmailError`. `code()` is PostHog's error code, such as `recipient_suppressed`, `kind().as_str()` is one of the coarse names that `7-rewrite.md` lists under "What every SDK's send takes and answers", and `status()` is the HTTP status. +- Suppressed recipient: `Err(error) if error.code() == "recipient_suppressed"`. +- A network error that is left after the retries is the same `EmailError`, with the code `network_error`, and so is a bad argument, with a code that starts with `invalid_`. +- An error PostHog answered with a wait carries it as `error.retry_after()`, an `Option`; it is `None` when PostHog named none. + +## Check + +`cargo check` with the features the app builds with. diff --git a/context/skills/migrate-email/references/template-to-code.md b/context/skills/migrate-email/references/template-to-code.md new file mode 100644 index 00000000..8782be2d --- /dev/null +++ b/context/skills/migrate-email/references/template-to-code.md @@ -0,0 +1,98 @@ +--- +title: Bring a stored template into the code +description: How a send of a template stored at the provider moves to PostHog with its content in the app's code +--- + +# Bring a stored template into the code + +A `template` site sends an email whose content is stored at the provider: the code passes only the template's ID and its variables. Such a site moves by bringing the email into the code. Its content becomes a file next to the send, the code renders the variables itself, and the site sends the rendered email in the code form: a template key, a subject, and HTML, text, or both, with the `from` and reply-to address the provider template set. The email then lives in the repository like the rest of the code, and the person changes it there. + +Step 3 reads the "Check" part of this file, and Step 7 reads the rest. The provider's `mapping.md` says under "Templates" what each part of its template language means and how it is written in code, and what keeps a template on the provider. + +A template made in PostHog, sent by its template ID, is the other way to move such a site. It is never the default: it is used only for a template the person asks to keep editable in PostHog, as Step 3 says. + +## Check + +The check needs the content of the version the site sends, because the code has only its ID. The provider's `account.md` says under "Template content" whether its API returns the content, and what the person copies from the dashboard when it doesn't or when they choose the dashboard. + +A template moves into the code when every part of it is in the provider's "Templates" table: each variable, fallback, condition, loop, helper, and tag, and each setting such as its subject, sender, and reply-to address. A part the table doesn't place keeps the site on the provider, and the reason names that part. A template moves however it was designed: the design, the layout, and the images come into the code as they are. + +These parts keep a template on the provider, unless the provider's table says how the code fills them: + +- a tag the provider fills from its own account at send time, such as its unsubscribe link, a view-in-browser link, or a block shared between templates that the content doesn't include; +- a setting the code form has no field for, such as `cc`, `bcc`, an attachment, or a custom header in the template; +- a helper whose result the provider computes in a way the table doesn't describe, such as a date format in a locale the table doesn't name; +- a template whose emails the provider sent with no text part, as the provider's table says: PostHog makes a text part from the HTML whenever a send has no text, so it would add one. The reason is `turns the plain-text part off`. + +A template that the app's own code creates, changes, or publishes through the provider's API keeps its sites on the provider too: the code would hold the content of one moment while the app goes on changing it at the provider. The reason is `the app changes this template at `. + +Write each API answer and each copy you make to a file in the system's temporary folder, never in the repository or the plan. Delete it as soon as no site that sends its template will bring the email into the code: when each such site stays on the provider, or moves to a template made in PostHog. Otherwise keep it until Step 7 has written the email, then delete it. Step 7 deletes every copy still there before it goes on to Step 8, on every way out of the step. When a copy Step 7 needs is gone by then, ask the person for a copy from the dashboard: the full-access key that an API read needs is deleted at the end of Step 5. Read the person's own copies where they saved them. + +## Where the email goes + +Write each email next to the module that sends it, in an `emails` folder, or in the folder where the app already keeps its email content. Name the files after the template key that Step 7 gives the send, such as `emails/welcome.html` and `emails/welcome.txt`. Two sites that send the same provider template share one email. + +Keep the content where the build ships it. A file that the code reads at run time by its path ships only when the build copies it: a bundler, a compiled binary, or a package that lists its data files can leave it out. So write the content as code, or embed it at build time, as the table below says, unless the app already ships template files the same way, such as a `templates` folder its template engine reads. + +## How the code renders it + +Pick the first that fits the part of the app that sends: + +1. **React Email.** When the app's manifest for that part already has a React Email package, such as `@react-email/components` or `react-email`, write the email as a component: rebuild it with React Email's components (`Html`, `Head`, `Preview`, `Body`, `Container`, `Section`, `Row`, `Column`, `Text`, `Link`, `Button`, `Img`, `Hr`) with inline styles, keeping the provider's text, links, images, colors, and layout. Each variable becomes a prop. Render it with `render` from `@react-email/render` and send the result as `html`. +2. **The app's template engine.** When the app already renders HTML on the server with a template engine in that language, such as Jinja2 or Django templates, ERB or ActionView, Blade or Twig, EEx or HEEx, Handlebars, Nunjucks, or EJS, write the email as a template of that engine, with its auto-escaping on, and render it the way the app renders its other templates. +3. **The language's own way.** Otherwise: + +| Language | The email | Escape a value with | +|---|---|---| +| `node` | A module, `emails/.ts` or `.js`, that exports one function per email, which takes the variables and returns `{ subject, html, text }` built with template literals. In TypeScript, give the variables a type | an `escapeHtml` function in the same folder that replaces `&`, `<`, `>`, `"`, and `'`, or the app's own one, such as from `escape-html` or `lodash` | +| `python` | A module, `emails/.py`, with the HTML and the text as string constants with `{{name}}` markers, and a function that replaces each marker | `html.escape(value, quote=True)` | +| `go` | `emails/.html` and `emails/.txt`, embedded with `//go:embed`, rendered with `html/template` and `text/template` | `html/template`, which escapes each value for where it stands | +| `ruby` | `emails/.html.erb` and `emails/.text.erb`, rendered with `ERB` from the standard library | `ERB::Util.html_escape`, as `<%= h(value) %>` | +| `php` | `emails/.html.php` and `emails/.txt.php`, plain PHP templates rendered with `ob_start()`, `include`, and `ob_get_clean()` | `htmlspecialchars($value, ENT_QUOTES \| ENT_HTML5, 'UTF-8')` | +| `dotnet` | A static class, `Emails/Email.cs`, with the HTML and the text as raw string literals with `{{name}}` markers, and a method that replaces each marker | `System.Net.WebUtility.HtmlEncode` | +| `rust` | `emails/.html` and `emails/.txt`, read with `include_str!`, and a function that replaces each `{{name}}` marker | a small `escape_html` function next to it that replaces `&`, `<`, `>`, `"`, and `'` | +| `elixir` | `emails/.html.eex` and `emails/.text.eex`, compiled with `EEx.function_from_file` | `Phoenix.HTML.html_escape/1` with `Phoenix.HTML.safe_to_string/1` when the app has `phoenix_html`, or `Plug.HTML.html_escape/1` when it has `plug`, otherwise a small `escape_html` function next to it that replaces `&`, `<`, `>`, `"`, and `'` | + +Write the `\|` above as a plain `|`. The table escapes it. + +- The provider's HTML and text go into the template as literal content. Before writing them, escape each sequence the destination reads as its own code, so text from the provider's editor never runs in the app: `<%` as `<%%` in ERB and EEx, `` in a PHP template, `{{` as `{{"{{"}}` in Go's templates, and the delimiters of the app's engine, such as `{{` and `{%` in Jinja2, Twig, Handlebars, and Nunjucks, as that engine documents. Where the content sits in a string literal of the code, as in Node.js, Python, and .NET, write it so nothing in it ends the literal or runs: in a JavaScript template literal, escape each `\`, `` ` ``, and `${`; in Python, use a triple-quoted string only when the content holds no `"""` and no `\`, and otherwise write the string as `repr()` writes it; in C#, use a raw string literal whose quotes outnumber the longest run of `"` in the content, without `$`. +- `html/template` writes `#ZgotmplZ` in place of a value that fills a URL attribute, such as `href` or `src`, when its scheme is not `http`, `https`, or `mailto`, such as `tel:`. In Go, pass such a value as `template.URL` only when the code builds that URL itself. When a value from elsewhere can hold another scheme, the site stays, and the reason is `a link Go's templates would rewrite`. +- `html/template` also writes `ZgotmplZ` in place of a value inside CSS, in a `style` attribute or a `