> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Localize Customer.io

> Connect Customer.io, import campaign and broadcast message actions, translate in Jobs, then push approved locales back.

Connect Customer.io once in workspace **Integrations**, then run the **Translate Customer.io Campaigns, Broadcasts, Newsletters & Transactional** automation template on a schedule. Import never changes Customer.io. **Push to Customer.io** is a separate action and never publishes — and for transactional messages it never sends.

## Supported content

* Campaigns, newsletters (one-time sends), broadcasts, and transactional messages.
* Message types: email (saved as HTML, opens in HTML File view), in-app messages (also HTML), push notifications, SMS (including Twilio), WhatsApp, and Slack messages (saved as JSON).
* Drag-and-drop emails are supported through the linked Design Studio email. Import brings in the component markup, subject, and preheader. Push writes the translated content back through the Design Studio API as an unpublished draft. Publish the email in Customer.io to go live.
* Out of scope: multilingual A/B variants. Newsletter and transactional messages with several default variants (A/B tests) import each variant but are skipped on push, because their translations share one per-language slot. Webhook actions carry machine config and are always skipped.
* Configure locales on each Customer.io action before pushing translations. Customer.io cannot create or match a locale it does not have — except on Design Studio emails, where push creates a missing language automatically.

## Prerequisites

| Requirement | Description |
| - | - |
| Native project | A [native project](https://hyperlocalise.dev/platform/projects/create-project.md) whose source and target locales map onto Customer.io locale keys. See [Match project locales](#step-2-match-project-locales). |
| Customer.io App API key | Created in Customer.io **Settings → API Credentials**. It needs read/write access to campaigns, newsletters, broadcasts, and transactional messages. |
| Customer.io region | `US` (`https://api.customer.io/v1`) or `EU` (`https://api-eu.customer.io/v1`). The region must match the workspace that issued the key. |
| Locale mapping | Hyperlocalise matches project locale tags to Customer.io locale keys or names exactly (after hyphen/underscore normalization). Keep locked pairs separate: `en-US` is not `en-GB`, `zh-CN` is not `zh-TW`, and `pt` is not `pt-BR`. Locales without a match are reported as unmapped. |

## Connect Customer.io

1. Open workspace **Integrations** and find **Customer.io**.
2. Paste the App API key and choose the region for that workspace.
3. Save. Hyperlocalise pings the Customer.io App API in that region to confirm the key can list broadcasts. A rejected key or unreachable region is not stored.
4. Confirm the connection shows as connected.

The API key is stored in WorkOS Pipes. Hyperlocalise stores only the region.

## Translate campaigns and broadcasts

### Step 1: Set up locales in Customer.io

Add a language variant for each locale you plan to translate into before you create the automation. Hyperlocalise can only import and push locales that already exist on the message — the Customer.io API cannot create language variants. For Design Studio emails you can skip this step: push creates a missing language on the linked email automatically.

1. In Customer.io, open the broadcast or campaign message.
2. Add each target language to the message. Note the locale key shown for each language (for example `en`, `fr-FR`).
3. Save the message as a **draft**.

A message with no language variants imports the default copy only. Push skips any locale that is not configured on the message.

### Step 2: Match project locales

Create or choose a [native project](https://hyperlocalise.dev/platform/projects/create-project.md) whose locale tags match Customer.io.

1. Set the project **source locale** to the language of the default copy in Customer.io.
2. Add a project target locale for each Customer.io language you will write back.
3. Use the same tag as the Customer.io locale **key** or **name** (`fr-FR` matches `fr-FR`). Matching is exact after hyphen/underscore normalization. There is no language fallback: `es` does not map to `es-MX`, and `fr` does not map to `fr-FR`.
4. Keep locked pairs on separate projects or omit the unused tag: `en-US` is not `en-GB`, `zh-CN` is not `zh-TW`, and `pt` is not `pt-BR`.

Unmapped project locales are reported as unmapped and skipped on import and push.

### Step 3: Create the automation

1. Open workspace **Automations** and select **New Automation**.
2. Apply the **Translate Customer.io Campaigns, Broadcasts, Newsletters & Transactional** template, or add the **Translate Customer.io Campaigns, Broadcasts, Newsletters & Transactional** skill from **Add Skill**.
3. Attach the native project from Step 2.
4. Choose a **scheduled** or **manual** trigger. A schedule imports changed message actions. It does not push translations.
5. Under **Customer.io**, set:
   * **Source locale** (usually the project source). It must be the same language as the project source locale.
   * Optional **Broadcasts**, **Newsletters**, and **Transactional messages** to limit import. Leave all empty to discover everything. Limit by campaign in the skill when needed.
   * **Existing translations**: **Only empty locales** (default), **Refresh imported locales**, or **Overwrite all locales**
6. Save the automation.

Customer.io is not a trigger type. Use a schedule or **Run now** for import. Use **Push to Customer.io** for write-back.

## Import message actions

**Run now** or wait for the schedule. Import writes one source file per eligible action:

* Campaign actions at `customer-io/campaigns/{campaign-slug}/{action-slug}.json`, except email actions (HTML below).
* Broadcast actions at `customer-io/broadcasts/{broadcast-slug}/actions/{action-slug}.json`, except email actions.
* Email actions at `customer-io/{broadcasts|campaigns|newsletters|transactional}/{slug}/{actions|contents}/{action-slug}.html`, with subject and preheader in field blocks. They open in HTML File view.
* Newsletter content at `customer-io/newsletters/{newsletter-slug}/contents/{content-slug}.json`.
* Transactional content at `customer-io/transactional/{message-slug}/contents/{content-slug}.json`.
* Push, SMS (including Twilio), WhatsApp, Slack, and in-app actions at the matching `.json` paths.

Design Studio–linked email actions import component markup, subject, and preheader from the linked Design Studio email (not only the compiled App API body) and store the Design Studio email id for push.

Import skips webhook actions and multilingual A/B variants. Newsletter and transactional messages with several default variants import each variant but are skipped on push, because their translations share one per-language slot.

When **Create native TMS job** is enabled, the run opens a job for mapped locales that still need translation. Import does not write anything to Customer.io.

Inspect **Run History** for imported, skipped, and failed actions, plus jobs created.

## Review and push locales

1. Translate and [approve](https://hyperlocalise.dev/platform/cat.md) every visible string for a mapped locale on each action you plan to write back.
2. Open a Customer.io file in the Content editor. The header shows **Ingest** and **Push to Customer.io** for that file. Choose **Ingest** to import the automation's configured set, or **Push to Customer.io** when at least one mapped locale is fully approved and no push is already running. Hyperlocalise then opens the automation **Run History** tab so you can follow the run.
3. Confirm Customer.io shows updated draft content for each locale. Push never publishes. For transactional messages it only updates message content — it never sends.

Push writes approved locales for actions that already have the locale configured on the message. Design Studio emails are the exception: push creates a missing language on the linked email automatically. Writes land as unpublished drafts — publish the email in Customer.io before it can send.

For HTML email actions, push merges approved field blocks onto the **remote** Customer.io copy. Segments you have not approved keep their existing Customer.io text instead of reverting to source language, so a partial push does not overwrite copy teammates edited in Customer.io.

Newsletter and transactional messages with several default variants are skipped on push.

## Change or remove access

Disconnect Customer.io from **Integrations** when this workspace should stop using that App API key. Inspect automations that depend on the connection before you disconnect. The key is stored in WorkOS Pipes; Hyperlocalise stores only the region.

## If import or push does not run

* Confirm Customer.io is connected with the correct **US** or **EU** region and the automation is **Active**.
* Confirm each target locale exists on the message in Customer.io (except Design Studio emails, where push can create a missing language).
* Confirm project locale tags match Customer.io locale keys or names exactly after hyphen/underscore normalization.
* If **Push to Customer.io** or **Ingest** is missing, open a Customer.io file. Those actions stay hidden on other files. Approve at least one mapped locale, confirm you can manage automations, and wait until any in-progress push finishes.
* Open **Run History** for the failed action or locale.

See [Automation troubleshooting](https://hyperlocalise.dev/platform/help/automations.md) and [Connection troubleshooting](https://hyperlocalise.dev/platform/help/connections.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.