Index of every page on this site: llms.txt
All skills
posthog avatar

/migrating-from-customer-io

@028173b official
by posthogposthog/posthog41k stars
3,718
Run it yourself

Move Customer.io automations into PostHog as draft workflows. Read each automation with the Customer.io MCP or CLI, preview the import with workflows-import-customerio (dry_run), then import and walk the user through what needs their input. Use when asked to migrate, move, switch, copy or import from Customer.io (customer.io, CIO) to PostHog workflows, including "migrate everything to PostHog".

  • 1 file
  • 9.2 KB
  • Updated last week
  • GitHub
Use this Skill: https://skilld.dev/gh/posthog/posthog/migrating-from-customer-io

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈106 tokens for metadata: the name and description. ≈2.2k when used: this file.

Description uses 5.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈426 characters, or 5.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Migrating from Customer.io

PostHog imports Customer.io automations as draft workflows. Drafts never send. A person reviews each one, fixes what the import could not carry over, and enables it.

You move the data between two MCP servers. Read from Customer.io's MCP (or the cio CLI), and pass what it returns unchanged to PostHog's workflows-import-customerio. PostHog does the translation, so do not rebuild workflows yourself with workflows-create.

Never move people

Pass automations, templates, sender identities and segment names only. Never fetch or pass customer profiles, segment members, deliveries or event data. The people are usually in PostHog already, and copying them is a privacy risk the user did not ask for.

Keep message content out of your context

Email templates are large, often tens of kilobytes of HTML each. When the PostHog project stored a Customer.io App API key (teams that ran the opt-out import have one), PostHog reads the message content from Customer.io itself. So pass the automation graph first, and read templates only if PostHog asks for them.

Steps

  1. Confirm the PostHog project. The drafts go into the PostHog MCP's active project. Read it with project-get, tell the user its name and id, and ask whether the drafts should go there. If not, switch with switch-project before you read anything from Customer.io.
  2. Find the environment. Ask which Customer.io workspace to migrate if there is more than one. Its id is the environment_id in every path below.
  3. List the automations. GET /v1/environments/{environment_id}/campaigns with the Customer.io read tool (cio_read_api on the MCP, cio api on the CLI). It returns 20 per page through page (0-based): read every page until one returns fewer than 20. Show the user the list with each automation's state, and ask which to move. Running automations are the usual answer; skip archived ones unless asked.
  4. Read each automation. GET /v1/environments/{environment_id}/campaigns/{campaign_id}. Keep the response's campaign object and its top-level actions array. campaign.actions does not exist.
  5. Read senders and segments. GET /v1/environments/{environment_id}/identities?type=email for sender_identities (id, email, name), and the segment list for segments (id, name, type). PostHog matches each email to the PostHog sender with the same address, and names the segments in its notes. For every dynamic segment the chosen automations check (in a trigger, entry filter, exit condition or branch), read its rules with GET /v1/environments/{environment_id}/segments/{segment_id} and add the conditions object to that segment's entry. Never read segment members.
  6. Preview without templates. Call workflows-import-customerio with source: "customerio", dry_run: true, campaigns: [{campaign, actions}], sender_identities and segments. Up to 50 automations per call.
  7. Read templates only if needed. Go by each automation's notes, not by content_fetched alone: true only means PostHog read some content, and one automation can still miss its messages. For every automation whose notes say message content was not part of the import, or that PostHog could not read its messages, read the template of every action that has a template_id with GET /v1/environments/{environment_id}/templates/{template_id}, keep the template object, and preview again with campaigns: [{campaign, actions, templates}]. Read templates one at a time: listing every template in the workspace times out on large ones. Tell the user that Import from Customer.io on the Workflows Opt-outs tab stores their App API key, which skips this step next time.
  8. Collect snippets and layouts. If a note names a Customer.io snippet, or a template body you read contains {{ snippets.name }}, read the workspace snippets and pass them as snippets ({name: content}). When PostHog read the content itself, it read the snippets too, and a note names any it could not find. If a note names a layout, read GET /v1/environments/{environment_id}/layouts/{layout_id} and pass its body as layouts ({layout_id: body}).
  9. Report the preview. For each automation, give its status and its notes, grouped by level (see below). Ask before importing anything with status failed; its validation_errors say why the draft would be rejected.
  10. Import. Call again with dry_run: false and the same arguments. Share each draft's link (/workflows/{workflow_id}) and the needs_input notes again, since the team must handle those before enabling.

When you are unsure of an endpoint's parameters, ask for that one endpoint's schema (cio_schema with resource.method). A whole resource's schema costs tens of thousands of tokens.

Reading the notes

Level Meaning What to tell the user
needs_input The draft needs a setting only the team can give: an email sender, a trigger cohort, a branch condition These block enabling. List them per workflow.
approximated The step works differently in PostHog, for example a wait capped at 30 days Worth a look before enabling.
unsupported The setting has no PostHog equivalent and was left out, for example an SMS step Decide whether to rebuild it another way.

The same notes appear in the PostHog app on the imported workflow, and workflows-import-notes returns them for one workflow.

Senders and categories

An email gets the PostHog email sender with the same address as its Customer.io sender. When no PostHog sender has that address, a needs_input note names it, so the user can add it as a sender. An email's subscription topic, or the automation's topic when the email has none, becomes the PostHog message category the opt-out import made from that topic. When the topics were not imported, a note says so.

Images

The import copies email images hosted by Customer.io into the project's media library, so they keep loading after the Customer.io account closes. That needs the uploaded_media:write scope. If a note says images still load from Customer.io's servers, ask the user to reconnect the PostHog MCP and allow uploading media, then import again.

Segments and cohorts

A real import turns each dynamic segment passed with its conditions into a realtime cohort, and uses it for that segment's triggers and conditions. The response's segment_cohorts says what happened to each segment: would_create in a preview, created, reused when an earlier import made the cohort, or not_converted with a reason. Tell the user which cohorts the import will create before importing for real.

A segment becomes a cohort only when every rule matches a cohort condition exactly: person attribute comparisons, such as equals, contains, exists, greater than and absolute dates. Rules on events, attribute changes, message activity, other segments, devices, relationships and relative dates ("in the last 30 days") have no exact match, so that segment is not converted and its automations get a needs_input note naming the rules. Creating cohorts needs the cohort:write scope and edit access to cohorts; the project also needs realtime cohorts and cohort triggers. When one is missing, the reason says which.

If the user already has a PostHog cohort that matches a segment, pass segment_cohorts: {"<segment id>": <cohort id>} and the import uses it instead of creating one. A cohort trigger needs a realtime cohort. A static segment gets its own note: workflows cannot check a static cohort, so the user rebuilds it as conditions. Static segment members are never imported.

Push notifications

Push steps import as unsupported notes, and device tokens never move with the import. If the user sends push from Customer.io, tell them that a device reaches PostHog only when its app registers it with the PostHog SDK, or when they import their exported device tokens into a PostHog push channel. That token import is a separate step the user starts, because tokens are people data.

Re-running

Importing an automation again replaces its draft, so you can re-run after fixing something in Customer.io. Edits the team made to that draft since are lost, so ask before you re-import. A workflow that someone already enabled, or that the user can't edit, is never changed: its result is skipped.

After the import

Do not enable the drafts. Point the user at the needs_input notes, then hand over to the building-workflows skill for testing and enabling, which needs the user's explicit sign-off.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 028173b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week

README badge

README badge for posthog/posthog/migrating-from-customer-io