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
- 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 withswitch-projectbefore you read anything from Customer.io. - Find the environment. Ask which Customer.io workspace to migrate if there is more than one. Its id is the
environment_idin every path below. - List the automations.
GET /v1/environments/{environment_id}/campaignswith the Customer.io read tool (cio_read_apion the MCP,cio apion the CLI). It returns 20 per page throughpage(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. - Read each automation.
GET /v1/environments/{environment_id}/campaigns/{campaign_id}. Keep the response'scampaignobject and its top-levelactionsarray.campaign.actionsdoes not exist. - Read senders and segments.
GET /v1/environments/{environment_id}/identities?type=emailforsender_identities(id,email,name), and the segment list forsegments(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 withGET /v1/environments/{environment_id}/segments/{segment_id}and add theconditionsobject to that segment's entry. Never read segment members. - Preview without templates. Call
workflows-import-customeriowithsource: "customerio",dry_run: true,campaigns: [{campaign, actions}],sender_identitiesandsegments. Up to 50 automations per call. - Read templates only if needed. Go by each automation's notes, not by
content_fetchedalone:trueonly 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 atemplate_idwithGET /v1/environments/{environment_id}/templates/{template_id}, keep thetemplateobject, and preview again withcampaigns: [{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. - 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 assnippets({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, readGET /v1/environments/{environment_id}/layouts/{layout_id}and pass itsbodyaslayouts({layout_id: body}). - Report the preview. For each automation, give its status and its notes, grouped by level (see below). Ask before importing anything with status
failed; itsvalidation_errorssay why the draft would be rejected. - Import. Call again with
dry_run: falseand the same arguments. Share each draft's link (/workflows/{workflow_id}) and theneeds_inputnotes 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.